%TEXTREAD Read formatted data from text file.
%    [A,B,C,...] = TEXTREAD(FILENAME,FORMAT,N) reads data from the file
%    FILENAME into the variables A,B,C,etc.  The number and types of each
%    return argument is given by the FORMAT string.  The number of return
%    arguments is the number of conversion specifiers in the FORMAT
%    string.  The FORMAT string supports a subset of the specifiers and
%    conventions of the C language FSCANF function.  If N is specified,
%    the format string will be reused N times.  Values of N smaller than
%    zero cause TEXTREAD to read the entire file (the default).
%
%    The FORMAT string can contain whitespace characters (which are
%    ignored), ordinary characters (which are expected to match the next
%    non-whitespace character in the input), or conversion
%    specifications.
%    
%    Supported conversion specifications:
%        %d  - read a signed integer value (output is a double array)
%        %u  - read a integer value (output is a double array)
%        %f  - read a floating point value (output is a double array)
%        %s  - read a whitespace separated string (output is a cellstr)
%        %q  - read a (possibly double quoted) string (output is a cellstr)
%        %c  - read characters (including white space) (output is char array)
%        %[...]  - reads the longest string containing characters in the set
%                  between the brackets (output is a cellstr)
%        %[^...] - reads the longest non-empty string containing characters
%                  not in the set between brackets (output is a cellstr)
%        
%    Using %* instead of % in a conversion causes TEXTREAD to skip the
%    matching characters in the input (and no output is created for this
%    conversion).  The % can be followed by an optional field width to
%    handle fixed width fields. For example %5d reads a 5 digit
%    integer. In addition the %f format supports the form %<width>.<prec>f.
%
%    TEXTREAD works by matching and converting groups of characters from
%    the input.  These input fields are defined as a string of non-white
%    space characters that extends to the next white space or delimiter
%    character or until the maximum field width is exhausted.  Repeated
%    delimiter characters are significant while repeated whitespace
%    characters are treated as one.
%
%    [...] = TEXTREAD(...,param,value,...) allows param/value pairs to be
%    used to customize the behavior of TEXTREAD.  Possible param/value
%    options are:
%         'whitespace'   - vector of characters to treat as whitespace
%                          (default is ' \b\r\n\t')
%         'delimiter'    - delimiter characters (default is none)
%         'expchars'     - exponent characters (default is 'eEdD')
%         'bufsize'      - Maximum string length in bytes (default is 4095)
%         'headerlines'  - Number of lines at beginning of file to skip
%         'commentstyle' - one of 
%              'matlab' -- characters after % are ignored
%              'shell'  -- characters after # are ignored
%              'c'      -- characters between /* and */ are ignored
%              'c++'    -- characters after // are ignored
%    
%    TEXTREAD is useful for reading text files with a known format.  Both
%    fixed and free format files can be handled.
%
%    Examples:
%     Suppose the text file mydata.dat contains data in the following form:
%        Sally    Type1 12.34 45 Yes
%        Joe      Type2 23.54 60 No
%        Bill     Type1 34.90 12 No
%          
%     This could be read using the following command
%       [names,types,x,y,answer] = textread('mydata.dat','%s %s %f %d %s');
%         
%     Read file as a fixed format file while skipping the doubles
%       [names,types,y,answer] = textread('mydata.dat','%9c %5s %*f %2d %3s');
%
%     Read file and match Type literal
%       [names,typenum,x,y,answer]=textread('mydata.dat','%s Type%d %f %d %s');
%
%     Read m-file into cell array of strings
%       file = textread('fft.m','%s','delimiter','\n','whitespace','');
%	
%   See also DLMREAD, SSCANF.

%   Clay M. Thompson 3-3-98
%   Copyright (c) 1984-98 by The MathWorks, Inc.
%   $Revision: 1.1 $ $Date: 1998/03/28 03:16:05 $

%   Implemented as a mex file.
