The scanf, fscanf, and sscanf family of textual scanning functions (hereinafter referred to only as scanf), can be used to parse objects of type Array, Matrix, and Vector, collectively known as rtables.

Parsing specifications for scanf are introduced by the "%" character, as described in the scanf help page. However, the occurrence of "{" in the specification alters the interpretation of the remainder in a way specific to parsing rtables:

The initial optional "*" means the same as it does for all scanf formats, which is to perform the parse but discard the result. Any other "*" appearing in an rtable scanf specification indicates that the appropriate information will be specified by additional parameters to scanf, much like the meaning of * in printf.

Normally, an optional width could follow, but for the rtable formats, this comes after the options, because the width applies to the individual elements being scanned, not the rtable as a whole.

The rtable parsing flags are enclosed in braces, "{}", and are broken into two sections, dimensions and options, separated by a semicolon. The semicolon may be left out if no options occur after the dimensions.

The optional modifiers are the same as for any scanf format (one of "l", "L", "z", or "Z").

The basefmt is any valid scanf format code (for example, "f").

If the basefmt is one of "a" or "s", the normal behavior of that format is modified slightly. The "a" and "s" formats usually scan only up to the first whitespace character (space, tab, or newline). When used as part of an rtable scanning format, and if the d(chars) option (see below) is being used, the "a" or "s" format will scan until the specified delimiter, or a newline, is encountered. This is illustrated in the examples at the end of this help page.

The rtfmt is one of "a", "m", "r", or "c", indicating that the result of scanning should be an Array, Matrix, Vector[row], or Vector[column].

The options consist of a combination of one or more of the following.

t

Interpret the file as providing the data transposed. In other words, each row of the data represents a column of the rtable. When indices are explicitly provided, the data ordering is unambiguous and this option is ignored.

F

The created rtable will be stored in Fortran (column major) order.

C

The created rtable will be stored in C (row major) order.

d(chars)

Any of the specified characters may appear between values read. This specification allows for the characters to appear as a delimiters, but their appearance is not mandatory. If the ")" character is allowed, it must be the first character specified in chars. At most 64 characters can be specified. You don't have to specify whitespace characters, since these are already allowed to appear. If a whitespace character is specified in chars, it must be the one and only character specified. In that case, fields are expected to be separated by at most one such character, and two consecutive such characters are assumed to refer to an empty entry (assumed to be zero for numeric typed rtables).

b(b1,b2), b-(b1,b2), or b+(b1,b2),

Each row of data gives a band of the Matrix, starting with the sub-diagonals (if b- was specified) or super-diagonals (if b+ was specified), or only the necessary-to-specify elements one row at a time (if b was specified). The (b1,b2) part specifies the number of sub- and super-diagonals. The ",b2" part is optional; if omitted, b2 = b1 is assumed. This specification only concerns the format of the parsed data; it does not affect the indexing functions or storage format, which will be rectangular unless otherwise specified using the s option.

u, u-, or u+

Each row of data gives only the necessary-to-specify elements of an upper triangular Matrix, strict upper triangular Matrix, or upper Hessenberg Matrix, respectively. Thus, each row is one shorter than the one before it. This specification only concerns the format of the parsed data; it does not affect the indexing functions or the storage format, which will be rectangular unless specified otherwise with the s option.

l, l-, or l+

Each row of data gives only the necessary-to-specify elements of a lower triangular Matrix, strict lower triangular Matrix, or lower Hessenberg Matrix. Thus, each row is one longer than the one before it. This specification only concerns the format of the parsed data; it does not affect the indexing functions or the storage format, which will be rectangular unless specified otherwise with the s option.

e(numElems)

Each row of data gives one entry, as a set of indices followed by a value, and there are numElems such entries. The number of indices expected is determined from the number of dimensions that were specified. The value of numElems may be specified as *. You can also omit(numElems), in which case numElems is computed from the specified dimensions. This specification only concerns the format of the parsed data; it does not affect the indexing functions or the storage format, which will be rectangular unless specified otherwise with the s option.

v(numElems)

The data is a set of vectors, the first of which give the indices (one index per vector), and the last one of which gives the values. There are numElems entries per vector. The number of index vectors expected is determined from the number of dimensions that were specified. The value of numElems may be specified as *. You can also omit (numElems), in which case numElems is computed from the specified dimensions. This specification only concerns the format of the parsed data; it does not affect the indexing functions or storage format, which will be rectangular unless specified otherwise with the s option.

y(dataType)

Indicates that the created table will have the specified dataType. See also in, fn, and c n that follow.

If the specified dataType is a numeric type, and the basefmt is "v" or "V", an "l" modifier is implied (i.e. the basefmt is treated as if it were "lv" or "lV"). This ensures that the CSV-formatted data is interpreted as numbers if possible.

a

Indicates that the created table will have dataType anything. This is equivalent to y(anything). This is the default except as specified for in and fn in the following section.

in where n must be 1, 2, 4, 8, or *.

Indicates that the created rtable will have a dataType of integer[n]. This is equivalent to y(integer[n]), and it is the default if the basefmt is for an integer format (i.e. "d", "o", or "x").

fn where n must be 8 or *.

Indicates that the created rtable will have a dataType of float[8]. This is equivalent to y(float[8]), and it is the default if the basefmt is a floating-point format (i.e. "e", "f", or "g").

cn where n must be 8 or *.

