wcstombs, _wcstombs_l

Artykuł
02/27/2013

Konwertuje sekwencja znaków szerokości odpowiedniej sekwencji znaków wielobajtowych.Bezpieczniejsze wersje te funkcje są dostępne; see wcstombs_s, _wcstombs_s_l.

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 szerokości znaków.
count
Maksymalna liczba bajtów, które mogą być przechowywane w ciągu znaków wielobajtowych dane wyjściowe.
locale
Ustawienia regionalne, aby użyć.

Wartość zwracana

Jeśli wcstombs pomyślnie konwertuje ciąg wielobajtowy zwraca liczbę bajtów zapisanych na ciąg wielobajtowy danych wyjściowych, z wyłączeniem kończące NULL (jeśli ma zastosowanie).Jeśli mbstr argument jest NULL, wcstombs zwraca wymagany rozmiar w bajtach ciąg docelowego.Jeśli wcstombs napotka szerokiego znaku nie może przekonwertować znaków wielobajtowych, zwraca –1 rzutować typu size_t i ustawia errno do EILSEQ.

Uwagi

wcstombs Funkcja konwertuje łańcuch szerokich znaków wskazywanej przez wcstr do odpowiednie wielobajtowych znaków i zapisuje wyniki w mbstr tablicy.count Parametru wskazuje maksymalną liczbę bajtów, które mogą być przechowywane w ciągu znaków wielobajtowych dane wyjściowe (to znaczy rozmiar mbstr).Ogólnie rzecz biorąc nie wiadomo, ile bajtów będzie wymagane podczas konwertowania łańcuch szerokich znaków.Niektóre znaki szeroki będzie wymagać tylko jednego bajtu w łańcuchu produkcji; inne wymagają dwóch.Jeśli istnieją dwa bajty w ciągu wielobajtowych wyjściowego dla każdego szerokiego znaku w ciągu wejściowego (łącznie z szerokiego znaku NULL), wynik jest gwarantowane do dopasowania.

Jeśli wcstombs napotka znak null szerokich znaków (L '\0'), przed lub po count występuje on konwertuje 0 8-bitowych i zatrzymuje.W ten sposób, ciąg znaków wielobajtowych w mbstr jest zakończony zerem tylko wtedy, gdy wcstombs napotka znak null szerokich znaków podczas konwersji.Jeśli sekwencji wskazywanej przez wcstr i mbstr nachodzą na siebie, zachowanie wcstombs jest niezdefiniowane.

Jeśli mbstr argument jest NULL, wcstombs zwraca wymagany rozmiar w bajtach ciąg docelowego.

wcstombssprawdza poprawność jego parametry.Jeśli wcstr jest NULL, lub jeśli count jest większa niżINT_MAX, funkcja ta wywołuje obsługi nieprawidłowy parametr, jak opisano w Sprawdzanie poprawności parametru .Jeśli wykonanie może w dalszym ciągu, funkcja ustawia errno do EINVAL i zwraca wartość -1.

wcstombswykorzystuje bieżące ustawienia regionalne dla wszelkich zachowanie zależnego od ustawień regionalnych; _wcstombs_ljest identyczny z wyjątkiem, że korzysta z ustawień regionalnych, przekazany w zamian.Aby uzyskać więcej informacji, zobacz Ustawienia regionalne.

W języku C++ funkcje te mają overloads szablonu, które wywołują nowsze, bezpieczne odpowiednikami tych funkcji.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Wymagania

Rozpoczęto wykonywanie procedury	Wymaganego nagłówka
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

Aby uzyskać dodatkowe informacje o zgodności, zobacz zgodności we wprowadzeniu.

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);
}