wcstombs, _wcstombs_l

Konwertuje sekwencję znaków szerokich na odpowiadającą sekwencję znaków wielobajtowych. Dostępne są bezpieczniejsze wersje tych funkcji; zobacz wcstombs_s, _wcstombs_s_l.

Składnia

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parametry

mbstr
Adres sekwencji znaków wielobajtowych.

wcstr
Adres sekwencji znaków szerokich.

count
Maksymalna liczba bajtów, które mogą być przechowywane w ciągu wyjściowym wielobajtowym.

locale
Ustawienia regionalne do użycia.

Wartość zwracana

Jeśli wcstombs ciąg wielobajtowy zostanie pomyślnie przekonwertowany, zwraca liczbę bajtów zapisanych w ciągu wyjściowym wielobajtowym z wyłączeniem zakończenia NULL (jeśli istnieje). mbstr Jeśli argument ma NULLwartość , wcstombs zwraca wymagany rozmiar w bajtach ciągu docelowego. Jeśli wcstombs napotka szeroki znak, nie może przekonwertować na znak wielobajtowy, zwraca -1 rzutowanie na typ size_t i ustawia wartość errno EILSEQ.

Uwagi

Funkcja wcstombs konwertuje ciąg wielobajtowy wskazywany przez wcstr na odpowiednie znaki wielobajtowe i przechowuje wyniki w tablicy mbstr . Parametr count wskazuje maksymalną liczbę bajtów, które mogą być przechowywane w ciągu wyjściowym wielobajtowym (czyli rozmiar mbstr). Ogólnie rzecz biorąc, nie wiadomo, ile bajtów będzie wymaganych podczas konwertowania ciągu wieloznakowego. Niektóre znaki szerokie będą wymagały tylko jednego bajtu w ciągu wyjściowym; inne wymagają 2 bajtów. Jeśli w ciągu wyjściowym wielobajtowym znajduje się 2 bajty dla każdego szerokiego znaku NULLw ciągu wejściowym (w tym znak szeroki), wynik ma gwarancję dopasowania.

Począwszy od systemu Windows 10 w wersji 1803 (10.0.17134.0), środowisko uruchomieniowe uniwersalnego języka C obsługuje korzystanie ze strony kodowej UTF-8. Użyj wcstombs(NULL, wcstr, 0) polecenia , aby uzyskać prawidłowy rozmiar, który będzie potrzebny do konwersji, ponieważ przy założeniu, że potrzebujesz dwóch bajtów dla każdego szerokiego znaku, może nie wystarczyć. Aby uzyskać więcej informacji o obsłudze protokołu UTF-8, zobacz obsługa protokołu UTF-8

Jeśli wcstombs napotka znak szeroki NULL (L'\0') przed lub w momencie count wystąpienia, konwertuje go na 8-bitowy znak 0 i zatrzymuje. W związku z tym ciąg znaków wielobajtowych w mbstr obiekcie jest zakończony wartością null tylko wtedy, gdy wcstombs napotka znak szeroki NULL podczas konwersji. Jeśli sekwencje wskazywane przez wcstr i mbstr nakładają się na siebie, zachowanie wcstombs jest niezdefiniowane.

mbstr Jeśli argument ma NULLwartość , wcstombs zwraca wymagany rozmiar w bajtach ciągu docelowego.

wcstombs weryfikuje jego parametry. Jeśli wcstr parametr ma NULLwartość lub count jest większy niż INT_MAX, ta funkcja wywołuje nieprawidłową procedurę obsługi parametrów, zgodnie z opisem w temacie Weryfikacja parametrów. Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja ustawia errno wartość EINVAL i zwraca wartość -1.

wcstombs używa bieżących ustawień regionalnych dla dowolnego zachowania zależnego od ustawień regionalnych; _wcstombs_l jest identyczna, z tą różnicą, że używa ustawień regionalnych przekazanych w zamian. Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++te funkcje mają przeciążenia szablonu, które wywołują nowsze, bezpieczne odpowiedniki tych funkcji. Aby uzyskać więcej informacji, zobacz Bezpieczne przeciążenia szablonów.

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Wymagania

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Przykład

Ten program ilustruje zachowanie wcstombs funkcji.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

Zobacz też

Konwersja danych
ustawienia regionalne
_mbclen, , mblen_mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte