C Programming/wchar.h/mbrtowc
mbrtowc() function is used for converting the multibyte character to wide character using conversion state.
mbrtowc()
[edit | edit source]Function of mbrtowc()
[edit | edit source]
mbrtowc() convert the multibyte character to wide character using conversion states
SYNOPSIS of a function mbrtowc():
[edit | edit source]#include <wchar.h>
size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);
Description of mbrtowc() function:
[edit | edit source]
Let us consider s is a Null pointer. Then mbrtowc() function can be called as:
mbrtowc(NULL, "", 1, ps);
Here value of pwc and n is ignored.
If s is not NULL, function should inspects mostly n bytes starting from where first s is pointed for the determination of number of bytes that will be needed for the completion of next character and it determines the value of corresponding wide character. And then if pwc is not a null pointer,it stored that value in the object pointed by pwc. If that corresponding wide character is wide null character then whatever is the resulting state described is the initial conversion state.
If the specified state pointer i.e. if ps is a null pointer then mbrtowc() function should use its own mbstate_t object, which shall be initialized to the initial conversion state at the starting of the program. Otherwise mbstate_t object pointed to by ps should be used to describe the current conversion state of the associated character sequence.
Parameter used:
[edit | edit source]
s:
s is used as string whose bytes are to be converted or counted.
n:
n is used for specification of maximum number of bytes for examination.
ps:
ps is the conversion state. If this is null then internal mbstate_t object is used.
Return values:
[edit | edit source]
0:
It returns 0 when the next count or fewer bytes complete the multibyte character that represent a null wide character.
>0:
It returns the value greater than zero i.e. positive value when the next count or fewer bytes complete the valid multibyte character, the value return is the number of bytes that complete the multibyte character.
-1:
It returns -1 when an encoding error occurs, i.e. the next count or fewer bytes don't contribute for complete and valid multibyte character, the errno value will be EILSEQ and the conversion state is confusing as it can be understood in more ways.
-2
It returns -2 when the next count bytes contribute to an incomplete multibyte and all count bytes have been processed.
http://pubs.opengroup.org/onlinepubs/009604499/functions/mbrtowc.html