function
<cwchar>

fgetws

wchar_t* fgetws (wchar_t* ws, int num, FILE* stream);
Get wide string from stream
Reads wide characters from stream and stores them as a C wide string into ws until (num-1) characters have been read or either a newline or the end-of-file is reached, whichever happens first.

A newline wide character makes fgetws stop reading, but it is considered a valid character by the function and included in the string copied to ws.

A terminating null character is automatically appended after the characters copied to ws.

The external representation of wide characters in files are multibyte characters: These are translated as if mbrtowc was called (using the stream's internal mbstate_t object).

The function behaves as if fgetwc was used to read the characters from the stream.

This is the wide character equivalent of fgets (<cstdio>).

Parameters

ws
Pointer to an array of wchar_t where the wide string read is copied.
num
Maximum number of characters to be copied into str (including the terminating null-character).
stream
Pointer to a FILE object that identifies an input stream.
stdin can be used as argument to read from the standard input.
The stream shall not have an orientation yet, or be wide-oriented (the first i/o operation on a stream determines whether it is byte- or wide- oriented, see fwide).

Return Value

On success, the function returns str.
If the end-of-file is encountered while attempting to read a character, the eof indicator is set (feof). If this happens before any characters could be read, the pointer returned is a null pointer (and the contents of str remain unchanged).
If a read error occurs, the error indicator (ferror) is set and a null pointer is also returned (but the contents pointed by str may have changed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/* fgetws example */
#include <stdio.h>

int main()
{
   FILE * pFile;
   wchar_t mystring [100];

   pFile = fopen ("myfile.txt" , "r");
   if (pFile != NULL)
   {
     if ( fgetws (mystring , 100 , pFile) != NULL )
       fputws ( mystring, stdout );
     fclose (pFile);
   }
   return 0;
}

This example reads the first line of myfile.txt or the first 99 characters, whichever comes first, and prints them on the screen.

See also