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
- fgets
- Get string from stream (function)
- fputws
- Write wide string to stream (function)
- fgetwc
- Get wide character from stream (function)