sscanf (MATLAB Functions)

Read string under format control

Syntax

A = sscanf(s, format)
A = sscanf(s, format, size)
[A, count, errmsg, nextindex] = sscanf(...)

Description

A = sscanf(s, format) reads data from the MATLAB string variable s, converts it according to the specified format string, and returns it in matrix A. format is a string specifying the format of the data to be read. See "Remarks" for details. sscanf is the same as fscanf except that it reads the data from a MATLAB string variable rather than reading it from a file.

A = sscanf(s, format, size) reads the amount of data specified by size and converts it according to the specified format string. size is an argument that determines how much data is read. Valid options aren Read n elements into a column vector. inf Read to the end of the file, resulting in a column vector containing the same number of elements as are in the file. [m,n] Read enough elements to fill an m-by-n matrix, filling the matrix in column order. n can be Inf, but not m.

`n`	Read `n` elements into a column vector.
`inf`	Read to the end of the file, resulting in a column vector containing the same number of elements as are in the file.
`[m,n]`	Read enough elements to fill an `m`-by-`n` matrix, filling the matrix in column order. `n` can be `Inf`, but not `m`.

If the matrix A results from using character conversions only, and size is not of the form [M,N], a row vector is returned.

sscanf differs from its C language namesakes scanf() and fscanf() in an important respect -- it is vectorized in order to return a matrix argument. The format string is cycled through the file until an end-of-file is reached or the amount of data specified by size is read in.

[A, count, errmsg, nextindex] = sscanf(...) reads data from the MATLAB string variable s, converts it according to the specified format string, and returns it in matrix A. count is an optional output argument that returns the number of elements successfully read. errmsg is an optional output argument that returns an error message string if an error occurred or an empty matrix if an error did not occur. nextindex is an optional output argument specifying one more than the number of characters scanned in s.

Remarks

When MATLAB reads a specified file, it attempts to match the data in the file to the format string. If a match occurs, the data is written into the matrix in column order. If a partial match occurs, only the matching data is written to the matrix, and the read operation stops.

The format string consists of ordinary characters and/or conversion specifications. Conversion specifications indicate the type of data to be matched and involve the character %, optional width fields, and conversion characters, organized as shown below:

Add one or more of these characters between the % and the conversion character.

An asterisk (*)
Skip over the matched value if the value is matched but not stored in the output matrix.

A digit string
Maximum field width

A letter
The size of the receiving object; for example, h for short, as in %hd for a short integer, or l for long, as in %ld for a long integer or %lg for a double floating-point number

An asterisk (`*`)	Skip over the matched value if the value is matched but not stored in the output matrix.
A digit string	Maximum field width
A letter	The size of the receiving object; for example, `h` for short, as in `%hd` for a short integer, or `l` for long, as in `%ld` for a long integer or `%lg` for a double floating-point number

Valid conversion characters are as shown.

%c
Sequence of characters; number specified by field width

%d
Base 10 integers

%e, %f, %g
Floating-point numbers

%i
Defaults to base 10 integers. Data starting with 0 is read as base 8. Data starting with 0x or 0X is read as base 16.

%o
Signed octal integer

%s
A series of non-white-space characters

%u
Signed decimal integer

%x
Signed hexadecimal integer

[...]
Sequence of characters (scanlist)

`%c`	Sequence of characters; number specified by field width
`%d`	Base 10 integers
`%e, %f, %g`	Floating-point numbers
`%i`	Defaults to base 10 integers. Data starting with `0` is read as base 8. Data starting with `0x` or `0X` is read as base 16.
`%o`	Signed octal integer
`%s`	A series of non-white-space characters
`%u`	Signed decimal integer
`%x`	Signed hexadecimal integer
`[...]`	Sequence of characters (scanlist)

If %s is used, an element read might use several MATLAB matrix elements, each holding one character. Use %c to read space characters, or %s to skip all white space.

Mixing character and numeric conversion specifications cause the resulting matrix to be numeric and any characters read to appear as their ASCII values, one character per MATLAB matrix element.

For more information about format strings, refer to the scanf() and fscanf() routines in a C language reference manual.

Examples

Example 1

The statements

s = '2.7183  3.1416';
A = sscanf(s,'%f')

create a two-element vector containing poor approximations to e and pi.

Example 2

Create matrix A with both character and numeric data:

A = ['abc 46 6 ghi'; 'def 7 89 jkl']                                
A =
   abc 46 6 ghi
   def 7 89 jkl

Read A into 2-by-N matrix B, ignoring the character data. As stated in the Description section, sscanf fills matrix B in column order:

B = sscanf(A, '%*s %d %d %*s', [2, inf])
B =
   476
   869

If you want sscanf to return the numeric data in B in the same order as in A, you can use this technique:

for k = 1:2
   C(k,:) = sscanf(A(k, :)', '%*s %d %d %*s', [1, inf]);
end

C
C =
    46     6
     7    89

See Also

eval, sprintf, textread

ss2tf stairs