/** @file  ../include/wchar.h

@internalComponent

*/

/** @fn  btowc(int c)

@param c

Note: This description also covers the following functions -

 wctob() 

@return   The btowc function returns the wide character converted from the single 

  byte c . If c is EOF or not a valid multibyte sequence of length 1 the function 

  returns WEOF.

  The btowc function converts a single-byte character into a corresponding 

wide character. If the character is EOF , or not valid in the initial shift state, btowc returns WEOF.

 The wctob function converts a wide character into a corresponding single-byte 

  character. If the wide character is WEOF , or not able to be represented as a single byte in the initial 

  shift state, wctob returns WEOF.

Examples:

@code

#include <wchar.h>

// Illustrates how to use btowc API

wint_t example_btowc(int c)

{

 wint_t wc = L'a';

 //  converting single byte to wide-character 

 wc = btowc(c);

 // return the character that was converted 

return (wc);

}

@endcode

@code

#include <wchar.h>

/* Illustrates how to use wctob API */

int example_wctob(void)

{

 wint_t wc = L'a';

 int c;

 /* represent a wide-char in a single byte*/

 c = wctob(wc);

 /* return the single byte */

 return(c);

}

@endcode

Limitations:

The current implementation of btowc and wctob is not affected by the LC_CTYPE category of the current locale.

It works only for UTF8 character set.

@see mbrtowc()

@see wcrtomb()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fgetwc(FILE *stream)

@param stream

Note: This description also covers the following functions -

 getwc()  getwchar() 

@return   If successful these routines return the next wide character from the stream. If the stream is at end-of-file or a read error occurs the routines 

return WEOF. The routines feof and ferror must be used to distinguish between end-of-file 

and error. If an error occurs the global variable errno is set to indicate the error. The end-of-file condition is remembered, 

even on a terminal, and all subsequent attempts to read will return WEOF until the condition is cleared with clearerr .

  The fgetwc function

obtains the next input wide character (if present) from the stream pointed at by stream, or the next character pushed back on the stream via ungetwc .

 The getwc function

acts essentially identical to fgetwc.

 The getwchar function

is equivalent to getwc with the argument stdin.

Examples:

@code

/* Illustrates how to use fgetwc API */

#include <stdio.h>

#include <wchar.h>

wint_t example_fgetwc(void)

{

 FILE *fp = NULL;

 wint_t retval;

 /* opening the input file */

 fp = fopen("input.txt","r");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

 /* Read a character from the opened file */

 retval = fgetwc(fp);

 /* Close the file open for reading */

 fclose(fp);

 /* return the character read from the file */

 return (retval);

}

@endcode

@code

/* Illustrates how to use getwc API */

#include <stdio.h>

#include <wchar.h>

wint_t example_getwc(void)

{

 FILE *fp =  NULL;

 wint_t retval;

 /* opening the input file */

 fp = fopen("input.txt","r");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

 /* Read a character from the opened file */

 retval = getwc(fp);

 /* Close the file open for reading */

 fclose(fp);

 /* return the character read from the file */

 return (retval);

}

@endcode

@code

/* Illustrates how to use getwchar API */

#include <stdio.h>

#include <wchar.h>

wint_t example_getwchar(void)

{

 wint_t retval;

 /* Read a character from standard input */

 retval = getwchar();

 /* return the character read */

 return (retval);

}

@endcode

@see ferror()

@see fopen()

@see fread()

@see getc()

@see putwc()

@see ungetwc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fgetws(wchar_t *  ws, int n, FILE *  fp)

@param ws

@param n

@param fp

@return   Upon successful completion fgetws returns ws. If end-of-file occurs before any characters are read, fgetws returns NULL and the buffer contents remain unchanged. If an error occurs fgetws returns NULL and the buffer contents are indeterminate. The fgetws function does not distinguish between end-of-file and error, 

and callers must use feof and ferror to determine which occurred.

  The fgetws function reads at most one less than the number of characters 

specified by n from the given fp and stores them in the wide character string ws. Reading stops when a newline character is found, at end-of-file or 

error. The newline, if any, is retained. If any characters are read, and there 

is no error, a '\\0' character is appended to end the string.

Examples:

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use fgetws API */

wchar_t *example_fgetws(wchar_t *buf)

