tcl::tommath

[add information about this math package, added to the core in tcl 8.5 ]

The generic/tclTomMathInterface.c file contains the comment

TclTommath_Init

Initializes the TclTomMath 'package', which exists as a placeholder so that the package data can be used to hold a stub table pointer.

This seems to mean that this "package" is being declared simply so that the package data structures can be (mis?)used as a place to store this pointer. The tcl::tommath version number is always the same as the Tcl version number.

AMG: Are there any extensions that use the tommath bignum library [L1 ] portion of Tcl? I wrote one at work, but in order to make it compile, I had to create an empty file called tommath_class.h and put it somewhere in the "-I" header include path. This is because tclTomMath.h contains the line #include <tommath_class.h>, but it doesn't seem to actually use anything that may be defined in tommath_class.h. See 1941434 for more information.

Once I got that out of the way, I found that tommath wasn't all that hard to use. I couldn't find any documentation, so I just read the source, which was easy to understand. Here's code to convert between a Tcl_WideUInt and an mp_int:

mp_int wideuint_to_bignum(Tcl_WideUInt uwide)
{
    mp_int bignum = {0, 0, MP_ZPOS, NULL};
    if (mp_init_size(&bignum, (CHAR_BIT * sizeof(Tcl_WideUInt)
                              + DIGIT_BIT - 1) / DIGIT_BIT) == MP_OKAY) {
        for (; uwide != 0; ++bignum.used) {
            bignum.dp[bignum.used] = (mp_digit)(uwide & MP_MASK);
            uwide >>= MP_DIGIT_BIT;
        }
    }

    /* The caller is responsible for freeing the allocated digits of the bignum
     * by using mp_clear().  Tcl does this when the bignum is placed inside a
     * Tcl_Obj.  bignum_to_wideuint() likewise internally frees the digits. */
    return bignum;
}

Tcl_WideUInt bignum_to_wideuint(mp_int bignum)
{
    Tcl_WideUInt uwide = 0;
    int i;
    for (i = 0; i < bignum.used; ++i) {
        uwide = (uwide << MP_DIGIT_BIT) | bignum.dp[i];
    }
    mp_clear(&bignum);
    return uwide;
}

These functions are adapted from the tommath sources. I used them with Tcl_TakeBignumFromObj() and Tcl_NewBignumObj() [L2 ] to put unsigned wide integers in Tcl_Objs.

Lars H: Re documentation, there is a 1.1MB PDF file in CVS: tcl/libtommath/tommath.pdf.