sscanf

Read formatted data from strings

Syntax

A = sscanf(str,formatSpec)

A = sscanf(str,formatSpec,sizeA)

[A,n] = sscanf(___)

[A,n,errmsg] = sscanf(___)

[A,n,errmsg,nextindex] = sscanf(___)

Description

A = sscanf(str,formatSpec) reads data from str, converts it according to the format specified by formatSpec, and returns the results in an array. str is either a character array or a string scalar. The sscanf function repeatedly applies formatSpec to sequences of characters in str until it either reaches the end of str or fails to match formatSpec to a sequence of characters. If str is a character array with more than one row, sscanf reads the characters in column order.

A = sscanf(str,formatSpec,sizeA) sets the size of the output array to be sizeA and then reads data from str into the output array. sizeA must be a positive integer or have the form [m n], where m and n are positive integers.

[A,n] = sscanf(___) also returns the number of elements that sscanf successfully reads into A.

[A,n,errmsg] = sscanf(___) also returns a character vector containing an error message when sscanf fails to read all the data into A. If sscanf succeeds, then errmsg is an empty character vector.

[A,n,errmsg,nextindex] = sscanf(___) also returns the index of the position in str that immediately follows the last character scanned by sscanf.

Examples

Convert Character Vector to Numbers

Create a character vector that represents several numbers separated by whitespace characters. Convert the character vector to a column vector of numbers. sscanf treats whitespace characters as separators between numbers.

chr = '2.7183  3.1416  0.0073'

chr = 
'2.7183  3.1416  0.0073'

A = sscanf(chr,'%f')

A = 3×1

    2.7183
    3.1416
    0.0073

Convert Text and Resize Output Array

Create a string that represents several numbers and convert it using sscanf. Specify the size of the output array.

str = "2.7183  3.1416  0.0073"

str = 
"2.7183  3.1416  0.0073"

A = sscanf(str,'%f',[1 3])

A = 1×3

    2.7183    3.1416    0.0073

Convert str to a 2-by-2 matrix. Because str represents only three numbers, sscanf pads A with enough zeros to fill in the matrix.

A = sscanf(str,'%f',[2 2])

A = 2×2

    2.7183    0.0073
    3.1416         0

Count Elements Found in Text

Create a string that contains numbers separated by whitespace characters. Count the elements that sscanf puts into the output array when it converts the string to numbers.

str = "78 72 64 66 49"

str = 
"78 72 64 66 49"

Count the elements in the output array A. Convert the numbers in the string using the %d operator. %d matches integers separated by whitespace. To return the number of elements in A, specify a second output argument.

[A,n] = sscanf(str,'%d')

A = 5×1

    78
    72
    64
    66
    49

n = 
5

Display Error Message

Create a string and read data from it. When sscanf fails to convert all of the input string, display the error message.

str = "3.14159 are the first 6 digits of pi"

str = 
"3.14159 are the first 6 digits of pi"

Convert the number in str. Since str also contains characters that %f cannot match, sscanf returns an error message. sscanf stops processing as soon as it encounters the word 'are' because it cannot be converted to a number.

[A,n,errmsg] = sscanf(str,'%f')

A = 
3.1416

n = 
1

errmsg = 
'Matching failure in format.'

Return Last Position Scanned

Create a character vector and read data from it. When sscanf fails to convert all of the input, return the index that immediately follows the position at which sscanf stopped. Use this index to display the unscanned input.

chr = '3.14159 are the first 6 digits of pi'

chr = 
'3.14159 are the first 6 digits of pi'

Convert the data in chr. Return the index.

[A,~,~,nextindex] = sscanf(chr,'%f')

A = 
3.1416

nextindex = 
9

Display the characters from chr that sscanf did not scan.

chr(nextindex:end)

ans = 
'are the first 6 digits of pi'

Match Specified Characters

Create a string that contains several temperatures, indicated by the degree symbol and the letter F. Convert the temperatures to a numeric array.

To insert the degree symbol (char(176)), use the insertBefore function.

T = "78F 72F 64F 66F 49F";
degreeSymbol = char(176);
T = insertBefore(T,'F',degreeSymbol)

T = 
"78°F 72°F 64°F 66°F 49°F"

Return the temperatures as a numeric array.

A = sscanf(T,strcat("%d",degreeSymbol,"F"))

A = 5×1

    78
    72
    64
    66
    49

Input Arguments

str — Input text to scan

character array | string scalar

Input text to scan, specified as a character array or string scalar. If str is a character array, then it can have multiple rows, and sscanf reads the characters in column order.

Data Types: char | string

formatSpec — Format of input fields

formatting operators

Format of the input fields, specified using formatting operators. formatSpec can be a character vector in single quotes, or a string scalar.

Numeric Fields

This table lists available conversion specifiers to convert text to numeric outputs. sscanf converts values to their decimal (base 10) representation.

