`mbrlen`

Articolo
10/12/2023

Determina il numero di byte necessari per completare un carattere multibyte nelle impostazioni locali correnti, con la possibilità di ricominciare nel mezzo di un carattere multibyte.

Sintassi

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

Parametri

str
Puntatore al byte successivo da controllare in una stringa di caratteri multibyte.

count
Numero massimo di byte da controllare.

mbstate
Puntatore allo stato di spostamento corrente del byte iniziale di str.

Valore restituito

Uno dei valori seguenti:

valore	Descrizione
0	I successivi `count` byte o un numero inferiore completano il carattere multibyte che rappresenta il carattere wide Null.
Da 1 a `count` incluso	I successivi `count` byte o un numero inferiore completano un carattere multibyte valido. Il valore restituito è il numero di byte che completa il carattere multibyte.
(size_t)(-2)	I successivi `count` byte contribuiscono a un carattere multibyte incompleto ma potenzialmente valido e tutti i `count` byte sono stati elaborati.
(size_t)(-1)	Si è verificato un errore di codifica. I byte successivi `count` o minori non contribuiscono a un carattere multibyte completo e valido. In tal caso, `errno` viene impostato su EILSEQ e non viene specificato lo stato di conversione in `mbstate`.

Osservazioni:

La funzione mbrlen controlla al massimo count byte a partire dal byte a cui punta str per determinare il numero di byte necessari per completare il carattere multibyte successivo, comprese tutte le sequenze di spostamento. Equivale alla chiamata mbrtowc(NULL, str, count, &mbstate) in cui mbstate è un oggetto fornito dall'utente mbstate_t o un oggetto interno statico fornito dalla libreria.

La funzione mbrlen salva e usa lo stato di spostamento di un carattere multibyte incompleto nel parametro mbstate. È per questo che **mbrlen**può essere riavviato al centro di un carattere multibyte, se necessario, ed esaminare al massimo count i byte. Se mbstate è un puntatore Null, mbrlen usa un oggetto mbstate_t interno statico per archiviare lo stato di spostamento. Poiché l'oggetto interno mbstate_t non è thread-safe, è consigliabile allocare e passare sempre il proprio mbstate parametro.

La mbrlen funzione differisce da _mbclen, mblen, _mblen_l in base alla riavviibilità. Lo stato di spostamento viene archiviato in mbstate per le chiamate successive alle stesse o ad altre funzioni riavviabili. I risultati non sono definiti quando si usano insieme funzioni riavviabili e non riavviabili. Ad esempio, un'applicazione deve usare wcsrlen anziché wcslen se viene usata una chiamata successiva a wcsrtombs anziché wcstombs.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

Routine TCHAR.H	`_UNICODE` e `_MBCS` non definito	`_MBCS` definito	`_UNICODE` definito
non applicabile	non applicabile	`mbrlen`	non applicabile

Requisiti

Ciclo	Intestazione obbligatoria
`mbrlen`	<wchar.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

Questo esempio mostra come l'interpretazione dei caratteri multibyte dipende dalla tabella codici corrente e illustra la possibilità di ripresa di 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

Vedi anche

Manipolazione delle stringhe
impostazioni locali

Condividi tramite