strread

(Not recommended) Read formatted data from string

strread is not recommended. Use textscan instead.

Syntax

A = strread(str)

[A,B,...] = strread(str)

[A,B,...] = strread(str,format)

[A,B,...] = strread(str,format,N)

[A,B,...] = strread(___,Name,Value)

Description

A = strread(str) reads numeric data from input character vector str into a 1-by-N vector A, where N equals the number of whitespace-separated numbers in str. Use this syntax with character vectors containing numeric data.

[A,B,...] = strread(str) reads numeric data from the character vector input str into scalar output variables A, B, and so on. The number of output variables must equal the number of whitespace-separated numbers in str.

[A,B,...] = strread(str,format) reads data from str into variables A, B, and so on using the specified format. The number of output variables must be equal to the number of format specifiers (such as %s or %d) in the format argument. You can read all of the data in str to a single output variable as long as you use only one format specifier.

The table Formats for strread lists the valid format specifiers.

[A,B,...] = strread(str,format,N) reads the first N values from str as determined by the format character vector, where N is an integer greater than zero. If N is -1, then strread reads all the values in str. When str contains only numeric data, you can set format to the empty character vector ('').

[A,B,...] = strread(___,Name,Value) customizes strread using Name,Value arguments. When str contains only numeric data, you can set format to the empty character vector ('').

Examples

Read Numeric Data into a Vector

Create a character vector containing numbers separated by spaces. Use strread to read the numeric data into a numeric array.

str = '0.41 8.24 3.57 6.24 9.27';
a = strread(str)

a = 1×5

    0.4100    8.2400    3.5700    6.2400    9.2700

Read Numeric Data into Separate Variables

Create a character vector containing numbers separated by spaces. Use strread to read the numeric data into separate variables.

str = '0.41 8.24 3.57 6.24 9.27';
[a, b, c, d, e] = strread(str)

a = 
0.4100

b = 
8.2400

c = 
3.5700

d = 
6.2400

e = 
9.2700

Read N Numbers into a Character Vector

Create a character vector containing numbers separated by spaces. Use strread to read only the first three numbers in the character vector and format the data as floating point.

str = '0.41 8.24 3.57 6.24 9.27';
a = strread('0.41 8.24 3.57 6.24 9.27', '%4.2f', 3)

a = 3×1

    0.4100
    8.2400
    3.5700

Truncate Data to One Digit

Create a character vector containing numbers separated by spaces. Truncate the data to one decimal digit by specifying format %3.1f. The second specifier, %*1d, tells strread not to read in the remaining decimal digit

str = '0.41 8.24 3.57 6.24 9.27';
a = strread(str, '%3.1f %*1d')

a = 5×1

    0.4000
    8.2000
    3.5000
    6.2000
    9.2000

Read Six Numbers into Two Variables

Create a character vector containing numbers separated by spaces. Read six numbers into two variables Use the format specifier %f twice to apply the same formatting to each output. The number of formats specified must match the number of outputs.

str = '0.41 8.24 3.57 6.24 9.27 3.29';
[a, b] = strread(str, '%f %f')

a = 3×1

    0.4100
    3.5700
    9.2700

b = 3×1

    8.2400
    6.2400
    3.2900

Read Text and Numeric Data to Two Variables

Create a character vector containing words and numbers separated by spaces and with commas separating each word-number pair.

str = 'Section 4, Page 7, Line 26';

Use strread to read text to one variable and numeric data to another. The format input '%s' designates that the first output will be character vectors separated by whitespace characters. '%d,' specifies that the second output will be signed integer values and ignoring ',' characters.

[name, value] = strread(str, '%s %d,')

name = 3×1 cell
    {'Section'}
    {'Page'   }
    {'Line'   }

value = 3×1

     4
     7
    26

Read Text Delimited by Commas

Create a character vector containing words and numbers with commas separating each word-number pair.

str = 'Section 4, Page 7, Line 26';

Read the character vector delimiting with commas instead of spaces. Use the '%s' format to specify reading a character vector. Since three outputs are specified three formats must be specified.

