Navigation

Operators and Keywords

Function List:

C++ API

: [a, …] = strread (str)
: [a, …] = strread (str, format)
: [a, …] = strread (str, format, format_repeat)
: [a, …] = strread (str, format, prop1, value1, …)
: [a, …] = strread (str, format, format_repeat, prop1, value1, …)

Read data from a string.

The string str is split into words that are repeatedly matched to the specifiers in format. The first word is matched to the first specifier, the second to the second specifier and so forth. If there are more words than specifiers, the process is repeated until all words have been processed.

The string format describes how the words in str should be parsed. It may contain any combination of the following specifiers:

%s

The word is parsed as a string.

%f
%n

The word is parsed as a number and converted to double.

%d
%u

The word is parsed as a number and converted to int32.

%*', '%*f', '%*s

The word is skipped.

For %s and %d, %f, %n, %u and the associated %*s … specifiers an optional width can be specified as %Ns, etc. where N is an integer > 1. For %f, format specifiers like %N.Mf are allowed.

literals

In addition the format may contain literal character strings; these will be skipped during reading.

Parsed word corresponding to the first specifier are returned in the first output argument and likewise for the rest of the specifiers.

By default, format is "%f", meaning that numbers are read from str. This will do if str contains only numeric fields.

For example, the string 

str = "\
Bunny Bugs   5.5\n\
Duck Daffy  -7.5e-5\n\
Penguin Tux   6"

can be read using 

[a, b, c] = strread (str, "%s %s %f");

Optional numeric argument format_repeat can be used for limiting the number of items read:

-1

(default) read all of the string until the end.

N

Read N times nargout items. 0 (zero) is an acceptable value for format_repeat.

The behavior of strread can be changed via property-value pairs. The following properties are recognized:

"commentstyle"

Parts of str are considered comments and will be skipped. value is the comment style and can be any of the following.

  • "shell" Everything from # characters to the nearest end-of-line is skipped.
  • "c" Everything between /* and */ is skipped.
  • "c++" Everything from // characters to the nearest end-of-line is skipped.
  • "matlab" Everything from % characters to the nearest end-of-line is skipped.
  • user-supplied. Two options: (1) One string, or 1x1 cell string: Skip everything to the right of it; (2) 2x1 cell string array: Everything between the left and right strings is skipped.
"delimiter"

Any character in value will be used to split str into words (default value = any whitespace). Note that whitespace is implicitly added to the set of delimiter characters unless a "%s" format conversion specifier is supplied; see "whitespace" parameter below. The set of delimiter characters cannot be empty; if needed Octave substitutes a space as delimiter.

"emptyvalue"

Value to return for empty numeric values in non-whitespace delimited data. The default is NaN. When the data type does not support NaN (int32 for example), then default is zero.

"multipledelimsasone"

Treat a series of consecutive delimiters, without whitespace in between, as a single delimiter. Consecutive delimiter series need not be vertically "aligned".

"treatasempty"

Treat single occurrences (surrounded by delimiters or whitespace) of the string(s) in value as missing values.

"returnonerror"

If value true (1, default), ignore read errors and return normally. If false (0), return an error.

"whitespace"

Any character in value will be interpreted as whitespace and trimmed; the string defining whitespace must be enclosed in double quotes for proper processing of special characters like "\t". In each data field, multiple consecutive whitespace characters are collapsed into one space and leading and trailing whitespace is removed. The default value for whitespace is " \b\r\n\t" (note the space). Whitespace is always added to the set of delimiter characters unless at least one "%s" format conversion specifier is supplied; in that case only whitespace explicitly specified in "delimiter" is retained as delimiter and removed from the set of whitespace characters. If whitespace characters are to be kept as-is (in e.g., strings), specify an empty value (i.e., "") for "whitespace"; obviously, whitespace cannot be a delimiter then.

When the number of words in str doesn’t match an exact multiple of the number of format conversion specifiers, strread’s behavior depends on the last character of str:

last character = "\n"

Data columns are padded with empty fields or Nan so that all columns have equal length

last character is not "\n"

Data columns are not padded; strread returns columns of unequal length

See also: textscan, textread, load, dlmread, fscanf.

Package: octave