Learn more about MATLAB

sscanf - Read formatted data from string

Syntax

A = sscanf(str, format) A = sscanf(str, format, sizeA) [A, count] = sscanf(...) [A, count, errmsg] = sscanf(...) [A, count, errmsg, nextindex] = sscanf(...)

Description

A = sscanf(str, format) reads data from string str, converts it according to the format, and returns the results in array A. The sscanf function reapplies the format until either reaching the end of str or failing to match the format. If sscanf cannot match the format to the data, it reads only the portion that matches into A and stops processing. If str is a character array with more than one row, sscanf reads the characters in column order.

A = sscanf(str, format, sizeA) reads sizeA elements into A, where sizeA can be an integer or can have the form [m,n].

[A, count] = sscanf(...) returns the number of elements that sscanf successfully reads.

[A, count, errmsg] = sscanf(...) returns an error message string when the operation is unsuccessful. Otherwise, errmsg is an empty string.

[A, count, errmsg, nextindex] = sscanf(...) returns one more than the number of characters scanned in str.

Inputs

format

String enclosed in single quotation marks that describes each type of element (field). Includes one or more of the following specifiers.

Field Type Specifier Details

Integer, signed
%d
Base 10

%i
Base determined from the values. Defaults to base 10. If initial digits are 0x or 0X, it is base 16. If initial digit is 0, it is base 8.

Integer, unsigned
%u
Base 10

%o
Base 8 (octal)

%x
Base 16 (hexadecimal)

Floating-point number
%f
Floating-point fields can contain any of the following (not case sensitive): Inf, -Inf, NaN, or -NaN.

%e

%g

Character string
%s
Read series of characters, until find white space.

%c
Read any single character, including white space.
(To read multiple characters, specify field length.)

%[...]
Read only characters in the brackets, until the first nonmatching character or white space.

Optionally:

To skip fields, insert an asterisk (*) after the percent sign (%). For example, to skip integers, specify %*d.
To specify the maximum width of a field, insert a number. For example, %10c reads exactly 10 characters at a time, including white space.
To skip a specific set of characters, insert the literal characters in the format. For example, to read only the floating-point number from 'pi=3.14159', specify a format of 'pi=%f'.

sizeA

Dimensions of the output array A. Specify in one of the following forms:

`inf`	Read to the end of the input string. (default)
`n`	Read at most `n` elements.
`[m,n]`	Read at most `mn` elements in column order. `n`* can be `inf`, but `m` cannot.

When the format includes %s, A can contain more than n columns. n refers to elements, not characters.

str

Character string.

Outputs

A

An array. If the format includes:

Only numeric specifiers, A is numeric, of class double. If sizeA is inf or n, then A is a column vector. If the input contains fewer than sizeA elements, MATLAB pads A with zeros.
Only character or string specifiers (%c or %s), A is a character array. If sizeA is inf or n, A is a row vector. If the input contains fewer than sizeA characters, MATLAB pads A with char(0).
A combination of numeric and character specifiers, A is numeric, of class double. MATLAB converts each character to its numeric equivalent. This conversion occurs even when the format explicitly skips all numeric values (for example, a format of '%*d %s').

If MATLAB cannot match the input to the format, and the format contains both numeric and character specifiers, A can be numeric or character. The class of A depends on the values MATLAB reads before processing stops.

count

Number of elements sscanf reads into A.

`errmsg`	An error message string when `sscanf` cannot open the specified file. Otherwise, an empty string.
`nextindex`	`sscanf` counts the number of characters `sscanf` reads from `str`, and then adds one.

Examples

Read multiple floating-point values from a string:

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

Read an octal integer from a string, identified by the '0' prefix, using %i to preserve the sign:

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

Read numeric values from a two-dimensional character array. By default, sscanf reads characters in column order. To preserve the original order of the values, read one row at a time.

mixed = ['abc 45 6 ghi'; 'def 7 89 jkl'];

[nrows, ncols] = size(mixed);
for k = 1:nrows
    nums(k,:) = sscanf(mixed(k,:), '%*s %d %d %*s', [1, inf]);
end;

% type the variable name to see the result
nums

MATLAB returns:

nums =
    45     6
     7    89