Navigation

Operators and Keywords

Function List:

C++ API

: [a, …] = textread (filename)
: [a, …] = textread (filename, format)
: [a, …] = textread (filename, format, n)
: [a, …] = textread (filename, format, prop1, value1, …)
: [a, …] = textread (filename, format, n, prop1, value1, …)

Read data from a text file.

The file filename is read and parsed according to format. The function behaves like strread except it works by parsing a file instead of a string. See the documentation of strread for details.

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

  • "headerlines": The first value number of lines of filename are skipped.
  • "endofline": Specify a single character or "\r\n". If no value is given, it will be inferred from the file. If set to "" (empty string) EOLs are ignored as delimiters.

The optional input n (format repeat count) specifies the number of times the format string is to be used or the number of lines to be read, whichever happens first while reading. The former is equivalent to requesting that the data output vectors should be of length N. Note that when reading files with format strings referring to multiple lines, n should rather be the number of lines to be read than the number of format string uses.

If the format string is empty (not just omitted) and the file contains only numeric data (excluding headerlines), textread will return a rectangular matrix with the number of columns matching the number of numeric fields on the first data line of the file. Empty fields are returned as zero values.

Examples: 

  Assume a data file like:
  1 a 2 b
  3 c 4 d
  5 e

  [a, b] = textread (f, "%f %s")
  returns two columns of data, one with doubles, the other a
  cellstr array:
  a = [1; 2; 3; 4; 5]
  b = {"a"; "b"; "c"; "d"; "e"}

  [a, b] = textread (f, "%f %s", 3)
  (read data into two culumns, try to use the format string
  three times)
  returns
  a = [1; 2; 3]
  b = {"a"; "b"; "c"}


  With a data file like:
  1
  a
  2
  b

  [a, b] = textread (f, "%f %s", 2)
  returns a = 1 and b = {"a"}; i.e., the format string is used
  only once because the format string refers to 2 lines of the
  data file.  To obtain 2x1 data output columns, specify N = 4
  (number of data lines containing all requested data) rather
  than 2.

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

Package: octave