vsscanf [V1.08 or later]

Read text in specified format from character string

[Classification]

Standard library

[Syntax]

#include <stdio.h>

int __far vsscanf(const char __far * restrict s, const char __far * restrict format, va_list arg); (C99) [V1.08 or later]

[Return value]

The number of input fields for which scanning, conversion, and storage were executed normally is returned. The return value does not include scanned fields that were not stored.

If an attempt is made to read to the end of the file, the return value is EOF.

If no field was stored, the return value is 0.

[Description]

This function converts the input from the string indicated by s and assigns the conversion result to the parameter indicated by pointer arg among the parameter sequence. The conversion method in this case complies with the format specified by the string indicated by format. When copying is executed between objects whose areas overlap, correct operation is not guaranteed.

Correct operation is not guaranteed if there is not enough arguments to satisfy the format. If the format becomes full even though arguments are still left, the extra arguments are merely evaluated and they will be ignored.

The format consists of 0 or more directives, and the directives in the format are executed in sequence. If there is no input character or execution of a directive fails due to an incorrect input, processing is terminated.

The format consists of the following three types of directives:

One or more Space characters

Space ( ), tab (\t), or new-line (\n).

Reading of input data is executed up to immediately before the first non-white-space character (this character is left but not read) or until reading can no longer be performed.

Ordinary characters

All ASCII characters other than "%".

Reading is executed by reading the next character.

Conversion specification

Fetches 0 or more arguments and directs the conversion.

Each conversion specification starts with "%". The following appear after the "%":

%[assignment-suppression-character][field-width][size][type-specification-character]

Each conversion specification is explained below.

(1)	Assignment suppression character

The assignment suppression character "*" suppresses assignment of the input field.

(2)	field width

This is a positive decimal integer that defines the maximum field width. When 0 is specified, there are no regulations.

It specifies the maximum number of characters that are read before the input field is converted. If the input field is smaller than this field width, sscanf reads all the characters in the field and then proceeds to the next field and its conversion specification.

If a space character or a character that cannot be converted is found before the number of characters equivalent to the field width is read, the characters up to the white space or the character that cannot be converted are read and stored. Then, sscanf proceeds to the next conversion specification.

(3)

size

This is an arbitrary optional size character hh, h, l, ll, j, z, t, or L, which changes the default method for interpreting the data type of the corresponding argument.

If there is no specification, a following d, i, o, u, x, or X type specification is forcibly applied to a pointer to an int or unsigned int argument. Furthermore, a following f, F, e, E, g, or G type specification is forcibly applied to a pointer to a float argument, and an n type specification is forcibly applied to an int pointer.

When hh is specified, a following d, i, o, n, u, x, or X type specification is forcibly applied to a pointer to a signed char or unsigned char argument. hh also causes a following f, F, e, E, g, or G type specification to be applied to a pointer to a float argument and a following n type specification to be applied to a pointer to a signed char argument. (C99) [V1.08 or later]

When h is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a pointer to a short int or unsigned short int argument. When h is specified, a following f, F, e, E, g, or G type specification is forcibly applied to a pointer to a float argument, and an n type specification is forcibly applied to a short int pointer.

When l is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a pointer to a long or unsigned long argument. When l is specified, a following f, F, e, E, g, or G type specification is forcibly applied to a pointer to a double argument, and an n type specification is forcibly applied to a long pointer.

When ll is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a pointer to a long long or unsigned long long argument. Furthermore, for ll, a following n type specification is forcibly applied to a long long pointer.

When j is specified, a following d, i, o, n, u, x, or X type specification is forcibly applied to a pointer to a intmax_t or uintmax_t argument, and an n type specification is forcibly applied to an intmax_t pointer. (C99) [V1.08 or later]

When z is specified, a following d, i, o, n, u, x, or X type specification is forcibly applied to a pointer to a size_t or signed int argument, and an n type specification is forcibly applied to an signed int pointer. (C99) [V1.08 or later]

When t is specified, a following d, i, o, n, u, x, or X type specification is forcibly applied to a pointer to a ptrdiff_t or unsigned int argument, and an n type specification is forcibly applied to an ptrdiff_t pointer. (C99) [V1.08 or later]

When L is specified, a following f, F, e, E, g, or G type specification is forcibly applied to a pointer to a long double argument. However, the double type and long double type have the same format in this compiler.

