Definito nell'intestazione
(1)
size_twcrtomb(char*s,wchar_t wc,mbstate_t*ps);
(dal C95)
size_twcrtomb(char*restrict s,wchar_t wc,mbstate_t*restrict ps);
(dal C99)
errno_twcrtomb_s(size_t*restrict retval,char*restrict s,rsize_t ssz,wchar_t wc,mbstate_t*restrict ps);
(2) (da C11)

Converte un carattere largo nella sua rappresentazione multibyte stretta.

1) Se s non è un puntatore nullo, la funzione determina il numero di byte necessari per memorizzare la rappresentazione del carattere multibyte di wc (comprese eventuali sequenze di spostamento e tenendo conto dello stato attuale di conversione multibyte *ps) e memorizza la rappresentazione multibyte del carattere nell'array di caratteri il cui primo elemento è puntato da saggiornando *ps se necessario. Al massimo MB_CUR_MAX byte possono essere scritti da questa funzione.
Se s è un puntatore nullo, la chiamata è equivalente a wcrtomb(buf, L'', ps) per un buffer interno buf.
Se wc è il carattere largo nullo L''viene memorizzato un byte nullo, preceduto da qualsiasi sequenza di spostamento necessaria per ripristinare lo stato di spostamento iniziale e il parametro di stato di conversione *ps viene aggiornato per rappresentare lo stato di spostamento iniziale.
Se la macro ambiente __STDC_ISO_10646__ è definita, i valori del tipo wchar_t corrispondono agli identificatori brevi dei caratteri nell'insieme Unicode richiesto (tipicamente la codifica UTF-32); altrimenti, sono definiti dall'implementazione. In ogni caso, la codifica dei caratteri multibyte utilizzata da questa funzione è specificata dal locale C attualmente attivo.2) Uguale a (1) tranne che per il fatto che
se s è un puntatore nullo, la chiamata è equivalente a wcrtomb_s(&retval, buf, sizeof buf, L'', ps) con le variabili interne retval e buf (la cui dimensione è maggiore di MB_CUR_MAX)
il risultato viene restituito nel parametro di uscita retval
i seguenti errori vengono rilevati in fase di esecuzione e chiamano la funzione di gestione dei vincoli attualmente installata:

  • retval o ps è un puntatore nullo.
  • ssz è zero o maggiore di RSIZE_MAX (a meno che s è nullo)
  • ssz è inferiore al numero di byte che verrebbero scritti (a meno che s è nullo)
  • s è un puntatore nullo ma ssz non è nullo
Come per tutte le funzioni con controllo dei limiti, wcrtomb_s è garantito 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

s - puntatore a un array di caratteri stretto in cui sarà memorizzato il carattere multibyte
wc - il carattere largo da convertire
ps - puntatore all'oggetto di stato di conversione utilizzato durante l'interpretazione della stringa multibyte
ssz - numero massimo di byte da scrivere (la dimensione del buffer) s)
retval - puntatore a un parametro di uscita in cui sarà memorizzato il risultato (numero di byte nella stringa multibyte, comprese eventuali sequenze di spostamento)

Valore di ritorno

1) In caso di successo, restituisce il numero di byte (comprese eventuali sequenze di spostamento) scritti nell'array di caratteri il cui primo elemento è puntato da s.
In caso di fallimento (se wc non è un carattere largo valido), restituisce (size_t)-1e memorizza EILSEQ in errnoe lascia *ps in uno stato non specificato.2) Restituisce zero in caso di successo e non zero in caso di fallimento, nel qual caso, s[0] è impostato su '' (a meno che s sia nullo o ssz sia zero o maggiore di RSIZE_MAX) e *retval è impostato su (size_t)-1 (a meno che retval è nullo)

Esempio

#include#include#include#include#includeintmain(void){setlocale(LC_ALL,"en_US.utf8");mbstate_t state;memset(&state,0,sizeof state);wchar_t in[]= L"zß水🍌";// or "zu00dfu6c34U0001F34C"size_t in_sz =sizeof in /sizeof*in;printf("Processing %zu wchar_t units: [ ", in_sz);for(size_t n =0; n < in_sz;++n)printf("%#x ",(unsignedint)in[n]);puts("]");char out[MB_CUR_MAX * in_sz];char*p = out;for(size_t n =0; n < in_sz;++n){int rc =wcrtomb(p, in[n],&state);if(rc ==-1)break;
        p += rc;}size_t out_sz = p - out;printf("into %zu UTF-8 code units: [ ", out_sz);for(size_t x =0; x < out_sz;++x)printf("%#x ",+(unsignedchar)out[x]);puts("]");}

Uscita:

Processing 5wchar_t units:[0x7a0xdf0x6c340x1f34c0]
into 11 UTF-8 code units:[0x7a0xc30x9f0xe60xb00xb40xf00x9f0x8d0x8c0]

Riferimenti

  • Norma C11 (ISO/IEC 9899:2011):
    • 7.29.6.3.3 La funzione wcrtomb (p: 444)
    • K.3.9.3.1.1 La funzione wcrtomb_s (p: 647-648)
  • Standard C99 (ISO/IEC 9899:1999):
    • 7.24.6.3.3 La funzione wcrtomb (p: 390)

Vedi anche

wctombwctomb_s(C11) converte un carattere largo nella sua rappresentazione multibyte
(funzione)
mbrtowc(C95) converte il prossimo carattere multibyte in carattere largo, dato lo stato
(funzione)