changeset 20521:4bb41929286b

Deprecate bitmax. * NEWS: Announce deprecation and replacement functions. * scripts/deprecated/bitmax.m: New function. Add deprecation message to docstring. Add deprecation warning to m-file. * scripts/deprecated/module.mk: Add deprecated versions to build system. * libinterp/corefcn/bitfcns.cc: Remove build-in function. Remove function from docstrings. * libinterp/corefcn/data.cc: Remove function from docstrings. * scripts/general/bitcmp.m: Replace bitmax function calls with flintmax. Remove function from docstrings. * scripts/general/bitget.m: Replace bitmax function calls with flintmax. Remove function from docstrings. * scripts/general/bitset.m: Replace bitmax function calls with flintmax. Remove function from docstrings. * scripts/specfun/factor.m: Replace bitmax function calls with flintmax. Remove function from docstrings. * scripts/statistics/distributions/unidpdf.m: Remove function from docstrings. * scripts/general/num2str.m: Replaced function in comment. * doc/interpreter/doccheck/aspell-octave.en.pws: Remove functions from list. * doc/interpreter/numbers.txi: Remove function from manual.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Wed, 09 Sep 2015 18:43:52 +0200
parents f515bac7c7c1
children a142b62527ef
files NEWS doc/interpreter/doccheck/aspell-octave.en.pws doc/interpreter/numbers.txi libinterp/corefcn/bitfcns.cc libinterp/corefcn/data.cc scripts/deprecated/bitmax.m scripts/deprecated/module.mk scripts/general/bitcmp.m scripts/general/bitget.m scripts/general/bitset.m scripts/general/num2str.m scripts/specfun/factor.m scripts/statistics/distributions/unidpdf.m
diffstat 13 files changed, 84 insertions(+), 75 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Tue Sep 08 10:39:50 2015 +0200
+++ b/NEWS	Wed Sep 09 18:43:52 2015 +0200
@@ -46,6 +46,7 @@
 
       Function             | Replacement
       ---------------------|------------------
+      bitmax               | flintmax
       wavread              | audioread
       wavwrite             | audiowrite
 
--- a/doc/interpreter/doccheck/aspell-octave.en.pws	Tue Sep 08 10:39:50 2015 +0200
+++ b/doc/interpreter/doccheck/aspell-octave.en.pws	Wed Sep 09 18:43:52 2015 +0200
@@ -74,7 +74,6 @@
 binornd
 Biomathematics
 bitmapped
-bitmax
 bitwise
 bivariate
 Blackman
--- a/doc/interpreter/numbers.txi	Tue Sep 08 10:39:50 2015 +0200
+++ b/doc/interpreter/numbers.txi	Wed Sep 09 18:43:52 2015 +0200
@@ -619,12 +619,7 @@
 
 As the maximum value that can be represented by a number is important
 for bit manipulation, particularly when forming masks, Octave supplies
-the function @code{bitmax}.
-
-@DOCSTRING(bitmax)
-
-This is the double precision version of the function @code{intmax},
-previously discussed.
+two functions 'flintmax' for floating point integers, and 'intmax'.
 
 Octave also includes the basic bitwise 'and', 'or', and 'exclusive or'
 operators.
--- a/libinterp/corefcn/bitfcns.cc	Tue Sep 08 10:39:50 2015 +0200
+++ b/libinterp/corefcn/bitfcns.cc	Wed Sep 09 18:43:52 2015 +0200
@@ -368,8 +368,8 @@
 @deftypefn {Built-in Function} {} bitand (@var{x}, @var{y})\n\
 Return the bitwise AND of non-negative integers.\n\
 \n\
