sscanf

Read formatted data from strings

collapse all in page

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.

example

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.

example

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

example

[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.

example

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

example

Examples

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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.'
Open Live Script

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'
Open Live Script

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

collapse all

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

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

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

collapse all

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

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

Data Types: double

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

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

expand all

Version History

Introduced before R2006a

See Also

| | | | | |

Topics