sscanf - Read formatted data from strings - MATLAB (original) (raw)

Read formatted data from strings

Syntax

Description

[A](#shared-A) = sscanf([str](#bvjmcrm-str),[formatSpec](#bvjmcrm%5Fsep%5Fshared-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. Thesscanf function repeatedly appliesformatSpec to sequences of characters instr until it either reaches the end of str or fails to match formatSpec to a sequence of characters. Ifstr is a character array with more than one row,sscanf reads the characters in column order.

example

[A](#shared-A) = sscanf([str](#bvjmcrm-str),[formatSpec](#bvjmcrm%5Fsep%5Fshared-formatSpec),[sizeA](#shared-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], wherem and n are positive integers.

example

[[A](#shared-A),[n](#bvjmcrm-n)] = sscanf(___) also returns the number of elements thatsscanf successfully reads into A.

example

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

example

[[A](#shared-A),[n](#bvjmcrm-n),[errmsg](#bvjmcrm-errmsg),[nextindex](#bvjmcrm-nextindex)] = sscanf(___) also returns the index of the position instr that immediately follows the last character scanned bysscanf.

example

Examples

collapse all

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 = 3×1

2.7183
3.1416
0.0073

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

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.

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.

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')

errmsg = 'Matching failure in format.'

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')

Display the characters from chr that sscanf did not scan.

ans = 'are the first 6 digits of pi'

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"))

Input Arguments

collapse all

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

Data Types: char | string

Data Types: char | string

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

Output Arguments

collapse all

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, thenerrmsg contains an error message. Ifsscanf converts all the data successfully, thenerrmsg 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

Usage notes and limitations:

• The input argument formatSpec must be a constant.
• The %s and %[...] conversion specifiers are not supported.
• The output arguments errmsg andnextinput 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 textstr, 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.

Version History

Introduced before R2006a