{

 FILE *fp = NULL;

 wint_t retval;

 int n;

 /* for example, 10 characters to be read */

 n = 10;

 /* opening the input file */

 fp = fopen("input.txt","r");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

 /* Read characters from the opened file */

 retval = fgetws(buf, n, fp);

 /* Close the file open for reading */

 fclose(fp);

 /* return the character read from the file */

 return (buf);

}

@endcode

@see feof()

@see ferror()

@see fgets()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fputwc(wchar_t wc, FILE *stream)

@param wc

@param stream

Note: This description also covers the following functions -

 putwc()  putwchar() 

@return   The fputwc, putwc, and putwchar functions

return the wide character written.

If an error occurs, the value WEOF is returned.

  The fputwc function

writes the wide character wc to the output stream pointed to by stream.

 The putwc function

acts essentially identically to fputwc.

 The putwchar function

is identical to putwc with an output stream of stdout.

Examples:

@code

/* Illustrates how to use putwc API */

#include <stdio.h>

#include <wchar.h>

wint_t example_putwc(void)

{

 FILE *fp = NULL;

 wchar_t wc = L'a';

 wint_t rval;

 /* opening the file to write*/

 fp = fopen("input.txt","w");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

/* write a character into fp */

 rval = putwc(wc, fp);

 /* Close the file opened for writing */

 fclose(fp);

 /* return the value that was written */

 return (rval);

}

@endcode

@code

/* Illustrates how to use fputwc API */

#include <stdio.h>

#include <wchar.h>

wint_t example_fputwc(void)

{

 FILE *fp = NULL;

 wchar_t wc = L'a';

 wint_t rval;

 /* opening the file to write*/

 fp = fopen("input.txt","w");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

/* write a character into fp */

 rval = fputwc(wc, fp);

 /* Close the file opened for writing */

 fclose(fp);

 /* return the value that was written */

 return (rval);

}

@endcode

@code

/* Illustrates how to use putwchar API */

#include <stdio.h>

#include <wchar.h>

wint_t example_putwchar(void)

{

 wint_t rval;

 wchar_t wc = L'q';

 /* write a character onto the standard output */

 rval = putwchar(wc);

 /* return the character that was written */

 return (rval);

}

@endcode

 Output of putwchar

@code

q

@endcode

@see ferror()

@see fopen()

@see getwc()

@see putc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fputws(const wchar_t *  ws, FILE *  fp)

@param ws

@param fp

@return   The fputws function

returns 0 on success and -1 on error.

  The fputws function writes the wide character string pointed to by ws to the stream pointed to by fp.

Examples:

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use fputws API */

int example_fputws(wchar_t *buf)

{

 FILE *fp = NULL;

 int retval;

 /* open the file for writing*/

 fp = fopen("write.txt","r");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

 /* Write the characters into the file */

 retval = fputws(buf, fp);

 /* Close the file open for writing */

 fclose(fp);

 /* return the number of characters written */

 /* into the file */

 return (retval);

}

@endcode

@see ferror()

@see fputs()

@see putwc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fwide(FILE *stream, int mode)

@param stream

@param mode

@return   The fwide function

returns a value according to orientation after the call of fwide; a value less than zero if byte-oriented, a value greater than zero

if wide-oriented, and zero if the stream has no orientation.

  The fwide function

determines the orientation of the stream pointed at by stream.

 If the orientation of stream has already been determined fwide leaves it unchanged. Otherwise fwide sets the orientation of stream according to mode.

 If mode is less than zero stream is set to byte-oriented. If it is greater than zero stream is set to wide-oriented. Otherwise mode is zero and stream is unchanged.

Examples:

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use fwide API */

int example_fwide(void)

