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 floating conversions including
%f32and%f64, decimal integer conversions%d,%i, and%u, hexadecimal%x, and binary%b. Documented size and signedness suffixes select nativeint8throughint64oruint8throughuint64; unsuffixed decimal signed/unsigned conversions returnint32/uint32, and unsuffixed hexadecimal/binary conversions returnuint64. - Supports skipped conversions with
%*and field widths such as%5for%10s. - Text columns return cell columns of strings. Numeric columns retain their selected native class, including exact 64-bit integers and physical single precision. With
'CollectOutput', true, only adjacent numeric columns of the same class are grouped into one 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.- Typed-integer file identifiers, repeat counts, and numeric controls are RunMat-only extensions. MATLAB compatibility mode rejects them before scanning; documented integer conversion specifiers remain enabled in both modes.
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 tensors in the class selected by the format specifier; integer columns are not routed through double.
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 · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Json
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.