mbrtoc16, mbrtoc32

  • Articolo

Converte il primo carattere multibyte UTF-8 in una stringa nel carattere UTF-16 o UTF-32 equivalente.

Sintassi

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
);

Parametri

destination
Puntatore all'oggetto char16_t o char32_t equivalente del carattere multibyte UTF-8 da convertire. Se null, la funzione non archivia un valore.

source
Puntatore alla stringa di caratteri multibyte UTF-8 da convertire.

max_bytes
Numero massimo di byte in source da esaminare per un carattere da convertire. Questo argomento deve essere un valore compreso tra uno e il numero di byte, incluso qualsiasi carattere di terminazione Null, rimanente in source.

state
Puntatore a un mbstate_t oggetto stato di conversione usato per interpretare la stringa multibyte UTF-8 in uno o più caratteri di output.

Valore restituito

In caso di esito positivo, restituisce il valore della prima di tali condizioni che si applica, dato il corrente valore state :

Valore Condizione
0 I caratteri successivi max_bytes o minori convertiti da source corrispondono al carattere wide Null, ovvero il valore archiviato se destination non è Null.

state contiene lo stato iniziale di spostamento.
Tra 1 e max_bytes, inclusi Il valore restituito è il numero di byte di source che completa un carattere multibyte valido. Il carattere wide convertito viene archiviato se destination non è Null.
-3 Il carattere wide successivo risultante da una chiamata precedente alla funzione è stato archiviato in destination se destination non è Null. Nessun byte da source viene utilizzato da questa chiamata alla funzione.

Quando source punta a un carattere multibyte UTF-8 che richiede più caratteri wide per rappresentare (ad esempio, una coppia di surrogati), il state valore viene aggiornato in modo che la chiamata di funzione successiva scriva il carattere aggiuntivo.
-2 I byte successivi max_bytes rappresentano un carattere multibyte UTF-8 incompleto, ma potenzialmente valido. Nessun valore viene archiviato in destination. Questo risultato può verificarsi se max_bytes è zero.
-1 Si è verificato un errore di codifica. I byte successivi max_bytes o minori non contribuiscono a un carattere multibyte UTF-8 completo e valido. Nessun valore viene archiviato in destination.

EILSEQ viene archiviato in errno e il valore state dello stato di conversione non è specificato.

Osservazioni:

La mbrtoc16 funzione legge fino a max_bytes byte da source per trovare il primo carattere multibyte UTF-8 valido e quindi archivia il carattere UTF-16 equivalente in destination. Se il carattere richiede più di un carattere di output UTF-16, ad esempio una coppia di surrogati, il state valore viene impostato per archiviare il carattere UTF-16 successivo nella destination chiamata successiva a mbrtoc16. La funzione mbrtoc32 è identica, ma l'output viene archiviato come carattere UTF-32.

Se source è Null, queste funzioni restituiscono l'equivalente di una chiamata effettuata usando argomenti di NULL per destination, "" (stringa con terminazione Null vuota) per sourcee 1 per max_bytes. I valori passati di destination e max_bytes vengono ignorati.

Se source non è Null, la funzione inizia all'inizio della stringa ed esamina fino a max_bytes byte per determinare il numero di byte necessari per completare il successivo carattere multibyte UTF-8, incluse eventuali sequenze di spostamento. Se i byte esaminati contengono un carattere multibyte UTF-8 valido e completo, la funzione converte il carattere in caratteri o caratteri a 32 bit o a 16 bit equivalenti. Se destination non è Null, la funzione archivia il primo (e possibilmente solo) carattere di risultato nella destinazione. Se sono necessari caratteri di output aggiuntivi, viene impostato un valore in state, in modo che le chiamate successive alla funzione restituiscano i caratteri aggiuntivi e restituiscono il valore -3. Se non sono più necessari caratteri di output, state viene impostato sullo stato iniziale di spostamento.

Per convertire caratteri multibyte non UTF-8 in caratteri UTF-16 LE, usare le mbrtowcfunzioni , mbtowc o _mbtowc_l .

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Requisiti

Funzione Intestazione C Intestazione C++
mbrtoc16, mbrtoc32 <uchar.h> <cuchar>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Vedi anche

Conversione dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s