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)