mbrtoc16, mbrtoc32

Traduit le premier caractère multioctet UTF-8 dans une chaîne en caractère équivalent UTF-16 ou UTF-32.

Syntaxe

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

Paramètres

destination
Pointeur vers le char16_t ou char32_t équivalent du caractère multioctet UTF-8 à convertir. Si vous spécifiez la valeur null, la fonction ne stocke pas de valeur.

source
Pointeur vers la chaîne de caractères multioctets UTF-8 à convertir.

max_bytes
Nombre maximal d’octets dans source à examiner pour rechercher un caractère à convertir. La valeur de cet argument doit être comprise entre 1 et le nombre d’octets, y compris toute marque de fin null, restant dans source.

state
Pointeur vers un objet d’état de conversion mbstate_t utilisé pour interpréter la chaîne multioctets UTF-8 à un ou plusieurs caractères de sortie.

Valeur retournée

En cas de réussite, retourne la valeur de la première de ces conditions qui s’applique, étant donné la valeur state actuelle :

Notes

La fonction mbrtoc16 lit jusqu’à max_bytes octets à partir de source pour rechercher le premier caractère multioctet UTF-8 complet et valide, puis elle stocke le caractère UTF-16 équivalent dans destination. Si le caractère nécessite plusieurs caractères de sortie UTF-16, par exemple s’il s’agit d’une paire de substitution, la valeur state stocke le caractère UTF-16 suivant dans destination lors du prochain appel à mbrtoc16. La fonction mbrtoc32 est identique, mais la sortie est stockée comme caractère UTF-32.

Si source est null, ces fonctions retournent l’équivalent d’un appel effectué à l’aide des arguments NULL pour destination, "" (une chaîne vide finissant par une valeur null) pour source et 1 pour max_bytes. Les valeurs passées de destination et max_bytes sont ignorées.

Si source n’est pas null, la fonction commence au début de la chaîne et elle inspecte jusqu’à max_bytes octets pour déterminer le nombre d’octets nécessaires pour terminer le caractère multioctet UTF-8 suivant, y compris les séquences de décalage. Si les octets examinés contiennent un caractère multioctet UTF-8 valide et complet, la fonction convertit le caractère en caractères larges 16 bits ou 32 bits équivalents. Si destination n’est pas null, la fonction stocke le premier (et éventuellement unique) caractère résultant dans la destination. Si des caractères de sortie supplémentaires sont nécessaires, une valeur est définie dans state. Ainsi, les appels suivants à la fonction génèrent les caractères supplémentaires et retournent la valeur -3. Si aucun autre caractère de sortie n’est nécessaire, state est définie à l’état de décalage initial.

Pour convertir des caractères multioctets non UTF-8 en caractères UTF-16 LE, utilisez les fonctions mbrtowc, mbtowc ou _mbtowc_l.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Spécifications

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Voir aussi

Conversion de données
Paramètres régionaux
Interprétation des séquences de caractères multioctets
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s