C++ Standard Library C++ STL Library

C++ <cwchar> - vfwscanf() Function



The C++ <cwchar> vfwscanf() function reads data from the stream, interprets it according to parameter format and stores the results into the locations pointed by the elements in the variable argument list identified by vlist.

Internally, the function retrieves arguments from the list identified by vlist as if va_start was used on it, and thus the state of vlist is likely altered by the call.

In any case, vlist should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

The multibyte characters of file are interpreted as wide characters as if mbrtowc() function is called to translate (using the stream's internal mbstate_t object).

Note: This function is wide character equivalent of vfscanf() function.

Syntax

int vfwscanf ( FILE * stream, const wchar_t* format, va_list vlist );

Parameters

stream Specify a pointer to a FILE object that specifies an input stream to read data from.
format

Specify the C wide string that contains a format string. The format string contains a sequence of characters that control how characters extracted from the stream are treated:

  • Whitespace characters: any single whitespace character in the format string consumes all available consecutive whitespace characters from the input (determined as if by calling iswspace() in a loop). Note that there is no difference between "\n", " ", "\t\t", or other whitespace in the format string.
  • Non-whitespace character, except format specifier (%): each such character in the format string consumes exactly one identical character from the input stream, or causes the function to fail if the next character on the stream does not compare equal.
  • Format specifiers: A sub-sequence beginning with % is used to specify the type and format of the data to be retrieved from the stream and stored into the locations pointed by the additional arguments.

A format specifier for wscanf() follows this prototype:

%[*][width][length]specifier

The following format specifiers are available:

specifierDescriptionCharacters extracted
iIntegerAny number of digits, optionally preceded by a sign (+ or -).
Decimal digits assumed by default (0-9), but a 0 prefix introduces octal digits (0-7), and 0x hexadecimal digits (0-f).
Signed argument.
d or uDecimal integerAny number of decimal digits (0-9), optionally preceded by a sign (+ or -).
d is for a signed argument, and u for an unsigned.
oOctal integerAny number of octal digits (0-7), optionally preceded by a sign (+ or -).
Unsigned argument.
x,  XHexadecimal integerAny number of hexadecimal digits (0-9, a-f, A-F), optionally preceded by 0x or 0X, and all optionally preceded by a sign (+ or -).
Unsigned argument.
a,  A
f,  F
e,  E
g,  G
Floating point numberA series of decimal digits, optionally containing a decimal point, optionally preceded by a sign (+ or -) and optionally followed by the e or E character and a decimal integer (or some of the other sequences supported by wcstof()).
Implementations complying with C99 also support hexadecimal floating-point format when preceded by 0x or 0X.
cCharacterThe next character. The function reads exactly width characters and stores them in the successive locations of the array passed as argument. No null character is appended at the end.
sString of charactersAny number of non-whitespace characters, stopping at the first whitespace character found. A terminating null character is automatically added at the end of the stored sequence.
pPointer addressA sequence of characters representing a pointer. The particular format used depends on the system and library implementation, but it is the same as the one used to format %p in fwprintf().
[characters]ScansetAny number of the characters specified between the brackets.
A dash (-) that is not the first character may produce non-portable behavior in some library implementations.
[^characters]Negated scansetAny number of characters none of them specified as characters between the brackets.
nCountNo input is consumed.
The number of characters read so far and stored in the pointed location.
%%A % followed by another % matches a single %.

Except for n, at least one character shall be consumed by any specifier. Otherwise the match fails, and the scan ends there.

Additional format values can be placed between the % and the specifier (also known as sub-specifier), which are as follows:

subs‑specifierDescription
*An optional starting asterisk indicates that the data is to be read from the stream but ignored (i.e. it is not stored in the location pointed by an argument).
widthSpecifies the maximum number of characters to be read in the current reading operation (optional).
lengthModifies the length of the data type. For example - %i is used for signed decimal integer, with ll length sub-specifier it becomes %lli which can be used for long long int data type. Here is the complete list of length sub-specifier.
vlist Specify a variable argument list containing the receiving arguments initialized with va_start.

Return Value

Returns number of receiving arguments successfully assigned (which may be zero in case a matching failure occurred before the first receiving argument was assigned), or EOF if input failure occurs before the first receiving argument was assigned.

If a reading error happens or the end-of-file is reached while reading, the proper indicator is set (feof() or ferror()). And, if either happens before any data could be successfully read, EOF is returned.

If an encoding error occurs while interpreting wide characters, errno is set to EILSEQ.

Example: vfwscanf() example

Lets assume that we have a file called employees.txt. This file contains following content:

John  25  3000
Marry 24  2750
Jo  27  2800
Kim 30  3100
Ramesh  28  3000

In the example below, the file is opened using fopen() function. Then the content of the file is parsed according to the specified format using vfwscanf() function. After performing this operation, it is closed using fclose() function.

#include <cwchar>
#include <cstdio>
#include <cstdarg>

void ScanFormatted ( FILE * stream, const wchar_t * format, ... ) {
  va_list args;
  va_start(args, format);
  vfwscanf(stream, format, args);
  va_end(args);
}

int main (){
  wchar_t name [80];
  int age, salary;

  //open the file in read mode
  FILE *pFile = fopen("employees.txt", "r");

  //reads data from the file until EOF is reached
  while (!feof(pFile)) {
    ScanFormatted(pFile, L"%ls %i %i", name, &age, &salary);
    wprintf(L"%ls is %i years old and earns %i dollars.\n", name, age, salary);
  }

  //closing the file
  fclose(pFile);

  return 0;
}

The output of the above code will be:

John is 25 years old and earns 3000 dollars.
Marry is 24 years old and earns 2750 dollars.
Jo is 27 years old and earns 2800 dollars.
Kim is 30 years old and earns 3100 dollars.
Ramesh is 28 years old and earns 3000 dollars.


Length sub-specifier

Specifiers
lengthd iu o x Xf F e E g G a Ac s [ ] [^]pn
(none)int*unsigned int*float*char*void**int*
hhsigned char*unsigned char* signed char*
hshort int*unsigned short int* short int*
llong int*unsigned long int*double*wchar_t* long int*
lllong long int*unsigned long long int* long long int*
jintmax_t*uintmax_t* intmax_t*
zsize_t*size_t* size_t*
tptrdiff_t*ptrdiff_t* ptrdiff_t*
L long double*

See <cinttypes> for the specifiers for extended types.


❮ C++ <cwchar> Library