mbrtoc16, mbrtoc32

Tłumaczy pierwszy znak wielobajtowy UTF-8 w ciągu na równoważny znak UTF-16 lub UTF-32.

Składnia

size_t mbrtoc16(
   char16_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

size_t mbrtoc32(
   char32_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

Parametry

destination
Wskaźnik do char16_t lub char32_t odpowiednik znaku wielobajtowego UTF-8 do konwersji. Jeśli wartość null, funkcja nie przechowuje wartości.

source
Wskaźnik do ciągu znaków wielobajtowych UTF-8 do konwersji.

max_bytes
Maksymalna liczba bajtów w source pliku do sprawdzenia, czy znak ma być konwertowany. Ten argument powinien być wartością między jedną a liczbą bajtów, w tym dowolnym separatorem wartości null, pozostałymi w sourceelememencie .

state
Wskaźnik do mbstate_t obiektu stanu konwersji używany do interpretowania ciągu wielobajtowego UTF-8 do co najmniej jednego znaku wyjściowego.

Wartość zwracana

Po powodzeniu zwraca wartość pierwszego z tych warunków, które mają zastosowanie, biorąc pod uwagę bieżącą state wartość:

Wartość	Stan
0	max_bytes Następne lub mniej znaków przekonwertowanych z source odpowiada znakowi o szerokości null, który jest wartością przechowywaną, jeśli destination nie ma wartości null. state zawiera stan początkowej zmiany.
Od 1 do max_bytes, włącznie	Zwracana wartość to liczba bajtów source , które zakończą prawidłowy znak wielobajtowy. Przekonwertowany znak szeroki jest przechowywany, jeśli destination nie ma wartości null.
–3	Następny szeroki znak wynikający z poprzedniego wywołania funkcji został zapisany, destination jeśli destination nie ma wartości null. Nie są używane żadne bajty z source tego wywołania funkcji. Gdy source wskazuje znak wielobajtowy UTF-8, który wymaga więcej niż jednego znaku szerokiego do reprezentowania (na przykład pary zastępczej), state wartość jest aktualizowana, aby następne wywołanie funkcji zapisywało dodatkowy znak.
-2	max_bytes Następne bajty reprezentują niekompletny, ale potencjalnie prawidłowy znak wielobajtowy UTF-8. Żadna wartość nie jest przechowywana w pliku destination. Ten wynik może wystąpić, jeśli max_bytes ma wartość zero.
-1	Wystąpił błąd kodowania. max_bytes Kolejne lub mniejsze bajty nie przyczyniają się do kompletnego i prawidłowego znaku wielobajtowego UTF-8. Żadna wartość nie jest przechowywana w pliku destination. EILSEQ jest przechowywany w pliku errno , a wartość state stanu konwersji jest nieokreślona.

Uwagi

Funkcja mbrtoc16 odczytuje do max_bytes bajtów, source aby znaleźć pierwszy pełny, prawidłowy znak wielobajtowy UTF-8, a następnie przechowuje odpowiedni znak UTF-16 w pliku destination. Jeśli znak wymaga więcej niż jednego znaku wyjściowego UTF-16, takiego jak para zastępcza, state wartość jest ustawiona do przechowywania następnego znaku UTF-16 w destination następnym wywołaniu metody mbrtoc16. Funkcja jest identyczna mbrtoc32 , ale dane wyjściowe są przechowywane jako znak UTF-32.

Jeśli source ma wartość null, te funkcje zwracają odpowiednik wywołania wykonanego przy użyciu argumentów NULL dla destination, "" (pusty, zakończony ciąg o wartości null) dla source, i 1 dla max_bytes. Przekazane wartości destination i max_bytes są ignorowane.

Jeśli source nie ma wartości null, funkcja rozpoczyna się na początku ciągu i sprawdza maksymalnie max_bytes bajty w celu określenia liczby bajtów wymaganych do ukończenia następnego znaku wielobajtowego UTF-8, w tym sekwencji przesunięcia. Jeśli badane bajty zawierają prawidłowy i kompletny znak wielobajtowy UTF-8, funkcja konwertuje znak na równoważny 16-bitowy lub 32-bitowy znak lub znaki. Jeśli destination nie ma wartości null, funkcja przechowuje pierwszy (i prawdopodobnie tylko) znak wyniku w miejscu docelowym. Jeśli wymagane są dodatkowe znaki wyjściowe, wartość jest ustawiona w stateelemecie , aby kolejne wywołania funkcji zwracały dodatkowe znaki i zwracały wartość -3. Jeśli nie są wymagane żadne znaki wyjściowe, state zostanie ustawiona na początkowy stan przesunięcia.

Aby przekonwertować znaki wielobajtowe inne niż UTF-8 na znaki UTF-16 LE, użyj mbrtowcfunkcji , mbtowc lub _mbtowc_l .

Domyślnie stan globalny tej funkcji jest zakresem aplikacji. Aby zmienić to zachowanie, zobacz Stan globalny w CRT.

Wymagania

Function	Nagłówek języka C	Nagłówek języka C++
mbrtoc16, mbrtoc32	<uchar.h>	<cuchar>

Aby uzyskać więcej informacji o zgodności, zobacz Zgodność.

Zobacz też

Konwersja danych
ustawienia regionalne
Interpretacja sekwencji znaków wielobajtowych
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s