Numeric Field Type	Conversion Specifier	Description
Integer, signed	%d	Base 10.
	%i	The values determine the base: The default is base 10. If the initial digits are 0x or 0X, then the values are base 16 (hexadecimal). If the initial digit is 0, then values are base 8 (octal).
	%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, %e, or %g	Floating-point values. Input fields can contain any of the following (not case sensitive): Inf, -Inf, NaN, or -NaN. Input fields that represent floating-point numbers can include leading + or - symbols and exponential notation using e or E. The conversion specifiers %f, %e, and %g all treat input fields the same way.

Character Fields

This table lists available conversion specifiers to convert text so that the output is a character array.

Character Field Type	Conversion Specifier	Description
Character vector or string scalar	%s	Read the text until sscanf encounters whitespace.
	%c	Read any single character, including whitespace. To read multiple characters at a time, specify field width. For example, %10c reads 10 characters at a time.
Pattern-matching	%[...]	Read only characters in the brackets up to the first nonmatching character or whitespace. Example: %[mus] reads 'summer ' as 'summ'.

If formatSpec contains a combination of numeric and character specifiers, then sscanf converts each character to its numeric equivalent.

Optional Operators

• Fields and Characters to Ignore

  sscanf reads all numeric values and characters in sequence, unless you tell it to ignore a particular field or a portion of a field. To skip fields, insert an asterisk (*) after the percent sign (%). For example, to skip integers, specify %*d.

• Field Width

  To specify the maximum number of digits or text characters to read at a time, insert a number after the percent character. For example, %10c reads up to 10 characters at a time, including whitespace. %4f reads up to four digits at a time, including the decimal point.

• Literal Text to Ignore

  sscanf ignores specified text immediately before or after the conversion specifier.

  Example: Level%u reads 'Level1' as 1.

  Example: %uStep reads '2Step' as 2.

Data Types: char | string

sizeA — Dimensions of output array

Inf (default) | integer | two-element row vector

Dimensions of the output array, A, specified as Inf, a positive integer, or a two-element row vector.

Form of sizeA Input	Description
Inf	Read input to the end. For numeric data, A is a column vector. For text data, A is a character vector.
n	Read at most n numeric values or space-delimited character fields. For numeric data, A is a column vector. For text data, A is a character vector.
[m n]	Read at most m*n numeric values or character fields. n can be Inf, but m cannot. A is m-by-n, filled in column order.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Output Arguments

A — Output data

column vector | matrix | character array

Output data, returned as a column vector, matrix, or character array. The class and size of A depend on the conversions specified by formatSpec and the size of the output array specified by sizeA:

• If formatSpec contains only numeric specifiers, then A is a numeric column vector. If you also specify the sizeA argument, then A is a matrix of the specified size, and is padded with zeros if necessary. If the input contains fewer than sizeA values, then the size of A is smaller than sizeA. Instead, it is the size required to store the values scanned from the input.

  • If formatSpec contains only 64-bit signed integer specifiers, then A is of class int64.

  • If formatSpec contains only 64-bit unsigned integer specifiers, then A is of class uint64.

  • Otherwise, A is of class double.

• If formatSpec contains only %c or %s specifiers, then A is a character vector. If you also specify sizeA, then A is a character array, and is padded as necessary with null characters. (The null character is a control character with the value zero.) If the input contains fewer than sizeA characters, then the size of A is smaller than sizeA. Instead, it is the size required to store the characters scanned from the input.

• If formatSpec contains a combination of numeric and character specifiers, then A is numeric, of class double, and sscanf converts each character to its numeric equivalent. This conversion occurs even when formatSpec explicitly skips all numeric fields (for example, formatSpec is '%*d %s').

• If sscanf cannot match all of the input to formatSpec, then A can be numeric or a character array. The class of A depends on the values that sscanf reads before it stops processing.

Data Types: double | int64 | uint64 | char

n — Number of elements read into output array

integer

Number of elements read into the output array, returned as an integer.

Data Types: double

errmsg — Error message

character vector

Error message, returned as a character vector. If str contains any data that sscanf cannot convert, then errmsg contains an error message. If sscanf converts all the data successfully, then errmsg is an empty character vector.

Data Types: char

nextindex — Position after last character scanned

integer

Position after the last character scanned, returned as an integer.

Data Types: double

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.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The input argument formatSpec must be a constant.

• The %s and %[...] conversion specifiers are not supported.

• The output arguments errmsg and nextinput are not supported.

• If you turn off dynamic memory allocation, you must provide the input argument sizeA and it must be a constant.

• In certain cases, the behavior of the generated code might differ from MATLAB^®. In such cases, the behavior of the generated code matches that of sscanf in the C language. These are some examples:

  • In the generated code, if sscanf reads a null byte, the returned values might be truncated.

  • If you read an integer value x into an integer format for which intmax is smaller than x, the MATLAB output saturates at intmax. In the generated code, this situation can cause an overflow.

  • If you use the formatting specifier %c to specify a field width that is greater than the number of characters that are available in the input text str, MATLAB returns a string shorter than the specified length that contains only the available characters. The generated code returns a string of the specified length, but the contents of the returned string can vary depending on the C/C++ compiler you use. In some cases, the returned string contains the input string padded with null characters (char(0)). In other cases, the returned string contains only null characters.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced before R2006a