A Tour of NTL: Traditional and ISO Modes

As of version 4.1, NTL can be compiled and used in one of two modes: Traditional or ISO. If you set the flag NTL_STD_CXX in the config.h file, you get ISO, and otherwise you get Traditional.

Traditional mode provides the same interface as that provided in versions 4.0 and earlier. Traditional mode is also the default, so old programs that used NTL should continue to work without any changes. So if you wish, you can completely ignore the new ISO mode, and ignore the rest of this page. However, if you want to fully exploit some important, new features of C++, in particular namespaces, read on. Also, it is likely that in future distributions of NTL, ISO mode will become the default mode, although Traditional mode will continue to be supported indefinitely.

In Traditional mode, the NTL header files include the traditional C++ header files <stdlib.h>, <math.h>, and <iostream.h>. These files declare a number of names (functions, types, etc.) in the global namespace. Additionally, the NTL header files declare a number of names, also in the global namespace.

In ISO mode, the NTL header files include the new C++ header files <cstdlib>, <cmath>, and <iostream>. These new header files are essentially the same as the traditional ones, except that all the the names are declared in a namespace called std. Additionally, the NTL header files declare a number of names, but these are all declared within a namespace called NTL.

ISO mode uses C++ features that are new to the new ISO C++ standard. I know of no compiler that truly implements all of the standard, but some come pretty close. If your complier is too old, you will not be able to use NTL in ISO mode; otherwise, you are free to use either ISO or Traditional mode, but I would recommend ISO mode for code that you expect to be around for a long time. In particular, if you want to develop and distribute a library that builds on top of NTL, it would be preferable to make it compatible with NTL in ISO mode, and even better, to make it compatible with either mode.

The upshot is, NTL will remain usable in Traditional indefinitely, assuming compilers maintain reasonable backward compatibilty with pre-standard C++ conventions for header files; however, if you want to program for the future, it is recommended to use ISO mode.

A crash course on namespaces

As already mentioned, the main difference between Traditional and ISO mode is that in ISO mode, all names are wrapped in namespaces. Namespaces are a feature that was introduced in the new C++ standard. One can declare names (functions, types, etc.) inside a namespace. By default, such names are not visible outside the namespace without explicit qualification.

The main advantage of namespaces is that it solves the namespace pollution problem: if two libraries define the same name in two inconsistent ways, it is very difficult, if not impossible, to combine these two libraries in the same program.

The traditional way of avoiding such problems in languages like C is for a library designer to attach a prefix specific to that library to all names. This works, but makes for ugly code. The function overloading mechanism in C++ eases the problem a bit, but is still not a complete solution.

The new namespace feature in C++ provides a reasonably complete and elegant solution to the namespace pollution problem. It is one of the nicest and most important recent additions to the C++ language.

Here is a simple example to illustrate namespaces.


namespace N {
   void f(int);
   void g(int);
   int x;
}

int x;

void h()
{
   x = 1;    // the global x
   N::x = 0; // the x in namespace N
   N::f(0);  // the f in namespace N
   g(1);     // error -- g is not visible here
}

All of this explicit qualification business can be a bit tedious. The easiest way to avoid this tedium is to use what is called a using directive, which effectively makes all names declared within a namespace visible in the global scope. Here is a variation on the previous example, with a using directive.


namespace N {
   void f(int);
   void g(int);
   int x;
}

int x;

using namespace N;

void h()
{
   x = 1;    // error -- ambiguous: the global x or the x in namespace N?
   ::x = 1;  // the global x
   N::x = 0; // the x in namespace N
   N::f(0);  // the f in namespace N
   f(0);     // OK -- N::f(int) is visible here
   g(1);     // OK -- N::g(int) is visible here
}

Here is another example.


namespace N1 {
   int x;
   void f(int);
   void g(int);
}

namespace N2 {
   int x;
   int y;
   void f(double);
   void g(int);
}

using namespace N1;
using namespace N2;

