Support integer truncate division and modulo operations

Author: edubart

bint.lua

@@ -163,6 +163,7 @@ local BINT_SIZE = BINT_BITS // BINT_WORDBITS
 local BINT_WORDMAX = (1 << BINT_WORDBITS) - 1
 local BINT_WORDMSB = (1 << (BINT_WORDBITS - 1))
 local BINT_MATHMININTEGER, BINT_MATHMAXINTEGER
+local BINT_MININTEGER
 
 -- Create a new bint without initializing.
 local function bint_newempty()
@@ -1191,6 +1192,56 @@ function bint.umod(x, y)
  return rema
 end
 
+--- Perform integer truncate division and modulo operation between two numbers considering bints.
+-- This is effectively the same of @{bint.__tdiv} and @{bint.__tmod}.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient following the remainder, both bint or lua number.
+-- @raise Asserts on attempt to divide by zero or on division overflow.
+-- @see bint.__tdiv
+-- @see bint.__tmod
+function bint.tdivmod(x, y)
+ local ax, ay = bint.abs(x), bint.abs(y)
+ local ix, iy = bint.tobint(ax), bint.tobint(ay)
+ local quot, rema
+ if ix and iy then
+ assert(not (bint.eq(x, BINT_MININTEGER) and bint.isminusone(y)), 'division overflow')
+ quot, rema = bint.udivmod(ix, iy)
+ else
+ quot, rema = ax // ay, ax % ay
+ end
+ local isxneg, isyneg = bint.isneg(x), bint.isneg(y)
+ if isxneg ~= isyneg then
+ quot = -quot
+ end
+ if isxneg then
+ rema = -rema
+ end
+ return quot, rema
+end
+
+--- Perform truncate division between two numbers considering bints.
+-- Truncate division is a division that rounds the quotient towards zero.
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The quotient, a bint or lua number.
+-- @raise Asserts on attempt to divide by zero or on division overflow.
+function bint.tdiv(x, y)
+ return (bint.tdivmod(x, y))
+end
+
+--- Perform integer truncate modulo operation between two numbers considering bints.
+-- The operation is defined as the remainder of the truncate division
+-- (division that rounds the quotient towards zero).
+-- @param x The numerator, a bint or lua number.
+-- @param y The denominator, a bint or lua number.
+-- @return The remainder, a bint or lua number.
+-- @raise Asserts on attempt to divide by zero or on division overflow.
+function bint.tmod(x, y)
+ local _, rema = bint.tdivmod(x, y)
+ return rema
+end
+
 --- Perform integer floor division and modulo operation between two numbers considering bints.
 -- This is effectively the same of @{bint.__idiv} and @{bint.__mod}.
 -- @param x The numerator, a bint or lua number.
@@ -1612,6 +1663,7 @@ setmetatable(bint, {
 })
 
 BINT_MATHMININTEGER, BINT_MATHMAXINTEGER = bint.new(math.mininteger), bint.new(math.maxinteger)
+BINT_MININTEGER = bint.mininteger()
 memo[memoindex] = bint
 
 return bint

docs/index.html

@@ -121,7 +121,7 @@ <h2>Usage</h2>
 </ul>
 
 <p>To output a very large integer with no loss you probably want to use <a href="index.html#tobase">bint.tobase</a>
-or call <a href="https://www.lua.org/manual/5.3/manual.html#pdf-tostring">tostring</a> to get a string representation.</p>
+or call <a href="https://www.lua.org/manual/5.1/manual.html#pdf-tostring">tostring</a> to get a string representation.</p>
 
 <h2>Precautions</h2>
 
@@ -352,6 +352,18 @@ <h2><a href="#Functions">Functions</a></h2>
 <td class="summary">Perform unsigned integer modulo operation between two integers considering bints.</td>
 </tr>
 <tr>
+<td class="name" nowrap><a href="#tdivmod">tdivmod (x, y)</a></td>
+<td class="summary">Perform integer truncate division and modulo operation between two numbers considering bints.</td>
+</tr>
+<tr>
+<td class="name" nowrap><a href="#tdiv">tdiv (x, y)</a></td>
+<td class="summary">Perform truncate division between two numbers considering bints.</td>
+</tr>
+<tr>
+<td class="name" nowrap><a href="#tmod">tmod (x, y)</a></td>
+<td class="summary">Perform integer truncate modulo operation between two numbers considering bints.</td>
+</tr>
+<tr>
 <td class="name" nowrap><a href="#idivmod">idivmod (x, y)</a></td>
 <td class="summary">Perform integer floor division and modulo operation between two numbers considering bints.</td>
 </tr>
@@ -1661,6 +1673,103 @@ <h3>Raises:</h3>
 
 
 
