textscan

Syntax

R = textscan(f, fmt)

R = textscan(f, fmt, n)

R = textscan(f, fmt, param, value, ...)

R = textscan(f, fmt, n, param, value, ...)

R = textscan(s, ...)

Inputs

f

An open file stream which needs to be read.

Type: integer

s

Input stream which needs to be read.

Type: string

fmt

Format to be applied to the input file or string. Valid formats are:

• '%d'
• '%f'
• '%g'
• '%c'
• %n
• '%s'

If no fmt is specified, '%f' or the float format is used as a default. The format %n is similar to %d, where a value is read as an integer.

The format specifications %c, %d, %f and %n can be an optional integer width specification.

For %c, the width specification gives the number of characters to read.

%f formats can also be specified as %a.bf, where a and b are integers, representing numbers to be read before and after the decimal point, respectively.

To include certain characters, %[...] can be used. To exclude certain characters, %[^...] can be used.

Type: string

n (optional)

When reading from a file, f, n specifies the number of lines to be read. When reading from a string, s specifies the number of times the format fmt is repeated. If n is 0, nothing is read. If n is -1, which is the default, data is read until the format fmt is applicable to the input.

Type: integer

param-value (optional)

Optional name-value pairs which specify the behavior of textscan. The following are the valid parameter names and their values:

headerlines: linestoskip

The number of lines to skip before applying the format.

Type: Finite, positive integer

delimter:delim

The delimiter to be used. If nothing is specified, whitespace is used a delimiter.

Type: string

endofline:eol

The character to be used for end of line. If nothing is specified, '\r\n' will be used. Valid values are '\r', '\r\n', or a single character.

Type: string

returnOnError:val

If true or 1, the output contains all data until the format cannot be applied or there is no more data to be read. This is the default option. If false or 0, an error is returned if the format cannot be applied to the data.

Type: logical

whitespace:space

The character to be used as whitespace. If nothing is specified, ' ' will be used.

Type: string

Outputs

R

A new column is created in the output, R, for every format specified in t

Type: cell

Examples

f = fopen('textscanfile.txt');
t = '%s %f %f %f %s';
R1 = textscan(f, t, 'headerlines',2,'delimiter', '\t')
R2 = textscan(f, t, 'headerlines',1,'delimiter', '\t')
fclose(fid);

R1 =
{
{
[1,1]
{
[1,1] 06-Sep-2013 01:00:00
}
{
[2,1] 06-Sep-2013 09:00:00
}
{
[3,1] 06-Sep-2013 17:00:00
}
{
[4,1] ## B
}
}
{
[1,2] [Matrix] 3 x 1
6.60000
15.60000
22.40000
}
{
[1,3] [Matrix] 3 x 1
89
51
41
}
{
[1,4] [Matrix] 3 x 1
4
5
9
}
[1,5]
{
[1,1] clear
}
{
[2,1] mainly clear
}
{
[3,1] mostly cloudy
}
}
R2 =
{
{
[1,1]
{
[1,1] 09-Sep-2013 01:00:00
}
{
[2,1] 09-Sep-2013 05:00:00
}
{
[3,1] ## C
}
}
{
[1,2] [Matrix] 2 x 1
15.20000
19.10000
}
{
[1,3] [Matrix] 2 x 1
91
94
}
{
[1,4] [Matrix] 2 x 1
8
7
}
{
[1,5]
{
[1,1] clear
}
{
[2,1] n/a
}
}
}

str='one two 12 three four 24.7e12 five six 56';
textscan(str, '%s %s %f', 2)   % Apply format twice
textscan(str, '%s %s %f', -1)  % Read to the end of the string
              
ans =
{
[1,1]
{
[1,1] one
[2,1] three
}
[1,2]
{
[1,1] two
[2,1] four
}
[1,3] [Matrix] 2 x 1
1.20000e+01
2.47000e+13
}
ans =
{
[1,1]
{
[1,1] one
[2,1] three
[3,1] five
}
[1,2]
{
[1,1] two
[2,1] four
[3,1] six
}
[1,3] [Matrix] 3 x 1
1.20000e+01
2.47000e+13
5.60000e+01
}

str='12.345678/1/2018 hello world!!';
textscan(str, '%2.3f/%d/%2n %2c %s')

ans =
{
[1,1] 12.346
[1,2] 1
[1,3] 20
[1,4]
{
[1,1] 18
}
[1,5]
{
[1,1] hello
}
}

f = textscan('one threes four','%s %[thre]')

f =
{
  [1,1]
  {
    [1,1] one
    [2,1] s
    [3,1] fou
  }
  [1,2]
  {
    [1,1] three
    [2,1] r
  }
}

f = textscan('one threes four','%s %[^thre]')

f = 
{
  [1,1] 
  {
    [1,1] one
    [2,1] three
    [3,1] r
  }
  [1,2] 
  {
    [1,1] s
    [2,1] fou
  }
}