1 ## Copyright (C) 1993-2012 John W. Eaton
3 ## This file is part of Octave.
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.
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.
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/>.
20 ## @deftypefn {Function File} {} num2str (@var{x})
21 ## @deftypefnx {Function File} {} num2str (@var{x}, @var{precision})
22 ## @deftypefnx {Function File} {} num2str (@var{x}, @var{format})
23 ## Convert a number (or array) to a string (or a character array). The
24 ## optional second argument may either give the number of significant
25 ## digits (@var{precision}) to be used in the output or a format
26 ## template string (@var{format}) as in @code{sprintf} (@pxref{Formatted
27 ## Output}). @code{num2str} can also handle complex numbers. For
35 ## num2str (123.456, 4)
38 ## s = num2str ([1, 1.34; 3, 3.56], "%5.1f")
44 ## Attr Name Size Bytes Class
45 ## ==== ==== ==== ===== =====
48 ## num2str (1.234 + 27.3i)
49 ## @result{} "1.234+27.3i"
53 ## The @code{num2str} function is not very flexible. For better control
54 ## over the results, use @code{sprintf} (@pxref{Formatted Output}).
55 ## Note that for complex @var{x}, the format string may only contain one
56 ## output conversion specification and nothing else. Otherwise, you
57 ## will get unpredictable results.
58 ## @seealso{sprintf, int2str, mat2str}
63 function retval = num2str (x, arg)
65 if (nargin != 1 && nargin != 2)
73 elseif (iscomplex (x))
76 fmt = cstrcat (arg, "%-+", arg(2:end), "i");
78 if (isnumeric (x) && x == fix (x) && abs (x) < (10 .^ arg))
79 fmt = sprintf ("%%%dd%%-+%ddi ", arg, arg);
81 fmt = sprintf ("%%%d.%dg%%-+%d.%dgi", arg+7, arg, arg+7, arg);
85 ## Setup a suitable format string
86 if (isnumeric (x) && x == fix (x) && abs (x) < 1e10)
87 if (max (abs (real (x(:)))) == 0)
90 dgt1 = ceil (log10 (max (max (abs (real (x(:)))),
91 max (abs (imag (x(:))))))) + 2;
93 dgt2 = dgt1 - (min (real (x(:))) >= 0);
95 if (length (abs (x) == x) > 0)
96 fmt = sprintf("%%%dg%%+-%dgi ", dgt2, dgt1);
98 fmt = sprintf("%%%dd%%+-%ddi ", dgt2, dgt1);
100 elseif (isscalar (x))
103 fmt = "%11.6g%-+11.6gi";
107 ## Manipulate the complex value to have real values in the odd
108 ## columns and imaginary values in the even columns.
112 perm = fix ([1:0.5:nc+0.5]);
113 perm(2:2:2*nc) = perm(2:2:2*nc) + nc;
114 idx = repmat ({':'}, nd, 1);
116 x = horzcat (real (x), imag (x));
119 fmt = cstrcat (deblank (repmat (fmt, 1, nc)), "\n");
120 tmp = sprintf (fmt, permute (x, [2, 1, 3:nd]));
122 ## Put the "i"'s where they are supposed to be.
124 tmp2 = strrep (tmp, " i\n", "i\n");
125 if (length (tmp) == length (tmp2))
132 tmp2 = strrep (tmp, " i", "i ");
140 tmp(length (tmp)) = "";
141 retval = char (strtrim (strsplit (tmp, "\n")));
147 if (isnumeric (x) && x == fix (x) && abs (x) < (10 .^ arg))
148 fmt = sprintf ("%%%dd ", arg);
150 fmt = sprintf ("%%%d.%dg", arg+7, arg);
154 if (isnumeric (x) && x == fix (x) && abs (x) < 1e10)
155 if (max (abs (x(:))) == 0)
158 dgt = floor (log10 (max (abs(x(:))))) + (min (real (x(:))) < 0) + 2;
160 if (length (abs (x) == x) > 0)
161 fmt = sprintf ("%%%dg ", dgt);
163 fmt = sprintf ("%%%dd ", dgt);
165 elseif (isscalar (x))
171 fmt = cstrcat (deblank (repmat (fmt, 1, columns (x))), "\n");
173 tmp = sprintf (fmt, permute (x, [2, 1, 3:nd]));
174 tmp(length (tmp)) = "";
175 retval = strtrim (char (strsplit (tmp, "\n")));
180 %!assert ((strcmp (num2str (123), "123") && strcmp (num2str (1.23), "1.23")));
181 %!assert (num2str (123.456, 4), "123.5");
182 %!assert (all (num2str ([1, 1.34; 3, 3.56], "%5.1f") == ["1.0 1.3"; "3.0 3.6"]));
183 %!assert (num2str (1.234 + 27.3i), "1.234+27.3i");
185 %!error num2str (1, 2, 3);