/** @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 *