C Programming/wchar.h/Function reference

fgetws
  is a function in the C programming language. It is wide-character version of the function. The w in  is for wide. A string is read as a multibyte-character or a wide character string  by   depending on whether the stream is opened in text/binary mode respectively. The  subroutine reads characters from the input stream, converts them to the corresponding wide character codes, and places them in the array pointed to by the string parameter.

The subroutine continues until either:
 * The number of characters specified by the number parameter '-1' are read
 * The subroutine encounters a newline or EOF character.

The fgetws subroutine terminates the wide character string with a NULL wide character.

Parameters
fgetws has three parameters:
 * 1)   - a string used to provide storage location for data
 * 2)   - the maximum number of readable characters
 * 3)   - a FILE pointer

Requirements
Although fgetws is wider relative to fgets, it can be compiled by an additional optional header along with stdio.h called wchar.h. However, fgets requires stdio.h compulsorily. Hence, fgetws provides option.

Return value
Just as fgets function, fgetws function also returns the same value string i.e. a ws is returned on success. The error condition is taken care-of by this function using a NULL pointer. A Null pointer is returned to the function-called for error or even at EOF(end of file). One can use also use the feof or ferror for error determination.

Compatibility
ubuntu, fedora, ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

mbrlen
mbrlen is the standard library function used to determine the length of the multi-byte character using conversion state. The mbrlen function differ from 'mblen' 'mblen l' by its restartability.

Need
To use this function in program one include the standard header file.

Syntax
size_t mbrlen (const char *s, size_t maxsize, mbstate_t *ps ).

the mbrlen function inspects at most maxsize of the string pointed i.e. s and extracts the next complete multibyte character. It updates the shift state *ps .If the multibyte character is not the NULL wide character, it returns the number of the bytes that were consumed by s.

Return value
(size_t) - 2 : the resulting conversion state indicates an incomplete multibyte character after all  maxsize character were converted.

(size_t) - 1 : the function detected an encoding error before completing the next multibyte character, in which case the function errno to EILSEQ amd leaves the resulting conversion state undefined.

0 : the next complete character is a null character, in which case the resulting conversion state is the initial  conversion state.

positive : if the next n or fewer byte complete a valid character ; the value returned shall be the number of bytes that complete the character.

Function of mbrtowc
mbrtowc convert the multibyte character to wide character using conversion states

SYNOPSIS of a function mbrtowc:

 * 1) include 

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

Description of mbrtowc function:
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 initialzed 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:
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:
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

Name
Putwc

Parameters
c is used for the character to be written. stream for pointer to FILE structure.

description
It is a standard library function. this function write a wide character to a FILE stream. it is included in the standard library Wchar.h. putwc function writes a wide character to output stream. it advances the file position accordingly. putwc function is same as fputwc.

Return value
on success this function return 0. otherwise it will give non-zero value.

swprintf
swprintf is a C standard library function as defined in wchar.h and it's required header files are stdio.h and wchar.h. It has function signature as 'int swprintf(wchar_t *s,, size_t n, const wchar_t format,...);

n the signature of swprintf: s : it is pointer to the buffer where you want to store the formatted string.The formatting string provides the extra arguments required n : it is maximum number of characters to be stored in the buffer appending the null character. format : this is the wide character string which shows the format of the output.

Usage
The swprintf function perform wide character output to an array of wide characters. The programmer must ensure that there is space for at least 'n' wide characters at 's'.

Description
swprintf is the function which prints the output after the null character in the consecutive wide character starting at *s.And it prints no n more characters up to next null character appears.swprintf is wide character version of sprintf.pointer arguments to swprintf are wide character string

return value
This function returns number of character written or -1 if an error exist.If s(pointer to buffer) or format is a null pointer ,invalid parameter is invoked.If the program allows to run this code the it returns -1 or errno is set to EINVAL. swprintf returns number of wide character which are stored in 's'(buffer) not counting the last null character.

Syntax
wchar_t *wcscat(wchar_t *a, const wchar_t *b);
 * 1) include 

Description
The job done by the functions strcat and Wcscat  is same as mentioned i.e concatenating two strings.. The difference is that the function strcat takes (normal) character strings  and wcscat takes wide character strings as arguments.

The function wcscat ,copy the wide character string say b including '\0'(at the end of string b), at the end of  wide character string say a. The '\0' character of the string a is replaced by the first character of the string 'b'. I.e function append the sring 'b' to the end of string 'a'. If wide character string 'a' is "hello" and  wide character string 'b' is "world". After calling the function wcscat(a, b) , string 'a' becomes "helloworld" and string 'b' remains same. The wide string 'a' must have memory of  at least  (strlen(a) + strlen(b) +1) bytes so that it can  store wcs(Wide character string) 'a', wcs 'b' and '\0'.

Sample Program
Output of program will be ' Hello World '.

Wide character string 'source'(World) is appended at the end of wide character string 'destination'(Hello).

Return Value
The function wcscat returns pointer to wide character string 'a' i.e pointer to the string which is concatenated.

wcscmp
In C language ,the function wcscmp is included in header file wchar.h wcscmp is similar to strcmp i.e it is used to compare two strings.but the function wcscmp is used to compare wide character strings. If two wide character strings say s1 and s2 are to be compared. Then function wcscmp returns positive integer if s1 is greater than s2. It returns negative integer if string s2 is greater than s1. if two wide character strings i.e s1 and s2 are same then function returns 0.

syntax
int wcscmp(const wchar_t *s1, const wchar_t *s2);
 * 1) include 

Sample program which uses function wcsncmp
Output of program will be 'char is less than character '

as value of difference is negative.

Description
Wcsncmp is the standard library function used to compare two wide character strings. The function is similar to standard library function strcmp. But the comparison is not like strcmp. The first difference is that the function wcsncmp compares the two strings upto some limit(at most n character) i.e  size_t n but strcmp compares the strings till '\0' occurs. and the second is that it handles wide characters as mentioned. It compares the wide-character string pointed to by say a and the wide character string pointed to by say b, but at most n wide characters from each string.

If the wide character string a is greater than wide character string b at first differentiating position i (i < n) then the function Wcsncmp returns positive integer and if second string is greater than first at the first differing position i (i < n), then the function wcsncmp  returns negative integer. if the first i characters (i < n) of a and b are equal, the function wcsncmp returns 0.

wcscpy
In C Programming language, functions  wcsncmp , wcscat , labs , mempcpy are used. Function wcscpy ,is similar to strcpy .strcpy is used to copy strings whereas wcscpy is used to handle wide strings for copying. It copies the wide-character  string  pointed  to  by  src,including  the  terminating L'\0' character, to the array pointed to by dest.