function [varargout] = textscan(varargin) %TEXTSCAN Read formatted data from text file. % C = TEXTSCAN(FID,'FORMAT') reads data from the text % file identified by FID into cell array C. The data are parsed into % fields and converted according to the conversions specified in the % string, FORMAT. The number of cells in C will equal the number of % conversion specifiers in FORMAT. The type of each cell is determined % by FORMAT. See "Format Options" below. % % C = TEXTSCAN(FID,'FORMAT',N) N must be a positive integer. FORMAT is % reused N times. % % C = TEXTSCAN(FID,'FORMAT',PARAMETER,VALUE, ...) % C = TEXTSCAN(FID,'FORMAT',N,PARAMETER,VALUE, ...) % Multiple PARAMETER and VALUE pairs may be used, in any order. A VALUE % must immediately follow its PARAMETER. See "Parameter Options" below. % % C = TEXTSCAN(STR,...) reads data from a string in exactly the same % way as from a file. You cannot automatically resume reading from the % same place in the string. You can use 'FORMAT', N, and PARAMETER/VALUE % arguments, as described above, with this syntax. % % [C, POSITION] = TEXTSCAN(...) returns the location of the file or % string position as the second output argument. For a file, this is % exactly equivalent to calling FTELL(FID) after making the call to % TEXTSCAN. For a string, it indicates how many characters were read. % % If TEXTSCAN fails to convert a data field, it stops reading and returns % all fields read before the failure. When reading from a file, you may % resume reading by calling TEXTSCAN again, with the original FID as the % first argument. When finished reading from the file, you should close % the file by calling FCLOSE(FID). When reading from a string, the two % output argument syntax must be used in order to be able to resume % reading from the same place. You may then call: % TEXTSCAN(STR(POSITION+1:end),...). % % TEXTSCAN regards a text file as consisting of blocks. Each block % consists of a number of internally consistent fields. Each field % consists of a group of characters delimited by a field delimiter % character (DLM). The fields may span over a number of rows. Each row is % delimited by an End-Of-Line (EOL) character sequence. % % Format Options: % % The FORMAT string is of the form: %. % is optional and specifies the number of characters in a field % to read. Setting to * causes TEXTSCAN to skip the particular % field in the input and no output cell is created for this % conversion. % only applies to the family of %f specifiers and states the % number of significant fractional digits to be converted. % must be given and determines the conversion output type. % % Supported FORMAT specifiers: % %n - read and convert a number to double % %d - read and convert a number to int32 % %d8 - read and convert a number to int8 % %d16 - read and convert a number to int16 % %d32 - read and convert a number to int32 % %d64 - read and convert a number to int64 % %u - read a number and convert to uint32 % %u8 - read and convert a number to uint8 % %u16 - read and convert a number to uint16 % %u32 - read a number and convert to uint32 % %u64 - read a number and convert to uint64 % %f - read a number and convert to double % %f32 - read a number and convert to single % %f64 - read a number and convert to double % %s - read a string % %q - read a (possibly double-quoted) string % %c - read a character, including whitespace % %[...] - reads characters matching characters between the % brackets until first non-matching character or % whitespace. Use %[]...] to include ] in the set. % %[^...] - reads characters not matching characters between the % brackets until first matching character or whitespace. % Use %[^]...] to exclude ] in the set. % % PARAMETER options: % % 'bufSize' - maximum string length in bytes (default is 4095) % 'commentStyle' - one of: % - a single string. Characters following the string until the % end of a line or file, will be ignored. % - a cell array of two strings. The first string indicates the % beginning of a comment, the second, the end, e.g. {'/*','*/'} % for C-style comments. % 'delimiter' - delimiter characters (default is none) % 'emptyValue' - Value to use when an empty field is encountered % (default is NaN). % 'endOfLine' - end of line character (default determined from file). % 'expChars' - exponent characters (default is 'eEdD'). % 'headerLines' - number of lines at beginning of file to skip. % 'whitespace' - whitespace characters (default is ' \b\t') % 'returnOnError'- behavior on failing to read or convert (1=true or 0) % (default is 1). % 'treatAsEmpty' - specify one or more strings to be treated in the % same way as empty values. Either a single % string or a cell array of strings may be used. % 'multipleDelimsAsOne' % - If a delimiter is specified, this option % may be set to 1 in order to have consecutive % delimiters treated as one delimiter. It may be % set to 0 in order to treat them as separate % delimiters. This option may not be set if a % delimiter is not specified. The default is 0. % % EXAMPLES: % Suppose the text file 'mydata.dat' contains data in the following form: % Sally Type1 12.34 45 1.23e10 inf NaN Yes % Joe Type2 23.54 60 9e19 -inf 0.001 No % Bill Type3 34.90 12 2e5 10 100 No % % Example 1: Read each column into a variable % fid = fopen('mydata.dat'); % C = textscan(fid,'%s%s%f32%d8%u%f%f%s'); % fclose(fid); % C{1}=> 'Sally','Joe','Bill' % C{2}=> 'Type1','Type2','Type3' % C{3}=> [12.34;23.54;34.9] %class single % C{4}=> [45;60;12] %class int8 % C{5}=> [4294967295; 4294967295; 200000] %class uint32 % C{6}=> [Inf;-Inf;10] %class double % C{7}=> [NaN;0.001;100] %class double % C{8}=> 'Yes','No','No' % % The first two elements of C{5} are the maximum values for a 32-bit % unsigned integer, or intmax('uint32'). % % Example 2: Read the first column, skipping the rest of the line: % fid = fopen('mydata.dat'); % names = textscan(fid,'%s%*[^\n]'); % fclose(fid); % % Example 3: Read the file as a fixed-format file, skipping the third field % fid = fopen('mydata.dat'); % C = textscan(fid,'%9c%5s%*f%d8%u%f%f%s'); % fclose(fid); % C{3}=> [45;60;12] %class int8 % % Example 4: Read the file and match 'Type' literal in second field % fid = fopen('mydata.dat'); % C = textscan(fid,'%sType%f%f32%d8%u%f%f%s'); % fclose(fid); % C{1}=> 'Sally','Joe','Bill' % C{2}=> [1;2;3] %'Type' in field two has been skipped. % % Example 5: Read the file using -Inf in empty cells: % Suppose data.csv contains: % 1,2,3,4,,6 % 7,8,9,,11,12 % % fid = fopen('data.csv'); % C = textscan(fid,'%f%f%f%f%u64%f','delimiter',',','emptyValue',-inf); % fclose(fid); % C{4}=> [4;-Inf] %class double % C{5}=> [0;11] %class uint64 (uint64(-Inf) == 0) % % Example 6: Read files with custom empty values and comments. % Suppose data.csv contains: % abc,2,NA,3,4 % //Comment here % def,na,5,6,7 % % fid = fopen('data.csv'); % C = textscan(fid,'%s%n%n%n%n','delimiter',',',... % 'treatAsEmpty',{'NA','na'},'commentStyle', '//') % fclose(fid); % C{1}=> 'abc','def' % C{2}=> [2;NaN] % C{3}=> [NaN;5] % % See also FOPEN, FREAD, FREWIND, FSEEK, FCLOSE, LOAD, SSCANF, IMPORTDATA. % Adapted by JP Barnard. Based on dataread.c by Clay M. Thompson 3-3-98 % Copyright 1984-2004 The MathWorks, Inc. % $Revision: 1.1.6.13 $ $Date: 2004/10/27 23:53:49 $ % Package: libmwbuiltins % Built-in function. if nargout == 0 builtin('textscan', varargin{:}); else [varargout{1:nargout}] = builtin('textscan', varargin{:}); end