-@var{x}, @var{y} must be in the range [0,bitmax]\n\
-@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}\n\
+@var{x}, @var{y} must be in the range [0,intmax]\n\
+@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}\n\
 @end deftypefn")
 {
   return bitop ("bitand", args);
@@ -378,10 +378,9 @@
 DEFUN (bitor, args, ,
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} bitor (@var{x}, @var{y})\n\
-Return the bitwise OR of non-negative integers.\n\
+Return the bitwise OR of non-negative integers @var{x} and @var{y}.\n\
 \n\
-@var{x}, @var{y} must be in the range [0,bitmax]\n\
-@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}\n\
+@seealso{bitor, bitxor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}\n\
 @end deftypefn")
 {
   return bitop ("bitor", args);
@@ -390,10 +389,9 @@
 DEFUN (bitxor, args, ,
        "-*- texinfo -*-\n\
 @deftypefn {Built-in Function} {} bitxor (@var{x}, @var{y})\n\
-Return the bitwise XOR of non-negative integers.\n\
+Return the bitwise XOR of non-negative integers @var{x} and @var{y}.\n\
 \n\
-@var{x}, @var{y} must be in the range [0,bitmax]\n\
-@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, bitmax}\n\
+@seealso{bitand, bitor, bitset, bitget, bitcmp, bitshift, intmax, flintmax}\n\
 @end deftypefn")
 {
   return bitop ("bitxor", args);
@@ -546,8 +544,8 @@
 \n\
 A positive @var{k} leads to a left shift; A negative value to a right shift.\n\
 \n\
-If @var{n} is omitted it defaults to log2(bitmax)+1.\n\
-@var{n} must be in the range [1,log2(bitmax)+1] usually [1,33].\n\
+If @var{n} is omitted it defaults to 64.\n\
+@var{n} must be in the range [1,64].\n\
 \n\
 @example\n\
 @group\n\
@@ -568,7 +566,7 @@
 @c @result{} 4  8\n\
 @end group\n\
 @end example\n\
-@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitmax}\n\
+@seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, intmax, flintmax}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -678,43 +676,6 @@
 %!error <N must be positive> bitshift (10, [-2 -1 0 1 2], -1)
 */
 
