#

A Tour of NTL: Programming Interface

In this section, we give a general overview of the NTL's programming interface.

### Basic Ring Classes

The basic ring classes are:

- `ZZ`: big integers
- `ZZ_p`: big integers modulo `p`
- `zz_p`: integers mod "single precision" `p`
- `GF2`: integers mod 2
- `ZZX`: univariate polynomials over `ZZ`
- `ZZ_pX`: univariate polynomials over `ZZ_p`
- `zz_pX`: univariate polynomials over `zz_p`
- `GF2X`: polynomials over GF2
- `ZZ_pE`: ring/field extension over ZZ_p
- `zz_pE`: ring/field extension over zz_p
- `GF2E`: ring/field extension over GF2
- `ZZ_pEX`: univariate polynomials over `ZZ_pE`
- `zz_pEX`: univariate polynomials over `zz_pE`
- `GF2EX`: univariate polynomials over `GF2E`

All these classes all support basic arithmetic operators

       +, -, (unary) -, +=, -=, ++, --,
       *, *=, /, /=, %, %=.

However, the operations

       %, %=

only exist for integer and polynomial classes, and do not exist for classes

      ZZ_p, zz_p, GF2, ZZ_pE, zz_pE, GF2E.

The standard equality operators (`==` and `!=`) are provided for each class. In addition, the class `ZZ` supports the usual inequality operators.

The integer and polynomial classes also support "shift operators" for left and right shifting. For polynomial classes, this means multiplication or division by a power of `X`.

### Floating Point Classes

In addition to the above ring classes, NTL also provides three different floating point classes:

- `xdouble`: "double precision" floating point with extended exponent range (for very large numbers);
- `quad_float`: "quasi" quadruple-precision floating point;
- `RR`: aribitrary precision floating point.

### Vectors and Matrices

There are also vectors and matrices over

       ZZ ZZ_p zz_p GF2 ZZ_pE zz_pE GF2E RR

which support the usual arithmetic operations.

### Functional and Procedural forms

Generally, for any function defined by NTL, there is a functional form, and a procedural form. For example:

       ZZ x, a, n;
       x = InvMod(a, n);  // functional form
       InvMod(x, a, n);   // procedural form

This example illustrates the normal way these two forms differ syntactically. However, there are exceptions. First, if there is a operator that can play the role of the functional form, that is the notation used:

       ZZ x, a, b;
       x = a + b;    // functional form
       add(x, a, b); // procedural form

Second, if the functional form's name would be ambiguous, the return type is simply appended to its name:

       ZZ_p x;
       x = random_ZZ_p();  // functional form
       random(x);          // procedural form

Third, there are a number of conversion functions (see below), whose name in procedural form is `conv`, but whose name in functioanl form is `to_T`, where `T` is the return type:

       ZZ x;
       double a;

       x = to_ZZ(a);  // functional form
       conv(x, a);    // procedural form

The use of the procedural form may be more efficient, since it will generally avoid the creation of a temporary object to store its result. However, it is generally silly to get too worked up about such efficiencies, and the functional form is usually preferable because the resulting code is usually easier to understand.

The above rules converning procedural and functional forms apply to essentially all of the arithmetic classes supported by NTL, with the exception of `xdouble` and `quad_float`. These two classes only support the functional/operator notation for arithmetic operations (but do support both forms for conversion).

### Conversions and Promotions

NTL does not provide automatic conversions from, say, `int` to `ZZ`. Most `C++` experts consider such automatic conversions bad form in library design, and I would agree with them. Some earlier versions of NTL had automatic conversions, but they caused too much trouble, so I took them out. Indeed, combining function overloading and automatic conversions is generally considered by programming language experts to be a bad idea (but that did not stop the designers of `C++` from doing it). It makes it very difficult to figure out which function ought to be called. `C++` has an incredibly complex set of rules for doing this; moreover, these rules have been changing over time, and no two compilers seem to implement exactly the same set of rules. And if a compiler has a hard time doing this, imagine what it is like for a programmer. In fact, the rules have become so complicated, that the latest edition of Stroustrup's `C++` book does not even explain them, although earlier verisons did. Possible explanations: (a) Stroustrup thinks his readers are too stupid to understand the rules, or (b) Stroustrup does not understand the rules, or (c) the rules are so complicated that Stroustrup finds it embarassing to talk about them.

Now it should be more clear why I didn't just implement, say, the `int` to `ZZ` conversion function as a `ZZ` constructor taking an argument of type `int`, instead of calling it `to_ZZ`. This would have introduced an automatic conversion, which I wanted to avoid for the reasons explained above. "OK. But why not make the constructor `explict`?" you ask. The main reason is that this is a fairly recently introduced language feature that is not universally available. And even if it were, what about, say, the `ZZ` to `int` conversion routine? How would you name that? The strategy I chose is simple, consistent, and portable.