void h()
{
   x = 1;     // error -- ambiguous: N1::x or N2::x?
   N1::x = 1; // OK
   N2::x = 1; // OK
   y = 1;     // OK  -- this is N2::y
   g(0);      // error -- ambiguous: N1::g(int) or N2::g(int)?
   f(0);      // OK -- N1::f(int), because it is the "best" match 
   f(0.0);    // OK  -- N2::f(double), because it is the "best" match
}

This example illustrates the interaction between using declarations and function overloading resolution. If several overloaded versions of a function are visible, it is not necessarily ambiguous: the usual overload resolution procedure is applied, and if there is a unique "best" match, then there is no ambiguity.

The examples presented here do not illustrate all of the features and nuances of namespaces. For this, you are referred to a C++ book.

Namespaces and NTL

In ISO mode, the standard library is "wrapped" in namespace std, and NTL is "wrapped" in namespace NTL. Thus, the header file <NTL/ZZ.h> in ISO mode looks something like this:


namespace NTL {

   // ...

   class ZZ { /* ... */ };

   // ...

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

   std::istream& operator>>(std::istream& s, ZZ& x);
   std::ostream& operator<<(std::ostream& s, const ZZ& a);

   // ...

  
}

Therefore, one must explicitly qualify all names, or use appropriate using directives. Here is how one could write the first example of the tour in ISO mode.


#include <NTL/ZZ.h>

int main()
{
   NTL::ZZ a, b, c; 

   std::cin >> a; 
   std::cin >> b; 
   c = (a+1)*(b+1);
   std::cout << c << "\n";
}

Notice how everything is explicitly qualified. Actually, the input/output operators << and >>, and the arithmetic operators + and * are not explicitly qualified, but rather, the compiler finds them through a gimmick called Koenig Lookup, which will look for functions (and operators) declared in namespace NTL, because the type of the argument (ZZ) is a class declared in that namespace.

Even with Koenig Lookup, explicit qualification can be a bit tedious. Here is the same example, this time with using directives.


#include <NTL/ZZ.h>

using namespace NTL;
using namespace std;

int main()
{
   ZZ a, b, c; 

   cin >> a; 
   cin >> b; 
   c = (a+1)*(b+1);
   cout << c << "\n";
}

To write NTL client code that will compile smoothly in either Traditional or ISO mode, one simply does the following:


#include <NTL/ZZ.h>

#ifdef NTL_STD_CXX
using namespace NTL;
using namespace std;
#endif

int main()
{
   ZZ a, b, c; 

   cin >> a; 
   cin >> b; 
   c = (a+1)*(b+1);
   cout << c << "\n";
}

Typically, when writing a program that uses NTL, you can simply insert the "ifdef" as above, and forget about all this namespace nonsense. However, if you are combining libraries, you may have to disambiguate things from time to time.

The Standard C++ library is huge. If you just use <iostream>, you should not have any ambiguous names. However, there are some potential ambiguities in other library components. One that I know of is the template class negate defined in <functional>, which conflicts with the NTL function negate. With namespaces, there should be no problem, unless the client code explicitly uses negate, in which case you will have to explicitly qualify negate to tell the compiler which negate you mean, either std::negate or NTL::negate.

NTL also explicitly defines various versions of min and max functions. Template versions of these functions are also defined in the standard library component <algorithm>. Because of the way the function overload resolution mechanism works, the "right" version of min or max should always be chosen, without any need for explicit qualification.

There may be other possible ambiguities between the standard library and NTL, but if they arise, they are easily fixed through explicit qualification.

Some global names

It is not quite true that all names declared in NTL header files are wrapped in namespace NTL. There are two classes of exceptions:

All names that start with the prefix "NTL_" are in fact macros. There are a number of documented and undocumented such macros. Note that any name with this prefix is a macro and all macros start with this prefix.
There are also a number of undocumented names that start with the prefix "_ntl_". These are not macros, but rather are names of functions, types, etc., that are declared in the global namespace. Any name with this prefix is in the global namespace, and all names in the global namespace start with this prefix. All functions with "C" linkage have this prefix.

Thus, NTL "owns" all names starting with "NTL_" or "_ntl_"; users of NTL should avoid names with these prefixes.

Further technicalities

