MBTOWC - convert multibyte character to wide character.

(ANSI Standard)

Usage:

#include <stdlib.h>
length = mbtowc(wc,mb,N);

Where:

wchar_t *wc;
is a null pointer or a pointer to a region of memory where the wide character may be stored.
const char *mb;
is a null pointer or a pointer to a string that contains a multibyte character.
size_t N;
gives a length, in bytes.
int length;
is typically the length of the converted multibyte character (but see below).

Description:

The "mbtowc" function converts the multibyte character beginning at "mb" into a wide character and stores the wide character in the location indicated by "wc". Multibyte and wide characters are interpreted according to current locale conventions.

At most, "mbtowc" only looks at the first N bytes of "mb". If "mb" does not begin with a valid multibyte character whose length is less than or equal to N, "mbtowc" returns -1. Otherwise, "mbtowc" will return the number of bytes in the multibyte character that was converted. This could be zero, if the string begins with '\0'. The result will always be less than or equal to N and to MB_CUR_MAX.

If "wc" is null, "mbtowc" simply returns the length of the first multibyte character in the first N bytes of "mb". It returns -1 if these bytes do not contain a valid multibyte character. Thus, with a null "wc", "mbtowc" behaves like "mblen".

If the "mb" argument is a null pointer, "mbtowc" returns 0 if multibyte characters do not have shift-dependencies, and a non-zero value otherwise. In this case, "mbtowc" does not change the value of "*wc".

NOTE: if the current locale has shift dependencies, "mbtowc" keeps track of the current shift state. Calling "mbtowc" with a null pointer for "mb" puts "mbtowc" into the initial shift state. Otherwise, the function will start out in whatever shift state it had at the end of the previous call.

See Also:

expl nsc lib mblen

expl nsc lib mbstowcs

expl nsc lib wcstombs

expl nsc lib wctomb

Copyright © 1996, Thinkage Ltd.