{

 FILE *fp = NULL;

 int retval;

 int mode;

 /* open a file */

 fp = fopen("input.txt","r");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

 /* set the mode to wide*/

 mode = 1;

 /* set the orientation of the file */

 retval = fwide(fp, mode);

 /*     check   the     return value */

 if(retval ==   1)

 {

        wprintf(L"Mode set to WIDE

");

 }

 else

 {

        wprintf(L"Error setting the mode to wide!!

");

 }

 /* set the mode to determine the orientation */

 mode = 0;

 /* Read back the orientation that was set */

 retval = fwide(fp ,mode);

 if(retval == 1)

 {

        wprintf("Mode not changed

");

 }

 else

 {

        wprintf("Error, mode changed!!

");

 }

 /* Close the file open for writing */

 fclose(fp);

 /* return the mode of fp */

 return (retval);

}

@endcode

@see ferror()

@see fgetc()

@see fgetwc()

@see fopen()

@see fputc()

@see fputwc()

@see freopen()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fwprintf(FILE *  stream, const wchar_t *  format, ...)

@param stream

@param format

@param ...

Note: This description also covers the following functions -

 swprintf()  snwprintf()  vsnwprintf()  wprintf()  vfwprintf()  vswprintf()  vwprintf() 

@return   The functions return the number of wide characters written, excluding the terminating null wide character in case of the functions swprintf , snwprintf , vswprintf and vsnwprintf . They return -1 when an error occurs.

The wprintf family of functions produces output according to a format as described below. The wprintf and vwprintf functions write output to stdout, the standard output stream; fwprintf and vfwprintf write output to the given output stream; swprintf , snwprintf , vswprintf and vsnwprintf write to the wide character string ws. 

These functions write the output under the control of a format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of stdarg) are converted for output. 

These functions return the number of characters printed (not including the trailing ‘\\0’ used to end output to strings). 

The swprintf , snwprintf , vswprintf and vsnwprintf functions will fail if n or more wide characters were requested to be written. 

@code

Note : 

1. swprintf and snwprintf can be used interchangeably. 

2. vswprintf and vsnwprintf can be used interchangeably. 

The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the % character. The arguments must correspond properly (after type promotion) with the conversion specifier. After the %, the following appear in sequence: 

@endcode

@code

An optional field, consisting of a decimal digit string followed by a $, specifying the next argument to access. If this field is not provided, the argument following the last argument accessed will be used. Arguments are numbered starting at 1. If unaccessed arguments in the format string are interspersed with ones that are accessed the results will be indeterminate. 

Zero or more of the following flags:

 '#'  The value should be converted to an "alternate form". For c, d, i, n, p, s, and u conversions, this option has no effect. For o conversions, the precision of the number is increased to force the first character of the output string to a zero (except if a zero value is printed with an explicit precision of zero). For x and X conversions, a non-zero result has the string ‘0x’ (or ‘0X’ for X conversions) prepended to it. For a, A, e, E, f, F, g, and G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For g and G conversions, trailing zeros are not removed from the result as they would otherwise be.  

'0(zero)'  Zero padding. For all conversions except n, the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion ( d, i, o, u, i, x, and X), the 0 flag is ignored.  

'-'  A negative field width flag; the converted value is to be left adjusted on the field boundary. Except for n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A - overrides a 0 if both are given.  

' (space)'  A blank should be left before a positive number produced by a signed conversion ( a, A, d, e, E, f, F, g, G, or i).  

'+'  A sign must always be placed before a number produced by a signed conversion. A + overrides a space if both are used.  

'’'  Decimal conversions ( d, u, or i) or the integral portion of a floating point conversion ( f or F) should be grouped and separated by thousands using the non-monetary separator returned by localeconv.  

An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width. 

An optional precision, in the form of a period . followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for d, i, o, u, x, and X conversions, the number of digits to appear after the decimal-point for a, A, e, E, f, and F conversions, the maximum number of significant digits for g and G conversions, or the maximum number of characters to be printed from a string for s conversions. 

An optional length modifier, that specifies the size of the argument. The following length modifiers are valid for the d, i, n, o, u, x, or X conversion:

@endcode

@code

 Modifier            d, i      o, u, x, X        n 

 hh signed char unsigned char signed char *

 h short unsigned short short *

 l (ell) long unsigned long long *

 ll (ell ell) long long unsigned long long long long *

 j intmax_t uintmax_t intmax_t *

 t ptrdiff_t (see note) ptrdiff_t *

 z (see note) size_t (see note)

 q (deprecated) quad_t u_quad_t quad_t *

@endcode

@code

Note: the t modifier, when applied to a o, u, x, or X conversion, indicates that the argument is of an unsigned type equivalent in size to a ptrdiff_t . The z modifier, when applied to a d or i conversion, indicates that the argument is of a signed type equivalent in size to a size_t . Similarly, when applied to an n conversion, it indicates that the argument is a pointer to a signed type equivalent in size to a size_t . 

The following length modifier is valid for the a, A, e, E, f, F, g, or G conversion:

@endcode

@code

 Modifier a, A, e, E, f, F, g, G

 L long double

@endcode

@code   

The following length modifier is valid for the c or s conversion:

Modifier c s

 l (ell) wint_t  wchar_t * 

@endcode

@code

A character that specifies the type of conversion to be applied. 

A field width or precision, or both, may be indicated by an asterisk ‘*’ or an asterisk followed by one or more decimal digits and a ‘$’ instead of a digit string. In this case, an int argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. If a single format directive mixes positional (nn$) and non-positional arguments, the results are undefined. 

The conversion specifiers and their meanings are: 

diouxX  

  The int (or appropriate variant) argument is converted to signed decimal ( d and i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal ( x and X) notation. The letters "abcdef" are used for x conversions; the letters "ABCDEF" are used for X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros.  

DOU  

  The long int argument is converted to signed decimal, unsigned octal, or unsigned decimal, as if the format had been ld, lo, or lu respectively. These conversion characters are deprecated, and will eventually disappear.  

eE  

  The double argument is rounded and converted in the style [-d . ddd e \*[Pm] dd] where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. An E conversion uses the letter ‘E’ (rather than ‘e’) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00. 

For a, A, e, E, f, F, g, and G conversions, positive and negative infinity are represented as inf and -inf respectively when using the lowercase conversion character, and INF and -INF respectively when using the uppercase conversion character. Similarly, NaN is represented as nan when using the lowercase conversion, and NAN when using the uppercase conversion. 

fF  

  The double argument is rounded and converted to decimal notation in the style [-ddd . ddd], where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it.  

gG  The double argument is converted in style f or e (or F or E for G conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style e is used if the exponent from its conversion is less than -4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit.  

aA  The double argument is converted to hexadecimal notation in the style [-0x h . hhhp[\*[Pm]d]], where the number of digits after the hexadecimal-point character is equal to the precision specification. If the precision is missing, it is taken as enough to exactly represent the floating-point number; if the precision is explicitly zero, no hexadecimal-point character appears. This is an exact conversion of the mantissa+exponent internal floating point representation; the [-0x h . hhh] portion represents exactly the mantissa; only denormalized mantissas have a zero value to the left of the hexadecimal point. The p is a literal character ‘p’; the exponent is preceded by a positive or negative sign and is represented in decimal, using only enough characters to represent the exponent. The A conversion uses the prefix "0X" (rather than "0x"), the letters "ABCDEF" (rather than "abcdef") to represent the hex digits, and the letter ‘P’ (rather than ‘p’) to separate the mantissa and exponent.  

C  Treated as c with the l (ell) modifier.  

c  The int argument is converted to an unsigned char , then to a wchar_t as if by btowc, and the resulting character is written. 

If the l (ell) modifier is used, the wint_t argument is converted to a wchar_t and written. 

S  Treated as s with the l (ell) modifier.  

s  The char * argument is expected to be a pointer to an array of character type (pointer to a string) containing a multibyte sequence. Characters from the array are converted to wide characters and written up to (but not including) a terminating NUL character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating NUL character. 

If the l (ell) modifier is used, the wchar_t * argument is expected to be a pointer to an array of wide characters (pointer to a wide string). Each wide character in the string is written. Wide characters from the array are written up to (but not including) a terminating wide NUL character; if a precision is specified, no more than the number specified are written (including shift sequences). If a precision is given, no null character need be present; if the precision is not specified, or is greater than the number of characters in the string, the array must contain a terminating wide NUL character. 

p  The void * pointer argument is printed in hexadecimal (as if by ‘%#x’ or ‘%#lx’).  

n  The number of characters written so far is stored into the integer indicated by the int * (or variant) pointer argument. No argument is converted. 

%  A ‘%’ is written. No argument is converted. The complete conversion specification is ‘%%’.  

@endcode

The decimal point character is defined in the program’s locale (category LC_NUMERIC). 

In no case does a non-existent or small field width cause truncation of a numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. 

Examples:

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use wprintf API */

int example_wprintf(void)

{

 int input = 12345;

 int rval;

 /* prints the integers on the standard output */

 rval = wprintf(L"%d", input);

 /* return the number of wide characters that were written */

 return(rval);

}

@endcode

 Output

@code

12345

@endcode

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use fwprintf API */

int example_fwprintf(void)

{

 FILE *fp = NULL;

 int retval;

 wchar_t *wcs = L"abc";

 /* open the file for writing*/

 fp = fopen("write.txt","w");

 if(fp == NULL)

 {

  wprintf(L"Error: File open

");

  return (-1);

 }

 /* print the characters into the file */

 retval = fwprintf(fp, L"%s", wcs);

 /* Close the file opened for writing */

 fclose(fp);

 /* return the number of wide characters that were written */

 return (retval);

}

@endcode

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use swprintf API */

int example_swprintf(wchar_t *buf, int maxlen)

{

 wchar_t *wcs = L"abcdef";

 int rval;

 /* prints the wide char string into the buffer buf */

 rval = swprintf(buf, maxlen, L"%s", wcs);

 /* return the number of wide characters that were written */

 return(rval);

}

@endcode

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use vwprintf API */

int example_vwprintf(va_list input)

{

 int rval;

 /* prints the integers on the standard output */

 rval = vwprintf(L"%d", input);

 /* return the number of wide characters that were written */

 return(rval);

}

@endcode

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use vfwprintf API */

int example_vfwprintf(va_list input)

{

  FILE *fp = NULL;

  int retval;

  /* open the file for writing*/

  fp = fopen("write.txt","w");

  if(fp == NULL)

  {

    wprintf(L"Error: File open

");

    return (-1);

  }

  /* print the characters into the file */

  retval = vfwprintf(fp, L"%s", input);

  /* Close the file opened for writing */

  fclose(fp);

  /* return the number of wide characters that were written */

  return (retval);

}

@endcode

@code

#include <stdio.h>

#include <wchar.h>

/* Illustrates how to use vswprintf API */

int example_vswprintf(wchar_t *buf, int maxlen, va_list input)

{

 int rval;

 /* prints the wide char string into the buffer buf */

 rval = vswprintf(buf, maxlen, L"%s", input);

 /* return the number of wide characters that were written */

 return(rval);

}

@endcode

Security considerations:

Refer to printf() .

Limitations:

Long double length modifiers are not supported. The maximum floating point 

precision is 15 digits.

@see btowc()

@see fputws()

@see printf()

@see putwc()

@see setlocale()

@see wcsrtombs()

@see wscanf()

@publishedAll

@externallyDefinedApi

*/

/** @fn  fwscanf(FILE *  stream, const wchar_t *  format, ...)

@param stream

@param format

@param ...

Refer to wscanf() for the documentation

@see fgetwc()

@see scanf()

@see wcrtomb()

@see wcstod()

@see wcstol()

@see wcstoul()

@see wprintf()

@publishedAll

@externallyDefinedApi

*/

/** @fn  getwc(FILE *stream)

@param stream

Refer to  fgetwc() for the documentation

@see ferror()

@see fopen()

@see fread()

@see getc()

@see putwc()

@see ungetwc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  getwchar(void)

Refer to fgetwc() for the documentation

@see ferror()

@see fopen()

@see fread()

@see getc()

@see putwc()

@see ungetwc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  mbrlen(const char *  s, size_t n, mbstate_t *  ps)

@param s

@param n

@param ps

@return   The mbrlen functions returns: 0 The next n or fewer bytes

represent the null wide character (L'\\0') \>0 The next n or fewer bytes

represent a valid character, mbrlen returns the number of bytes used to complete the multibyte character. ( size_t-2)   The next n contribute to, but do not complete, a valid multibyte character sequence,

and all n bytes have been processed. ( size_t-1)   An encoding error has occurred.

The next n or fewer bytes do not contribute to a valid multibyte character.

  The mbrlen function inspects at most n bytes pointed to by s to determine the number of bytes needed to complete the next

multibyte character.

 The mbstate_t

argument, ps, is used to keep track of the shift state.

If it is NULL, mbrlen uses an internal, static mbstate_t

object, which is initialized to the initial conversion state

at program startup.

 It is equivalent to:

@code

mbrtowc(NULL, s, n, ps); 

@endcode

Except that when ps is a NULL pointer, mbrlen uses its own static, internal mbstate_t

object to keep track of the shift state. The behavior of the mbrlen is affected by LC_CTYPE category of the current locale.

Examples:

 A function that calculates the number of characters in a multibyte

character string:

@code

size_t

nchars(const char *s)

{

        size_t charlen, chars;

        mbstate_t mbs;

        chars = 0;

        memset(&mbs;, 0, sizeof(mbs));

        while ((charlen = mbrlen(s, MB_CUR_MAX, &mbs;)) != 0 &&

            charlen != (size_t)-1 && charlen != (size_t)-2) {

                s += charlen;

                chars++;

        }

        return (chars);

}

@endcode

Errors:

The mbrlen function will fail if: 

[EILSEQ] An invalid multibyte sequence was detected.  

[EINVAL] The conversion state is invalid.

Limitations:

The current implementation of mbrlen is not affected by the LC_CTYPE category of the current locale.

It works only for UTF8 character set.

@see mblen()

@see mbrtowc()

@publishedAll

@externallyDefinedApi

*/

/** @fn  mbrtowc(wchar_t *  pwc, const char *  s, size_t n, mbstate_t *  ps)

@param pwc

@param s

@param n

@param ps

@return   The mbrtowc functions returns: 0 The next n or fewer bytes

represent the null wide character (L'\\0') \>0 The next n or fewer bytes

represent a valid character, mbrtowc returns the number of bytes used to complete the multibyte character. ( size_t-2)   The next n contribute to, but do not complete, a valid multibyte character sequence,

and all n bytes have been processed. ( size_t-1)   An encoding error has occurred.

The next n or fewer bytes do not contribute to a valid multibyte character.

  The mbrtowc function inspects at most n bytes pointed to by s to determine the number of bytes needed to complete the next multibyte

character.

If a character can be completed, and pwc is not NULL, the wide character which is represented by s is stored in the wchar_t

it points to.

 If s is NULL, mbrtowc behaves as if pwc was NULL, s was an empty string ("")

and n was 1.

 The mbstate_t

argument, ps, is used to keep track of the shift state.

If it is NULL, mbrtowc uses an internal, static mbstate_t

object, which is initialized to the initial conversion state

at program startup.

 The behavior of the mbrtowc is affected by LC_CTYPE category of the current locale.

Examples:

@code

#include <stdio.h>

#include <stdlib.h>

#include <wchar.h>

/* Illustrates how to use mbrtowc API */

size_t example_mbrtowc()

{

 size_t len;

 wchar_t wc[100];

 char *s = 'a';

 size_t n = 1;

 mbstate_t ps;

 /* converting multibyte sequence to a wide-char sequence */

 len = mbrtowc(wc,(const char *) s, n, &ps;);

 /* checking for error value */

 if(len < 0)

 {

        wprintf(L"mbrtowc returned error!!

");

 }

 /* returning no of bytes consumed */

 return (len);

}

@endcode

Errors:

The mbrtowc function will fail if: 

[EILSEQ] An invalid multibyte sequence was detected.  

[EINVAL]The conversion state is invalid. 

Limitations:

The current implementation of mbrtowc is not affected by the LC_CTYPE category of the current locale.

It works only for UTF8 character set.

@see mbtowc()

@see setlocale()

@see wcrtomb()

@publishedAll

@externallyDefinedApi

*/

/** @fn  mbsinit(const mbstate_t *ps)

@param ps

@return   The mbsinit function returns non-zero if ps is NULL or describes an initial conversion state,

otherwise it returns zero.

  The mbsinit function determines whether the mbstate_t

object pointed to by ps describes an initial conversion state.

 The behavior of the mbsinit is affected by LC_CTYPE category of the current locale.

Examples:

@code

#include <stdlib.h>

#include <wchar.h>

/* Illustrates how to use mbsinit API */

int example_mbsinit(void)

{

 mbstate_t mbs;

 int state;

 /* testing for the initial state */

 state = mbsinit(&mbs;);

 /* return the state */

 return(state);

}

@endcode

Limitations:

The current implementation of mbsinit is not affected by the LC_CTYPE category of the current locale.

It works only for UTF8 character set.

@see mbrlen()

@see mbrtowc()