Updated March 15, 2023
Introduction to Matlab Textscan
Inbuilt function from MATLAB, textscan() perform the operation of reading formatted data from text file or string, converting and writing data to cell array.Textscan() supports initializing reading from any point in a file. Once the user opens the file, textscan() can start reading from any point instructed by the user. The subsequent textscan() continues reading operation the file when the last textscan() operation is left off.
Syntax
| Syntax | Description |
| C = textscan(fileID,formatSpec) | This form of the command textscan() is used to read data from an open text file indicated by fileID into a cell array, C. |
| C = textscan(fileID,formatSpec,N) | This form of the command textscan() is used to read data from an open text file indicated by fileID into a cell array, Cfor theformatSpec, N times. In order to read additional,textscan() can be called using the original fileIDagain. |
| C = textscan(chr,formatSpec) | This form of the command textscan() is used to read data from the character vector ‘chr’ and store it in the cell array ‘C.’ While reading data from character vector, each time, recurring calls to textscan()re-initiate the scan from the beginning. A scan can be resumed from the last position on request for a position output.
Textscan()tries to match the data in ‘chr’ to the format given in the form offormatSpec. |
| C = textscan(chr,formatSpec,f) | This form of the command textscan() is used to read dataforformatSpecf times, where f is a positive integer. |
| C = textscan(___,Name,Value) | This form of the command textscan() is used to read data specifying options in the form of one or more Name, Value pair arguments. |
| [C,position] = textscan(___) | This form of the command textscan() is used to read data returning the position pointed in the file or in the character vector at the end of the process of scanning as the second output argument.
The return value For a file- value equals to return value of ftell(fileID) For a character vector- position indicating the number of characters textscan reads. |
Examples of Matlab Textscan
Different examples are mentioned below:
Example #1
Code:
chr_str = '0.31 3.24 5.67 6.44 9.17';Scan_str = textscan(chr_str,'%f'); celldisp(Scan_str)
Output:
Example #2
Code:
filestr = 'grades.txt';
ID_file = fopen(filestr);
File_formatSpec = '%s';
Cy = 4;
Result_text = textscan(ID_file,File_formatSpec,Cy,'Delimiter','|');
C_data0 = textscan(ID_file,'%d %f %f %f')
Output:
Example #3
Code:
chr_str = 'It is;my code';Scan_str = textscan(chr_str,'%s','Delimiter',';','EmptyValue',-Inf); celldisp(Scan_str)
Output:
Working of TextScan()
Textscan()is designed to convert numeric fields to a specific output type, following MATLAB rules with respect to the process of overflow, truncation, and the application of NaN, Inf, and -Inf.
For example, the integer NaNis represented as zero in MATLAB. Therefore, if textscan() encounters an empty field associated with an integer format specifier, it returns the empty value as zero and not NaN.
While matching the data with respect to a text conversion specifier, textscan() reads until it finds either a delimiter or an end-of-line character, whereas while matching the data to a numeric conversion specifier, textscan() reads until it reaches to a non-numeric character. Thus, in casetextscan(), it can not match the data to any specific conversion specifier; it tries to match the data to the conversion specifier next in the formatSpec. As represented in the diagram below, the characters such as Signs (+ or -), decimal points, and exponent characters are considered numeric characters.
Resuming a Text Scan
If textscan() fails to convert a data field, it does not proceed with the operation reading and returns the fields read before the failure. When reading from a file, the reading operation from the same file can be resumed by calling textscan() again having the same file identifier, filed, as the first input argument. For a string reading operation carried out by the textscan() method, the syntax of the two-output argument enables the user to resume the reading operation from the string at the point where the last reading operation is terminated. The following code talks about the implementation of this operation.
textscan(str(position+1:end), ...)
lyric = 'Blackbird singing in the dead of night';
[firstword,pos] = textscan(lyric,'%9c',1);
lastpart = textscan(lyric(pos+1:end),'%s');
celldisp(lastpart)
Output:
Thetextscan() and textread() Functions exhibit similar functionalities, but they differ from each other in various aspects such as:
- The textscan() function ensures better performance than that oftextread() method. Hence it is a better choice in case of reading large files.
- With the textscan() function, the reading operation can be started reading from any point in the file. Once the file is open by the user as it is a prerequisite for textscan() that it requires the user to open the file first, then the user can have access to any position in the file to begin the textscan() at the desired point whereas the textread() function has limited feature of supporting reading operation only from the beginning of any file.
- Subsequent textscan() operations start reading of the given file at that point where the earliertextscan() operation is left off. But in the case of the textread() function, it always begins from the beginning of the input file irrespective of the status of the reading operation carried out by any of the prior textread() function call.
- Textscan()results in a return value as a single cell array independent of a number of fields that a user reads. With textscan(), it is not required to match the number of output arguments to that of the number of fields being read.
- Textscan()supports more options on the conversion of the data being read.
- Textscan()is equipped with more user-configurable options that that of textread() operation.
Additional Note
Textscan()supports importing any complex number as a whole into a complex numeric field, performing conversion operations for the real and imaginary parts to the defined numeric type. There are 2 Valid forms for a complex number, supported bytextscan() method, are :
1. ±<real>±<imag>i|j
Example:
3.7-2.1i
Output:
2. ±<imag>i|j
Example:
-4j
Output:
3. It is not recommended to include embedded white space to a complex number. Textscan() understands an embedded white space as a field delimiter.
Recommended Articles
This is a guide to Matlab Textscan. Here we discuss the Working of TextScan() and Examples along with the codes and outputs. You may also have a look at the following articles to learn more –