-DEFUN (bitmax, args, ,
-       "-*- texinfo -*-\n\
-@deftypefn  {Built-in Function} {} bitmax ()\n\
-@deftypefnx {Built-in Function} {} bitmax (\"double\")\n\
-@deftypefnx {Built-in Function} {} bitmax (\"single\")\n\
-Return the largest integer that can be represented within a floating point\n\
-value.\n\
-\n\
-The default class is @qcode{\"double\"}, but @qcode{\"single\"} is a\n\
-valid option.  On IEEE 754 compatible systems, @code{bitmax} is\n\
-@w{@math{2^{53} - 1}} for @qcode{\"double\"} and @w{@math{2^{24} -1}} for\n\
-@qcode{\"single\"}.\n\
-@seealso{flintmax, intmax, realmax, realmin}\n\
-@end deftypefn")
-{
-  octave_value retval;
-  std::string cname = "double";
-  int nargin = args.length ();
-
-  if (nargin == 1 && args(0).is_string ())
-    cname = args(0).string_value ();
-  else if (nargin != 0)
-    {
-      print_usage ();
-      return retval;
-    }
-
-  if (cname == "double")
-    retval = (static_cast<double> (max_mantissa_value<double> ()));
-  else if (cname == "single")
-    retval = (static_cast<float> (max_mantissa_value<float> ()));
-  else
-    error ("bitmax: not defined for class '%s'", cname.c_str ());
-
-  return retval;
-}
-
 DEFUN (flintmax, args, ,
        "-*- texinfo -*-\n\
 @deftypefn  {Built-in Function} {} flintmax ()\n\
@@ -726,7 +687,7 @@
 The default class is @qcode{\"double\"}, but @qcode{\"single\"} is a valid\n\
 option.  On IEEE 754 compatible systems, @code{flintmax} is @w{@math{2^{53}}}\n\
 for @qcode{\"double\"} and @w{@math{2^{24}}} for @qcode{\"single\"}.\n\
-@seealso{bitmax, intmax, realmax, realmin}\n\
+@seealso{intmax, realmax, realmin}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -785,7 +746,7 @@
 @end table\n\
 \n\
 The default for @var{type} is @code{int32}.\n\
-@seealso{intmin, flintmax, bitmax}\n\
+@seealso{intmin, flintmax}\n\
 @end deftypefn")
 {
   octave_value retval;
@@ -856,7 +817,7 @@
 @end table\n\
 \n\
 The default for @var{type} is @code{int32}.\n\
-@seealso{intmax, flintmax, bitmax}\n\
+@seealso{intmax, flintmax}\n\
 @end deftypefn")
 {
   octave_value retval;
--- a/libinterp/corefcn/data.cc	Tue Sep 08 10:39:50 2015 +0200
+++ b/libinterp/corefcn/data.cc	Wed Sep 09 18:43:52 2015 +0200
@@ -4719,7 +4719,7 @@
 the number of rows and columns and any further arguments specify additional\n\
 matrix dimensions.  The optional argument @var{class} specifies the return\n\
 type and may be either @qcode{\"double\"} or @qcode{\"single\"}.\n\
-@seealso{realmax, realmin, intmax, bitmax}\n\
+@seealso{realmax, realmin, intmax, flintmax}\n\
 @end deftypefn")
 {
   int nargin = args.length ();
@@ -4892,7 +4892,7 @@
 \n\
 The optional argument @var{class} specifies the return type and may be\n\
 either @qcode{\"double\"} or @qcode{\"single\"}.\n\
-@seealso{realmin, intmax, bitmax, eps}\n\
+@seealso{realmin, intmax, flintmax, eps}\n\
 @end deftypefn")
 {
   return fill_matrix (args, std::numeric_limits<double>::max (),
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/scripts/deprecated/bitmax.m	Wed Sep 09 18:43:52 2015 +0200
@@ -0,0 +1,52 @@
+## Copyright (C) 2004-2015 John W. Eaton
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn {Function File} {@var{r} =} bitmax (@var{precision})
+##
+## @code{bitmax} is deprecated and will be removed in Octave version 4.4.
+## Use @code{flintmax (precision) - 1} for the equivalent functionality.
+##
+## Return the largest integer @var{r} that can be represented within a
+## floating point value.
+##
+## The default class is @qcode{"double"}, but @qcode{"single"} is a valid
+## option.  On IEEE 754 compatible systems, @code{bitmax} is
+## @w{@math{2^{53} - 1}} for @qcode{"double"} and @w{@math{2^{24} - 1}} for
+## @qcode{"single"}.
+##
+## @seealso{flintmax, intmax, realmax, realmin}
+## @end deftypefn
+
+## Deprecated in version 4.2
+
+function r = bitmax (precision)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "bitmax is obsolete and will be removed from a future version of Octave, please use flintmax instead");
+  endif
+
+  if (nargin == 0)
+    precision = "double";
+  endif
+  r = flintmax (precision) - 1;
+
+endfunction
--- a/scripts/deprecated/module.mk	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/deprecated/module.mk	Wed Sep 09 18:43:52 2015 +0200
@@ -2,6 +2,7 @@
 
 scripts_deprecated_FCN_FILES = \
   scripts/deprecated/bicubic.m \
+  scripts/deprecated/bitmax.m \
   scripts/deprecated/delaunay3.m \
   scripts/deprecated/dump_prefs.m \
   scripts/deprecated/find_dir_in_path.m \
--- a/scripts/general/bitcmp.m	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/general/bitcmp.m	Wed Sep 09 18:43:52 2015 +0200
@@ -20,7 +20,7 @@
 ## @deftypefn {Function File} {} bitcmp (@var{A}, @var{k})
 ## Return the @var{k}-bit complement of integers in @var{A}.
 ##
-## If @var{k} is omitted @code{k = log2 (bitmax) + 1} is assumed.
+## If @var{k} is omitted @code{k = log2 (flintmax) + 1} is assumed.
 ##
 ## @example
 ## @group
@@ -33,7 +33,7 @@
 ## @end group
 ## @end example
 ##
-## @seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, bitmax}
+## @seealso{bitand, bitor, bitxor, bitset, bitget, bitcmp, bitshift, flintmax}
 ## @end deftypefn
 
 ## Liberally based on the version by Kai Habel from octave-forge
@@ -49,10 +49,10 @@
   endif
 
   if (isa (A, "double"))
-    bmax = bitmax;
+    bmax = flintmax - 1;
     amax = ceil (log2 (bmax));
   elseif (isa (A, "single"))
-    bmax = bitmax ("single");
+    bmax = flintmax ("single") - 1;
     amax = ceil (log2 (bmax));
   elseif (isinteger (A))
     amax = sizeof (ones (1, class (A))) * 8;
@@ -76,14 +76,14 @@
 
 %!test
 %! Amax = 53;
-%! Bmax = bitmax;
+%! Bmax = flintmax - 1;
 %! A = bitshift (Bmax,-2);
 %! assert (bitcmp (A,Amax),bitor (bitshift (1,Amax-1), bitshift (1,Amax-2)));
 %! assert (bitcmp (A,Amax-1), bitshift (1,Amax-2));
 %! assert (bitcmp (A,Amax-2), 0);
 %!test
 %! Amax = 24;
-%! Bmax = bitmax ("single");
+%! Bmax = flintmax ("single") - 1;
 %! A = bitshift (Bmax,-2);
 %! assert (bitcmp (A,Amax),bitor (bitshift (single (1),Amax-1), bitshift (single (1),Amax-2)));
 %! assert (bitcmp (A,Amax-1), bitshift (single (1),Amax-2));
--- a/scripts/general/bitget.m	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/general/bitget.m	Wed Sep 09 18:43:52 2015 +0200
@@ -28,7 +28,7 @@
 ## @result{} 0  1  1  0  0  1  0  0
 ## @end group
 ## @end example
-## @seealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, bitmax}
+## @seealso{bitand, bitor, bitxor, bitset, bitcmp, bitshift, intmax, flintmax}
 ## @end deftypefn
 
 ## Liberally based of the version by Kai Habel from octave-forge
@@ -40,10 +40,10 @@
   endif
 
   if (isa (A, "double"))
-    Amax = ceil (log2 (bitmax));
+    Amax = ceil (log2 (flintmax));
     _conv = @double;
   elseif (isa (A, "single"))
-    Amax = ceil (log2 (bitmax ("single")));
+    Amax = ceil (log2 (flintmax ("single")));
     _conv = @single;
   else
     if (isa (A, "uint8"))
--- a/scripts/general/bitset.m	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/general/bitset.m	Wed Sep 09 18:43:52 2015 +0200
@@ -32,7 +32,7 @@
 ##   @result{} 1011
 ## @end group
 ## @end example
-## @seealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, bitmax}
+## @seealso{bitand, bitor, bitxor, bitget, bitcmp, bitshift, intmax, flintmax}
 ## @end deftypefn
 
 function C = bitset (A, n, val)
@@ -54,7 +54,7 @@
   cl = class (A);
 
   if (isfloat (A) && isreal (A))
-    Bmax = bitmax (cl);
+    Bmax = flintmax (cl);
     Amax = ceil (log2 (Bmax));
   elseif (isinteger (A))
     Bmax = intmax (cl);
--- a/scripts/general/num2str.m	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/general/num2str.m	Wed Sep 09 18:43:52 2015 +0200
@@ -204,7 +204,7 @@
 %!assert (num2str (complex (NA, 1)), "NA+1i")
 %!assert (num2str (complex (1, NA)), "1+NAi")
 
-## FIXME: Integers greater than bitmax() should be masked to show just
+## FIXME: Integers greater than flintmax() - 1 should be masked to show just
 ##        16 digits of precision.
 %!xtest
 %! assert (num2str (1e23), "100000000000000000000000");
--- a/scripts/specfun/factor.m	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/specfun/factor.m	Wed Sep 09 18:43:52 2015 +0200
@@ -29,7 +29,7 @@
 ## their multiplicities.  That is, @code{prod (@var{pf} .^ @var{n}) == @var{q}}.
 ##
 ## Implementation Note: The input @var{q} must be less than
-## @code{bitmax} (9.0072e+15) in order to factor correctly.
+## @code{flintmax} (9.0072e+15) in order to factor correctly.
 ## @seealso{gcd, lcm, isprime, primes}
 ## @end deftypefn
 
@@ -82,7 +82,7 @@
   q = prod (pf);
   if (q != qorig)
     error ("factor: Q too large to factor");
-  elseif (q > bitmax)
+  elseif (q >= flintmax ())
     warning ("factor: Q too large.  Answer is unreliable");
   endif
 
--- a/scripts/statistics/distributions/unidpdf.m	Tue Sep 08 10:39:50 2015 +0200
+++ b/scripts/statistics/distributions/unidpdf.m	Wed Sep 09 18:43:52 2015 +0200
@@ -24,7 +24,7 @@
 ## the integer values 1--@var{n} with equal probability.
 ##
 ## Warning: The underlying implementation uses the double class and will only
-## be accurate for @var{n} @leq{} @code{bitmax} (@w{@math{2^{53} - 1}} on
+## be accurate for @var{n} < @code{flintmax} (@w{@math{2^{53}}}) on
 ## IEEE 754 compatible systems).
 ## @end deftypefn