Another thing to be aware of is that there are some small, annoying differences between the old standard C include files <stdlib.h> and <math.h>, and the new C++ include files <cstdlib> and <cmath>, above and beyond the namespace wrapping. Specifically, the new header files declare several overloaded versions of some functions. For example, in the old header files, there was one function

   int abs(int);

Now there are several, including:

   int abs(int);
   long abs(long);
   float abs(float);
   double abs(double);
   long double abs(long double);

Also, functions like log and sqrt are also overloaded. So instead of just

   double log(double);

there are

   float log(float);
   double log(double);
   long double log(long double);

This can lead to compile-time errors in some old codes, such as:

   double log_2 = log(2);

With the old header files, the int value 2 would have been converted to a double, and the function

   double log(double);

would have been called.

With the new header files, the compiler would raise an error, because the function call is now ambiguous.

Of course, the fix is trivial:

   double log_2 = log(2.0);

This will compile correctly with either old or new header files.

Don't you just love the ISO?

A note on documentation

The ".txt" files documenting NTL's modules still reflect NTL's Traditional mode. There should be no confusion in interpretting the meaning in ISO mode. Just remember: all of NTL is wrapped in namespace NTL, and the standard library is wrapped in namespace std.

Further changes in NTL version 4.1

The ISO Standard for C++ is not compatible with the language defined in the second edition of Stroustrup's C++ book. This is in fact quite annoying. Besides introducing namespaces, several modifications were made in version 4.1 that will allow NTL to be compiled smoothly under either the old or the new definition of the language (or any reasonable approximation thereof). These changes do not affect the (documented) NTL interface, and so version 4.1 should be backward compatible.

Here is a summary of the other changes:

Got rid of all friend functions. It turns out that new C++ and old C++ disagree quite strongly about the semantics of a friend function declaration. In getting rid of these, I also made a number of fields public which used to be private, but to prevent accidental misuse, I gave them strange names (e.g., the previously private member rep in class ZZ_p is now the public member _ZZ_p__rep).
This change is effective in both Traditional and ISO modes.
In my view, the ISO committee really committed an act of sabotage here. Now the friend mechanism is much more awkward than before, which makes the use of private members more awkward, which simply encourages programmers (like me) to avoid them altogether.
When compiling in ISO mode, all calls to new have been replaced by new(std::nothrow).
The ISO committee also committed an act of sabotage when they changed the semantics of the memory allocation operator new. In old C++, a memory allocation error simply returned a null pointer; in new C++ an exception is thrown. The old semantics are available via new(std::nothrow).
You may of course use NTL in Traditional mode with a compiler that implements the new semantics for new. In this case, if the memory allocation fails, an exception will be thrown, and assuming you don't catch it, you will simply get an error message that is less informative than the one NTL would have printed. Also, your compiler may have a backward compatatibilty flag to use the old new semantics.
Various and sundry other small changes, such as fixing occurrences of the the "log(2)" problem mentioned above.

Standard C++ and the Real World

At the time of this writing, I know of no compiler that actually implements the new C++ standard. Some come closer than others.

One compiler that comes fairly close is one available (for a price) from www.kai.com. One of the things it does not do correctly is that the global namespace is partially polluted with some function names from the standard C library, even if you use header files that are supposed to wrap them in namespace std (these names are also in namespace std). Besides this problem, and the fact there are a couple of very esoteric language features not yet implemented, the KAI compiler does a reasonable job.

I used this compiler (version 3.4g, with the "--strict" flag) to make sure NTL worked correctly under the new standard (which was not entirely trivial), in either Traditional or ISO mode.

NTL should also compiles correctly in in either Traditional or ISO mode using recent versions of the GNU compiler (which is free); I checked it with egcs-2.91.66. This version of the compiler is still some distance from implementing standard C++, but is getting closer. There are several language features that are not yet implemented correctly, and also the entire contents of the standard C++ library are visible in the global namespace (as well as namespace std). Nevertheless, NTL can still be used in ISO mode with the GNU compiler, as long as one is aware of the limitations of this compiler.

I do not yet know how NTL in ISO mode works on other compilers. Feedback is always welcome.

As usual, NTL should continue to work in Traditional mode on just about any available C++ compiler.