C Programming/wchar.h/Function reference

fgetws

fgetws is a function in the C programming language. It is wide-character version of the function fgets. The w in fgetws is for wide. A string is read as a multibyte-character or a wide character string by fgetws depending on whether the stream is opened in text/binary mode respectively. The fgetws 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.

Syntax

#include <stdio.h>
#include <wchar.h>
wchar_t *fgetws( 
    wchar_t *string;
    int n;
    FILE *stream ;
);

Parameters

fgetws has three parameters:

1. string - a string used to provide storage location for data
2. n - the maximum number of readable characters
3. stream - 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

References

• http://pubs.opengroup.org/onlinepubs/009695399/functions/fgetws.html
• http://www.freebsd.org/cgi/man.cgi?query=fgetws&apropos=0&sektion=0&manpath=FreeBSD+7.1-RELEASE&format
• http://msdn.microsoft.com/en-us/library/c37dh6kf(v=vs.71).aspx
• http://publib.boulder.ibm.com/infocenter/pseries/v5r3/index.jsp?topic=/com.ibm.aix.basetechref/doc/basetrf1/getws.htm

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<wchar.h>.

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 .

Sources

• http://pubs.opengroup.org/onlinepubs/9699919799/functions/mbrlen.html .
• http://www.qnx.com/developers/docs/6.5.0/index.jsp?topic=/com.qnx.doc.neutrino_lib_re/m/mbrlen.html.
• http://publib.boulder.ibm.com/infocenter/pseries/v5r3/topic/com.ibm.aix.basetechref/doc/basetrf1/mbrlen.htm.

mbrtowc

Function of mbrtowc()

mbrtowc() convert the multibyte character to wide character using conversion states

SYNOPSIS of a function mbrtowc():

#include <wchar.h>

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

putwc

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.

wcscat

Syntax

#include <wchar.h>
wchar_t *wcscat(wchar_t *a, const wchar_t *b);

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

#include <stdio.h>
#include <wchar.h>
#define SIZE 32

int main() {

      wchar_t destination[SIZE] = L"Hello"; /*SIZE should be sufficient enough to store both strings and NULL termination '\0' */
      wchar_t * source  = L" World";
      wchar_t * ptr;

      ptr = wcscat( destination, source );
      printf(" %ls\n", ptr ); /* prints "hello World"*/
     /*OR printf("%ls\n" , destination);*/

      return 0;

}

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

#include <wchar.h>
      int wcscmp(const wchar_t *s1, const wchar_t *s2);

Sample program which uses function wcsncmp

#include <stdio.h>
#include <wchar.h>
int main() {
        wchar_t string1[] = L"char";
        wchar_t string2[] = L"character";
        int difference;

        difference = wcscmp( string1, string2 );
        if ( difference == 0 )
                printf( " Both strings are same"  );
        else {
                if ( difference < 0 )
                        printf( " char is less than character\n" );
                else
                        printf(" char is greater than character\n" );
        }
        return 0;
}

Output of program will be 'char is less than character '
as value of difference is negative.

wcsncmp

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.