Definito nell'intestazione
(1)
size_tmbsrtowcs(wchar_t* dst,constchar** src,size_t len,mbstate_t* ps );
(dal C95)
size_tmbsrtowcs(wchar_t*restrict dst,constchar**restrict src,size_t len,mbstate_t*restrict ps);
(dal C99)
errno_tmbsrtowcs_s(size_t*restrict retval,wchar_t*restrict dst,rsize_t dstsz,constchar**restrict src,rsize_t len,mbstate_t*restrict ps);
(2) (da C11)

1) Converte una sequenza di caratteri multibyte a terminazione nulla, che inizia nello stato di conversione descritto da *psdall'array il cui primo elemento è puntato da *src alla sua rappresentazione in caratteri larghi. Se dst non è nullo, i caratteri convertiti vengono memorizzati negli elementi successivi dell'array wchar_t puntato da dst. Non più di len vengono scritti nell'array di destinazione. Ogni carattere multibyte viene convertito come se fosse una chiamata a mbrtowc. La conversione si interrompe se:
* Il carattere multibyte nullo è stato convertito e memorizzato. *src è impostato su NULL e *ps rappresenta lo stato di spostamento iniziale.
* È stato riscontrato un carattere multibyte non valido (secondo il locale C corrente). *src è impostato per puntare all'inizio del primo carattere multibyte non convertito.
* Il prossimo carattere largo da memorizzare supererebbe il valore di len. *src è impostato sul punto di inizio del primo carattere multibyte non convertito. Questa condizione non viene verificata se dst==NULL.2) Uguale a (1), tranne per il fatto che
* la funzione restituisce il suo risultato come parametro esterno retval
* se nessun carattere nullo è stato scritto in dst dopo len sono stati scritti caratteri larghi, allora L'' viene memorizzato in dst[len], il che significa che sono stati scritti len+1 caratteri larghi in totale
* La funzione blocca l'array di destinazione a partire dal null terminante e fino a quando dstsz
* Se src e dst si sovrappongono, il comportamento non è specificato.
* I seguenti errori vengono rilevati in fase di esecuzione e chiamano la funzione di gestione dei vincoli attualmente installata:

  • retval, ps, srco *src è un puntatore nullo
  • dstsz o len è maggiore di RSIZE_MAX/sizeof(wchar_t) (a meno che dst è nullo)
  • dstsz non è zero (a meno che dst è nullo)
  • Non c'è nessun carattere nullo nel primo dstsz caratteri multibyte nel campo *src e len è maggiore di dstsz (a meno che dst è nullo)
Come per tutte le funzioni con controllo dei limiti, mbsrtowcs_s è garantita solo se __STDC_LIB_EXT1__ è definito dall'implementazione e se l'utente definisce __STDC_WANT_LIB_EXT1__ alla costante intera 1 prima di includere wchar.h.

Parametri

dst - puntatore a un array di caratteri ampio in cui saranno memorizzati i risultati
src - puntatore al primo elemento di una stringa multibyte null-terminata
len - numero di caratteri larghi disponibili nell'array puntato da dst
ps - puntatore all'oggetto stato di conversione
dstsz - numero massimo di caratteri wide che verranno scritti (dimensione dell'oggetto dst )
retval - puntatore a un oggetto size_t in cui il risultato sarà memorizzato

Valore di ritorno

1) In caso di successo, restituisce il numero di caratteri larghi, escluso il carattere di terminazione L''scritti nell'array di caratteri. Se dst==NULLrestituisce il numero di caratteri larghi che sarebbero stati scritti se la lunghezza fosse stata illimitata. In caso di errore di conversione (se è stato incontrato un carattere multibyte non valido), restituisce (size_t)-1e memorizza EILSEQ in errnoe lascia *ps in uno stato non specificato.2) zero in caso di successo (nel qual caso il numero di caratteri larghi, escluso lo zero finale, che sono stati o sarebbero stati scritti su dstè memorizzato in *retval), non zero in caso di errore. In caso di violazione dei vincoli di runtime, viene memorizzato il valore (size_t)-1 in *retval (a meno che retval è nullo) e imposta dst[0] a L'' (a meno che dst sia nullo o dstmax sia zero o maggiore di RSIZE_MAX)

Esempio

#include#include#include#includevoidprint_as_wide(constchar* mbstr){mbstate_t state;memset(&state,0,sizeof state);size_t len =1+mbsrtowcs(NULL,&mbstr,0,&state);wchar_t wstr[len];mbsrtowcs(&wstr[0],&mbstr, len,&state);wprintf(L"Wide string: %ls n", wstr);wprintf(L"The length, including L'\0': %zun", len);}intmain(void){setlocale(LC_ALL,"en_US.utf8");print_as_wide(u8"zu00dfu6c34U0001f34c");// u8"zß水🍌"}

Uscita:

Wide string: zß水🍌
The length, including L'':5

Riferimenti

  • Norma C11 (ISO/IEC 9899:2011):
    • 7.29.6.4.1 La funzione mbsrtowcs (p: 445)
    • K.3.9.3.2.1 La funzione mbsrtowcs_s (p: 648-649)
  • Standard C99 (ISO/IEC 9899:1999):
    • 7.24.6.4.1 La funzione mbsrtowcs (p: 391)

Vedi anche

mbstowcsmbstowcs_s(C11) converte una stringa di caratteri multibyte stretta in stringa larga
(funzione)
mbrtowc(C95) converte il prossimo carattere multibyte in carattere largo, dato lo stato
(funzione)
wcsrtombswcsrtombs_s(C95)(C11) converte una stringa larga in una stringa stretta di caratteri multibyte, dato lo stato
(funzione)