mbsrtowcs

Konwertuje ciąg znaków wielobajtowych w bieżących ustawieniach regionalnych na odpowiedni ciąg znaków szeroki, z możliwością ponownego uruchomienia w środku znaku wielobajtowego. Dostępna jest bezpieczniejsza wersja tej funkcji; zobacz mbsrtowcs_s.

Składnia

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

Parametry

wcstr
Adres do przechowywania wynikowego przekonwertowanego ciągu znaków szerokiego.

mbstr
Wskaźnik pośredni do lokalizacji ciągu znaków wielobajtowych do konwersji.

count
Maksymalna liczba znaków (nie bajtów) do konwersji i przechowywania w pliku wcstr.

mbstate
Wskaźnik do mbstate_t obiektu stanu konwersji. Jeśli ta wartość jest wskaźnikiem o wartości null, używany jest statyczny obiekt stanu konwersji wewnętrznej. Ponieważ obiekt wewnętrzny mbstate_t nie jest bezpieczny wątkowo, zalecamy, aby zawsze przekazywać własny mbstate parametr.

Wartość zwracana

Zwraca liczbę znaków, które zostały pomyślnie przekonwertowane, a nie łącznie z znakiem null zakończenia, jeśli istnieje. Zwraca wartość (size_t)(-1) w przypadku wystąpienia błędu i ustawia wartość errno EILSEQ.

Uwagi

Funkcja mbsrtowcs konwertuje ciąg znaków wielobajtowych pośrednio wskazywanych przez mbstr, na znaki szerokie przechowywane w buforze wskazywanym przez wcstrelement przy użyciu stanu konwersji zawartego w mbstateobiekcie . Konwersja jest kontynuowana dla każdego znaku, dopóki nie zostanie napotkany znak wielobajtowy o wartości null, sekwencja wielobajtowa, która nie odpowiada prawidłowemu znakowi w bieżących ustawieniach regionalnych lub dopóki count znaki nie zostały przekonwertowane. W przypadku mbsrtowcs napotkania wielobajtowego znaku null ('\0') przed lub w count czasie, konwertuje go na 16-bitowy znak null i zatrzymuje.

W związku z tym ciąg znaków szeroki w wcstr obiekcie jest zakończony wartością null tylko w przypadku mbsrtowcs napotkania wielobajtowego znaku null podczas konwersji. Jeśli sekwencje wskazywane przez mbstr i wcstr nakładają się na siebie, zachowanie mbsrtowcs jest niezdefiniowane. mbsrtowcs ma to wpływ na kategorię LC_TYPE bieżących ustawień regionalnych.

Funkcja mbsrtowcs różni się od mbstowcsfunkcji , _mbstowcs_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 powinna używać mbsrlen zamiast mbslen, jeśli kolejne wywołanie mbsrtowcs metody jest używane zamiast mbstowcs.

Jeśli wcstr nie jest wskaźnikiem o wartości null, obiekt wskaźnika wskazywany przez mbstr element ma przypisany wskaźnik o wartości null, jeśli konwersja została zatrzymana, ponieważ osiągnięto znak null zakończenia. W przeciwnym razie zostanie przypisany adres tuż obok ostatniego przekonwertowanego znaku wielobajtowego, jeśli istnieje. Umożliwia to kolejne wywołanie funkcji w celu ponownego uruchomienia konwersji, w której zatrzymano to wywołanie.

wcstr Jeśli argument jest wskaźnikiem o wartości null, count argument jest ignorowany i mbsrtowcs zwraca wymagany rozmiar w szerokich znakach dla ciągu docelowego. Jeśli mbstate jest wskaźnikiem o wartości null, funkcja używa niezwiązanego z wątkiem obiektu statycznego stanu konwersji wewnętrznej mbstate_t . Jeśli sekwencja mbstr znaków nie ma odpowiedniej reprezentacji znaków wielobajtowych, zwracana jest wartość -1 i errno jest ustawiona na EILSEQwartość .

Jeśli mbstr jest wskaźnikiem o wartości null, wywoływana jest nieprawidłowa procedura obsługi parametrów, zgodnie z opisem w temacie Walidacja parametru. Jeśli wykonanie może kontynuować, ta funkcja ustawia errno EINVAL wartość i zwraca wartość -1.

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

mbsrtowcs Funkcja jest bezpieczna wielowątkowość, o ile funkcja w bieżącym wątku nie wywołuje setlocale tak długo, jak ta funkcja jest wykonywana, a mbstate argument nie jest wskaźnikiem null.

Wymagania

Procedura	Wymagany nagłówek
mbsrtowcs	<wchar.h>

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit