HP 3000 Manuals HP 3000 Manuals
sscanf
Reads formatted data from a character string in memory.
Syntax
#include <stdio.h>
int sscanf (const char *string, const char *format
[,item [,item]...]);
Parameters
string A pointer to a buffer in memory containing the formatted
data to be read.
format A pointer to a character string defining the format of the
data to be read (or the character string itself enclosed in
double quotes).
item The address of a variable into which the data will be
placed. Refer below for descriptions of conversion
specifications.
Return Values
>=0 The number of successfully matched and assigned input
items.
EOF An error occurred on input (no input characters, or a
matching error occurred before any conversion).
Description
The sscanf function reads externally formatted data from a buffer in
memory, converts the data to internal format, and stores the results in a
group of arguments. The format consists of white-space characters,
conversion specifications, and literal characters.
The sscanf function returns the number of successfully matched and
assigned input items or returns EOF if there are no input characters
available or if a matching error occurred before any conversion was made.
This function behaves identically to the scanf() function except that
sscanf() reads data from a character string instead of from stdin.
White-Space Characters
White-space characters (blanks, tabs, newlines, or form feeds) cause
input to be read up to the next non-white-space character.
Conversion Specifications
A conversion specification is a character sequence that tells sscanf()
how to interpret the data received at that point in the input.
In the format, a conversion specification is introduced by a percent sign
(%), optionally followed by an asterisk (*) (called the assignment
suppression character), optionally followed by an integer value (called
the field width). The conversion specification is terminated by a
character specifying the type of data to expect; the terminating
characters are called conversion characters. The integer and
floating-point conversion characters may be optionally preceded by a
character indicating the size of the receiving variable.
When a conversion specification is encountered in a format, it is matched
up with the corresponding item in the item list. The data formatted by
that specification is then stored in the location pointed to by that
item. For example, if there are four conversion specifications in a
format, the first specification is matched up with the first item, the
second specification with the second item, and so on.
The number of conversion specifications in the format is directly related
to the number of items specified in the item list. With one exception,
there must be at least as many items as there are conversion
specifications in the format. If there are too few items in the item
list, an error occurs; if there are too many items, the excess items are
ignored. The one exception occurs when the assignment suppression
character (*) is used. If an asterisk occurs immediately after the
percent sign (before the field width, if any), the data formatted by that
conversion specification is discarded. No corresponding item is expected
in the item list; this is useful for skipping over unwanted data in the
input.
Conversion Characters
There are 14 conversion characters: five format integer data, three
format character data, three format floating-point data, and three
special characters.
The integer conversion characters are:
d A decimal integer is expected.
i A signed integer is expected.
o An octal integer is expected.
u An unsigned decimal integer is expected.
x A hexadecimal integer is expected.
The character conversion characters are:
c A single character is expected, normal skip over
leading white space is suppressed.
s A character string is expected.
[ A character string is expected, normal skip over
leading white space is suppressed.
The floating-point conversion characters are:
e, f, g A floating-point number is expected. (The
capitalized forms of these characters are also
accepted.)
The special characters are:
p Matches an implementation-defined set of sequences.
n No input is consumed. The corresponding argument
is a pointer to an integer into which is written
the number of characters read from the input stream
so far by this call to fscanf().
% Matches a single %. No conversion or assignment
occurs. The complete conversion specification is
&%&%
Integer Conversion Characters
The d, o, and x conversion characters read characters from string until
an inappropriate character is encountered, or until the number of
characters specified by the field width, if given, is exhausted
(whichever comes first).
For d, an inappropriate character is any character except +, -, and 0
through 9. For o, an inappropriate character is any character except +,
-, and 0 through 7. For x, an inappropriate character is any character
except +, -, 0 through 9, and the characters a through f and A through F.
Note that negative octal and hexadecimal values are stored in their twos
complement form with sign extension. Thus, they might look unfamiliar if
you print them out later using printf().
These integer conversion characters can be preceded by a l to indicate
that a long int should be expected rather than an int. They can also be
preceded by h to indicate a short int. The corresponding items in the
item list for these conversion characters must be pointers to integer
variables of the appropriate length.
Character Conversion Characters
The c conversion character reads the next character from string no matter
what that character is. The corresponding item in the item list must be
a pointer to a character variable. If a field width is specified, the
number of characters indicated by the field width are read. In this
case, the corresponding item must refer to a character array large enough
to hold the characters read.
Note that strings read using the c conversion character are not
automatically terminated with a null character in the array. Because all
C library functions that use strings assume the existence of a null
terminator, be sure to add the '\0' character yourself. If you do not,
library functions are not able to tell where the string ends, and you
will get unexpected results.
The s conversion character reads a character string from string, which is
delimited by one or more space characters (blanks, tabs, or newlines).
If field width is not given, the input string consists of all characters
from the first nonspace character up to (but not including) the first
space character. Any initial space characters are skipped over. If a
field width is given, characters are read, beginning with the first
nonspace character, up to the first space character, or until the number
of characters specified by the field width is reached (whichever comes
first). The corresponding item in the item list must refer to a
character array large enough to hold the characters read, plus a
terminating null character, which is added automatically.
The s conversion character cannot be made to read a space character as
part of a string. Space characters are always skipped over at the
beginning of a string, and they terminate reading whenever they occur in
the string. For example, suppose you want to read the first character
from the following input line:
" Hello, there!"
(Ten spaces followed by "Hello, there!"; the double quotes are added for
clarity). If you use %c, you get a space character. However, if you use
%1s, you get "H" (the first nonspace character in the input).
The [ conversion character also reads a character string from string.
However, you should use this character when a string is not to be
delimited by space characters. The left bracket is followed by a list of
characters, and is terminated by a right bracket. If the first character
after the left bracket is a circumflex (^), characters are read from
string until a character is read that matches one of the characters
between the brackets. If the first character is not a circumflex,
characters are read from string until a character not occurring between
the brackets is found. The corresponding item in the item list must
refer to a character array large enough to hold the characters read, plus
a terminating null character, which is added automatically. In some
implementations, a minus sign (-) may specify a range of characters.
The three string conversion characters provide you with a complete set of
string-reading capabilities. The c conversion character can be used to
read any single character, or to read a character string when the exact
number of characters in the string is known beforehand. The s conversion
character enables you to read any character string that is delimited by
space characters and is of unknown length. Finally, the [ conversion
character enables you to read character strings that are delimited by
characters other than space characters, and which are of unknown length.
Floating-Point Conversion Characters
The e, f, and g (or E, F, and G, respectively) conversion characters read
characters from string until an inappropriate character is encountered,
or until the number of characters specified by the field width, if given,
is exhausted (whichever comes first).
The e, f, and g characters expect data in the following form: an
optionally signed string of digits (possibly containing a decimal point),
followed by an optional exponent field consisting of an E or e followed
by an optionally signed integer. Thus, an inappropriate character is any
character except +, -, ., 0 through 9, E, or e.
These floating-point conversion characters may be preceded by a lowercase
L (l), to indicate that a double value is expected rather than a float,
or by an uppercase L (in ANSI C) to indicate that a long double value is
expected rather than a float. The corresponding items in the item list
for these conversion characters must be pointers to floating-point
variables of the appropriate length.
Literal Characters
Any characters included in the format that are not part of a conversion
specification are literal characters. A literal character is expected to
occur in the input at exactly that point. Note that since the percent
sign is used to introduce a conversion specification, you must type two
percent signs (%%) to get a literal percent sign.
Examples
The following program reads a string from stdin, stores the string in the
character array string, and prints the first word of the string.
#include <stdio.h>
main()
{
char string[80], word[25], *gets();
/* get the string */
printf("Enter your string: ");
gets(string);
/* get the first word */
sscanf(string, "%s", word);
printf("The first word is %s.\n", word);
}
The sscanf() function is often used to convert ASCII characters into
other forms, such as integer or floating-point values. For example, the
following program uses sscanf() to implement a five-function calculator:
#include <stdio.h>
main()
{
char line[80], *gets(), op[4];
long n1, n2;
double arg1, arg2;
/* print prompt (>) and get input */
printf("\n> ");
gets(line);
/* begin loop */
while(line[0] != 'q') {
sscanf(line, "%*s%s", op);
if(op[0] == '+') {
sscanf(line, "%lf%*s%lf", &arg1, &arg2);
printf("Answer: %g\n\n", arg1+arg2);
} else if(op[0] == '-') {
sscanf(line, "%lf%*s%lf", &arg1, &arg2);
printf("Answer: %g\n\n", arg1-arg2);
} else if(op[0] == '*') {
sscanf(line, "%lf%*s%lf", &arg1, &arg2);
printf("Answer: %g\n\n", arg1*arg2);
} else if(op[0] == '/') {
sscanf(line, "%lf%*s%lf", &arg1, &arg2);
printf("Answer: %g\n\n", arg1/arg2);
} else if(op[0] == '%') {
sscanf(line, "%ld%*s%ld", &n1, &n2);
while(n1 >= n2)
n1 -= n2;
printf("Answer: %ld\n\n", n1);
} else
printf("Can't recognize operator: %s\n\n", op);
printf("> ");
gets(line);
}
}
The calculator program above accepts input lines having the form
value operator value
where value is any number, and operator is the symbol +, -, *, /, or %,
representing addition, subtraction, multiplication, division, or
remainder, respectively. All functions, except for the remainder
function, are performed in floating-point values; values for these
functions can be entered with or without a decimal point. Values for the
remainder function must not have a decimal point. There must be at least
one space between each value and the operator.
Note that in this program, the entire input line is read using gets().
Then, the different parts of the input line are read from line using
sscanf(). The input line is stored as an ASCII string in line, but
portions are converted to floating-point or integer values, depending on
the operator.
Examples of valid entries are
15.778 * 3.89
27 % 8
17 + 39.72
The program terminates when it reads a line beginning with the letter
"q", such as "quit".
There are two differences between reading data from stdin and reading
data from a string. First, reading data from stdin causes that data to
no longer remain in stdin. This is not true for a string. Because the
data is stored in a string, the data remains in memory, even if that data
has been read several times. Second, because the data read from stdin
disappears as you read it, the next read operation from stdin always
begins when the previous read operation is terminated. This is not true
when you read from a string using sscanf().
Each successive read operation starts at the beginning of the string.
Thus, if you want to read five words from a string stored in a character
array, you must read the words in a single sscanf() call. If you try to
read one word in five separate sscanf() calls, each call starts reading
at the beginning of the string and so you read the same word five times.
See Also
getc(), setlocale(), printf(), strtod(), strtol(), ANSI C 4.9.6.6,
POSIX.1 8.1