{
   ZZ a, b, c; 

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

</pre>

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

<pre>

#include &lt;NTL/ZZ.h&gt;

NTL_CLIENT

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

   cin &gt;&gt; a; 
   cin &gt;&gt; b; 
   c = (a+1)*(b+1);
   cout &lt;&lt; c &lt;&lt; "\n";
}

</pre>

<p>
Here, <tt>NTL_CLIENT</tt> is a macro defined by NTL
that expands into zero, one, or two appropriate <i>using</i> directives,
depending on the settings of <tt>NTL_STD_CXX</tt>,
<tt>NTL_PSTD_NNS</tt>, and <tt>NTL_PSTD_NHF</tt>.
Alternatively, instead of using the <tt>NTL_CLIENT</tt> macro,
you can write:
<p>

<pre>
#if (defined(NTL_PSTD_NNS) || defined(NTL_STD_CXX))
   using namespace NTL;
#endif

#if (defined(NTL_PSTD_NHF) || defined(NTL_STD_CXX))
   using namespace std;
#endif
</pre>

Typically,
when writing a program that uses NTL,
you can
simply insert the <tt>NTL_CLIENT</tt> 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.

<p>

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

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

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

<p>
<h3>
Some global names
</h3>
<p>

It is not quite true that <i>all</i> names
declared in NTL header files are wrapped in namespace NTL.
There are two classes of exceptions:
<p>
<ul>
<li>
All names that start with the prefix "<tt>NTL_</tt>"
are in fact <i>macros</i>.  
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.

<p>

<li>
There are also a number of undocumented names that start with the 
prefix "<tt>_ntl_</tt>".
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 <tt>"C"</tt> linkage have this prefix.
</ul>
<p>
Thus, NTL "owns" all names starting with "<tt>NTL_</tt>" or "<tt>_ntl_</tt>";
users of NTL should avoid names with these prefixes.

<p>
<h3>
Further technicalities
</h3>
<p>

Another thing to be aware of is that there are some small, annoying
differences between the old standard <tt>C</tt> include files
<tt>&lt;stdlib.h&gt;</tt> and <tt>&lt;math.h&gt;</tt>,
and the new <tt>C++</tt> include files 
<tt>&lt;cstdlib&gt;</tt> and <tt>&lt;cmath&gt;</tt>,
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
<pre>
   int abs(int);
</pre>
Now there are several, including:
<pre>
   int abs(int);
   long abs(long);
   float abs(float);
   double abs(double);
   long double abs(long double);
</pre>
Also, functions like <tt>log</tt> and <tt>sqrt</tt> are also overloaded.
So instead of just
<pre>
   double log(double);
</pre>
there are
<pre>
   float log(float);
   double log(double);
   long double log(long double);
</pre>

<p>
This can lead to compile-time errors in some old codes, such as:
<pre>
   double log_2 = log(2);
</pre>

<p>
With the old header files, the <tt>int</tt> value 2 would have
been converted to a <tt>double</tt>, and the function 
<pre>
   double log(double);
</pre>
would have been called.
<p>
With the new header files, the compiler would raise an error,
because the function call is now ambiguous.
<p>
Of course, the fix is trivial:
<pre>
   double log_2 = log(2.0);
</pre>
This will compile correctly with either old or new header files.

<p>
Don't you just love the ISO?


<p>
<h3>
A note on documentation
</h3>
<p>

The "<tt>.txt</tt>" 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 <tt>NTL</tt>,
and the standard library is wrapped in namespace <tt>std</tt>.


<p>
<h3>
Further changes in NTL version 4.1
</h3>
<p>

The ISO Standard for <tt>C++</tt> is not compatible with the
language defined in the second edition of Stroustrup's <tt>C++</tt> 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
<i>either</i> 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.
<p>
Here is a summary of the other changes:
<ul>
<li>
Got rid of all <tt>friend</tt> functions.
It turns out that new <tt>C++</tt> and old <tt>C++</tt> disagree 
quite strongly about the semantics of a <tt>friend</tt> 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 <tt>rep</tt> in class <tt>ZZ_p</tt>
is now the public member <tt>_ZZ_p__rep</tt>).

<p>
This change is effective in both Traditional and ISO modes.

<p>
In my view, the ISO committee really committed an act of sabotage here.
Now the <tt>friend</tt> 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.

<p>

<li>
When <tt>NTL_STD_CXX</tt> or <tt>NTL_PSTD_NTN</tt> are set, 
all calls to <tt>new</tt>
have been replaced by <tt>new(std::nothrow)</tt>.

<p>
The ISO committee also committed an act of sabotage when they changed
the semantics of the memory allocation operator <tt>new</tt>.
In old <tt>C++</tt>, a memory allocation error simply returned
a null pointer; in new <tt>C++</tt> an exception is thrown.
The old semantics are available via  <tt>new(std::nothrow)</tt>.

<p>
You may of course use NTL in Traditional mode with a compiler that
implements the new semantics for <tt>new</tt>.
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 <tt>new</tt> semantics.

<p>

<li>
Various and sundry other small changes, such as fixing
occurrences of the
the "<tt>log(2)</tt>" problem mentioned above.

</ul>

<p>


<p>
<h3>
Standard C++ and the Real World
</h3>

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

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

<p>
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.

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

<p>
It has also been reported that
NTL compiles correctly in ISO mode using the
Metroworks CodeWarrior Pro 5, v. 5.3 compiler on a PowerMac 7500 running
on a 200MHz 604e.

<p>
NTL cannot be used with Microsoft Visual C++ versions 5 or 6
in ISO mode, although this compiler still works with NTL in Traditional mode.
I have tested NTL with  Microsoft Visual C++ version 6,
and found that one can use the <tt>NTL_PSTD_NNS</tt> to useful effect,
especially if one wants to use the STL.
So one can wrap NTL in a namespace.
However, the <tt>NTL_PSTD_NHF</tt> still does not work:
MSVC++ 6 is very inconsistent about the location of a number of
names; even when one uses the new header files, some names
in the standard library are in namespace <tt>std</tt>,
while others are in the global namespace.
Further, it appears that Koenig lookup is not properly
implemented in MSVC++ 6, but luckily, NTL does not rely on this.

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

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

<p>




<center>
<a href="tour-modules.html"><img src="arrow1.gif" alt="[Previous]" align=bottom></a>
 <a href="tour.html"><img src="arrow2.gif" alt="[Up]" align=bottom></a> 
<a href="tour-unix.html"> <img src="arrow3.gif" alt="[Next]" align=bottom></a>
</center>
</body>
</html>