Converts a multibyte character to its wide-character
    representation.

    Format

      #include  <wchar.h>

      size_t mbrtowc  (wchar_t *pwc, const char *s, size_t n,
                      mbstate_t *ps);

1  –  Arguments

 pwc

    A pointer to the resulting wide-character code.

 s

    A pointer to a multibyte character.

 n

    The maximum number of bytes that comprise the multibyte
    character.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

2  –  Description

    If s is a NULL pointer, mbrtowc is equivalent to the call:

        mbrtowc(NULL, "", 1, ps)

    In this case, the values of pwc and n are ignored.

    If s is not a NULL pointer, mbrtowc inspects at most n bytes
    beginning with the byte pointed to by s to determine the
    number of bytes needed to complete the next multibyte character
    (including any shift sequences).

    If the function determines that the next multibyte character
    is completed, it determines the value of the corresponding wide
    character and then, if pwc is not a NULL pointer, stores that
    value in the object pointed to by pwc. If the corresponding
    wide character is the null wide character, the resulting state
    described is the initial conversion state.

    If mbrtowc is called as a counting function, which means that pwc
    is a NULL pointer and s is neither a NULL pointer nor a pointer
    to a null byte, the value of the internal mbstate_t object will
    remain unchanged.

3  –  Return Values

    x                  The number of bytes comprising the multibyte
                       character.
    0                  The next n or fewer bytes complete the
                       multibyte character that corresponds to the
                       null wide character (which is the value stored
                       if pwc is not a NULL pointer). The wide-
                       character code corresponding to a null byte
                       is zero.
    -1                 Indicates an encoding error. The next n or
                       fewer bytes do not contribute to a complete
                       and valid multibyte character. errno is set to
                       EILSEQ. The conversion state is undefined.
    -2                 Indicates an incomplete but potentially valid
                       multibyte character (all n bytes have been
                       processed).