mbsrtowcs

Artykuł
02/27/2013

Konwertuje ciąg znaków wielobajtowych odpowiedni ciąg znaków szerokości.Bardziej bezpieczna wersja ta funkcja jest dostępna; see mbsrtowcs.

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

[out]wcstr
Wynikowy konwertowany ciąg znaków szerokości adres lokalizacji.
[w]mbstr
Pośrednio wskazuje lokalizację ciąg znaków wielobajtowych do konwersji.
[w]count
Liczba znaków do konwersji.
[w]mbstate
Wskaźnik do mbstate_t obiekt stanu konwersji.

Wartość zwracana

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

Uwagi

mbsrtowcs Funkcja konwertuje ciąg znaków wielobajtowych, począwszy od stanu określonej konwersji zawartych w mbstate, z pośrednich wartości wskazywanej w mbstr, pod adresem wcstr.Konwersja będzie nadal dla każdego znaku do: po napotkał null, kończące znaków wielobajtowych, w przypadku napotkania innych niż odpowiedni znak lub podczas następnego znaku mogłaby przekroczyć limit, zawartych w count.Jeśli mbsrtowcs napotka wielobajtowych znaków null (\0), przed lub po count występuje konwertuje ją na null 16-bitowe, kończącego znaku i zatrzymuje.

W ten sposób, ciąg znaków szerokości na wcstr jest zakończony zerem tylko wtedy, gdy mbsrtowcs napotka wielobajtowych znaków null podczas konwersji.Jeśli sekwencji wskazywanej przez mbstr i wcstr nachodzą na siebie, zachowanie mbsrtowcs jest niezdefiniowane.mbsrtowcsdotyczy kategorii LC_TYPE bieżące ustawienia regionalne.

mbsrtowcs Funkcja różni się od mbstowcs, _mbstowcs_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 mbsrlen zamiast mbslen, jeśli kolejne wywołania mbsrtowcs w przypadku, gdy używana zamiastmbstowcs.

Jeśli wcstr argument jest NULL, mbsrtombs zwraca wymagany rozmiar słowa 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.

Jeśli mbstr jest NULL, wywoływana jest funkcja obsługi nieprawidłowy parametr, jak opisano w Sprawdzanie poprawności parametru.Jeśli wykonanie może kontynuować, ta funkcja ustawia errno do EINVAL i zwraca wartość -1.

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

mbsrtowcs 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.