6.23.16 mbrlen Function

Determines the length of a multibyte character.

Include

<wchar.h>

Prototype

size_t mbrlen(const char * restrict s, size_t n, mbstate_t * restrict ps);

Arguments

s

a pointer to the multibyte character to check

n

the maximum number of bytes to check

ps

a pointer to a mbstate_t object that holds the current conversion state

Return Value

The function returns the length of a multibyte sequence between 0 and n inclusive, representing the length; or the value -1 or -2, as per the mbrtowc() function. nonzero if ps is a null pointer or if the pointed-to object describes an initial conversion state; otherwise, it returns zero.

Remarks

An object of type mbstate_t is used to describe the current conversion state from a particular multibyte character sequence to a wide character sequence (or the reverse conversion) based on the current locale. For both conversions, the initial conversion state corresponds to the beginning of a new multibyte character in the initial shift state. A zero-valued mbstate_t always represents an initial conversion state.

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

#include <wchar.h>
#include <stdlib.h>
#include <string.h>

int main(void)
{
  char * string = "The final frontier";
  mbstate_t state = {0};
  wchar_t   wc;

  mbrtowc(&wc, string, MB_CUR_MAX, &state);
  if(mbsinit(&state))                 // check initial conversion state
    wprintf(L"In initial conversion state\n");
  else
    memset(&state, 0, sizeof(state));   // set initial conversion state
}

Example Output

In initial conversion state