+</dd>
+ <dt>
+ <a name = "tdivmod"></a>
+ <strong>tdivmod (x, y)</strong>
+ </dt>
+ <dd>
+ Perform integer truncate division and modulo operation between two numbers considering bints.
+ This is effectively the same of ??? and ???.
+
+
+ <h3>Parameters:</h3>
+ <ul>
+ <li><span class="parameter">x</span>
+ The numerator, a bint or lua number.
+ </li>
+ <li><span class="parameter">y</span>
+ The denominator, a bint or lua number.
+ </li>
+ </ul>
+
+ <h3>Returns:</h3>
+ <ol>
+
+ The quotient following the remainder, both bint or lua number.
+ </ol>
+
+ <h3>Raises:</h3>
+ Asserts on attempt to divide by zero or on division overflow.
+
+ <h3>See also:</h3>
+ <ul>
+ </ul>
+
+
+</dd>
+ <dt>
+ <a name = "tdiv"></a>
+ <strong>tdiv (x, y)</strong>
+ </dt>
+ <dd>
+ Perform truncate division between two numbers considering bints.
+ Truncate division is a division that rounds the quotient towards zero.
+
+
+ <h3>Parameters:</h3>
+ <ul>
+ <li><span class="parameter">x</span>
+ The numerator, a bint or lua number.
+ </li>
+ <li><span class="parameter">y</span>
+ The denominator, a bint or lua number.
+ </li>
+ </ul>
+
+ <h3>Returns:</h3>
+ <ol>
+
+ The quotient, a bint or lua number.
+ </ol>
+
+ <h3>Raises:</h3>
+ Asserts on attempt to divide by zero or on division overflow.
+
+
+
+</dd>
+ <dt>
+ <a name = "tmod"></a>
+ <strong>tmod (x, y)</strong>
+ </dt>
+ <dd>
+ Perform integer truncate modulo operation between two numbers considering bints.
+ The operation is defined as the remainder of the truncate division
+ (division that rounds the quotient towards zero).
+
+
+ <h3>Parameters:</h3>
+ <ul>
+ <li><span class="parameter">x</span>
+ The numerator, a bint or lua number.
+ </li>
+ <li><span class="parameter">y</span>
+ The denominator, a bint or lua number.
+ </li>
+ </ul>
+
+ <h3>Returns:</h3>
+ <ol>
+
+ The remainder, a bint or lua number.
+ </ol>
+
+ <h3>Raises:</h3>
+ Asserts on attempt to divide by zero or on division overflow.
+
+
+
 </dd>
  <dt>
  <a name = "idivmod"></a>
@@ -2370,7 +2479,7 @@ <h2 class="section-header "><a name="Fields"></a>Fields</h2>
 </div> <!-- id="main" -->
 <div id="about">
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-07-17 10:18:54 </i>
+<i style="float:right;">Last updated 2020-09-24 08:14:54 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

tests.lua

@@ -10,7 +10,7 @@ local function test(bits, wordbits)
  local bint = require 'bint'(bits, wordbits)
  local luabits = luainteger_bitsize()
 
- local function assert_eq(a , b)
+ local function assert_eq(a, b)
  if a ~= b then --luacov:disable
  local msg = string.format(
  "assertion failed:\n expected '%s' of type '%s',\n but got '%s' of type '%s'",
@@ -19,6 +19,10 @@ local function test(bits, wordbits)
  end --luacov:enable
  end
 
+ local function assert_eqf(a, b)
+ assert(bint.abs(a - b) <= 1e-6, 'assertion failed')
+ end
+
  do --utils
  assert(bint(-2):iszero() == false)
  assert(bint(-1):iszero() == false)
@@ -623,6 +627,31 @@ local function test(bits, wordbits)
  test_ops(0xc19076, 0x31ffd4)
  end
 
+ do --tdivmod
+ assert_eq(bint.tdiv( 7, 3 ):tointeger(), 2)
+ assert_eq(bint.tdiv(-7, 3 ):tointeger(), -2)
+ assert_eq(bint.tdiv( 7, -3 ):tointeger(), -2)
+ assert_eq(bint.tdiv(-7, -3 ):tointeger(), 2)
+ assert_eq(bint.tdiv( 6, 3 ):tointeger(), 2)
+ assert_eq(bint.tdiv(-6, 3 ):tointeger(), -2)
+ assert_eq(bint.tdiv( 6, -3 ):tointeger(), -2)
+ assert_eq(bint.tdiv(-6, -3 ):tointeger(), 2)
+
+ assert_eq(bint.tmod( 7, 3 ):tointeger(), 1)
+ assert_eq(bint.tmod(-7, 3 ):tointeger(), -1)
+ assert_eq(bint.tmod( 7, -3 ):tointeger(), 1)
+ assert_eq(bint.tmod(-7, -3 ):tointeger(), -1)
+ assert_eq(bint.tmod( 6, 3 ):tointeger(), 0)
+ assert_eq(bint.tmod(-6, 3 ):tointeger(), 0)
+ assert_eq(bint.tmod( 6, -3 ):tointeger(), 0)
+ assert_eq(bint.tmod(-6, -3 ):tointeger(), 0)
+
+ assert_eqf(bint.tdiv(7.5, 2.2), 3.0) assert_eqf(bint.tmod(7.5, 2.2), 0.9)
+ assert_eqf(bint.tdiv(-7.5, 2.2), -3.0) assert_eqf(bint.tmod(-7.5, 2.2), -0.9)
+ assert_eqf(bint.tdiv(7.5, -2.2), -3.0) assert_eqf(bint.tmod(7.5, -2.2), 0.9)
+ assert_eqf(bint.tdiv(-7.5, -2.2), 3.0) assert_eqf(bint.tmod(-7.5, -2.2), -0.9)
+ end
+
  do -- upowmod
  assert_eq(bint.upowmod(65, 17, 3233):tointeger(), 2790)
  assert_eq(bint.upowmod(2790, 413, 3233):tointeger(), 65)