(4)	type specification character

These are characters that specify the type of conversion that is to be applied.

The characters that specify conversion types and their meanings are as follows.

Read a decimal integer into the corresponding argument. The corresponding type is in accordance with the size character.

Read a decimal, octal, or hexadecimal integer into the corresponding argument. The corresponding type is in accordance with the size character.

Read an octal integer into the corresponding argument. The corresponding type is in accordance with the size character.

Read an unsigned decimal integer into the corresponding argument. The corresponding type is in accordance with the size character.

x, X

Read a hexadecimal integer into the corresponding argument. The corresponding type is in accordance with the size character.

e, f, g, E, F, G

Read a floating-point number, infinite value, or Not-a-Number (NaN) into the corresponding argument. The corresponding type is in accordance with the size character.

Read a string into a given array. The corresponding argument should be "char __far arg[ ]".

The pointer must always be the far pointer. When passing a constant, add a cast to the argument to clearly show that it is a pointer. Correct operation is not guaranteed when a null pointer is passed.

[ ]

Read a non-empty string into the memory area starting with argument arg. This area must be large enough to accommodate the string and the null character (\0) that is automatically appended to indicate the end of the string. The corresponding argument should be "char *arg".

The character pattern enclosed by [ ] can be used in place of the type specification character s. The character pattern is a character set that defines the search set of the characters constituting the input field of sscanf. If the first character within [ ] is "^", the search set is complemented, and all ASCII characters other than the characters within [ ] are included. In addition, a range specification feature that can be used as a shortcut is also available. For example, %[0-9] matches all decimal numbers. In this set, "-" cannot be specified as the first or last character. The character preceding "-" must be less in lexical sequence than the succeeding character.

%[abcd]

Matches character strings that include only a, b, c, and d.

%[^abcd]

Matches character strings that include any characters other than a, b, c, and d.

%[A-DW-Z]

Matches character strings that include A, B, C, D, W, X, Y, and Z.

%[z-a]

Matches z, -, and a (this is not considered a range specification).

Scan one character. The corresponding argument should be "char __far *arg".

The pointer must always be the far pointer. When passing a constant, add a cast to the argument to clearly show that it is a pointer.

Store the pointer that was scanned. The corresponding argument should be "void __far **arg".

The pointer must always be the far pointer. When passing a constant, add a cast to the argument to clearly show that it is a pointer.

Input data is not read. The number of characters that have been read so far is written to the corresponding parameter.

Even though the %n directive is executed, the number of input items that are returned when the function ends is not increased. The corresponding type is in accordance with the size character.

Match the character "%". No conversion or assignment is performed. The conversion specification is "%%".

F conversion can only be specified for C99 libraries.

Make sure that a floating-point number (type specification characters e, f, g, E, F, and G) corresponds to thefollowing general format.

[ + | - ] ddddd [ . ] ddd [ E | e [ + | - ] ddd ]

However, the portions enclosed by [ ] in the above format are arbitrarily selected, and ddd indicates a decimal digit.

[Caution]

-	sscanf may stop scanning a specific field before the normal end-of-field character is reached or may stop completely.

-	sscanf stops scanning and storing a field and moves to the next field under the following conditions.

-	The substitution suppression character (*) appears after "%" in the format specification, and the input field at that point has been scanned but not stored.

-	A field width (positive decimal integer) specification character was read.

-	The character to be read next cannot be converted according to the conversion specification (for example, if Z is read when the specification is a decimal number).

-	The next character in the input field does not appear in the search set (or appears in the complement search set).

If sscanf stops scanning the input field at that point because of any of the above reasons, it is assumed that the next character has not yet been read, and this character is used as the first character of the next field or the first character for the read operation to be executed after the input.

-	sscanf ends under the following conditions:

-	The next character in the input field does not match the corresponding ordinary character in the string to be converted.

-	The next character in the input field is EOF.

-	The string to be converted ends.

If a list of characters that is not part of the conversion specification is included in the string to be converted, make sure that the same list of characters does not appear in the input. sscanf scans matching characters but does not store them. If there was a mismatch, the first character that does not match remains in the input as if it were not read.

[Restrictions]

a or A conversion and hexadecimal floating-point numbers are not supported.