`wcsrtombs_s`

Artykuł
10/12/2023

Przekonwertuj ciąg znaków szeroki na reprezentację ciągu znaków wielobajtowych. Wersja z ulepszeniami zabezpieczeń wcsrtombs zgodnie z opisem w temacie Funkcje zabezpieczeń w narzędziu CRT.

Składnia

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

Parametry

pReturnValue
Rozmiar w bajtach przekonwertowanego ciągu, w tym terminator o wartości null.

mbstr
Adres buforu dla wynikowego przekonwertowanego ciągu znaków wielobajtowych.

sizeInBytes
Rozmiar w bajtach buforu mbstr .

wcstr
Wskazuje ciąg znaków szeroki do przekonwertowania.

count
Maksymalna liczba bajtów do przechowywania w buforze mbstr lub _TRUNCATE.

mbstate
Wskaźnik do mbstate_t obiektu stanu konwersji.

Wartość zwracana

Zero, jeśli działanie powiedzie się, kod błędu w przypadku niepowodzenia.

Błąd	Wartość zwracana i `errno`
`mbstr` is `NULL` i `sizeInBytes`> 0	`EINVAL`
`wcstr` jest `NULL`	`EINVAL`
Bufor docelowy jest za mały, aby zawierał przekonwertowany ciąg (chyba że `count` jest `_TRUNCATE`to ; zobacz uwagi poniżej)	`ERANGE`

Jeśli wystąpi którykolwiek z tych warunków, jest wywoływany nieprawidłowy wyjątek parametru zgodnie z opisem w temacie Weryfikacja parametru . Jeśli wykonywanie jest dozwolone do kontynuowania, funkcja zwraca kod błędu i ustawia je errno zgodnie z opisem w tabeli.

Uwagi

Funkcja wcsrtombs_s konwertuje ciąg znaków szerokich znaków wskazywanych przez na wcstr znaki wielobajtowe przechowywane w buforze wskazywanym przez mbstrmetodę przy użyciu stanu konwersji zawartego w mbstateobiekcie . Konwersja będzie kontynuowana dla każdego znaku do momentu spełnienia jednego z następujących warunków:

Napotkano znak szeroki o wartości null
Napotkano szeroki znak, którego nie można przekonwertować
Liczba bajtów przechowywanych w buforze mbstr jest countrówna .

Ciąg docelowy jest zawsze zakończony wartością null (nawet jeśli wystąpi błąd).

Jeśli count jest to wartość _TRUNCATEspecjalna, funkcja wcsrtombs_s konwertuje tyle ciągu, jak będzie mieścić się w buforze docelowym, pozostawiając miejsce na terminator o wartości null.

Jeśli wcsrtombs_s ciąg źródłowy zostanie pomyślnie przekonwertowany, umieści rozmiar w bajtach przekonwertowanego ciągu, w tym terminator o wartości null, na *pReturnValue wartość (podany pReturnValue nie NULLjest ). Rozmiar jest obliczany nawet wtedy, gdy mbstr argument to NULL; umożliwia określenie wymaganego rozmiaru buforu. Jeśli mbstr wartość to NULL, count jest ignorowana.

Jeśli wcsrtombs_s napotka szeroki znak, nie może przekonwertować na znak wielobajtowy, umieszcza wartość -1 w *pReturnValue, ustawia bufor docelowy na pusty ciąg, ustawia errno wartość EILSEQna , i zwraca wartość EILSEQ.

Jeśli sekwencje wskazywane przez wcstr i mbstr nakładają się na siebie, zachowanie wcsrtombs_s jest niezdefiniowane. wcsrtombs_s ma to wpływ na kategorię LC_TYPE bieżące ustawienia regionalne.

Ważne

Upewnij się, że wcstr i mbstr nie nakładają się, i że count poprawnie odzwierciedla liczbę znaków szerokich do przekonwertowania.

Funkcja wcsrtombs_s różni się od wcstombs_sfunkcji , _wcstombs_s_l dzięki możliwości ponownego uruchamiania. Stan konwersji jest przechowywany dla mbstate kolejnych wywołań do tych samych lub innych funkcji możliwych do ponownego uruchomienia. Wyniki są niezdefiniowane podczas mieszania funkcji możliwych do ponownego uruchomienia i niezwiązanych z uruchamianiem. Na przykład aplikacja będzie używać wcsrlen zamiast wcslen, jeśli kolejne wywołanie wcsrtombs_s zostało użyte zamiast wcstombs_s.

W języku C++używanie tych funkcji jest uproszczone przez przeciążenia szablonu; przeciążenia mogą automatycznie wnioskować długość buforu (eliminując konieczność określenia argumentu rozmiaru) i mogą automatycznie zastępować starsze, niezabezpieczone funkcje nowszymi, bezpiecznymi odpowiednikami. 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.

Wyjątki

wcsrtombs_s Funkcja jest bezpieczna wielowątkowość, o ile nie ma funkcji w bieżących wywołaniach setlocale wątku, gdy ta funkcja jest wykonywana, a mbstate parametr ma wartość null.

Przykład

// crt_wcsrtombs_s.cpp
//
// 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;
    errno_t         err;
    mbstate_t       mbstate;

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

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Wymagania

Procedura	Wymagany nagłówek
`wcsrtombs_s`	<wchar.h>

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Udostępnij za pośrednictwem