Merge pull request #1922 from bettio/bigint-clarifications

Add clarifications to bigint code

Make existing code more understandable

These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).

SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later

Author: bettio

doc/src/programmers-guide.md

@@ -740,7 +740,7 @@ The following Erlang type specification enumerates this type:
 Erlang/OTP uses the Christian epoch to count time units from year 0 in the Gregorian calendar.  The, for example, the value 0 in Gregorian seconds represents the date Jan 1, year 0, and midnight (UTC), or in Erlang terms, `{{0, 1, 1}, {0, 0, 0}}`.
 
 ```{attention}
-AtomVM is currently limited to representing integers in at most 64 bits, with one bit representing the sign bit.
+AtomVM is currently limited to representing time in at most 64 bits, with one bit representing the sign bit.
 However, even with this limitation, AtomVM is able to resolve microsecond values in the Gregorian calendar for over
 292,000 years, likely well past the likely lifetime of an AtomVM application (unless perhaps launched on a deep
 space probe).

src/libAtomVM/bif.c

@@ -1026,6 +1026,7 @@ term bif_erlang_fdiv_2(Context *ctx, uint32_t fail_label, int live, term arg1, t
 
 static term div_maybe_bigint(Context *ctx, uint32_t fail_label, uint32_t live, term arg1, term arg2)
 {
+    // 0 is always normalized to `term_from_int(0)`, so we can do this
     if (UNLIKELY(arg2 == term_from_int(0))) {
         RAISE_ERROR_BIF(fail_label, BADARITH_ATOM);
     }
@@ -1346,6 +1347,7 @@ term bif_erlang_abs_1(Context *ctx, uint32_t fail_label, int live, term arg1)
 
 static term rem_maybe_bigint(Context *ctx, uint32_t fail_label, uint32_t live, term arg1, term arg2)
 {
+    // 0 is always normalized to `term_from_int(0)`, so we can do this
     if (UNLIKELY(arg2 == term_from_int(0))) {
         RAISE_ERROR_BIF(fail_label, BADARITH_ATOM);
     }

src/libAtomVM/nifs.c

@@ -2051,6 +2051,8 @@ static term nif_erlang_binary_to_atom_1(Context *ctx, int argc, term argv[])
     return result;
 }
 
+// This make_bigint version doesn't do any overflow check and it doesn't normalize integers
+// These contraints are ok for parse_integer, since it checks this before calling make_bigint
 static term make_bigint(Context *ctx, const intn_digit_t bigres[], size_t bigres_len, intn_integer_sign_t sign)
 {
     size_t intn_data_size;

src/libAtomVM/opcodesswitch.h

@@ -1557,6 +1557,8 @@ static size_t decode_nbits_integer(Context *ctx, const uint8_t *encoded, term *o
 static term large_integer_to_term(Context *ctx, int num_bytes, const uint8_t **encoded)
 {
     const uint8_t *compact_term = *encoded;
+    // num_bytes is decoded from a 3 bits value and incremented by 2,
+    // meaning that minimum value is 0 and maximum value is 7
     switch (num_bytes) {
         case 0:
         case 1:
@@ -1815,8 +1817,11 @@ static bool maybe_call_native(Context *ctx, atom_index_t module_name, atom_index
     static size_t decode_nbits_integer(Context *ctx, const uint8_t *encoded, term *out_term)
     {
         const uint8_t *new_encoded = encoded;
-        unsigned int len;
+        uint32_t len;
         DECODE_LITERAL(len, new_encoded);
+        // TODO: check this: actually should be enough: len = *(new_encoded)++ >> 4;
+        // it seems that likely range is something like from 9 (9 + 0) to 24 (9 + 15)
+        // that is 192 bits integer
 
         len += 9;