out1, out2, … = StrRead(s, [format], [cycle], [delimiter])

s

The subject string.

format

The format string specifying how to read the string. It can have specific format specification fields (see below). The format is cycled until the end of the string or number of times specified by the optional parameter cycle. If the format is not supplied then the subject string is assumed to be white space separated numeric entries.

cycle

An optional integer specifying the number of format specifier cycles. It is ignored when no format specifier is provided. Non-integer values are rounded down to nearest integer.

delimiter

An optional string specifying the delimiter used to separate each entry in the subject string. Defaults to space.

out1, out2,…

A set of outputs. The number of outputs equals the number of format specifiers in the format string. The outputs are matrices for numeric format specifiers and tables otherwise. In case of a mismatch between the format string and the subject string, the relevant outputs are returned as empty.

A format specification, which consists of optional and required fields, has the following form, starting with the escape character %:

% [width] [.precision]type

type

A required character field that specifies how the associated argument is to be interpreted, either as a character, string, or number.  It can be any of these:

d

Decimal signed integer.

c

Character.

s

String.

f

Floating double precision.

*

Ignore the characters following this symbol.

width

An optional integer that causes to read at most that many characters for conversion to the desired type.

precision

An optional integer.  For a non-integer numeric type, causes the decimal portion of the output to be expressed in at least precision digits.  For string type, causes the output to be truncated at precision characters.

Example 1

Read a string with numeric entries separated by white space.

a = StrRead('0.41 2.24 3.67 8.23 91.27'); print(a)

[Matrix] 1 x 5

         0.41  2.24  3.67  8.23  91.27

Example 2

Read the same string, but in pairs, and store each element of the pair in two different matrices.

a,b = StrRead('0.41 2.24 3.67 8.23 91.27', ‘%f%f’); print(a,b)

[Matrix] 1 x 3

         0.41  3.67  91.27

[Matrix] 1 x 2

         2.24  8.23

Example 3

Read the string as integer.

a = StrRead('0.41 2.24 3.67 8.23 91.27', ‘%d’); print(a)

[Matrix] 1 x 5

         0  2  3  8  91

Example 4

Read the string as integer, but only the first three numbers.

a = StrRead('0.41 2.24 3.67 8.23 91.27', ‘%d’, 3); print(a)

[Matrix] 1 x 3

         0  2  3

Example 5

Read up to four characters at a time and retain only the single digit after the decimal.

a = StrRead('0.41 2.24 3.67 8.23 91.27', ‘%4.1f’); print(a)

[Matrix] 1 x 5

         0.40 2.20 3.60 8.20 91.20

Example 6

Read the strings and numbers in separate variables.

a,b = StrRead('Section 1 Page 2 Line 10',‘%s%d’); print(a[1],a[2],a[3]);print(‘\n’,b)

Section    Page    Line

[Matrix] 1 x 3

   1  2  10

Example 7

Read the characters only, but ignore the numbers.

a = StrRead('a10 b20 c30','%c%*d'); print(a[1],a[2],a[3])

a        b        c

Example 8

Read numbers separate by commas instead of spaces

a = StrRead('0.41,2.24,3.67,8.23,91.27','%f', ','); print(a)

[Matrix] 1 x 5

         0.41  2.24  3.67  8.23  91.27

t = Sscanf(s, format, [cycle])

s

The subject string.

format

The format string specifying how to read the string.  It can have specific format specification fields (see below). The format is cycled until the end of the string or number of times specified by the optional parameter cycle.

cycle

An optional integer specifying the number of format-specifier cycles. Non-integer values are rounded down to nearest integer.

t

A table of matched items. Empty if no matches found.

A format specification, which consists of optional and required fields, has the following form starting with the escape character %:

% [width] [.precision]type

type

A required character field that specifies how the associated argument is to be interpreted, either as a character, string, or number.  It can be any of these:

d

Decimal signed integer.

c

Character.

s

String.

f

Floating double precision.

*

Ignore the characters following this symbol.

[]

Matches all characters inside brackets. If the ^ is present, [^…] then matches all characters not inside brackets.

width

An optional integer that causes to read at most that many characters for conversion to the desired type.

precision

An optional integer.  For a non-integer numeric type, causes the decimal portion of the output to be expressed in at least precision digits.  For string type, causes the output to be truncated at precision characters.

Example 1

Reads a string formatted as numbers.

t = Sscanf('0.41 6.24  1.20', '%f'); print(t[1],t[2],t[3])

0.41 6.24  1.20

Example 2

Reads only the first two numbers.

t = Sscanf('0.41 6.24  1.20','%f',2); print(t[1],t[2])

0.41        6.24

Example 3

Reads up to one decimal point.

t = Sscanf('0.41 6.24  1.20','%3f%*c'); print(t[1],t[2],t[3])

0.40        6.20        1.20

Example 4

Read the first four characters including the space as a single item and the number separately.

t = Sscanf('ab c 1','%4c%*c%d'); print(t[1],t[2])

ab c        1

Example 5

Read up to non-matching characters in brackets as a single item.

t = Sscanf('a bx', '%[ acb]'); print(t[1])

a b

Example 6

Alternatively read until any matching characters in the bracket is found.

t = Sscanf('a bx', '%[^x]'); print(t[1])

a b

fid

The file handle.

format

The format string specifying how to read the string.  It can have specific format specification fields (see below). The format is cycled until the end of the. See function Sscanf.

t

An array of tables of matched items. Empty if no matches found.

Example

Assume the file contents as below:

A B

C

Then, the contents can be read as follows:

fid = Open('filename')

t = FScanf(fid, '%s'); // the output will be an array of two tables

print(t[1][1],t[1][2]); // print the first line

A        B

print(t[2][1]); // print the second line

C