I’ve written a few books on using external libraries, which I shamelessly plug later in this post. After confirming that the library is installed (see last week’s post), the next step isn’t to code, but rather to peruse the online documentation, the API or Application Programming Interface.

For the GMP library, which handles painfully large integers, the API or online manual is found here: https://gmplib.org/manual/index

Don’t expect any handholding. Programmers write to other programmers. Often they’re so immersed in the topic they forget about people who are just starting out. That’s okay; it’s the reason you’re reading this blog and not the official GNU manual. But do check out the manual.

The GMP integer values are stored as structures cast as the mpz_t datatype. (I assume the structure’s contents are revealed somewhere on the library’s website, though knowing the details isn’t necessary.) So to use the huge integer values, you must follow certain procedures and use the specific functions available in the GMP library.

Due to its construction, the mpz_t datatype requires three steps to initialize; you cannot use the equal sign operator to assign a value:

1. Declare the mpz_t variable.
2. Initialize the variable.
3. Assign the variable a value.

The declaration is simple:

mpz_t i;

This statement creates an mpz_t variable i. It allocates the structure, but like any variable declared in C, the contents are garbage. A second step is required:

mpz_init(i);

The mpz_init() function initializes variable i, setting its int value to zero. The variable can now be used in the host of mpz and gmp functions.

To assign a value to the mpz_t variable, you use one of an mpz_set function:

mpz_set_ui(i,1000000000);

The mpz_set_ui() function assigns an unsigned integer (ui) value of one billion to mpz_t variable i. The variable can now be used in your code, but only with special functions. For example, the gmp_printf() function, shown in this code:

2022_10_08-Lesson.c

#include <gmp.h>

int main()
{
    mpz_t i;
    mpz_init(i);

    /* i equals one billion */
    mpz_set_ui(i,1000000000);
    gmp_printf("%Zd\n",i);

    return(0);
}

The gmp_printf() function at Line 10 works like the standard printf() function, though it’s capable of outputting mpz_t values. The %Zd placeholder outputs the mpz_t value as a decimal number. Here’s a sample run:

1000000000

Impressive!

But this code is only a start.

As I wrote earlier, various mpz_set functions are available to assign specific values to mpz_t variables. For example, mpz_set_si() to assign a signed int value; mpz_set_d() to assign a double. The full list is available on this page. You can even convert a value from a string.

The library also hosts functions that read standard input for assigning values, such as gmp_scanf(). The manual lists the lot.

In next week’s Lesson, I cover some basic math and mpz_t value manipulation.

Oh! Here are the books I’ve written that cover augmenting your C code by incorporating other libraries: