octave_packages/m/io/dlmwrite.m

   1 ## Copyright (C) 2002-2012 Paul Kienzle
   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} {} dlmwrite (@var{file}, @var{M})
  21 ## @deftypefnx {Function File} {} dlmwrite (@var{file}, @var{M}, @var{delim}, @var{r}, @var{c})
  22 ## @deftypefnx {Function File} {} dlmwrite (@var{file}, @var{M}, @var{key}, @var{val} @dots{})
  23 ## @deftypefnx {Function File} {} dlmwrite (@var{file}, @var{M}, "-append", @dots{})
  24 ## @deftypefnx {Function File} {} dlmwrite (@var{fid}, @dots{})
  25 ## Write the matrix @var{M} to the named file using delimiters.
  26 ##
  27 ## @var{file} should be a file name or writable file ID given by @code{fopen}.
  28 ##
  29 ## The parameter @var{delim} specifies the delimiter to use to separate
  30 ## values on a row.
  31 ##
  32 ## The value of @var{r} specifies the number of delimiter-only lines to
  33 ## add to the start of the file.
  34 ##
  35 ## The value of @var{c} specifies the number of delimiters to prepend to
  36 ## each line of data.
  37 ##
  38 ## If the argument @code{"-append"} is given, append to the end of
  39 ## @var{file}.
  40 ##
  41 ## In addition, the following keyword value pairs may appear at the end
  42 ## of the argument list:
  43 ##
  44 ## @table @asis
  45 ## @item "append"
  46 ## Either @samp{"on"} or @samp{"off"}.  See @samp{"-append"} above.
  47 ##
  48 ## @item "delimiter"
  49 ## See @var{delim} above.
  50 ##
  51 ## @item "newline"
  52 ## The character(s) to use to separate each row.  Three special cases
  53 ## exist for this option.  @samp{"unix"} is changed into "\n",
  54 ## @samp{"pc"} is changed into "\r\n", and @samp{"mac"} is changed
  55 ## into "\r".  Other values for this option are kept as is.
  56 ##
  57 ## @item "roffset"
  58 ## See @var{r} above.
  59 ##
  60 ## @item "coffset"
  61 ## See @var{c} above.
  62 ##
  63 ## @item "precision"
  64 ## The precision to use when writing the file.  It can either be a
  65 ## format string (as used by fprintf) or a number of significant digits.
  66 ## @end table
  67 ##
  68 ## @example
  69 ## dlmwrite ("file.csv", reshape (1:16, 4, 4));
  70 ## @end example
  71 ##
  72 ## @example
  73 ## dlmwrite ("file.tex", a, "delimiter", "&", "newline", "\\n")
  74 ## @end example
  75 ##
  76 ## @seealso{dlmread, csvread, csvwrite}
  77 ## @end deftypefn
  78
  79 ## Author: Paul Kienzle <pkienzle@users.sf.net>
  80 ##
  81 ## This program was originally granted to the public domain
  82 ##
  83 ## 2002-03-08 Paul Kienzle <pkienzle@users.sf.net>
  84 ## * Initial revision
  85 ## 2005-11-27 Bill Denney <bill@givebillmoney.com>
  86 ## * Significant modifications of the input arguments for additional
  87 ## functionality.
  88
  89 function dlmwrite (file, M, varargin)
  90
  91   if (nargin < 2)
  92     print_usage ();
  93   endif
  94
  95   ## set defaults
  96   delim = ",";
  97   r = c = 0;
  98   newline = "\n";
  99   if (ischar (M))
 100     precision = "%c";
 101   else
 102     precision = "%.16g";
 103   endif
 104   opentype = "wt";
 105
 106   ## process the input arguments
 107   i = 0;
 108   while (i < length (varargin))
 109     i++;
 110     if (strcmpi (varargin{i}, "delimiter"))
 111       delim = varargin{++i};
 112     elseif (strcmpi (varargin{i}, "newline"))
 113       newline = varargin{++i};
 114       if (strcmpi (newline, "unix"))
 115         newline = "\n";
 116       elseif (strcmpi (newline, "pc"))
 117         newline = "\r\n";
 118       elseif (strcmpi (newline, "mac"))
 119         newline = "\r";
 120       endif
 121     elseif (strcmpi (varargin{i}, "roffset"))
 122       r = varargin{++i};
 123     elseif (strcmpi (varargin{i}, "coffset"))
 124       c = varargin{++i};
 125     elseif (strcmpi (varargin{i}, "precision"))
 126       precision = varargin{++i};
 127       if (! strcmpi (class (precision), "char"))
 128         precision = sprintf ("%%.%gg", precision);
 129       endif
 130     elseif (strcmpi (varargin{i}, "-append"))
 131       opentype = "at";
 132     elseif (strcmpi (varargin{i}, "append"))
 133       i++;
 134       if (strcmpi (varargin{i}, "on"))
 135         opentype = "at";
 136       elseif (strcmpi (varargin{i}, "off"))
 137         opentype = "wt";
 138       else
 139         error ('dlmwrite: append must be "on" or "off"');
 140       endif
 141     else
 142       if (i == 1)
 143         delim = varargin{i};
 144       elseif (i == 2)
 145         r = varargin{i};
 146       elseif (i == 3)
 147         c = varargin{i};
 148       else
 149         print_usage();
 150       endif
 151     endif
 152   endwhile
 153
 154   if (ischar (file))
 155     [fid, msg] = fopen (file, opentype);
 156   elseif (isscalar (file) && isnumeric (file))
 157     [fid, msg] = deal (file, "invalid file number");
 158   else
 159     error ("dlmwrite: FILE must be a filename string or numeric FID");
 160   endif
 161
 162   if (fid < 0)
 163     error (["dlmwrite: " msg]);
 164   else
 165     if (r > 0)
 166       fprintf (fid, "%s",
 167                repmat ([repmat(delim, 1, c + columns(M)-1), newline], 1, r));
 168     endif
 169     if (iscomplex (M))
 170       cprecision = regexprep (precision, '^%([-\d.])', '%+$1');
 171       template = [precision, cprecision, "i", ...
 172                   repmat([delim, precision, cprecision, "i"], 1, ...
 173                   columns(M) - 1), newline ];
 174     else
 175       template = [precision, repmat([delim, precision], 1, columns(M)-1),...
 176                   newline];
 177     endif
 178     if (c > 0)
 179       template = [repmat(delim, 1, c), template];
 180     endif
 181     if (iscomplex (M))
 182       M = M.';
 183       b = zeros (2*rows(M), columns (M));
 184       b(1: 2 : end, :) = real (M);
 185       b(2: 2 : end, :) = imag (M);
 186       fprintf (fid, template, b);
 187     else
 188       fprintf (fid, template, M.');
 189     endif
 190     if (! isscalar (file))
 191       fclose (fid);
 192     endif
 193   endif
 194
 195 endfunction
 196
 197
 198 %!test
 199 %! f = tmpnam ();
 200 %! dlmwrite (f,[1,2;3,4],'precision','%5.2f','newline','unix','roffset',1,'coffset',1);
 201 %! fid = fopen (f,"rt");
 202 %! f1 = char (fread (fid,Inf,'char')');
 203 %! fclose (fid);
 204 %! dlmwrite (f,[5,6],'precision','%5.2f','newline','unix','coffset',1,'delimiter',',','-append');
 205 %! fid = fopen (f,"rt");
 206 %! f2 = char (fread (fid,Inf,'char')');
 207 %! fclose (fid);
 208 %! unlink (f);
 209 %!
 210 %! assert (f1,",,\n, 1.00, 2.00\n, 3.00, 4.00\n");
 211 %! assert (f2,",,\n, 1.00, 2.00\n, 3.00, 4.00\n, 5.00, 6.00\n");
 212