textscan — Parse formatted text from a string or file identifier.
C = textscan(textOrFileID, formatSpec) parses formatted text from a string or from the current position of a file identifier opened by fopen.
Syntax
C = textscan(textOrFileID, formatSpec)
C = textscan(textOrFileID, formatSpec, args...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
textOrFileID | Any | Yes | — | Input text or file identifier opened by fopen. |
formatSpec | StringScalar | Yes | — | Format specification such as '%f %s'. |
args... | Any | Variadic | — | Optional repeat count followed by name-value pairs. |
Returns
| Name | Type | Description |
|---|---|---|
C | Any | Cell array containing one output per conversion, or collected groups. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:textscan:InvalidArgument | Input, format specification, repeat count, or name-value options are malformed. | textscan: invalid argument |
RunMat:textscan:InvalidFormat | Format specification cannot be parsed or contains unsupported conversions. | textscan: invalid format specification |
RunMat:textscan:File | A file identifier is invalid or cannot be read. | textscan: file read failed |
RunMat:textscan:Parse | Input text cannot be parsed according to the format specification. | textscan: parse failed |
How textscan works
- Accepts string, string-array scalar, row character-vector, numeric file identifier, or scalar numeric tensor file identifier as the first argument.
- Supports optional repeat count
Nbefore name-value options. - Supports numeric conversions
%f,%e,%g,%d,%i, and%u; text conversions%s,%q,%c, and character-set conversions such as%[ABC]and%[^,]. - Supports skipped conversions with
%*and field widths such as%5for%10s. - Text columns return cell columns of strings. Numeric columns return column tensors. With
'CollectOutput', true, adjacent numeric columns are grouped into one numeric matrix. - Recognizes
Delimiter,MultipleDelimsAsOne,HeaderLines,TreatAsEmpty,CommentStyle,CollectOutput,ReturnOnError, andWhitespaceoptions. - Line comments and block comments are ignored while scanning input. Blank records are skipped after header/comment processing.
ReturnOnErrordefaults to true, returning data parsed before the first incompatible token. Set it to false to raise a parse error.
Does RunMat run textscan on the GPU?
textscan does not launch provider kernels or participate in fusion.
GPU memory and residency
textscan is a host file/string import source. It returns host cells and tensors and does not create GPU-resident arrays.
Examples
Parse numeric and text columns
C = textscan("1 alpha\n2 beta\n", "%f %s");
nums = C{1};
labels = C{2};Parse CSV with header and missing tokens
txt = "name,value\nA,1.5\nB,NA\n";
C = textscan(txt, "%s %f", 'Delimiter', ',', 'HeaderLines', 1, 'TreatAsEmpty', 'NA');Read from a file identifier
fid = fopen("log.txt", "r");
C = textscan(fid, "%f %s", 'HeaderLines', 1);
fclose(fid);Using textscan with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how textscan changes the result.
Run a small textscan example, explain the result, then change one input and compare the output.
FAQ
Does textscan read filenames directly?⌄
No. Like MATLAB, a text string is parsed as text content. Use fopen to get a file identifier when reading a file.
How are text outputs represented?⌄
Text conversions return cell columns containing string values. Numeric conversions return dense double tensors.
When should I use readmatrix instead?⌄
Use readmatrix for simple numeric delimited files. Use textscan when legacy code has explicit format strings, mixed text/numeric columns, comments, or skipped fields.
Related Io functions
Import
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname · uigetfile · uiputfile
Tabular
csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · readmatrix · spreadsheetImportOptions · writecell · writematrix · xlsread
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Json
Archive
Http
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how textscan is executed, line by line, in Rust.
- View the source for textscan in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.