The function fscanf is based on a C standard library function of the same name. It reads characters from a file, matching numbers and substrings according to a specification in fmt. Unlike the C fscanf, the Maple version returns a list of the scanned objects.

The function sscanf is based on a C standard library function of the same name. It scans through str, matching numbers and substrings according to a specification in fmt. Unlike the C sscanf, the Maple version returns a list of the scanned objects.

The function scanf is based on a C standard library function of the same name. It reads characters from the current input stream, matching numbers and substrings according to a specification in fmt. Unlike the C scanf, the Maple version returns a list of the scanned objects.

The call scanf(fmt) is equivalent to fscanf(default, fmt).

Each of the functions fscanf, sscanf, and scanf return a list of the scanned objects.

If no objects were scanned successfully, an empty list is returned.

If no objects were scanned successfully because the end of the input was encountered immediately, 0 is returned.

The format string, fmt, is a Maple string made up of a sequence of conversion specifications, possibly separated by other characters. Each conversion specification has the following format:

The % symbol begins the conversion specification. The optional * indicates that the object is to be scanned, but not returned as part of the result (that is, it is discarded).

The width indicates the maximum number of characters to scan for this object. This can be used to scan one larger object as two smaller objects.

Modifiers

The optional modifiers are used to indicate the type of the value to be returned:

l or L

The letters "l" and "L" are supported for compatibility with the C scanf function, and indicate that a "long int" or "long long" is to be returned. In Maple, these flags have no effect, except when used with the %v or %V formats, where they indicate a desire to get numeric results when possible.

zc or Z

One of these flags can precede any of the numeric formats, namely d, o, x, e, f, or g, indicating that a complex value is to be scanned. Each of the real and imaginary parts of the complex value are scanned using the specified format with the "z" or "Z" elided. The "z" modifier scans the real part, followed by the character specified by c, followed by the imaginary part. The "Z" modifier scans the real part, followed by a "+" or "-" sign, followed by the imaginary part, followed by a string of character(s) corresponding to the current setting of interface(imaginaryunit).

The z and Z modifiers can result in one of the few conditions in which scanf will raise an exception when passed a valid format specification. If scanf is part way through scanning a complex value (for example, the real part has already been successfully scanned), and is unable to finish scanning the remainder (for example, there is no imaginary part after the real part), scanf will raise an exception of the form "`%1` expected in input for complex format", where %1 will be replaced by the expected character (for example, a comma).

Formats

The code indicates the type of object to be scanned. It determines the type of object that will be returned in the resulting list. The code can be one of the following:

Integer Formats

d

The next non-blank characters in the input must make up a signed or unsigned decimal integer. A Maple integer is returned.

o

The next non-blank characters in the input must make up an unsigned octal (base 8) integer. The integer is converted to decimal and returned as a Maple integer.

x

The next non-blank characters in the input must make up an unsigned hexadecimal (base 16) integer. The digits corresponding to the decimal numbers 10 through 15 are represented by the letters A through F (either uppercase or lowercase) in the input. The integer is converted to decimal and returned as a Maple integer.

Floating Point Formats

e, f, or g

The next non-blank characters in the input must make up a signed or unsigned decimal number, possibly including a decimal point, and possibly followed by E or e, an optional sign, and a decimal integer indicating a power of ten. The number is returned as a Maple floating-point value.

In addition to numeric values, the e, f, and g formats also recognize the special values "Inf" and "NaN". If an "I" or "N" is encountered when scanf is looking for the first digit of a number, it assumes that one of these special values has been found, and proceeds to look for the subsequent "nf" or "aN". If the rest of the special value is not found, an exception is raised.

y

The next non-blank characters in the input must make up an IEEE hex-dump format floating point value. This value must consist of sixteen hexadecimal characters. The value is converted to and returned as a Maple float.

he, hf, hg

These are special formats for reading one or two-dimensional numeric arrays. In general, such arrays should be read using the more sophisticated functionality provided by the {} format, but the he, hf, and hg formats are provided for backward compatibility with hfarrays, and provide some intelligence in automatically dealing with a variety of textual layouts of such arrays.

The following input must make up a one or two-dimensional array of floating point (or integer) values. Characters encountered during scanning are categorized into three classes: numeric, separator, and terminator. All the characters that can appear within a number (the digits, decimal point, signs, E, e, D, and d) are numeric. Any white space, commas, or square brackets are separators. A square bracket not immediately followed by a comma, and any other character, are terminators. If a backslash is encountered, it and the following character are ignored completely.

The dimensions of the array are determined by the number of lines read, and the number of values in the first line. If either of these is 1, or if the number of rows multiplied by the number of columns does not equal the total number of values read, a one-dimensional array is produced.

The definition of "the first line" is "everything read up to the first line break that does not immediately follow a comma or a backslash, or up to the first closing square bracket that IS immediately followed by a comma."

The kinds of things that can be read this way include anything that was written by the corresponding printf, "typical" tables of numbers, and lprinted or saved (in text form) Maple lists and lists of lists.

The result is returned as an hfarray of one or two dimensions.

hx

The following input must make up a one or two dimensional array of floating point numbers in IEEE hex-dump format (16 characters per number). The dimensions of the array are determined as described for the "%he", "%hf", and "%hg" formats above.

String Formats

c

The next character (blank or otherwise) is returned as a Maple string. If a width is specified, that many characters (blank or otherwise) are returned as a single Maple string.

s

The next non-blank characters, up to but not including the following blank characters (or the end of the string) are returned as a Maple string.

[...]

