octave_packages/m/general/idivide.m

   1 ## Copyright (C) 2008-2012 David Bateman
   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} {} idivide (@var{x}, @var{y}, @var{op})
  21 ## Integer division with different rounding rules.
  22 ##
  23 ## The standard behavior of integer division such as @code{@var{a} ./ @var{b}}
  24 ## is to round the result to the nearest integer.  This is not always the
  25 ## desired behavior and @code{idivide} permits integer element-by-element
  26 ## division to be performed with different treatment for the fractional
  27 ## part of the division as determined by the @var{op} flag.  @var{op} is
  28 ## a string with one of the values:
  29 ##
  30 ## @table @asis
  31 ## @item "fix"
  32 ## Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
  33 ## towards zero.
  34 ##
  35 ## @item "round"
  36 ## Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
  37 ## towards the nearest integer.
  38 ##
  39 ## @item "floor"
  40 ## Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
  41 ## towards negative infinity.
  42 ##
  43 ## @item "ceil"
  44 ## Calculate @code{@var{a} ./ @var{b}} with the fractional part rounded
  45 ## towards positive infinity.
  46 ## @end table
  47 ##
  48 ## @noindent
  49 ## If @var{op} is not given it defaults to @code{"fix"}.
  50 ## An example demonstrating these rounding rules is
  51 ##
  52 ## @example
  53 ## @group
  54 ## idivide (int8 ([-3, 3]), int8 (4), "fix")
  55 ##   @result{} int8 ([0, 0])
  56 ## idivide (int8 ([-3, 3]), int8 (4), "round")
  57 ##   @result{} int8 ([-1, 1])
  58 ## idivide (int8 ([-3, 3]), int8 (4), "floor")
  59 ##   @result{} int8 ([-1, 0])
  60 ## idivide (int8 ([-3, 3]), int8 (4), "ceil")
  61 ##   @result{} int8 ([0, 1])
  62 ## @end group
  63 ## @end example
  64 ##
  65 ## @seealso{ldivide, rdivide}
  66 ## @end deftypefn
  67
  68 function z = idivide (x, y, op)
  69   if (nargin < 2 || nargin > 3)
  70     print_usage ();
  71   elseif (nargin == 2)
  72     op = "fix";
  73   else
  74     op = tolower (op);
  75   endif
  76
  77   if (strcmp (op, "round"))
  78     z = x ./ y;
  79   else
  80     if (isfloat (x))
  81       typ = class (y);
  82     elseif (isfloat (y))
  83       typ = class (x);
  84     else
  85       typ = class (x);
  86       if (!strcmp (class (x), class (y)))
  87         error ("idivide: incompatible types");
  88       endif
  89     endif
  90
  91     if (strcmp (op, "fix"))
  92       z = cast (fix (double (x) ./ double (y)), typ);
  93     elseif (strcmp (op, "floor"))
  94       z = cast (floor (double (x) ./ double (y)), typ);
  95     elseif (strcmp (op, "ceil"))
  96       z = cast (ceil (double (x) ./ double (y)), typ);
  97     else
  98       error ("idivide: unrecognized rounding type");
  99     endif
 100   endif
 101 endfunction
 102
 103 %!shared a, af, b, bf
 104 %! a = int8(3);
 105 %! af = 3;
 106 %! b = int8([-4, 4]);
 107 %! bf = [-4, 4];
 108
 109 %!assert (idivide (a, b), int8 ([0, 0]))
 110 %!assert (idivide (a, b, "floor"), int8([-1, 0]))
 111 %!assert (idivide (a, b, "ceil"), int8 ([0, 1]))
 112 %!assert (idivide (a, b, "round"), int8 ([-1, 1]))
 113
 114 %!assert (idivide (af, b), int8 ([0, 0]))
 115 %!assert (idivide (af, b, "floor"), int8([-1, 0]))
 116 %!assert (idivide (af, b, "ceil"), int8 ([0, 1]))
 117 %!assert (idivide (af, b, "round"), int8 ([-1, 1]))
 118
 119 %!assert (idivide (a, bf), int8 ([0, 0]))
 120 %!assert (idivide (a, bf, "floor"), int8([-1, 0]))
 121 %!assert (idivide (a, bf, "ceil"), int8 ([0, 1]))
 122 %!assert (idivide (a, bf, "round"), int8 ([-1, 1]))
 123
 124 %!error (idivide (uint8(1), int8(1)))