octave_packages/m/strings/mat2str.m

   1 ## Copyright (C) 2002-2012 Rolf Fabian
   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{s} =} mat2str (@var{x}, @var{n})
  21 ## @deftypefnx {Function File} {@var{s} =} mat2str (@var{x}, @var{n}, "class")
  22 ## Format real, complex, and logical matrices as strings.  The
  23 ## returned string may be used to reconstruct the original matrix by using
  24 ## the @code{eval} function.
  25 ##
  26 ## The precision of the values is given by @var{n}.  If @var{n} is a
  27 ## scalar then both real and imaginary parts of the matrix are printed
  28 ## to the same precision.  Otherwise @code{@var{n}(1)} defines the
  29 ## precision of the real part and @code{@var{n}(2)} defines the
  30 ## precision of the imaginary part.  The default for @var{n} is 15.
  31 ##
  32 ## If the argument "class" is given then the class of @var{x} is
  33 ## included in the string in such a way that @code{eval} will result in the
  34 ## construction of a matrix of the same class.
  35 ##
  36 ## @example
  37 ## @group
  38 ## mat2str ([ -1/3 + i/7; 1/3 - i/7 ], [4 2])
  39 ##      @result{} "[-0.3333+0.14i;0.3333-0.14i]"
  40 ##
  41 ## mat2str ([ -1/3 +i/7; 1/3 -i/7 ], [4 2])
  42 ##      @result{} "[-0.3333+0i 0+0.14i;0.3333+0i -0-0.14i]"
  43 ##
  44 ## mat2str (int16([1 -1]), "class")
  45 ##      @result{} "int16([1 -1])"
  46 ##
  47 ## mat2str (logical (eye (2)))
  48 ##      @result{} "[true false;false true]"
  49 ##
  50 ## isequal (x, eval (mat2str (x)))
  51 ##      @result{} 1
  52 ## @end group
  53 ## @end example
  54 ##
  55 ## @seealso{sprintf, num2str, int2str}
  56 ## @end deftypefn
  57
  58 ## Author: Rolf Fabian <fabian@tu-cottbus.de>
  59
  60 function s = mat2str (x, n = 15, cls = "")
  61
  62   if (nargin < 1 || nargin > 3 || ! (isnumeric (x) || islogical (x)))
  63     print_usage ();
  64   elseif (ndims (x) > 2)
  65     error ("mat2str: X must be two dimensional");
  66   endif
  67
  68   if (nargin == 2 && ischar (n))
  69     cls = n;
  70     n = 15;
  71   elseif (isempty (n))
  72     n = 15;   # Default precision
  73   endif
  74
  75   x_islogical = islogical (x);
  76   x_iscomplex = iscomplex (x);
  77
  78   if (x_iscomplex)
  79     if (isscalar (n))
  80       n = [n, n];
  81     endif
  82     fmt = sprintf ("%%.%dg%%+.%dgi", n(1), n(2));
  83   elseif (x_islogical)
  84     v = {"false", "true"};
  85     fmt = "%s";
  86   else
  87     fmt = sprintf ("%%.%dg", n(1));
  88   endif
  89
  90   nel = numel (x);
  91
  92   if (nel == 0)
  93     ## Empty, only print brackets
  94     s = "[]";
  95   elseif (nel == 1)
  96     ## Scalar X, don't print brackets
  97     if (x_iscomplex)
  98       s = sprintf (fmt, real (x), imag (x));
  99     elseif (x_islogical)
 100       s = v{x+1};
 101     else
 102       s = sprintf (fmt, x);
 103     endif
 104   else
 105     ## Non-scalar X, print brackets
 106     fmt = cstrcat (fmt, " ");
 107     if (x_iscomplex)
 108       t = x.';
 109       s = sprintf (fmt, [real(t(:))'; imag(t(:))']);
 110     elseif (x_islogical)
 111       t = v(x+1);
 112       s = cstrcat (sprintf (fmt, t{:}));
 113     else
 114       s = sprintf (fmt, x.');
 115     endif
 116
 117     s = cstrcat ("[", s);
 118     s(end) = "]";
 119     idx = strfind (s, " ");
 120     nc = columns (x);
 121     s(idx(nc:nc:end)) = ";";
 122   endif
 123
 124   if (strcmp ("class", cls))
 125     s = cstrcat (class (x), "(", s, ")");
 126   endif
 127
 128 endfunction
 129
 130
 131 %!assert (mat2str (0.7), "0.7");
 132 %!assert (mat2str (pi), "3.14159265358979");
 133 %!assert (mat2str (pi, 5), "3.1416");
 134 %!assert (mat2str (single (pi), 5, "class"), "single(3.1416)");
 135 %!assert (mat2str ([-1/3 + i/7; 1/3 - i/7], [4 2]), "[-0.3333+0.14i;0.3333-0.14i]")
 136 %!assert (mat2str ([-1/3 +i/7; 1/3 -i/7], [4 2]), "[-0.3333+0i 0+0.14i;0.3333+0i -0-0.14i]")
 137 %!assert (mat2str (int16 ([1 -1]), 'class'), "int16([1 -1])")
 138 %!assert (mat2str (true), "true");
 139 %!assert (mat2str (false), "false");
 140 %!assert (mat2str (logical (eye (2))), "[true false;false true]");
 141
 142 %% Test input validation
 143 %!error mat2str ()
 144 %!error mat2str (1,2,3,4)
 145 %!error mat2str (["Hello"])
 146 %!error mat2str (ones(3,3,2))
 147