Navigation

Operators and Keywords

Function List:

C++ API

Function File: C = textscan (fid, format)
Function File: C = textscan (fid, format, n)
Function File: C = textscan (fid, format, param, value, …)
Function File: C = textscan (fid, format, n, param, value, …)
Function File: C = textscan (str, …)
Function File: [C, position] = textscan (fid, …)

Read data from a text file or string.

The string str or file associated with fid is read from and parsed according to format. The function behaves like strread except it can also read from file instead of a string. See the documentation of strread for details.

In addition to the options supported by strread, this function supports a few more:

  • "collectoutput": A value of 1 or true instructs textscan to concatenate consecutive columns of the same class in the output cell array. A value of 0 or false (default) leaves output in distinct columns.
  • "endofline": Specify "\r", "\n" or "\r\n" (for CR, LF, or CRLF). If no value is given, it will be inferred from the file. If set to "" (empty string) EOLs are ignored as delimiters and added to whitespace.
  • "headerlines": The first value number of lines of fid are skipped.
  • "returnonerror": If set to numerical 1 or true (default), return normally when read errors have been encountered. If set to 0 or false, return an error and no data. As the string or file is read by columns rather than by rows, and because textscan is fairly forgiving as regards read errors, setting this option may have little or no actual effect.

When reading from a character string, optional input argument n specifies the number of times format should be used (i.e., to limit the amount of data read). When reading from file, n specifies the number of data lines to read; in this sense it differs slightly from the format repeat count in strread.

The output C is a cell array whose second dimension is determined by the number of format specifiers.

The second output, position, provides the position, in characters, from the beginning of the file.

If the format string is empty (not: omitted) and the file contains only numeric data (excluding headerlines), textscan will return data in a number of columns matching the number of numeric fields on the first data line of the file.

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

Package: octave