octave_packages/m/general/randi.m

   1 ## Copyright (C) 2010-2012 Rik Wehbring
   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} {} randi (@var{imax})
  21 ## @deftypefnx {Function File} {} randi (@var{imax}, @var{n})
  22 ## @deftypefnx {Function File} {} randi (@var{imax}, @var{m}, @var{n}, @dots{})
  23 ## @deftypefnx {Function File} {} randi ([@var{imin} @var{imax}], @dots{})
  24 ## @deftypefnx {Function File} {} randi (@dots{}, "@var{class}")
  25 ## Return random integers in the range 1:@var{imax}.
  26 ##
  27 ## Additional arguments determine the shape of the return matrix.  When no
  28 ## arguments are specified a single random integer is returned.  If one
  29 ## argument @var{n} is specified then a square matrix @w{(@var{n} x @var{n})} is
  30 ## returned.  Two or more arguments will return a multi-dimensional
  31 ## matrix @w{(@var{m} x @var{n} x @dots{})}.
  32 ##
  33 ## The integer range may optionally be described by a two element matrix
  34 ## with a lower and upper bound in which case the returned integers will be
  35 ## on the interval @w{[@var{imin}, @var{imax}]}.
  36 ##
  37 ## The optional argument "@var{class}" will return a matrix of the requested
  38 ## type.  The default is "double".
  39 ##
  40 ## The following example returns 150 integers in the range 1-10.
  41 ##
  42 ## @example
  43 ## ri = randi (10, 150, 1)
  44 ## @end example
  45 ##
  46 ## Implementation Note: @code{randi} relies internally on @code{rand} which
  47 ## uses class "double" to represent numbers.  This limits the maximum
  48 ## integer (@var{imax}) and range (@var{imax} - @var{imin}) to the value
  49 ## returned by the @code{bitmax} function.  For IEEE floating point numbers
  50 ## this value is @w{@math{2^{53} - 1}}.
  51 ##
  52 ## @seealso{rand}
  53 ## @end deftypefn
  54
  55 ## Author: Rik Wehbring
  56
  57 function ri = randi (bounds, varargin)
  58
  59   if (nargin < 1)
  60     print_usage();
  61   endif
  62
  63   if (! (isnumeric (bounds) && isreal (bounds)))
  64     error ("randi: IMIN and IMAX must be real numeric bounds");
  65   endif
  66
  67   if (isscalar (bounds))
  68     imin = 1;
  69     imax = fix (bounds);
  70     if (imax < 1)
  71       error ("randi: require IMAX >= 1");
  72     endif
  73   else
  74     imin = fix (bounds(1));
  75     imax = fix (bounds(2));
  76     if (imax < imin)
  77       error ("randi: require IMIN <= IMAX");
  78     endif
  79   endif
  80
  81   if (nargin > 1 && ischar (varargin{end}))
  82     rclass = varargin{end};
  83     varargin(end) = [];
  84   else
  85     rclass = "double";
  86   endif
  87
  88   if (strfind (rclass, "int"))
  89     if (imax > intmax (rclass))
  90       error ("randi: require IMAX < intmax (CLASS)");
  91     endif
  92   elseif (strcmp (rclass, "single"))
  93     if (imax > bitmax (rclass))
  94       error ("randi: require IMAX < bitmax (CLASS)");
  95     endif
  96   endif
  97   ## Limit set by use of class double in rand()
  98   if (imax > bitmax)
  99     error ("randi: maximum integer IMAX must be smaller than bitmax ()");
 100   endif
 101   if ((imax - imin) > bitmax)
 102     error ("randi: maximum integer range must be smaller than bitmax ()");
 103   endif
 104
 105
 106   ri = imin + floor ( (imax-imin+1)*rand (varargin{:}) );
 107
 108   if (! strcmp (rclass, "double"))
 109     ri = cast (ri, rclass);
 110   endif
 111
 112 endfunction
 113
 114 %!test
 115 %! ri = randi (10, 1000, 1);
 116 %! assert(isequal(ri, fix (ri)));
 117 %! assert(min(ri) == 1);
 118 %! assert(max(ri) == 10);
 119 %! assert(rows(ri) == 1000);
 120 %! assert(columns(ri) == 1);
 121 %! assert(strcmp (class (ri), "double"));
 122 %!test
 123 %! ri = randi ([-5, 10], 1000, 1, "int8");
 124 %! assert(isequal(ri, fix (ri)));
 125 %! assert(min(ri) == -5);
 126 %! assert(max(ri) == 10);
 127 %! assert(strcmp (class (ri), "int8"));
 128 %!
 129 %!assert(size (randi(10, 3,1,2)) == [3, 1, 2])
 130
 131 %% Test input validation
 132 %!error(randi())
 133 %!error(randi("test"))
 134 %!error(randi(10+2i))
 135 %!error(randi(0))
 136 %!error(randi([10, 1]))
 137 %!error(randi(256, "uint8"))
 138 %!error(randi(2^25, "single"))
 139 %!error(randi(bitmax() + 1))
 140 %!error(randi([-1, bitmax()]))
 141