/** @file  ../include/wctype.h
@internalComponent
*/

/** @fn  iswalnum(wint_t i)
@param i
@return   The functions return non-zero if i is wide alphabet or wide digit and zero otherwise.

 

 The iswalnum() function tests whether 'i' is a wide alphabet or wide digit i.e. it belongs to class alnum(see defns for definition).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class alnum, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswalnum()
#include<stdio.h>  //printf()
void test_iswalnum()
{
   int arr[]={'8',0xe1,'5','Z',0xfd,0xFF12,0xFF19,0xFF71,0x03A3};
   int i = 0;
   int size = 9;
   for( i=0; i<size; i++)
   {
     int ret = iswalnum(arr[i]); //call to the API with chars in the arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide alnum", arr[i]);
     }
     else
     {
        printf("
%lc is a wide alnum ", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
8 is wide alnum
«¡ is wide alnum
5 is wide alnum
Z is wide alnum
«ò is wide alnum
£² is wide alnum
£¹ is wide alnum
± is wide alnum
¦² is wide alnum
@endcode
@see isalnum()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/

/** @fn  iswalpha(wint_t i)
@param i
@return   The functions return non-zero if 'i' is a wide alphabet and zero otherwise.

 

 The iswalpha() function tests whether 'i' is a wide alphabet i.e. 
  it belongs to class alpha (see defns for definition).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class alpha, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswalpha()
#include<stdio.h>  //printf()
void test_iswalpha()
{
   int arr[]={'a',0xe1,'5','Z',0xfd, 0x3041,0xFF9D,0x009F,0x007E};
   int i = 0;
   int size = 9;
   for( i=0; i<size; i++)
   {
     int ret = iswalpha(arr[i]); //call to API with chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide alphabet", arr[i]);
     }
     else
     {
        printf("
%lc is wide alphabet", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
a is wide alphabet
«¡ is wide alphabet
5 is not wide alphabet
Z is wide alphabet
«ò is wide alphabet
¤¡ is wide alphabet
Ý is wide alphabet
 is not wide alphabet
~ is not wide alphabet
@endcode
@see isalpha()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswblank(wint_t i)
@param i
@return   The functions return non-zero if 'i' is wide blank character and zero otherwise.

 

 The iswblank() function tests whether 'i' is a wide-character that belongs to the
character class - blank (see defns for definition).
The character class blank contains the character space('') and the horizontal tabulation(' ').

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class blank, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswblank()
#include<stdio.h> //printf()
int test_iswblank()
{
   int arr[]={0x0020,'0',0x0009,'R',0x3000, 0x000A, 0x002};
   int i = 0;
   int size = 7;
   for( i=0; i<size; i++)
   {
     int ret = iswblank(arr[i]); //call to the API with the chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide blank ", arr[i]);
     }
     else
     {
        printf("
%lc is wide blank", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
is wide blank
0 is not wide blank
     is wide blank
R is not wide blank
¡¡ is wide blank
 is not wide blank
 is not wide blank
@endcode
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswcntrl(wint_t i)
@param i
@return   The functions return non-zero if 'i' is a wide control character and returns zero otherwise.

 

 The iswcntrl() function tests whether 'i' is a wide control character 
  i.e it belongs to class cntrl (see defns for definition).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class cntrl, irrespective of the locale they belong to.

 The control characters are:

 BELL

 DELETE

 BACKSPACE

 LINE FEED

 VERTICAL TABULATION

 FORM FEED

 CARRIAGE RETURN...and the like.



Examples:
@code
#include<wctype.h> //iswcntrl()
#include<stdio.h> //printf()
int test_iswcntrl()
{
   int arr[]={0x7F,'9','A','$','\a'};
   int i = 0;
   int size = 5;
   for( i=0; i<size; i++)
   {
     int ret = iswcntrl(arr[i]); //call to API with chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide cntrl char ", arr[i]);
     }
     else
     {
        printf("
%lc is wide cntrl char", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
is wide cntrl char
9 is not wide cntrl char
A is not wide cntrl char
$ is not wide cntrl char
 is wide cntrl char
@endcode
@see iswcntrl()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswctype(wint_t wc, wctype_t charclass)
@param wc
@param charclass

Note: This description also covers the following functions -
 wctype() 

@return   The iswctype function returns non-zero if, and only if, wc has the property described by charclass , or charclass is zero. The wctype function returns 0 if property is invalid, otherwise it returns a value of type wctype_t
that can be used in subsequent calls to iswctype .


The iswctype() function tests whether the wide-character wch belongs to the character class/category chcl. 

The result of this function is undefined unless the argument is WEOF or a valid wchar_t value. 

The functionality of this API is independent of the program’s current locale and so it returns non-zero for all the characters given in ’wch’(of various locales supported) that belong to the class chcl(see _ctype.h for definition of values that can be used to specify category), irrespective of the locale they belong to. 

For example: digits 0 to 9 would belong to _CTYPE_D class (i.e. class digit), and a to z would belong to _CTYPE_L class (i.e. class lower).



Examples:
 Reimplement iswalpha in terms of iswctype and wctype :
@code
int
myiswalpha(wint_t wc)
{
        return (iswctype(wc, wctype("alpha")));
}

@endcode
@code
#include <wchar.h>
/* Illustrates how to use wctype API */
wctype_t example_wctype()
{  
 wctype_t type;
 
  /* get the type by passing the operation string to the wctype API */
 type = wctype("alnum");
  
 /* if the operation is successful then it should return non-zero value */
 /* else returns 0 */
  return type;
}