As mentioned above, there are numerous explicit conversion routines, which come in both functional and procedural forms. A complete list of these can be found in conversions.txt. This is the only place these are documented; they do not appear in the ".txt" files.

Even though there are no automatic conversions, users of NTL can still have most of their benefits, while avoiding their pitfalls. This is because all of the basic arithmetic operations (in both their functional and procedural forms), comparison operators, and assignment are overloaded to get the effect of automatic "promotions". For example:

       ZZ x, a;

       x = a + 1;
       if (x < 0)
          mul(x, 2, a);
       else
          x = -1;

These promotions are documented in the ".txt" files, usually using a kind of "short hand" notation. For example:

    ZZ operator+(const ZZ& a, const ZZ& b);

    // PROMOTIONS: operator + promotes long to ZZ on (a, b).

This means that in addition to the declared function, there are two other functions that are logically equivalent to the following:

    ZZ operator+(long a, const ZZ& b) { return to_ZZ(a) + b; }
    ZZ operator+(const ZZ& a, long b) { return a + to_ZZ(b); }

Note that this is not how NTL actually implements these functions. It is in generally more efficient to write

       x = y + 2;

than it is to write

       x = y + to_ZZ(2);

The former notation avoids the creation and destruction of a temporary `ZZ` object to hold the value 2.

Also, don't have any inhibitions about writing tests like

       if (x == 0) ...

and assignments like

       x = 1;

These are all optimized, and do not execute significaltly slower than the "lower level" (and much less natural)

       if (IsZero(x)) ...

and

       set(x);

Some types have even more promotions. For example, the type `ZZ_pX` has promotions from `long` and `ZZ_p`. Thus, the `add` function for `ZZ_pX` takes the following argument types:

       (ZZ_pX, ZZ_pX), (ZZ_pX, ZZ_p), (ZZ_pX, long), (ZZ_p, ZZ_pX), (long, ZZ_pX)

Each of these functions effectively converts the argument to be promoted to a `ZZ_pX`.

Note that when promoting a pair of arguments, at least one of the arguments must be of the target type.

I have tried to be very consistent with these promotions so that one usually won't need to hunt through the documentation. For a given type, there is a natural, fixed set of types that promote to it. Here is the complete list:

       destination: source

       xdouble:     double
       quad_float:  double
       RR:          double
       ZZ:          long
       ZZ_p:        long
       ZZ_pX:       long, ZZ_p
       zz_p:        long
       ZZ_pX:       long, zz_p
       ZZX:         long, ZZ
       GF2:         long
       GF2X:        long, GF2
       GF2E:        long, GF2
       GF2EX:       long, GF2, GF2E
       ZZ_pE:       long, ZZ_p
       ZZ_pEX:      long, ZZ_p, ZZ_pE
       zz_pE:       long, zz_p
       zz_pEX:      long, zz_p, zz_pE

All the promotions are documented, but here are a few general rules describing the available promotions:

- Promotions apply uniformly to both procedural and functional forms, as well as to the corresponding assignment operator forms. E.g.,

         x = x + 2;
         add(x, x, 2);
         x += 2;

- The addition, subtraction, multiplication, equality and comparison routines always promote both arguments. E.g.,

         x = 2 + y;
         add(x, 2, y);
         if (3 > x || y == 5) ...

- The assignment operator always promotes the right-hand side. E.g.,

         x = 2;

- For non-integer, non-polynomial types, the division routine promotes both arguments. E.g.,

         RR x, y, z;
            ...
         x = 1.0/y;
         z = y/2.0;

  For integer or polynomial types, the division routine promotes the denominator only. E.g.,

         ZZ x, y;
            ...
         y = x/2;

- Matrix by scalar and vector by scalar multiplication promote the scalar. E.g.,

         vec_ZZ v, w;
            ...
         v = w*2;
         v = 2*w;
         v *= 2;

- The monomial constructors for polynomials and the corresponding `SetCoeff` routines promote the coefficient argument. E.g.,

         ZZX f;
         f = ZZX(3, 5);  // f == 5*X^3
         SetCoeff(f, 0, 2);  // f == 5*x^3 + 2;

- In module `ZZ`, the modular arithmetic routines, as well as the bit-wise and, or, and xor routines promote their arguments. There are also several other routines in module `ZZ` that have both `ZZ` and `long` versions, e.g., `NumBits`, `bit`, `weight`. Check the documentation in `ZZ.txt` for complete details.

### Some Conversion and Promotion Technicalities

Usually, conversions and promotions are semantically equivalent. There are three exceptions, however.

One exception is conversion of floating point `double` to `ZZ`. The safest way to do this is to apply an explicit conversion operator, and not to rely on promotions. For example, consider

       ZZ a; double x;

       a = a + x;