The characters between the left square bracket, "[", and the right square bracket, "]", are taken as a list of characters that are acceptable as a character string. Characters are scanned from the input until one is encountered that is NOT in the list. The scanned characters are then returned as a Maple string.

If the list begins with a caret, "^", the list is deemed to consist of all those characters NOT in the list.

If a right square bracket, "]", is to appear in the list, it must immediately follow the opening left square bracket, "[", or the caret, "^", if there is one.

A hyphen, "-", can be used in the list to represent a range of characters. For example, "A-Z" represents any uppercase letter. If a hyphen, "-", is to appear as a character instead of representing a range, it must appear either at the beginning or the end of the list.

Algebraic Formats

a

The next non-blank characters, up to but not including the following blank characters (or the end of the string) are collected and passed to the Maple parser. An unevaluated Maple expression is returned.

m

A single Maple expression, encoded in Maple's ".m" file format is collected from the input. Characters are read until a complete expression is parsed; the width specification is ignored.

Rectangular Table Formats

{...}wft

The characters between the left brace, "{", and the right brace, "}", are options for scanning Arrays, Matrices, or Vectors (that is, the various classes of rtable). The optional w is an integer specifying the width to scan for each element (any width specified before the opening "{" would apply to the entire rtable being scanned, but is ignored). The character f specifies the format code, and can be any format code supported by scanf{...}. The character t, which must be one of "a", "m", "c", or "r", specifies the type of object to be created (Array, Matrix, Vector[column], or Vector[row] respectively).

Details on rtable formatting options are described in the help page rtable_scanf.

Other Formats

v or V

Reads one field from a standard CSV (Comma Separated Values) file (%v), or a Microsoft CSV file (%V). The result is returned as a string, unless the L or l modifier was specified (i.e. %lv), in which case the result is returned as a number if at all possible. This includes numbers that were quoted in the CSV file (even if there are commas separating the thousands).

It is not recommended to use the width modifier with the %v format, as it will cause scanf to stop mid-field, and thus get out of sync with the field delimiters.

The behavior of %v and %V, except for differences in the file format expected:

1 - Spaces outside of quoted strings are significant in the Microsoft format, and ignored in the standard CSV format.

2 - Within strings, quotation marks are escaped by doubling them in Microsoft format, or by preceding them with a backslash in the standard format. The standard CSV format also supports additional backslash escape sequences \\ , \n, \r, \t, and \f, meaning backslash, newline, carriage return, tab, and formfeed respectively.

The %v and %V formats are often best used in conjunction with a %1[,\n] format specification, as in "%v%1[,\n]". This will cause scanf to return two values, the first of which is the value of the field, and the second the delimiter that terminated the field, which will be either "," or "\n" (newline). These correspond to field and record separators respectively in the CSV formats.

Empty fields in the input (for example, two adjacent commas, an empty quoted field, or two commas separated only be whitespace when using %v) are returned as an empty string for %v or %V, or as zero for %lv or %lV.

n

The total number of characters scanned up to the %n is returned as a Maple integer.

Non-blank characters in fmt but not within a conversion specification are skipped, but they must match the corresponding characters in the input. White space in fmt is ignored, except that a space immediately preceding a %c specification causes the %c specification to skip any blanks in the input.

The scanf functions use the underlying implementation provided by the hardware vendor for the %o and %x formats. As a result input of octal and hexadecimal integers is subject to the restrictions of the machine architecture.

With fscanf, if a file name is given, and that file is not yet open, it is opened in READ mode with type TEXT.

The scanf function will read entire lines from the default input stream, but only use up as many characters as are needed to satisfy the format specifications. The remaining characters will be saved for subsequent calls to scanf.

In the examples below, we use sscanf for the convenience of showing both the input and the parsing specification together. The first argument is the input (which would come from a file if we were using fscanf), and the second is the parsing specification. Line breaks in the input are represented by "\n".

The sscanf, fscanf and scanf commands are thread safe as of Maple 15.

Parallel calls to file i/o commands on the same file descriptor will be serialized in an arbitrary order.  If you need the commands to execute in a particular order you must use Maple's synchronization tools to enforce this.  See Threads:-Mutex.

For more information on thread safety, see index/threadsafe.

$\mathrm{sscanf}\left(''123.456E7\; 123.456E7''\,''\%g\%d.\%d\; \%[Ee]\; \%d''\right)$

$\left[1.23456\times {10}^9\,123\,456\,''E''\,7\right]$

$\mathrm{sscanf}\left(''123.456E7\; 123.456E7''\,''\%s\; \%c\%f''\right)$

$\left[''123.456E7''\,''1''\,2.3456\times {10}^8\right]$

$\mathrm{sscanf}\left(''X=123.4\; Y=-27.9\; Z=2.3E-5''\,''X=\%f\; Y=\%f\; Z=\%f''\right)$

$\left[123.4\,\mathrm{-27.9}\,0.000023\right]$

$\mathrm{sscanf}\left(''25\; 1/(x^4+1)\; test''\,''\%d\%a\%s''\right)$

$\left[25\,\frac{1}{x^4+1}\,''test''\right]$

$\mathrm{sscanf}\left(''123,\; abc\backslash n''\,''\%v\%1[,\backslash n]\%v\%1[,\backslash n]''\right)$

$\left[''123''\,'',''\,''abc''\,''''\right]$

$\mathrm{sscanf}\left(''123,\; abc\backslash n''\,''\%lV\%1[,\backslash n]\%lV\%1[,\backslash n]''\right)$

$\left[123\,'',''\,''abc''\,''''\right]$