mbrlen

Déterminer le nombre d'octets requis pour terminer un caractère multioctet dans les paramètres régionaux actuels, avec la capacité de redémarrer au milieu d'un caractère multioctet.

Syntaxe

size_t mbrlen(
   const char * str,
   size_t count,
   mbstate_t * mbstate
);

Paramètres

str
Pointeur vers l'octet suivant à examiner dans une chaîne de caractères multioctets.

count
Nombre maximal d'octets à examiner.

mbstate
Pointeur vers l'état du décalage actuel de l'octet initial de str.

Valeur retournée

L’une des valeurs suivantes :

Value	Description
0	Les count (ou moins) octets suivants terminent le caractère multioctet qui représente le caractère null large.
1 à count, inclusivement	Les count (ou moins) octets suivants terminent un caractère multioctet valide. La valeur retournée est le nombre d'octets qui terminent le caractère multioctet.
(size_t)(-2)	Les count octets suivants contribuent à un caractère multioctets incomplet mais potentiellement valide, et tous les count octets ont été traités.
(size_t)(-1)	Une erreur d'encodage s'est produite. Les octets suivants count ou moins ne contribuent pas à un caractère multioctet complet et valide. Dans ce cas, errno est défini à EILSEQ et l'état de la conversion dans mbstate n'est pas spécifié.

Notes

La fonction mbrlen examine au plus count octets à partir de l'octet pointé par str pour déterminer le nombre d'octets qui sont nécessaires pour terminer le caractère multioctet suivant, y compris les séquences de décalage. Il équivaut à l’appel mbrtowc(NULL, str, count, &mbstate) où mbstate est un objet fourni par mbstate_t l’utilisateur ou un objet interne statique fourni par la bibliothèque.

La fonction mbrlen enregistre et utilise l'état du décalage d'un caractère multioctet incomplet dans le paramètre mbstate. C’est pourquoi ***mbrlen** peut redémarrer au milieu d’un caractère multioctet, si nécessaire, et examiner au maximum count les octets. Si mbstate est un pointeur null, mbrlen utilise un objet mbstate_t statique interne pour stocker l'état du décalage. Étant donné que l’objet interne mbstate_t n’est pas thread-safe, nous vous recommandons d’allouer et de transmettre toujours votre propre mbstate paramètre.

La mbrlen fonction diffère de _mbclen, mblen_mblen_l par sa capacité de redémarrage. L'état du décalage est stocké dans mbstate pour les appels suivants à la même ou à d'autres fonctions redémarrables. Les résultats ne sont pas définis quand l'utilisation de fonctions redémarrables est combinée avec l'utilisation de fonctions non redémarrables. Par exemple, une application doit utiliser wcsrlen au lieu de wcslen si un appel ultérieur à wcsrtombs est utilisé à la place de wcstombs

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

Mappages de routine de texte générique

Routine TCHAR.H	_UNICODE et _MBCS non défini	_MBCS Défini	_UNICODE Défini
Non applicable	Non applicable	mbrlen	Non applicable

Spécifications

Routine	En-tête requis
mbrlen	<wchar.h>

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

Exemple

Cet exemple montre comment l'interprétation des caractères multioctets dépend de la page de codes actuelle et montre la capacité de reprise de mbrlen.

// crt_mbrlen.c
// Compile by using: cl crt_mbrlen.c
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <locale.h>
#include <wchar.h>

size_t Example(const char * pStr)
{
    size_t      charLen = 0;
    size_t      charCount = 0;
    mbstate_t   mbState = {0};

    while ((charLen = mbrlen(pStr++, 1, &mbState)) != 0 &&
            charLen != (size_t)-1)
    {
        if (charLen != (size_t)-2) // if complete mbcs char,
        {
            charCount++;
        }
    }
    return (charCount);
}

int main( void )
{
    int         cp;
    size_t      charCount = 0;
    const char  *pSample =
        "\x82\xD0\x82\xE7\x82\xAA\x82\xC8: Shift-jis hiragana.";

    cp = _getmbcp();
    charCount = Example(pSample);
    printf("\nCode page: %d\n%s\nCharacter count: %d\n",
        cp, pSample, charCount);

    setlocale(LC_ALL, "ja-JP"); // Set Japanese locale
    _setmbcp(932); // and Japanese multibyte code page
    cp = _getmbcp();
    charCount = Example(pSample);
    printf("\nCode page: %d\n%s\nCharacter count: %d\n",
        cp, pSample, charCount);
}

Code page: 0
é╨éτé¬é╚: Shift-jis hiragana.
Character count: 29

Code page: 932
????: Shift-jis hiragana.
Character count: 25

Voir aussi

Manipulation de chaîne
Paramètres régionaux