@endcode

Limitations:

The current implementation of iswctype and wctype is dependent on the locale support of Symbian OS. It doesn't work for the locales which the Symbian OS



 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswdigit(wint_t i)
@param i
@return   The functions return non-zero if 'i' is a wide digit and zero otherwise.

 

 The iswdigit() function tests whether 'i' is a wide digit.
The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class digit(see defns for definition), irrespective of the locale they belong to.

 For example, the digits 0 to 9 fall under class digit.

Examples:
@code
#include<wctype.h> //iswdigit()
#include<stdio.h> //printf()
void test_iswdigit()
{
   int arr[]={'8',0xe1,'5','Z',0xfd,
   0xFF12,0xFF19,0xFF71,0x03A3};
   int i = 0;
   int size = 9;
   for( i=0; i<size; i++)
   {
     int ret = iswdigit(arr[i]); //call to the API with chars in arr[]
     if( (!ret) != 0 )
     {
         printf("
%lc is not a wide digit", arr[i]);
     }
     else
     {
         printf("
%lc is a wide digit", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
8 is wide digit
«¡ is not wide digit
5 is wide digit
Z is not wide digit
«ò is not wide digit
£² is wide digit
£¹ is wide digit
±  is not wide digit
¦²  is not wide digit
@endcode
@see isdigit()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswgraph(wint_t i)
@param i
@return   The function returns non-zero if 'i' has visual representation and zero otherwise.

 

 The iswgraph() function tests whether 'wch' is a visible wide-character 
  i.e it belongs to class graph (see defns for definition).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class graph, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h>
#include<stdio.h>
int test_iswgraph()
{
   int arr[]={'n','\f', 0xe1, '6', ' '};
   int i = 0;
   int size = 5;
   for( i=0; i<size; i++)
   {
     int ret = iswgraph(arr[i]);
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide visible char ", arr[i]);
     }
     else
     {
        printf("
%lc is wide visible char", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
n is wide visible char
 is not wide visible char
«¡ is wide visible char
6 is wide visible char
  is not wide visible char

@endcode
@see isgraph()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswlower(wint_t i)
@param i
@return   The function returns non-zero if 'i' is wide lower-case and zero otherwise.

 

 The iswlower() function tests whether 'i' is a wide-character which is from among lower-case alphabets.

 Characters that belong to class cntrl, class punct and digit are not a part 
  of class lower (see defns for definition).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class lower(see defns for definition), irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswlower()
#include<stdio.h> //printf()
int test_iswlower()
{
   int arr[]={ 0x0126, 0xee, 'r' , '9' , 'g', 0xFF51, 0x0451, 0x03CE };
   int i = 0;
   int size = 8;
   for( i=0; i<size; i++)
   {
     int ret = iswlower(arr[i]); //call to the API with chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide lower-case ", arr[i]);
     }
     else
     {
        printf("
%lc is wide lower-case", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code

©¤ is not wide lower-case
«Â is wide lower-case
r is wide lower-case
9 is not wide lower-case
g is wide lower-case
£ñ is wide lower-case
§× is wide lower-case
¦ü is wide lower-case

@endcode
@see islower()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswprint(wint_t i)
@param i
@return   The function returns non-zero if the wide character is printable and
returns zero otherwise.

 

 The iswprint() function tests whether 'i' is a wide-character 
  that can be printed i.e it belongs to class print (see defns for definition).

 Characters used for representing the alphabets, digits, punctuation characters 
  and space are classified as printable. No characters under class cntrl are printable.

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class print, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswprint()
#include<stdio.h> //printf()
int test_iswprint()
{
   int arr[]={'n',', 0xe1, '6', ' '};
   int i = 0;
   int size = 5;
   for( i=0; i<size; i++)
   {
     int ret = iswprint(arr[i]); //call to the API with chars in the arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide printable char ", arr[i]);
     }
     else
     {
        printf("
%lc is wide printable char", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code

n is wide printable char
 is not wide printable char
«¡ is wide printable char
6 is wide printable char
  is wide printable char

@endcode
@see isprint()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswpunct(wint_t i)
@param i
@return   The function returns non-zero if 'wch' is a wide character and
returns zero otherwise.

 

 The iswpunct() function tests whether 'wch' can be classfied wide 
  punctuation character i.e. it belongs to class punct (see defns for definition)

 The characters that can be classified as alphabets, digits, space or control 
  characters do not belong to punctuation wide-character code.

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class punct, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswpunct()
#include<stdio.h>  //printf()
int test_iswpunct()
{
 
   int arr[]={0x3003,'3',0x301C,'*', '+'};
   int i = 0;
   int size = 5;
   for( i=0; i<size; i++)
   {
     int ret = iswpunct(arr[i]);//call to the API with chars in arr[]
     if( (!ret) != 0 )
     {
         printf("
0x%x is not wide punc char ", arr[i]);
     }
     else
     {
         printf("
0x%x is a wide punc char", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code

0x3003 is a wide punc char
0 0x33 is not  wide punc char
0x301c is a wide punc char
0x2a is a wide punc char
0x2b is a wide punc char

@endcode
@see ispunct()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswspace(wint_t i)
@param i
@return   The functions return zero if the character tests false and
return non-zero if the character tests true.

 

 The iswspace() function tests whether 'i' is a wide-character 
  that introduces white-space (see defns for definition)

 The following are such characters in the POSIX locale:

 SPACE

 FORM-FEED

 NEWLINE

 CARRIAGE-RETURN

 TAB

 VERTICAL-TAB

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class space, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswspace()
#include<stdio.h> //printf()
int test_iswspace()
{
   int arr[]={'\n','0','w','R',0x3000,' ', 0x000A, 0x002};
   int i = 0;
   int size = 8;
   for( i=0; i<size; i++)
   {
     int ret = iswspace(arr[i]); //call to the API with chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide space ", arr[i]);
     }
     else
     {
        printf("
%lc is wide space", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code

is wide space
0 is not wide space
w is not wide space
R is not wide space
¡¡ is wide space
  is wide space
 is wide space
 is wide space

@endcode
@see isspace()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswupper(wint_t i)
@param i
@return   The functions return zero if the character tests false and
return non-zero if the character tests true.

 

 The iswupper() function tests whether wch is a wide-character that belongs 
  to upper-case letters, i.e. checks if it belongs to class upper (see defns for definition).

 Characters that belong to class cntrl, punct and digit are not
a part of class upper(see defns for definition).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current locale and so it returns non-zero for all the characters (of various locales supported) that belong to the class upper, irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswupper()
#include<stdio.h>  //printf()
int test_iswupper()
{
   int arr[]={'8',0xe1,'5','Z',0x0126 , 0xFF21 ,'G' , 0x03A4 , 0x00CF };
   int i = 0;
   int size = 9;
   for( i=0; i<size; i++)
   {
     int ret = iswupper(arr[i]); //call to the API with the chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%lc is not wide upper-case ", arr[i]);
     }
     else
     {
        printf("
%lc is wide upper-case", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code

8 is not wide upper-case «¡ is not wide upper-case
5 is not wide upper-case
Z is wide upper-case
©¤ is wide upper-case
£Á is wide upper-case
G is wide upper-case
¦³ is wide upper-case
ªÁ is wide upper-case

@endcode
@see isupper()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  iswxdigit(wint_t i)
@param i
@return   The functions return zero if the character tests false and
return non-zero if the character tests true.

 

 The iswxdigit() function tests whether 'i' is a wide-character belongs to the set of
characters that are used to represent hexadecimal digits.

 For example: The characters that can be used to represent hexadecimal values:
are - 0,1,2,3,4,5,6,7,8,9 and a,b,c,d,e,f and A,B,C,D,E,F.

 Generally, the characters that can be classified as digits are used for the representing
hexadecimal values along with one or more sets of continuous characters of other categories
that are used to represent the hexadecimal values other than the digits(base 10).

 The result of this function is undefined unless
the argument is WEOF or a valid wchar_t
value.

 The functionality of this API is independent of the program's current 
  locale and so it returns non-zero for all the characters (of various locales 
  supported) that belong to the class xdigit (see defns for definition), irrespective of the locale they belong to.



Examples:
@code
#include<wctype.h> //iswxdigit()
#include<stdio.h> //printf()
int test_iswxdigit()
{
   int arr[]={'F','a','M','9','2'};
   int i = 0;
   int size = 5;
   for( i=0; i<size; i++)
   {
     int ret = iswxdigit(arr[i]); //call to the API with the chars in arr[]
     if( (!ret) != 0 )
     {
        printf("
%c is not wide hex-digit ", arr[i]);
     }
     else
     {
        printf("
%c is wide hex-digit", arr[i]);
     }
   }
printf("
");
}

@endcode
 Output
@code
F is wide hex-digit
a is wide hex-digit
M is not wide hex-digit
9 is wide hex-digit
2 is wide hex-digit

@endcode
@see isdigit()
@see iswctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  towctrans(wint_t wc, wctrans_t desc)
@param wc
@param desc

Note: This description also covers the following functions -
 wctrans() 

@return   The towctrans function returns the transliterated character if successful, otherwise
it returns the character unchanged and sets errno . The wctrans function returns non-zero if successful, otherwise it returns zero
and sets errno .


  The wctrans function returns a value of type wctrans_t
which represents the requested wide character mapping operation and
may be used as the second argument for calls to towctrans .

 The following character mapping names are recognised: 

@code
 tolower	toupper

@endcode

 The towctrans function transliterates the wide character wc according to the mapping described by desc .

 The behavior of the wctrans and towtrans is affected by LC_CTYPE category of the current locale.

Examples:
@code
#include <wchar.h>
/* Illustrates how to use wctrans API */
wctrans_t example_wctrans()
{  
  wctrans_t type;
 
  /* get the type by passing the operation string to the wctrans API */
 type = wctrans("alnum");
  
 /* if the operation is successful then it should return non-zero value else returns 0 */
  return type;
}

@endcode
@code
#include <wchar.h>
#include <wctype.h>
/* Illustrates how to use towctrans API */
TInt example_towctrans(void)
{ 
 wctrans_t type;
 /* get the type by passing the string */  
 type = wctrans("tolower");
  
 /* if the type is 0 then return an error, else call the API to translate */
 if(type == (wctype_t)0)
  return -1;
  /* translate the input char to specified type */
 wint_t twc = towctrans(L'K',type);
 /* return no error if conversion is ok else return error */  
 if(twc != (wint_t)L'k')
   return -1;
  
  return 1;
}

@endcode

Limitations:   

The current implementation of wctrans and towtrans is dependent on the locale support of Symbian OS. It doesn't work for the locales which the Symbian OS doesn't support.

@see tolower()
@see toupper()
@see wctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  towlower(wint_t i)
@param i
@return   If the argument is an upper-case letter, the towlower function returns the corresponding lower-case letter if there is
one; otherwise the argument is returned unchanged.

  The towlower function converts an upper-case letter to the corresponding lower-case
letter.

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

Examples:
@code
#include <wchar.h>
/* Illustrates how to use towlower API */
wint_t example_towlower(void)
{ 
 /* input character */
  wint_t uwc = L'M'; 
  wint_t lwc;
  /* convert a wide char from upper case to lower case */
  lwc = towlower(uwc);
 
 /* return the converted char or error if not */
  return lwc;
}

@endcode

Limitations:

The current implementation of towlower is dependent on the locale and works only for locales supported 
by Symbian OS.

@see iswlower()
@see tolower()
@see towupper()
@see wctrans()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  towupper(wint_t i)
@param i
@return   If the argument is a lower-case letter, the towupper function returns the corresponding upper-case letter if there is
one; otherwise the argument is returned unchanged.

  The towupper function converts a lower-case letter to the corresponding
upper-case letter.

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

Examples:
@code
#include <wchar.h>
/* Illustrates how to use towupper API */
wint_t example_towupper(void)
{ 
 /* input character */
  wint_t lwc = L'm'; 
  wint_t uwc;
  /* convert a wide char from lower case to upper case */
  uwc = towupper(lwc);
 
 /* return the converted char or error if not */
  return uwc;
}

@endcode

Limitations:

The current implementation of towupper is dependent on the locale and works only for locales supported 
by Symbian OS.

@see iswupper()
@see toupper()
@see towlower()
@see wctrans()


 

@publishedAll
@externallyDefinedApi
*/

/** @fn  wctrans(const char *charclass)
@param charclass

Refer to  towctrans() for the documentation

@see tolower()
@see toupper()
@see wctype()


 

@publishedAll
@externallyDefinedApi
*/


/** @fn  wctype(const char *property)
@param property

Refer to  iswctype() for the documentation


 

@publishedAll
@externallyDefinedApi
*/


/** @typedef typedef	int	wctrans_t

A scalar type that can hold values which represent locale-specific character mappings.

@publishedAll
@externallyDefinedApi
*/

/** @typedef typedef	unsigned long	wctype_t

A scalar type of a data object that can hold values which represent locale-specific character classification.

@publishedAll
@externallyDefinedApi
*/


/** @def WEOF

Constant expression of type wint_t that is returned by several MSE functions to indicate end-of-file.

@publishedAll
@externallyDefinedApi
*/