Indicates that the created rtable will have a dataType of complex[8]. In this case, the basefmt is applied to the real and the imaginary parts of the input. This is equivalent to y(complex[8]), and it is the default if the basefmt contains a complex format flag ("zc" or "Z").

r

The created rtable will be read-only when completed.

x(indfns) where indfns is a sequence of indexing functions, or *.

Specifies the indexing functions of the created rtable. If the indfns themselves have parameters (such as band[b]), these can also be specified as *.

s(storage) where storage is an rtable storage layout, or *.

Specifies the storage format of the created rtable. If storage itself has parameters (such as band[b]), these can also be specified as *.

h(numElems)

Reads a file of hardware floats and produces a dense rectangular rtable with C ordering, and no indexing functions (compatible with the hfarray of Maple V Release 5). The numElems is optional, and specifies the approximate number of elements (which will preallocate the appropriate storage). This format option gives the behavior of the %hX formats of Release 5.

m(mismatchValue)

Specifies the value that is to be assigned to an rtable element if the scanned value is not type-compatible with the rtable. The mismatchValue is optional, and if omitted, a suitable value compatible with the rtable is used (zero for numeric tables, $''''$ for strings, false for booleans, and NULL for other tables).

Note that the mismatch value is only used if the scanf format successfully scanned a value, and that value is not compatible with the rtable. If the data in the input doesn't even match the scanf format, an exception will be raised, and the mismatch value will not be used. Thus, this option is primarily useful in conjunction with the "%v" and "%V" formats when reading CSV files into numeric rtables. Any non-numeric values will be converted to the mismatchValue (which then should be numeric).

The mismatch value option is also useful when reading into rtables of other specific types. For example, if the option y(posint) was specified, an $m\left(99999\right)$ option would cause all non-positive integers (i.e. 0 and negative integers) that were read to be turned into 99999.

o(postEOFValue)

Specifies the value that is to be assigned to an rtable element if the end of the input (typically a file) is reached before the rtable has been filled. The postEOFValue is optional, and if omitted, a suitable value compatible with the rtable is used (zero for numeric tables, $''''$ for strings, false for booleans, and NULL for other tables).

In all of the above, * means that a corresponding extra parameter to scanf is expected, and the * is replaced with the line-printed form of that parameter. Note that this is more like the use of * in printf, and is different from the usual use of * in scanf. Usually, * means to scan but to not return the specified object (that is, to skip over it).

For backward compatibility with Maple V Release 5, the %he, %hf, %hg, and %hx will still work as well. In general,

are equivalent to,

for code in {"e", "f", "g", "y"}, and %hx is a synonym for %hy.

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".

$\mathrm{sscanf}\left(''1\; 2\; 3\; 4''\,''\%\{2,2\}fm''\right)$

$\left[\left[\begin{array}{cc}1.& 2.\\ 3.& 4.\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\; 2\; 3\; 4''\,''\%\{4\}fr''\right)$

$\left[\left[\begin{array}{cccc}1.& 2.& 3.& 4.\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\; 2\backslash n3\; 4''\,''\%\{;h\}fa''\right)$

$\left[\left[\begin{array}{cc}1.& 2.\\ 3.& 4.\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\; 1\; 3+2I\backslash n2\; 2\; 4-5I''\,''\%\{3,3;e(2)c8\}Zfm''\right)$

$\left[\left[\begin{array}{ccc}3.+2.\mathrm{I}& 0.+0.\mathrm{I}& 0.+0.\mathrm{I}\\ 0.+0.\mathrm{I}& 4.-5.\mathrm{I}& 0.+0.\mathrm{I}\\ 0.+0.\mathrm{I}& 0.+0.\mathrm{I}& 0.+0.\mathrm{I}\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\backslash t2\backslash nabc\; 123\backslash t4''\,''\%\{2,2;d(\backslash t)\}sm''\right)$

$\left[\left[\begin{array}{cc}''1''& ''2''\\ ''abc\; 123''& ''4''\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\backslash t2\backslash nabc\; +\; 123\backslash t1\; /\; (x+y)''\,''\%\{2,2;d(\backslash t)\}am''\right)$

$\left[\left[\begin{array}{cc}1& 2\\ \mathrm{abc}+123& \frac{1}{x+y}\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1,2,,\backslash n3,x,5,\backslash n6,y,8,9\backslash n''\,''\%\{3,4\}vm''\right)$

$\left[\left[\begin{array}{cccc}''1''& ''2''& ''''& ''''\\ ''3''& ''x''& ''5''& ''''\\ ''6''& ''y''& ''8''& ''9''\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1,2,,\backslash n3,x,5,\backslash n6,y,8,9\backslash n''\,''\%\{3,4;f8m(-1)\}vm''\right)$

$\left[\left[\begin{array}{cccc}1.& 2.& 0.& 0.\\ 3.& \mathrm{-1.}& 5.& 0.\\ 6.& \mathrm{-1.}& 8.& 9.\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\; 2''\,''\%\{2,3;o(999)\}dm''\right)$

$\left[\left[\begin{array}{ccc}1& 2& 999\\ 999& 999& 999\end{array}\right]\right]$

$\mathrm{sscanf}\left(''1\; -2\; -3\; 4''\,''\%\{2,2;y(posint)m(9999)\}dm''\right)$

$\left[\left[\begin{array}{cc}1& 9999\\ 9999& 4\end{array}\right]\right]$