Definito nell'intestazione
(1)
size_twcsrtombs(char*dst,constwchar_t**src,size_t len,mbstate_t* ps );
(dal C95)
size_twcsrtombs(char*restrict dst,constwchar_t**restrict src,size_t len,mbstate_t*restrict ps);
(dal C99)
errno_twcsrtombs_s(size_t*restrict retval,char*restrict dst,rsize_t dstsz,constwchar_t**restrict src,rsize_t len,mbstate_t*restrict ps);
(2) (da C11)

1) Converte una sequenza di caratteri larghi dall'array il cui primo elemento è puntato da *src alla sua rappresentazione multibyte stretta che inizia nello stato di conversione descritto da *ps. Se dst non è nullo, i caratteri convertiti vengono memorizzati negli elementi successivi dell'array di caratteri puntato da dst. Non più di len vengono scritti nell'array di destinazione.
Ogni carattere viene convertito come se fosse una chiamata a wcrtomb. La conversione si interrompe se:
* Il carattere nullo L'' è stato convertito e memorizzato. I byte memorizzati in questo caso sono la sequenza unshift (se necessario) seguita da '', *src è impostato su NULL e *ps rappresenta lo stato di spostamento iniziale.
* A wchar_t che non corrisponde a un carattere valido nel locale C corrente. *src è impostato per puntare al primo carattere largo non convertito.
* il prossimo carattere multibyte da memorizzare supererebbe il limite di len. *src è impostato per puntare al primo carattere largo 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 la conversione si interrompe senza scrivere un carattere nullo, la funzione memorizzerà '' nel byte successivo in dstche può essere dst[len] o dst[dstsz], a seconda di quale sia il primo (il che significa che possono essere scritti fino a len+1/dstsz+1 byte totali). In questo caso, non può essere scritta alcuna sequenza unshift prima del null finale.
* la funzione taglia l'array di destinazione a partire dal null di terminazione 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 (a meno che dst è nullo)
  • dstsz non è zero (a meno che dst è nullo)
  • len è maggiore di dstsz e la conversione non incontra errori di codifica o nullità nel parametro src entro il momento in cui dstsz (a meno che dst sia nullo)
Come per tutte le funzioni con controllo dei limiti, wcsrtombs_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 stretto in cui saranno memorizzati i caratteri multibyte
src - puntatore al primo elemento di una stringa larga a terminazione nulla
len - numero di byte disponibili nell'array puntato da dst
ps - puntatore all'oggetto stato di conversione
dstsz - numero massimo di byte che verranno scritti (dimensione dell'oggetto dst array)
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 byte (comprese le sequenze di spostamento, ma esclusa la terminazione '') scritti nell'array di caratteri il cui primo elemento è puntato da dst. Se dst==NULLrestituisce il numero di byte che sarebbero stati scritti. In caso di errore di conversione (se è stato incontrato un carattere largo non valido), restituisce (size_t)-1e memorizza EILSEQ in errnoe lascia *ps in uno stato non specificato.2) Restituisce zero in caso di successo (nel qual caso il numero di byte, 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 di un vincolo di esecuzione, memorizza (size_t)-1 in *retval (a meno che retval è nullo) e imposta dst[0] a '' (a meno che dst sia nullo o dstmax sia zero o maggiore di RSIZE_MAX)

Esempio

#include#include#include#includevoidprint_wide(constwchar_t* wstr){mbstate_t state;memset(&state,0,sizeof state);size_t len =1+wcsrtombs(NULL,&wstr,0,&state);char mbstr[len];wcsrtombs(mbstr,&wstr, len,&state);printf("Multibyte string: %sn", mbstr);printf("Length, including '\0': %zun", len);}intmain(void){setlocale(LC_ALL,"en_US.utf8");print_wide(L"zu00dfu6c34U0001f34c");// or L"zß水🍌"}

Uscita:

Multibyte string: zß水🍌
Length, including '':11

Riferimenti

  • Norma C11 (ISO/IEC 9899:2011):
    • 7.29.6.4.2 La funzione wcsrtombs (p: 446)
    • K.3.9.3.2.2 La funzione wcsrtombs_s (p: 649-651)
  • Standard C99 (ISO/IEC 9899:1999):
    • 7.24.6.4.2 La funzione wcsrtombs (p: 392)

Vedi anche

wcstombswcstombs_s(C11) converte una stringa larga in una stringa stretta di caratteri multibyte
(funzione)
wcrtombwcrtomb_s(C95)(C11) converte un carattere largo nella sua rappresentazione multibyte, dato lo stato
(funzione)
mbsrtowcsmbsrtowcs_s(C95)(C11) converte una stringa di caratteri multibyte stretta in stringa larga, dato lo stato
(funzione)