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 :

Valeur	Condition
0	Les max_bytes (ou moins) caractères suivants convertis à partir de source correspondent au caractère large null, qui est la valeur stockée si destination n’est pas null. state contient l’état de décalage initial.
Entre 1 et max_bytes, inclusif	La valeur retournée est le nombre d’octets de source qui terminent un caractère multioctet valide. Les caractères larges convertis sont stockés si destination n’est pas null.
-3	Le caractère large suivant résultant d’un appel précédent à la fonction a été stocké dans destination si destination n’est pas null. Aucun octet de source n’est utilisé par cet appel à la fonction. Lorsque source pointe vers un caractère multioctet UTF-8 dont la représentation nécessite plusieurs caractères larges (par exemple une paire de substitution), la valeur state est mise à jour pour que l’appel de fonction suivant écrive le caractère supplémentaire.
-2	Les max_bytes octets suivants représentent un caractère multioctet UTF-8 incomplet, mais potentiellement valide. Aucune valeur n’est stockée dans destination. Ce résultat peut se produire si max_bytes est égal à zéro.
-1	Une erreur d’encodage s’est produite. Les max_bytes (ou moins) octets suivants ne contribuent pas à un caractère multioctet UTF-8 complet et valide. Aucune valeur n’est stockée dans destination. EILSEQ est stocké dans errno et la valeur d’état de conversion state n’est pas spécifiée.

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

Fonction	En-tête C	En-tête C++
mbrtoc16, mbrtoc32	<uchar.h>	<cuchar>

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