textscan

Returns result R after reading a formatted data from a file stream \, f, or string, s.

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

Reads formatted data from a file, with headerlines and delimiters. The contents of 'textscanfile.txt' are: ## A ID = 02476 ## YKZ Timestamp Temp Humidity Wind Weather 06-Sep-2013 01:00:00 6.6 89 4 clear 06-Sep-2013 09:00:00 15.6 51 5 mainly clear 06-Sep-2013 17:00:00 22.4 41 9 mostly cloudy ## B ID = 02477 ## YVR Timestamp Temp Humidity Wind Weather 09-Sep-2013 01:00:00 15.2 91 8 clear 09-Sep-2013 05:00:00 19.1 94 7 n/a ## C ID = 02478 ## YYZ Timestamp Temp Humidity Wind Weather 
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
}
}
}
Reads formatted data from a string, using repeat parameter. 
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
}
Reads formatted data from a file, skipping new lines.
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
}
}
Reads formatted data from a string, using %[..] to include characters.
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
  }
}
Reads formatted data from a string, using %[..] to exclude characters. 
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
  }
}
Trim trailing characters. 
R = textscan('234 str    123      ', '%s %s %d', 'whitespace', ' ')
R =
{
  [1,1]
  {
    [1,1] 234
  }
  [1,2]
  {
    [1,1] str
  }
  [1,3] 123
}
Return with error if there is a format mismatch. 
textscan('45 62 three four 24.7e12 five six 56', '%s %s %f', 'ReturnOnError', 0)
Error: invalid input; format(s) cannot be applied in field 3 [%f] to row [1] of the output in call to function textscan