Read text in specified format from character string
int __far sscanf(const char __far *s, const char __far *format, ...);
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.
This function converts the input from the string indicated by s, and assigns the conversion result to the object indicated by the argument following format. 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:
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.
The assignment suppression character "*" suppresses assignment of the input field.
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.
This is an arbitrary optional size character h, l, ll, 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 an int or unsigned int argument. Furthermore, a following f, e, E, g, or G type specification is forcibly applied to a float argument, and an n type specification is forcibly applied to an int pointer.
When h is specified, a following d, i, o, u, x, or X type specification is forcibly applied to a short int or unsigned short int argument. When h is specified, a following f, e, E, g, or G type specification is forcibly applied 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 long or unsigned long argument. When l is specified, a following f, e, E, g, or G type specification is forcibly applied 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 long long and unsigned long long argument. Furthermore, for ll, a following n type specification is forcibly applied to a long long pointer.
When L is specified, a following f, e, E, g, or G type specification is forcibly applied to a long double argument. However, the double type and long double type have the same format in this compiler.
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.
Make sure that a floating-point number (type specification characters e, f, g, E, 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.
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. |
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.
The next character in the input field does not match the corresponding ordinary character in the string to be converted. |
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. |