[a, b, c] = strread(str,'%s %s %s', 'delimiter', ',')

a = 1×1 cell array
    {'Section 4'}

b = 1×1 cell array
    {'Page 7'}

c = 1×1 cell array
    {'Line 26'}

Input Arguments

str — Input text

character array | string scalar

Input text specified as a character array or string scalar.

Data Types: char | string

format — Output format

character array | string scalar

Output format, specified as a character array or string scalar that specifies the format and data type of the output determines the number and types of return arguments. The number of return arguments must match the number of conversion specifiers in the format character vector.

The strread function continues reading str until the entire character vector is read. If there are fewer format specifiers than there are entities in str, strread reapplies the format specifiers, starting over at the beginning.

The format character vector supports a subset of the conversion specifiers and conventions of the C language fscanf routine. White-space characters in the format character vector are ignored.

Formats for strread

Format	Action	Output
Literals (ordinary characters)	Ignore the matching characters. For example, in a character vector that has Dept followed by a number (for department number), to skip the Dept and read only the number, use 'Dept' in the format character vector.	None
%d	Read a signed integer value.	Double array
%u	Read an integer value.	Double array
%f	Read a floating-point value.	Double array
%s	Read a white-space separated character vector.	Cell array of character vectors
%q	Read a double quoted character vector, ignoring the quotes.	Cell array of character vectors
%c	Read characters, including white space.	Character array
%[...]	Read the longest character vector containing characters specified in the brackets.	Cell array of character vectors
%[^...]	Read the longest nonempty character vector containing characters that are not specified in the brackets.	Cell array of character vectors
%*...	Ignore the characters following *.	No output
%w...	Read field width specified by w. The %f format supports %w.pf, where w is the field width and p is the precision.

Data Types: char | string

N — Number of Values

integer greater than zero

Number of values, specified as an integer greater than zero. If N is -1, then strread will find all possible values in str.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: strread(str,'','whitespace','\t')

whitespace — Whitespace characters

character vector | string array

Whitespace characters, specified as a character vector or string array. strread treats characters specified by the input symbols as whitespace. The default is '\b\r\n\t'.

Symbol	Whitespace Character
\b	Backspace
\n	New line
\r	Carriage return
\t	Horizontal tab
\\	Backslash
%%	Percent sign
''	Single quotation mark

delimiter — delimiter character

character vector | string scaler

Delimiter character, specified as a character vector or string scaler containing the delimiter. The default is one or more whitespace characters. For example, if the character vector str uses a semicolon as a delimiter, specify 'delimiter' as ';'.

expchars — Exponent characters

character vector | string scaler

Exponent characters, specified as a character vector or string scalar containing characters that are treated as exponents, such as 'e' in the number 4.3e12. The default is 'eEdD'.

bufsize — Buffer size

positive integer

Buffer size, specified as a positive integer containing the maximum character vector length in bytes. Default is 4095.

commentstyle — Comment style

character vector | string scaler

Comment style, specified as a character vector or string scalar containing the style of symbol that strread uses to designate comments. strread ignores characters designated by the corresponding symbol.

Style	Action
'matlab'	Ignores characters after %.
'shell'	Ignores characters after #.
'c'	Ignores characters between /* and */.
'c++'	Ignores characters after //.

emptyvalue — Empty value

numeric scalar

Value to return for empty numeric fields in delimited files, specified as a numeric scalar

Tips

• If you terminate the input character vector with a newline character (\n), strread returns arrays of equal size by padding arrays of lesser size with the emptyvalue character:

  [A,B,C] = strread(sprintf('5,7,1,9\n'),'%d%d%d', ...
               'delimiter', ',', 'emptyvalue',NaN)
  A =
       5
       9
  B =
       7
     NaN
  C =
       1
     NaN

  If you remove the \n from the input character vector of this example, array A continues to be a 2-by-1 array, but B and C are now 1-by-1.

Version History

Introduced in R2006a