`wcsrtombs`

Artykuł
10/12/2023

Przekonwertuj ciąg znaków szeroki na reprezentację ciągu znaków wielobajtowych. Dostępna jest bezpieczniejsza wersja tej funkcji; zobacz wcsrtombs_s.

Składnia

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

mbstr
Wynikowa przekonwertowana lokalizacja adresu ciągu znaków wielobajtowych.

wcstr
Pośrednio wskazuje lokalizację szerokiego ciągu znaków do przekonwertowania.

count
Liczba znaków do przekonwertowania.

mbstate
Wskaźnik do mbstate_t obiektu stanu konwersji.

Wartość zwracana

Zwraca liczbę bajtów, które zostały pomyślnie przekonwertowane, a nie łącznie z wartością null kończącą bajt (jeśli istnieje), w przeciwnym razie wartość -1 w przypadku wystąpienia błędu.

Uwagi

Funkcja wcsrtombs konwertuje ciąg znaków szerokich, zaczynając od określonego stanu konwersji zawartego w mbstate, z wartości pośrednich wskazywanych na w wcstr, na adres mbstr. Konwersja będzie kontynuowana dla każdego znaku do: po napotkaniu znaku szerokiego o wartości null, gdy napotkany jest inny znak lub gdy następny znak przekroczy limit zawarty w count. Jeśli wcsrtombs napotka znak null o szerokim znaku (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 wcsrtombs podczas konwersji występuje znak null znaku szerokiego. Jeśli sekwencje wskazywane przez wcstr i mbstr nakładają się na siebie, zachowanie wcsrtombs jest niezdefiniowane. wcsrtombs ma to wpływ na kategorię LC_TYPE bieżące ustawienia regionalne.

Funkcja wcsrtombs różni się od wcstombsfunkcji , _wcstombs_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 wcsnlen, jeśli kolejne wywołanie wcsrtombs zostało użyte zamiast wcstombs.

mbstr Jeśli argument ma NULLwartość , wcsrtombs zwraca wymagany rozmiar w bajtach ciągu docelowego. Jeśli mbstate ma wartość null, używany jest stan konwersji wewnętrznej mbstate_t . Jeśli sekwencja wchar znaków nie ma odpowiedniej reprezentacji znaków wielobajtowych, zwracana jest wartość -1, a errno parametr jest ustawiony na EILSEQwartość .

W języku C++ta funkcja ma przeciążenie szablonu, które wywołuje nowszy, bezpieczny odpowiednik tej 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.

Wyjątki

wcsrtombs Funkcja jest bezpieczna wielowątkowość, o ile żadna funkcja w bieżących wywołaniach setlocale wątku jest wykonywana i 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" );
    }
}

The string was successfuly converted.

Wymagania

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

Zobacz też

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

Share via