wcsrtombs

Artykuł
02/27/2013

Konwertowanie ciągu szerokich znaków na jej reprezentację ciągu znaków wielobajtowych.Bardziej bezpieczna wersja ta funkcja jest dostępna; see wcsrtombs_s.

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parametry

[out]mbstr
Wynikowy przekonwertować ciąg znaków wielobajtowych adres lokalizacji.
[w]wcstr
Pośrednio wskazuje lokalizację konwertowanego łańcucha szerokich znaków.
[w]count
Liczba znaków do konwersji.
[w]mbstate
Wskaźnik do mbstate_t obiekt stanu konwersji.

Wartość zwracana

Zwraca liczbę bajtów pomyślnie przekonwertowane, nie włączając null, kończące bajtem null (jeśli ma zastosowanie), w przeciwnym razie -1, jeśli wystąpił błąd.

Uwagi

wcsrtombs Funkcja konwertuje ciąg znaków szerokości, począwszy od stanu określonej konwersji zawartych w mbstate, z pośrednich wartości wskazywanej w wcstr, pod adresem mbstr.Konwersja będzie nadal dla każdego znaku do: po napotkał kończące szerokiego znaku null, w przypadku napotkania innych niż odpowiedni znak lub podczas następnego znaku mogłaby przekroczyć limit, zawartych w count.Jeśli wcsrtombs 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 wcsrtombs napotka znak null szerokich znaków podczas konwersji.Jeśli sekwencji wskazywanej przez wcstr i mbstr nachodzą na siebie, zachowanie wcsrtombs jest niezdefiniowane.wcsrtombsdotyczy kategorii LC_TYPE bieżące ustawienia regionalne.

wcsrtombs Funkcja różni się od wcstombs, _wcstombs_l przez jego restartability.Stan konwersji jest przechowywany w mbstate dla kolejnych zaproszeń na to samo lub inne funkcje Przerywalne.Wyniki są niezdefiniowane, przy użyciu funkcji Przerywalne i nonrestartable.Na przykład, aplikacja będzie korzystać z wcsrlen zamiast wcsnlen, jeśli kolejne wywołania wcsrtombs zostały użyte zamiast wcstombs.

Jeśli mbstr argument jest NULL, wcsrtombs zwraca wymagany rozmiar w bajtach ciąg docelowego.Jeśli mbstate ma wartość null, wewnętrznego mbstate_t stan konwersji jest używany.Jeżeli sekwencja znaków wchar nie ma odpowiedniego wielobajtowe reprezentacji znaków, zwracany jest -1 i errno jest ustawiona na EILSEQ.

W języku C++ funkcja ta ma przeciążenia szablon, który wywołuje nowsze, bezpieczne odpowiednika tej funkcji.Aby uzyskać więcej informacji, zobacz Secure, szablon Overloads.

Wyjątki

wcsrtombs Funkcja jest wielowątkowym bezpieczne tak długo, jak długo wywoła żadnej funkcji w bieżącym wątku setlocale podczas wykonywania tej funkcji oraz mbstate nie ma wartości null.

Przykład

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfuly converted.\n" );
    }
}