This is equivialent to

       a = a + long(x);

One could also use an explicit conversion function:

       a = a + to_ZZ(x);

The second version guarantees that there is no loss of precision, and also guarantees that the floor of `x` is computed. With the first version, one may lose precision when `x` is converted to a `long`, and also the direction of truncation for negative numbers is implementation dependent (usually truncating towards zero, instead of computing the floor).

The second exception is conversion of `unsigned int` or `unsigned long` to `ZZ`. Again, the safest way to do this is with an explicit conversion operator. As above, if one relies on promotions, the unsigned integer will be first converted to a signed `long`, which is most likely not what was intended.

The third exception can occur on 64-bit machines when converting a signed or unsigned `long` to one of NTL's extended precision floating-point types (`RR` or `quad_float`). These types only provide promotions from `double`, and converting a `long` to a `double` on a 64-bit machine can lead to a loss of precision. Again, if one uses the appropriate NTL conversion routine, no loss of precision will occur.

Another pitfall too avoid is initialzing `ZZ`s with integer constants that are too big. Consider the following:

       ZZ x;
       x = 1234567890123456789012;

This integer constant is too big, and this overflow condition may or may not cause your compiler to give you a warning or an error. The easiest way to introduce such large constants into your program is as follows:

       ZZ x;
       x = to_ZZ("1234567890123456789012");

Conversion functions are provided for converting `C` character strings to the types `ZZ`, `RR`, `quad_float`, and `xdouble`.

One should also be careful when converting to `RR`. All of these conversions round to the current working precision, which is usually, but not always what one wants.

### Aliasing

An important feature of NTL is that aliasing of input and output parameters is always allowed. For example, if you write `mul(x, a, b)`, then `a` or `b` may alias (have the same address as) `x` (or any object that `x` contains, e.g., scalar/vector or scalar/polynomial multiplication).

### Constructors, Destructors, and Memory Management

NTL generally takes care of managing the space occupied by large, dynamically sized objects, like objects of class `ZZ` or any of NTL's dynamic vectors. However, it is helpful to understand a little of what is happening behind the scenes.

Most classes are implemented as a pointer, and the default constructor just sets this pointer to 0. Space is allocated for the object as needed, and when the object's destructor is called, the space is freed. Exceptions to this are the "modular" classes `ZZ_p`, `ZZ_pE`, `zz_pE`, and `GF2E`. Since, for a given modulus, the sizes of these objects are fixed, the default constructor allocates the appropriate amount of space.

Copies are "deep" rather than "shallow". This means the data itself is copied, and not just a pointer to the data. If the destination object does not have enough space to hold the source data, then the space held by the destination object is "grown". This is done using the `C` routine `realloc()`. Note, however, that if the source object is smaller than the destination object, the space held by the destination object is retained. This strategy usually yields reasonable behaviour; however, one can take explicit control of the situation if necessary, since almost all NTL classes have a method `kill()` which frees all space held by the object, and sets its state to the default initial state (a value 0 or a zero-length vector).

The only exception to the above are the special classes `ZZ_pBak`, `ZZ_pContext`, and the analogous classes for `zz_p`, `ZZ_pE`, `zz_pE`, and `GF2E`. These objects are implemented as referenced-counted pointers, and copies are "shallow".

While we are discussing initialization, there is one technical point worth mentioning. It is safe to declare global objects of any NTL type (except modular types), as long as one uses only the default constructor. For example, the global declarations

       ZZ global_integer;
       vec_ZZ_p global_vector;

should always work, since their initialization only involves setting a pointer to 0. However, one should avoid initializing global objects with non-default constructors, and should avoid doing anything that would lead to non-trivial computations with NTL objects prior to the beginning of the execution of routine `main()`. The reasons for this are quite esoteric and can only be appreciated by a true `C++` afficianado. Actually, most such initializations and computations probably will work, but it is somewhat platform dependant.

Normal people usually do none of these things, so all of this should not matter too much. There is, however, one possible exception to this. A programmer might want to have a global constant initialized like this:

       const quad_float Pi = to_quad_float("3.1415926535897932384626433832795029");

While this probably will work fine on most platforms, it may not be an entirely portable construction, since it will involve a non-trivial computation before execution of `main()` begins. A more portable strategy is to define a function returning a read-only reference:

       const quad_float& Pi()
       {
          static quad_float pi =
             to_quad_float("3.1415926535897932384626433832795029");
          return pi;
       }

and then call the function `Pi()` to get a read-only reference to this constant value:

       area = Pi()*r*r;

The initialization will then take place the first time `Pi()` is called, which is presumably after `main()` starts, and so everything should work fine. This is a very simple and general strategy that most `C++` experts recommend using whenever the initialization of a non-global object requires non-trivial computation.