octave_packages/m/io/textread.m

   1 ## Copyright (C) 2009-2012 Eric Chassande-Mottin, CNRS (France)
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {[@var{a}, @dots{}] =} textread (@var{filename})
  21 ## @deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format})
  22 ## @deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{n})
  23 ## @deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{prop1}, @var{value1}, @dots{})
  24 ## @deftypefnx {Function File} {[@var{a}, @dots{}] =} textread (@var{filename}, @var{format}, @var{n}, @var{prop1}, @var{value1}, @dots{})
  25 ## Read data from a text file.
  26 ##
  27 ## The file @var{filename} is read and parsed according to @var{format}.  The
  28 ## function behaves like @code{strread} except it works by parsing a file
  29 ## instead of a string.  See the documentation of @code{strread} for details.
  30 ##
  31 ## In addition to the options supported by @code{strread}, this function
  32 ## supports two more:
  33 ##
  34 ## @itemize
  35 ## @item "headerlines":
  36 ## The first @var{value} number of lines of @var{filename} are skipped.
  37 ##
  38 ## @item "endofline":
  39 ## Specify a single character or "\r\n".  If no value is given, it will be
  40 ## inferred from the file.  If set to "" (empty string) EOLs are ignored as
  41 ## delimiters.
  42 ## @end itemize
  43 ##
  44 ## The optional input @var{n} specifes the number of times to use
  45 ## @var{format} when parsing, i.e., the format repeat count.
  46 ##
  47 ## @seealso{strread, load, dlmread, fscanf, textscan}
  48 ## @end deftypefn
  49
  50 function varargout = textread (filename, format = "%f", varargin)
  51
  52   ## Check input
  53   if (nargin < 1)
  54     print_usage ();
  55   endif
  56
  57   if (! ischar (filename) || ! ischar (format))
  58     error ("textread: FILENAME and FORMAT arguments must be strings");
  59   endif
  60
  61   ## Read file
  62   fid = fopen (filename, "r");
  63   if (fid == -1)
  64     error ("textread: could not open '%s' for reading", filename);
  65   endif
  66
  67   ## Skip header lines if requested
  68   headerlines = find (strcmpi (varargin, "headerlines"), 1);
  69   ## Beware of zero valued headerline, fskipl would skip to EOF
  70   if (! isempty (headerlines) && (varargin{headerlines + 1} > 0))
  71     fskipl (fid, varargin{headerlines + 1});
  72     varargin(headerlines:headerlines+1) = [];
  73   endif
  74
  75   if (nargin > 2 && isnumeric (varargin{1}))
  76     nlines = varargin{1};
  77   else
  78     nlines = Inf;
  79   endif
  80
  81   if (isfinite (nlines) && (nlines >= 0))
  82     str = tmp_str = "";
  83     n = 0;
  84     ## FIXME: Can this be done without slow loop?
  85     while (ischar (tmp_str) && n++ <= nlines)
  86       str = strcat (str, tmp_str);
  87       tmp_str = fgets (fid);
  88     endwhile
  89   else
  90     str = fread (fid, "char=>char").';
  91   endif
  92   fclose (fid);
  93
  94   if (isempty (str))
  95     warning ("textread: empty file");
  96     return;
  97   endif
  98
  99   endofline = find (strcmpi (varargin, "endofline"), 1);
 100   if (! isempty (endofline))
 101     ## 'endofline' option set by user.
 102     if (! ischar (varargin{endofline + 1}));
 103       error ("textread: character value required for EndOfLine");
 104     endif
 105   else
 106     ## Determine EOL from file.  Search for EOL candidates in first 3000 chars
 107     eol_srch_len = min (length (str), 3000);
 108     ## First try DOS (CRLF)
 109     if (! isempty (findstr ("\r\n", str(1 : eol_srch_len))))
 110       eol_char = "\r\n";
 111     ## Perhaps old Macintosh? (CR)
 112     elseif (! isempty (findstr ("\r", str(1 : eol_srch_len))))
 113       eol_char = "\r";
 114     ## Otherwise, use plain UNIX (LF)
 115     else
 116       eol_char = "\n";
 117     endif
 118     ## Set up default endofline param value
 119     varargin(end+1:end+2) = {'endofline', eol_char};
 120   endif
 121
 122   ## Set up default whitespace param value if needed
 123   if (isempty (find (strcmpi ('whitespace', varargin))))
 124     varargin(end+1:end+2) = {'whitespace', " \b\t"};
 125   endif
 126
 127   ## Call strread to make it do the real work
 128   [varargout{1:max (nargout, 1)}] = strread (str, format, varargin {:});
 129
 130 endfunction
 131
 132
 133 %!test
 134 %! f = tmpnam();
 135 %! d = rand (5, 3);
 136 %! dlmwrite (f, d, 'precision', '%5.2f');
 137 %! [a, b, c] = textread (f, "%f %f %f", "delimiter", ",", "headerlines", 3);
 138 %! unlink(f);
 139 %! assert (a, d(4:5, 1), 1e-2);
 140 %! assert (b, d(4:5, 2), 1e-2);
 141 %! assert (c, d(4:5, 3), 1e-2);
 142
 143 %% Test input validation
 144 %!error textread ()
 145 %!error textread (1)
 146 %!error <arguments must be strings> textread (1, '%f')
 147 %!error <arguments must be strings> textread ("fname", 1)
 148