MATLAB®

sscanf - Read formatted data from string

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 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 rather than reading it from a file. If s is a character array with more than one row, sscanf reads the characters in column order.

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 are

Characteristics of the output matrix A depend on the values read from the input string and on the size argument. If sscanf reads only numbers, and if size is not of the form [m,n], matrix A is a column vector of numbers. If sscanf reads only characters or strings, and if size is not of the form [m,n], matrix A is a row vector of characters. See the Remarks section for more information.

sscanf differs from its C language namesake scanf() in an important respect — it is vectorized to return a matrix argument. The format string is cycled through the input string until the first of these conditions occurs:

• The format string fails to match the data in the input string

• The amount of data specified by size is read

• The end of the string is reached

[A, count, errmsg, nextindex] = sscanf(...) reads data from the MATLAB string (character array) 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 values successfully read. errmsg is an optional output argument that returns an error message string if an error occurred or an empty string 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 string, it attempts to match the data in the input string to the format string. If a match occurs, the data is written into the output matrix. 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.

Valid conversion characters are as shown.

Format specifiers %e, %f, and %g accept the text 'inf', '-inf', 'nan', and '-nan'. This text is not case sensitive. The sscanf function converts these to the numeric representation of Inf, -Inf, NaN, and -NaN.

Use %c to read space characters, or %s to skip all white space.

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

Output Characteristics: Only Numeric Values Read

Format characters that cause sscanf to read numbers from the input string are %d, %e, %f, %g, %i, %o, %u, and %x. When sscanf reads only numbers from the input string, the elements of the output matrix A are numbers.

When there is no size argument or the size argument is inf, sscanf reads to the end of the input string. The output matrix is a column vector with one element for each number read from the input.

When the size argument is a scalar n, sscanf reads at most n numbers from the input string. The output matrix is a column vector with one element for each number read from the input.

When the size argument is a matrix [m,n], sscanf reads at most (m*n) numbers from the input string. The output matrix contains at most m rows and n columns. sscanf fills the output matrix in column order, using as many columns as it needs to contain all the numbers read from the input. Any unfilled elements in the final column contain zeros.

Output Characteristics: Only Character Values Read

The format characters that cause sscanf to read characters and strings from the input string are %c and %s. When sscanf reads only characters and strings from the input string, the elements of the output matrix A are characters. When sscanf reads a string from the input, the output matrix includes one element for each character in the string.

When there is no size argument or the size argument is inf, sscanf reads to the end of the input string. The output matrix is a row vector with one element for each character read from the input.

When the size argument is a scalar n, sscanf reads at most n character or string values from the input string. The output matrix is a row vector with one element for each character read from the input. When string values are read from the input, the output matrix can contain more than n columns.

When the size argument is a matrix [m,n], sscanf reads at most (m*n) character or string values from the input string. The output matrix contains at most m rows. sscanf fills the output matrix in column order, using as many columns as it needs to contain all the characters read from the input. When string values are read from the input, the output matrix can contain more than n columns. Any unfilled elements in the final column contain char(0).

Output Characteristics: Both Numeric and Character Values Read

When sscanf reads a combination of numbers and either characters or strings from the input string, the elements of the output matrix A are numbers. This is true even when a format specifier such as '%*d %s' tells MATLAB to ignore numbers in the input string and output only characters or strings. When sscanf reads a string from the input, the output matrix includes one element for each character in the string. All characters are converted to their numeric equivalents in the output matrix.

When there is no size argument or the size argument is inf, sscanf reads to the end of the input string. The output matrix is a column vector with one element for each character read from the input.

When the size argument is a scalar n, sscanf reads at most n number, character, or string values from the input string. The output matrix contains at most n rows. sscanf fills the output matrix in column order, using as many columns as it needs to represent all the numbers and characters read from the input. When string values are read from the input, the output matrix can contain more than one column. Any unfilled elements in the final column contain zeros.

When the size argument is a matrix [m,n], sscanf reads at most (m*n) number, character, or string values from the input string. The output matrix contains at most m rows. sscanf fills the output matrix in column order, using as many columns as it needs to represent all the numbers and characters read from the input. When string values are read from the input, the output matrix can contain more than n columns. Any unfilled elements in the final column contain zeros.

Note   This section applies only when sscanf actually reads a combination of numbers and either characters or strings from the input string. Even if the format string has both format characters that would result in numbers (such as %d) and format characters that would result in characters or strings (such as %s), sscanf might actually read only numbers or only characters or strings. If sscanf reads only numbers, see Output Characteristics: Only Numeric Values Read. If sscanf reads only characters or strings, see Output Characteristics: Only Character Values Read.

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

When using the %i conversion specifier, sscanf reads data starting with 0 as base 8 and returns the converted value as signed:

sscanf('-010', '%i')
ans =
    -8

When using %o, on the other hand, sscanf returns the converted value as unsigned:

sscanf('-010', '%o')
ans =
  4.2950e+009

Example 3

Create character array A representing 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 reads the characters in A in column order, filling 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