Documentation Center

  • Trials
  • Product Updates

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.

Input Arguments

format

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

Field TypeSpecifierDetails

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.

%ld or %li

64-bit values, base 10, 8, or 16

Integer, unsigned

%u

Base 10

%o

Base 8 (octal)

%x

Base 16 (hexadecimal)

%lu, %lo, %lx

64-bit values, base 10, 8, or 16

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 m*n 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.

Output Arguments

A

An array. If the format includes:

  • Only numeric specifiers, A is numeric. If format includes only 64-bit signed integer specifiers, A is of class int64. Similarly, if format includes only 64-bit unsigned integer specifiers, A is of class uint64. Otherwise, A is 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

Example 1

Read multiple floating-point values from a string:

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

Example 2

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

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

Example 3

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 =
    45     6
     7    89

Example 4

sscanf finds one match for %s

[str count] = sscanf('ThisIsOneString', '%s')
str =
    ThisIsOneString
count =
     1

sscanf finds four matches for %s. Because it does not match space characters, there are no spaces in the output string:

[str count] = sscanf('These Are Four Strings', '%s')
str =
    TheseAreFourStrings
count =
     4

sscanf finds five word matches for %s and four space character matches for %c. Because the %c specifier does match a space character, the output string does include spaces:

[str count] = sscanf('Five strings and four spaces', '%s%c')
str =
    Five strings and four spaces
count =
    9

sscanf finds three word matches for %s and two numeric matches for %d. Because the format specifier has a mixed %d and %s format, sscanf converts all nonnumeric characters to numeric:

[str count] = sscanf('5 strings and 4 spaces', '%d%s%s%d%s');
str'
  Columns 1 through 9
     5   115   116   114   105   110   103   115    97
  Columns 10 through 18
   110   100     4   115   112    97    99   101   115
count
count =
     5

Example 5

[str, count] = sscanf('one two three', '%c')
str =
    one two three
count =
    13

[str, count] = sscanf('one two three', '%13c')
str =
    one two three
count =
     1

[str, count] = sscanf('one two three', '%s')
str =
    onetwothree
count =
     3

[str, count] = sscanf('one two three', '%1s')
str =
    onetwothree
count =
    11

Example 6

tempString = '78°F 72°F 64°F 66°F 49°F';

degrees = char(176);
tempNumeric = sscanf(tempString, ['%d' degrees 'F'])'
tempNumeric =
    78    72    64    66    49

More About

expand all

Tips

  • Format specifiers for the reading functions sscanf and fscanf differ from the formats for the writing functions sprintf and fprintf. The reading functions do not support a precision field. The width field specifies a minimum for writing but a maximum for reading.

See Also

| |

Was this topic helpful?