--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename cln.info
+@settitle CLN, a Class Library for Numbers
+@c @setchapternewpage off
+@c I hate putting "@noindent" in front of every paragraph.
+@c For `info' and TeX only.
+@paragraphindent 0
+@c %**end of header
+
+@dircategory Mathematics
+@direntry
+* CLN: (cln). Class Library for Numbers (C++).
+@end direntry
+
+@c My own index.
+@defindex my
+@c Don't need the other types of indices.
+@synindex cp my
+@synindex fn my
+@synindex vr my
+@synindex ky my
+@synindex pg my
+@synindex tp my
+
+
+@c For `info' only.
+@ifinfo
+This file documents @sc{cln}, a Class Library for Numbers.
+
+Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
+Richard B. Kreckel, @code{<kreckel@@ginac.de>}.
+
+Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008.
+Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the author.
+@end ifinfo
+
+
+@c For TeX only.
+@c prevent ugly black rectangles on overfull hbox lines:
+@finalout
+@titlepage
+@title CLN, a Class Library for Numbers
+
+@author @uref{http://www.ginac.de/CLN}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008.
+@sp 0
+Copyright @copyright{} Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008.
+
+@sp 2
+Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
+Richard B. Kreckel, @code{<kreckel@@ginac.de>}.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation approved
+by the authors.
+
+@end titlepage
+@page
+
+
+@c Table of contents
+@contents
+
+
+@node Top, Introduction, (dir), (dir)
+
+@c @menu
+@c * Introduction:: Introduction
+@c @end menu
+
+
+@node Introduction, Top, Top, Top
+@comment node-name, next, previous, up
+@chapter Introduction
+
+@noindent
+CLN is a library for computations with all kinds of numbers.
+It has a rich set of number classes:
+
+@itemize @bullet
+@item
+Integers (with unlimited precision),
+
+@item
+Rational numbers,
+
+@item
+Floating-point numbers:
+
+@itemize @minus
+@item
+Short float,
+@item
+Single float,
+@item
+Double float,
+@item
+Long float (with unlimited precision),
+@end itemize
+
+@item
+Complex numbers,
+
+@item
+Modular integers (integers modulo a fixed integer),
+
+@item
+Univariate polynomials.
+@end itemize
+
+@noindent
+The subtypes of the complex numbers among these are exactly the
+types of numbers known to the Common Lisp language. Therefore
+@code{CLN} can be used for Common Lisp implementations, giving
+@samp{CLN} another meaning: it becomes an abbreviation of
+``Common Lisp Numbers''.
+
+@noindent
+The CLN package implements
+
+@itemize @bullet
+@item
+Elementary functions (@code{+}, @code{-}, @code{*}, @code{/}, @code{sqrt},
+comparisons, @dots{}),
+
+@item
+Logical functions (logical @code{and}, @code{or}, @code{not}, @dots{}),
+
+@item
+Transcendental functions (exponential, logarithmic, trigonometric, hyperbolic
+functions and their inverse functions).
+@end itemize
+
+@noindent
+CLN is a C++ library. Using C++ as an implementation language provides
+
+@itemize @bullet
+@item
+efficiency: it compiles to machine code,
+@item
+type safety: the C++ compiler knows about the number types and complains
+if, for example, you try to assign a float to an integer variable.
+@item
+algebraic syntax: You can use the @code{+}, @code{-}, @code{*}, @code{=},
+@code{==}, @dots{} operators as in C or C++.
+@end itemize
+
+@noindent
+CLN is memory efficient:
+
+@itemize @bullet
+@item
+Small integers and short floats are immediate, not heap allocated.
+@item
+Heap-allocated memory is reclaimed through an automatic, non-interruptive
+garbage collection.
+@end itemize
+
+@noindent
+CLN is speed efficient:
+
+@itemize @bullet
+@item
+The kernel of CLN has been written in assembly language for some CPUs
+(@code{i386}, @code{m68k}, @code{sparc}, @code{mips}, @code{arm}).
+@item
+@cindex GMP
+On all CPUs, CLN may be configured to use the superefficient low-level
+routines from GNU GMP version 3.
+@item
+It uses Karatsuba multiplication, which is significantly faster
+for large numbers than the standard multiplication algorithm.
+@item
+For very large numbers (more than 12000 decimal digits), it uses
+@iftex
+Sch{@"o}nhage-Strassen
+@cindex Sch{@"o}nhage-Strassen multiplication
+@end iftex
+@ifinfo
+Schoenhage-Strassen
+@cindex Schoenhage-Strassen multiplication
+@end ifinfo
+multiplication, which is an asymptotically optimal multiplication
+algorithm, for multiplication, division and radix conversion.
+@item
+@cindex binary splitting
+It uses binary splitting for fast evaluation of series of rational
+numbers as they occur in the evaluation of elementary functions and some
+constants.
+@end itemize
+
+@noindent
+CLN aims at being easily integrated into larger software packages:
+
+@itemize @bullet
+@item
+The garbage collection imposes no burden on the main application.
+@item
+The library provides hooks for memory allocation and throws exceptions
+in case of errors.
+@item
+@cindex namespace
+All non-macro identifiers are hidden in namespace @code{cln} in
+order to avoid name clashes.
+@end itemize
+
+
+@chapter Installation
+
+This section describes how to install the CLN package on your system.
+
+
+@section Prerequisites
+
+@subsection C++ compiler
+
+To build CLN, you need a C++ compiler.
+Actually, you need GNU @code{g++ 3.0.0} or newer.
+
+The following C++ features are used:
+classes, member functions, overloading of functions and operators,
+constructors and destructors, inline, const, multiple inheritance,
+templates and namespaces.
+
+The following C++ features are not used:
+@code{new}, @code{delete}, virtual inheritance.
+
+CLN relies on semi-automatic ordering of initializations of static and
+global variables, a feature which I could implement for GNU g++
+only. Also, it is not known whether this semi-automatic ordering works
+on all platforms when a non-GNU assembler is being used.
+
+@subsection Make utility
+@cindex @code{make}
+
+To build CLN, you also need to have GNU @code{make} installed.
+
+Only GNU @code{make} 3.77 is unusable for CLN; other versions work fine.
+
+@subsection Sed utility
+@cindex @code{sed}
+
+To build CLN on HP-UX, you also need to have GNU @code{sed} installed.
+This is because the libtool script, which creates the CLN library, relies
+on @code{sed}, and the vendor's @code{sed} utility on these systems is too
+limited.
+
+
+@section Building the library
+
+As with any autoconfiguring GNU software, installation is as easy as this:
+
+@example
+$ ./configure
+$ make
+$ make check
+@end example
+
+If on your system, @samp{make} is not GNU @code{make}, you have to use
+@samp{gmake} instead of @samp{make} above.
+
+The @code{configure} command checks out some features of your system and
+C++ compiler and builds the @code{Makefile}s. The @code{make} command
+builds the library. This step may take about half an hour on an average
+workstation. The @code{make check} runs some test to check that no
+important subroutine has been miscompiled.
+
+The @code{configure} command accepts options. To get a summary of them, try
+
+@example
+$ ./configure --help
+@end example
+
+Some of the options are explained in detail in the @samp{INSTALL.generic} file.
+
+You can specify the C compiler, the C++ compiler and their options through
+the following environment variables when running @code{configure}:
+
+@table @code
+@item CC
+Specifies the C compiler.
+
+@item CFLAGS
+Flags to be given to the C compiler when compiling programs (not when linking).
+
+@item CXX
+Specifies the C++ compiler.
+
+@item CXXFLAGS
+Flags to be given to the C++ compiler when compiling programs (not when linking).
+
+@item CPPFLAGS
+Flags to be given to the C/C++ preprocessor.
+@end table
+
+Examples:
+
+@example
+$ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
+@end example
+@example
+$ CC="gcc -V 3.2.3" CFLAGS="-O2 -finline-limit=1000" \
+ CXX="g++ -V 3.2.3" CXXFLAGS="-O2 -finline-limit=1000" \
+ CPPFLAGS="-DNO_ASM" ./configure
+@end example
+@example
+$ CC="gcc-4.2" CFLAGS="-O2" CXX="g++-4.2" CXXFLAGS="-O2" ./configure
+@end example
+
+Note that for these environment variables to take effect, you have to set
+them (assuming a Bourne-compatible shell) on the same line as the
+@code{configure} command. If you made the settings in earlier shell
+commands, you have to @code{export} the environment variables before
+calling @code{configure}. In a @code{csh} shell, you have to use the
+@samp{setenv} command for setting each of the environment variables.
+
+Currently CLN works only with the GNU @code{g++} compiler, and only in
+optimizing mode. So you should specify at least @code{-O} in the
+CXXFLAGS, or no CXXFLAGS at all. If CXXFLAGS is not set, CLN will be
+compiled with @code{-O}.
+
+The assembler language kernel can be turned off by specifying
+@code{-DNO_ASM} in the CPPFLAGS. If @code{make check} reports any
+problems, you may try to clean up (see @ref{Cleaning up}) and configure
+and compile again, this time with @code{-DNO_ASM}.
+
+If you use @code{g++} 3.2.x or earlier, I recommend adding
+@samp{-finline-limit=1000} to the CXXFLAGS. This is essential for good
+code.
+
+If you use @code{g++} from gcc-3.0.4 or older on Sparc, add either
+@samp{-O}, @samp{-O1} or @samp{-O2 -fno-schedule-insns} to the
+CXXFLAGS. With full @samp{-O2}, @code{g++} miscompiles the division
+routines. Also, do not use gcc-3.0 on Sparc for compiling CLN, it
+won't work at all.
+
+Also, please do not compile CLN with @code{g++} using the @code{-O3}
+optimization level. This leads to inferior code quality.
+
+Some newer versions of @code{g++} require quite an amount of memory.
+You might need some swap space if your machine doesn't have 512 MB of
+RAM.
+
+By default, both a shared and a static library are built. You can build
+CLN as a static (or shared) library only, by calling @code{configure}
+with the option @samp{--disable-shared} (or @samp{--disable-static}).
+While shared libraries are usually more convenient to use, they may not
+work on all architectures. Try disabling them if you run into linker
+problems. Also, they are generally slightly slower than static
+libraries so runtime-critical applications should be linked statically.
+
+
+@subsection Using the GNU MP Library
+@cindex GMP
+
+Starting with version 1.1, CLN may be configured to make use of a
+preinstalled @code{gmp} library for some low-level routines. Please
+make sure that you have at least @code{gmp} version 3.0 installed
+since earlier versions are unsupported and likely not to work. This
+feature is known to be quite a boost for CLN's performance.
+
+By default, CLN will autodetect @code{gmp} and use it. But if you have
+installed the @code{gmp} library and its header file in some place where
+your compiler cannot find it by default, you must help @code{configure}
+by setting @code{CPPFLAGS} and @code{LDFLAGS}. Here is an example:
+
+@example
+$ CFLAGS="-O2" CXXFLAGS="-O2" CPPFLAGS="-I/opt/gmp/include" \
+ LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
+@end example
+
+If you do not want CLN to make use of a preinstalled @code{gmp}
+library, then you can explicitly specify so by calling
+@code{configure} with the option @samp{--without-gmp}.
+
+
+@section Installing the library
+@cindex installation
+
+As with any autoconfiguring GNU software, installation is as easy as this:
+
+@example
+$ make install
+@end example
+
+The @samp{make install} command installs the library and the include files
+into public places (@file{/usr/local/lib/} and @file{/usr/local/include/},
+if you haven't specified a @code{--prefix} option to @code{configure}).
+This step may require superuser privileges.
+
+If you have already built the library and wish to install it, but didn't
+specify @code{--prefix=@dots{}} at configure time, just re-run
+@code{configure}, giving it the same options as the first time, plus
+the @code{--prefix=@dots{}} option.
+
+
+@section Cleaning up
+
+You can remove system-dependent files generated by @code{make} through
+
+@example
+$ make clean
+@end example
+
+You can remove all files generated by @code{make}, thus reverting to a
+virgin distribution of CLN, through
+
+@example
+$ make distclean
+@end example
+
+
+@chapter Ordinary number types
+
+CLN implements the following class hierarchy:
+
+@example
+ Number
+ cl_number
+ <cln/number.h>
+ |
+ |
+ Real or complex number
+ cl_N
+ <cln/complex.h>
+ |
+ |
+ Real number
+ cl_R
+ <cln/real.h>
+ |
+ +-------------------+-------------------+
+ | |
+Rational number Floating-point number
+ cl_RA cl_F
+<cln/rational.h> <cln/float.h>
+ | |
+ | +--------------+--------------+--------------+
+ Integer | | | |
+ cl_I Short-Float Single-Float Double-Float Long-Float
+<cln/integer.h> cl_SF cl_FF cl_DF cl_LF
+ <cln/sfloat.h> <cln/ffloat.h> <cln/dfloat.h> <cln/lfloat.h>
+@end example
+
+@cindex @code{cl_number}
+@cindex abstract class
+The base class @code{cl_number} is an abstract base class.
+It is not useful to declare a variable of this type except if you want
+to completely disable compile-time type checking and use run-time type
+checking instead.
+
+@cindex @code{cl_N}
+@cindex real number
+@cindex complex number
+The class @code{cl_N} comprises real and complex numbers. There is
+no special class for complex numbers since complex numbers with imaginary
+part @code{0} are automatically converted to real numbers.
+
+@cindex @code{cl_R}
+The class @code{cl_R} comprises real numbers of different kinds. It is an
+abstract class.
+
+@cindex @code{cl_RA}
+@cindex rational number
+@cindex integer
+The class @code{cl_RA} comprises exact real numbers: rational numbers, including
+integers. There is no special class for non-integral rational numbers
+since rational numbers with denominator @code{1} are automatically converted
+to integers.
+
+@cindex @code{cl_F}
+The class @code{cl_F} implements floating-point approximations to real numbers.
+It is an abstract class.
+
+
+@section Exact numbers
+@cindex exact number
+
+Some numbers are represented as exact numbers: there is no loss of information
+when such a number is converted from its mathematical value to its internal
+representation. On exact numbers, the elementary operations (@code{+},
+@code{-}, @code{*}, @code{/}, comparisons, @dots{}) compute the completely
+correct result.
+
+In CLN, the exact numbers are:
+
+@itemize @bullet
+@item
+rational numbers (including integers),
+@item
+complex numbers whose real and imaginary parts are both rational numbers.
+@end itemize
+
+Rational numbers are always normalized to the form
+@code{@var{numerator}/@var{denominator}} where the numerator and denominator
+are coprime integers and the denominator is positive. If the resulting
+denominator is @code{1}, the rational number is converted to an integer.
+
+@cindex immediate numbers
+Small integers (typically in the range @code{-2^29}@dots{}@code{2^29-1},
+for 32-bit machines) are especially efficient, because they consume no heap
+allocation. Otherwise the distinction between these immediate integers
+(called ``fixnums'') and heap allocated integers (called ``bignums'')
+is completely transparent.
+
+
+@section Floating-point numbers
+@cindex floating-point number
+
+Not all real numbers can be represented exactly. (There is an easy mathematical
+proof for this: Only a countable set of numbers can be stored exactly in
+a computer, even if one assumes that it has unlimited storage. But there
+are uncountably many real numbers.) So some approximation is needed.
+CLN implements ordinary floating-point numbers, with mantissa and exponent.
+
+@cindex rounding error
+The elementary operations (@code{+}, @code{-}, @code{*}, @code{/}, @dots{})
+only return approximate results. For example, the value of the expression
+@code{(cl_F) 0.3 + (cl_F) 0.4} prints as @samp{0.70000005}, not as
+@samp{0.7}. Rounding errors like this one are inevitable when computing
+with floating-point numbers.
+
+Nevertheless, CLN rounds the floating-point results of the operations @code{+},
+@code{-}, @code{*}, @code{/}, @code{sqrt} according to the ``round-to-even''
+rule: It first computes the exact mathematical result and then returns the
+floating-point number which is nearest to this. If two floating-point numbers
+are equally distant from the ideal result, the one with a @code{0} in its least
+significant mantissa bit is chosen.
+
+Similarly, testing floating point numbers for equality @samp{x == y}
+is gambling with random errors. Better check for @samp{abs(x - y) < epsilon}
+for some well-chosen @code{epsilon}.
+
+Floating point numbers come in four flavors:
+
+@itemize @bullet
+@item
+@cindex @code{cl_SF}
+Short floats, type @code{cl_SF}.
+They have 1 sign bit, 8 exponent bits (including the exponent's sign),
+and 17 mantissa bits (including the ``hidden'' bit).
+They don't consume heap allocation.
+
+@item
+@cindex @code{cl_FF}
+Single floats, type @code{cl_FF}.
+They have 1 sign bit, 8 exponent bits (including the exponent's sign),
+and 24 mantissa bits (including the ``hidden'' bit).
+In CLN, they are represented as IEEE single-precision floating point numbers.
+This corresponds closely to the C/C++ type @samp{float}.
+
+@item
+@cindex @code{cl_DF}
+Double floats, type @code{cl_DF}.
+They have 1 sign bit, 11 exponent bits (including the exponent's sign),
+and 53 mantissa bits (including the ``hidden'' bit).
+In CLN, they are represented as IEEE double-precision floating point numbers.
+This corresponds closely to the C/C++ type @samp{double}.
+
+@item
+@cindex @code{cl_LF}
+Long floats, type @code{cl_LF}.
+They have 1 sign bit, 32 exponent bits (including the exponent's sign),
+and n mantissa bits (including the ``hidden'' bit), where n >= 64.
+The precision of a long float is unlimited, but once created, a long float
+has a fixed precision. (No ``lazy recomputation''.)
+@end itemize
+
+Of course, computations with long floats are more expensive than those
+with smaller floating-point formats.
+
+CLN does not implement features like NaNs, denormalized numbers and
+gradual underflow. If the exponent range of some floating-point type
+is too limited for your application, choose another floating-point type
+with larger exponent range.
+
+@cindex @code{cl_F}
+As a user of CLN, you can forget about the differences between the
+four floating-point types and just declare all your floating-point
+variables as being of type @code{cl_F}. This has the advantage that
+when you change the precision of some computation (say, from @code{cl_DF}
+to @code{cl_LF}), you don't have to change the code, only the precision
+of the initial values. Also, many transcendental functions have been
+declared as returning a @code{cl_F} when the argument is a @code{cl_F},
+but such declarations are missing for the types @code{cl_SF}, @code{cl_FF},
+@code{cl_DF}, @code{cl_LF}. (Such declarations would be wrong if
+the floating point contagion rule happened to change in the future.)
+
+
+@section Complex numbers
+@cindex complex number
+
+Complex numbers, as implemented by the class @code{cl_N}, have a real
+part and an imaginary part, both real numbers. A complex number whose
+imaginary part is the exact number @code{0} is automatically converted
+to a real number.
+
+Complex numbers can arise from real numbers alone, for example
+through application of @code{sqrt} or transcendental functions.
+
+
+@section Conversions
+@cindex conversion
+
+Conversions from any class to any its superclasses (``base classes'' in
+C++ terminology) is done automatically.
+
+Conversions from the C built-in types @samp{long} and @samp{unsigned long}
+are provided for the classes @code{cl_I}, @code{cl_RA}, @code{cl_R},
+@code{cl_N} and @code{cl_number}.
+
+Conversions from the C built-in types @samp{int} and @samp{unsigned int}
+are provided for the classes @code{cl_I}, @code{cl_RA}, @code{cl_R},
+@code{cl_N} and @code{cl_number}. However, these conversions emphasize
+efficiency. On 32-bit systems, their range is therefore limited:
+
+@itemize @minus
+@item
+The conversion from @samp{int} works only if the argument is < 2^29 and >= -2^29.
+@item
+The conversion from @samp{unsigned int} works only if the argument is < 2^29.
+@end itemize
+
+In a declaration like @samp{cl_I x = 10;} the C++ compiler is able to
+do the conversion of @code{10} from @samp{int} to @samp{cl_I} at compile time
+already. On the other hand, code like @samp{cl_I x = 1000000000;} is
+in error on 32-bit machines.
+So, if you want to be sure that an @samp{int} whose magnitude is not guaranteed
+to be < 2^29 is correctly converted to a @samp{cl_I}, first convert it to a
+@samp{long}. Similarly, if a large @samp{unsigned int} is to be converted to a
+@samp{cl_I}, first convert it to an @samp{unsigned long}. On 64-bit machines
+there is no such restriction. There, conversions from arbitrary 32-bit @samp{int}
+values always works correctly.
+
+Conversions from the C built-in type @samp{float} are provided for the classes
+@code{cl_FF}, @code{cl_F}, @code{cl_R}, @code{cl_N} and @code{cl_number}.
+
+Conversions from the C built-in type @samp{double} are provided for the classes
+@code{cl_DF}, @code{cl_F}, @code{cl_R}, @code{cl_N} and @code{cl_number}.
+
+Conversions from @samp{const char *} are provided for the classes
+@code{cl_I}, @code{cl_RA},
+@code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}, @code{cl_F},
+@code{cl_R}, @code{cl_N}.
+The easiest way to specify a value which is outside of the range of the
+C++ built-in types is therefore to specify it as a string, like this:
+@cindex Rubik's cube
+@example
+ cl_I order_of_rubiks_cube_group = "43252003274489856000";
+@end example
+Note that this conversion is done at runtime, not at compile-time.
+
+Conversions from @code{cl_I} to the C built-in types @samp{int},
+@samp{unsigned int}, @samp{long}, @samp{unsigned long} are provided through
+the functions
+
+@table @code
+@item int cl_I_to_int (const cl_I& x)
+@cindex @code{cl_I_to_int ()}
+@itemx unsigned int cl_I_to_uint (const cl_I& x)
+@cindex @code{cl_I_to_uint ()}
+@itemx long cl_I_to_long (const cl_I& x)
+@cindex @code{cl_I_to_long ()}
+@itemx unsigned long cl_I_to_ulong (const cl_I& x)
+@cindex @code{cl_I_to_ulong ()}
+Returns @code{x} as element of the C type @var{ctype}. If @code{x} is not
+representable in the range of @var{ctype}, a runtime error occurs.
+@end table
+
+Conversions from the classes @code{cl_I}, @code{cl_RA},
+@code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}, @code{cl_F} and
+@code{cl_R}
+to the C built-in types @samp{float} and @samp{double} are provided through
+the functions
+
+@table @code
+@item float float_approx (const @var{type}& x)
+@cindex @code{float_approx ()}
+@itemx double double_approx (const @var{type}& x)
+@cindex @code{double_approx ()}
+Returns an approximation of @code{x} of C type @var{ctype}.
+If @code{abs(x)} is too close to 0 (underflow), 0 is returned.
+If @code{abs(x)} is too large (overflow), an IEEE infinity is returned.
+@end table
+
+Conversions from any class to any of its subclasses (``derived classes'' in
+C++ terminology) are not provided. Instead, you can assert and check
+that a value belongs to a certain subclass, and return it as element of that
+class, using the @samp{As} and @samp{The} macros.
+@cindex cast
+@cindex @code{As()()}
+@code{As(@var{type})(@var{value})} checks that @var{value} belongs to
+@var{type} and returns it as such.
+@cindex @code{The()()}
+@code{The(@var{type})(@var{value})} assumes that @var{value} belongs to
+@var{type} and returns it as such. It is your responsibility to ensure
+that this assumption is valid. Since macros and namespaces don't go
+together well, there is an equivalent to @samp{The}: the template
+@samp{the}.
+
+Example:
+
+@example
+@group
+ cl_I x = @dots{};
+ if (!(x >= 0)) abort();
+ cl_I ten_x_a = The(cl_I)(expt(10,x)); // If x >= 0, 10^x is an integer.
+ // In general, it would be a rational number.
+ cl_I ten_x_b = the<cl_I>(expt(10,x)); // The same as above.
+@end group
+@end example
+
+
+@chapter Functions on numbers
+
+Each of the number classes declares its mathematical operations in the
+corresponding include file. For example, if your code operates with
+objects of type @code{cl_I}, it should @code{#include <cln/integer.h>}.
+
+
+@section Constructing numbers
+
+Here is how to create number objects ``from nothing''.
+
+
+@subsection Constructing integers
+
+@code{cl_I} objects are most easily constructed from C integers and from
+strings. See @ref{Conversions}.
+
+
+@subsection Constructing rational numbers
+
+@code{cl_RA} objects can be constructed from strings. The syntax
+for rational numbers is described in @ref{Internal and printed representation}.
+Another standard way to produce a rational number is through application
+of @samp{operator /} or @samp{recip} on integers.
+
+
+@subsection Constructing floating-point numbers
+
+@code{cl_F} objects with low precision are most easily constructed from
+C @samp{float} and @samp{double}. See @ref{Conversions}.
+
+To construct a @code{cl_F} with high precision, you can use the conversion
+from @samp{const char *}, but you have to specify the desired precision
+within the string. (See @ref{Internal and printed representation}.)
+Example:
+@example
+ cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
+@end example
+will set @samp{e} to the given value, with a precision of 40 decimal digits.
+
+The programmatic way to construct a @code{cl_F} with high precision is
+through the @code{cl_float} conversion function, see
+@ref{Conversion to floating-point numbers}. For example, to compute
+@code{e} to 40 decimal places, first construct 1.0 to 40 decimal places
+and then apply the exponential function:
+@example
+ float_format_t precision = float_format(40);
+ cl_F e = exp(cl_float(1,precision));
+@end example
+
+
+@subsection Constructing complex numbers
+
+Non-real @code{cl_N} objects are normally constructed through the function
+@example
+ cl_N complex (const cl_R& realpart, const cl_R& imagpart)
+@end example
+See @ref{Elementary complex functions}.
+
+
+@section Elementary functions
+
+Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item @var{type} operator + (const @var{type}&, const @var{type}&)
+@cindex @code{operator + ()}
+Addition.
+
+@item @var{type} operator - (const @var{type}&, const @var{type}&)
+@cindex @code{operator - ()}
+Subtraction.
+
+@item @var{type} operator - (const @var{type}&)
+Returns the negative of the argument.
+
+@item @var{type} plus1 (const @var{type}& x)
+@cindex @code{plus1 ()}
+Returns @code{x + 1}.
+
+@item @var{type} minus1 (const @var{type}& x)
+@cindex @code{minus1 ()}
+Returns @code{x - 1}.
+
+@item @var{type} operator * (const @var{type}&, const @var{type}&)
+@cindex @code{operator * ()}
+Multiplication.
+
+@item @var{type} square (const @var{type}& x)
+@cindex @code{square ()}
+Returns @code{x * x}.
+@end table
+
+Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item @var{type} operator / (const @var{type}&, const @var{type}&)
+@cindex @code{operator / ()}
+Division.
+
+@item @var{type} recip (const @var{type}&)
+@cindex @code{recip ()}
+Returns the reciprocal of the argument.
+@end table
+
+The class @code{cl_I} doesn't define a @samp{/} operation because
+in the C/C++ language this operator, applied to integral types,
+denotes the @samp{floor} or @samp{truncate} operation (which one of these,
+is implementation dependent). (@xref{Rounding functions}.)
+Instead, @code{cl_I} defines an ``exact quotient'' function:
+
+@table @code
+@item cl_I exquo (const cl_I& x, const cl_I& y)
+@cindex @code{exquo ()}
+Checks that @code{y} divides @code{x}, and returns the quotient @code{x}/@code{y}.
+@end table
+
+The following exponentiation functions are defined:
+
+@table @code
+@item cl_I expt_pos (const cl_I& x, const cl_I& y)
+@cindex @code{expt_pos ()}
+@itemx cl_RA expt_pos (const cl_RA& x, const cl_I& y)
+@code{y} must be > 0. Returns @code{x^y}.
+
+@item cl_RA expt (const cl_RA& x, const cl_I& y)
+@cindex @code{expt ()}
+@itemx cl_R expt (const cl_R& x, const cl_I& y)
+@itemx cl_N expt (const cl_N& x, const cl_I& y)
+Returns @code{x^y}.
+@end table
+
+Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operation:
+
+@table @code
+@item @var{type} abs (const @var{type}& x)
+@cindex @code{abs ()}
+Returns the absolute value of @code{x}.
+This is @code{x} if @code{x >= 0}, and @code{-x} if @code{x <= 0}.
+@end table
+
+The class @code{cl_N} implements this as follows:
+
+@table @code
+@item cl_R abs (const cl_N x)
+Returns the absolute value of @code{x}.
+@end table
+
+Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operation:
+
+@table @code
+@item @var{type} signum (const @var{type}& x)
+@cindex @code{signum ()}
+Returns the sign of @code{x}, in the same number format as @code{x}.
+This is defined as @code{x / abs(x)} if @code{x} is non-zero, and
+@code{x} if @code{x} is zero. If @code{x} is real, the value is either
+0 or 1 or -1.
+@end table
+
+
+@section Elementary rational functions
+
+Each of the classes @code{cl_RA}, @code{cl_I} defines the following operations:
+
+@table @code
+@item cl_I numerator (const @var{type}& x)
+@cindex @code{numerator ()}
+Returns the numerator of @code{x}.
+
+@item cl_I denominator (const @var{type}& x)
+@cindex @code{denominator ()}
+Returns the denominator of @code{x}.
+@end table
+
+The numerator and denominator of a rational number are normalized in such
+a way that they have no factor in common and the denominator is positive.
+
+
+@section Elementary complex functions
+
+The class @code{cl_N} defines the following operation:
+
+@table @code
+@item cl_N complex (const cl_R& a, const cl_R& b)
+@cindex @code{complex ()}
+Returns the complex number @code{a+bi}, that is, the complex number with
+real part @code{a} and imaginary part @code{b}.
+@end table
+
+Each of the classes @code{cl_N}, @code{cl_R} defines the following operations:
+
+@table @code
+@item cl_R realpart (const @var{type}& x)
+@cindex @code{realpart ()}
+Returns the real part of @code{x}.
+
+@item cl_R imagpart (const @var{type}& x)
+@cindex @code{imagpart ()}
+Returns the imaginary part of @code{x}.
+
+@item @var{type} conjugate (const @var{type}& x)
+@cindex @code{conjugate ()}
+Returns the complex conjugate of @code{x}.
+@end table
+
+We have the relations
+
+@itemize @asis
+@item
+@code{x = complex(realpart(x), imagpart(x))}
+@item
+@code{conjugate(x) = complex(realpart(x), -imagpart(x))}
+@end itemize
+
+
+@section Comparisons
+@cindex comparison
+
+Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item bool operator == (const @var{type}&, const @var{type}&)
+@cindex @code{operator == ()}
+@itemx bool operator != (const @var{type}&, const @var{type}&)
+@cindex @code{operator != ()}
+Comparison, as in C and C++.
+
+@item uint32 equal_hashcode (const @var{type}&)
+@cindex @code{equal_hashcode ()}
+Returns a 32-bit hash code that is the same for any two numbers which are
+the same according to @code{==}. This hash code depends on the number's value,
+not its type or precision.
+
+@item bool zerop (const @var{type}& x)
+@cindex @code{zerop ()}
+Compare against zero: @code{x == 0}
+@end table
+
+Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item cl_signean compare (const @var{type}& x, const @var{type}& y)
+@cindex @code{compare ()}
+Compares @code{x} and @code{y}. Returns +1 if @code{x}>@code{y},
+-1 if @code{x}<@code{y}, 0 if @code{x}=@code{y}.
+
+@item bool operator <= (const @var{type}&, const @var{type}&)
+@cindex @code{operator <= ()}
+@itemx bool operator < (const @var{type}&, const @var{type}&)
+@cindex @code{operator < ()}
+@itemx bool operator >= (const @var{type}&, const @var{type}&)
+@cindex @code{operator >= ()}
+@itemx bool operator > (const @var{type}&, const @var{type}&)
+@cindex @code{operator > ()}
+Comparison, as in C and C++.
+
+@item bool minusp (const @var{type}& x)
+@cindex @code{minusp ()}
+Compare against zero: @code{x < 0}
+
+@item bool plusp (const @var{type}& x)
+@cindex @code{plusp ()}
+Compare against zero: @code{x > 0}
+
+@item @var{type} max (const @var{type}& x, const @var{type}& y)
+@cindex @code{max ()}
+Return the maximum of @code{x} and @code{y}.
+
+@item @var{type} min (const @var{type}& x, const @var{type}& y)
+@cindex @code{min ()}
+Return the minimum of @code{x} and @code{y}.
+@end table
+
+When a floating point number and a rational number are compared, the float
+is first converted to a rational number using the function @code{rational}.
+Since a floating point number actually represents an interval of real numbers,
+the result might be surprising.
+For example, @code{(cl_F)(cl_R)"1/3" == (cl_R)"1/3"} returns false because
+there is no floating point number whose value is exactly @code{1/3}.
+
+
+@section Rounding functions
+@cindex rounding
+
+When a real number is to be converted to an integer, there is no ``best''
+rounding. The desired rounding function depends on the application.
+The Common Lisp and ISO Lisp standards offer four rounding functions:
+
+@table @code
+@item floor(x)
+This is the largest integer <=@code{x}.
+
+@item ceiling(x)
+This is the smallest integer >=@code{x}.
+
+@item truncate(x)
+Among the integers between 0 and @code{x} (inclusive) the one nearest to @code{x}.
+
+@item round(x)
+The integer nearest to @code{x}. If @code{x} is exactly halfway between two
+integers, choose the even one.
+@end table
+
+These functions have different advantages:
+
+@code{floor} and @code{ceiling} are translation invariant:
+@code{floor(x+n) = floor(x) + n} and @code{ceiling(x+n) = ceiling(x) + n}
+for every @code{x} and every integer @code{n}.
+
+On the other hand, @code{truncate} and @code{round} are symmetric:
+@code{truncate(-x) = -truncate(x)} and @code{round(-x) = -round(x)},
+and furthermore @code{round} is unbiased: on the ``average'', it rounds
+down exactly as often as it rounds up.
+
+The functions are related like this:
+
+@itemize @asis
+@item
+@code{ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1}
+for rational numbers @code{m/n} (@code{m}, @code{n} integers, @code{n}>0), and
+@item
+@code{truncate(x) = sign(x) * floor(abs(x))}
+@end itemize
+
+Each of the classes @code{cl_R}, @code{cl_RA},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item cl_I floor1 (const @var{type}& x)
+@cindex @code{floor1 ()}
+Returns @code{floor(x)}.
+@item cl_I ceiling1 (const @var{type}& x)
+@cindex @code{ceiling1 ()}
+Returns @code{ceiling(x)}.
+@item cl_I truncate1 (const @var{type}& x)
+@cindex @code{truncate1 ()}
+Returns @code{truncate(x)}.
+@item cl_I round1 (const @var{type}& x)
+@cindex @code{round1 ()}
+Returns @code{round(x)}.
+@end table
+
+Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item cl_I floor1 (const @var{type}& x, const @var{type}& y)
+Returns @code{floor(x/y)}.
+@item cl_I ceiling1 (const @var{type}& x, const @var{type}& y)
+Returns @code{ceiling(x/y)}.
+@item cl_I truncate1 (const @var{type}& x, const @var{type}& y)
+Returns @code{truncate(x/y)}.
+@item cl_I round1 (const @var{type}& x, const @var{type}& y)
+Returns @code{round(x/y)}.
+@end table
+
+These functions are called @samp{floor1}, @dots{} here instead of
+@samp{floor}, @dots{}, because on some systems, system dependent include
+files define @samp{floor} and @samp{ceiling} as macros.
+
+In many cases, one needs both the quotient and the remainder of a division.
+It is more efficient to compute both at the same time than to perform
+two divisions, one for quotient and the next one for the remainder.
+The following functions therefore return a structure containing both
+the quotient and the remainder. The suffix @samp{2} indicates the number
+of ``return values''. The remainder is defined as follows:
+
+@itemize @bullet
+@item
+for the computation of @code{quotient = floor(x)},
+@code{remainder = x - quotient},
+@item
+for the computation of @code{quotient = floor(x,y)},
+@code{remainder = x - quotient*y},
+@end itemize
+
+and similarly for the other three operations.
+
+Each of the classes @code{cl_R}, @code{cl_RA},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item struct @var{type}_div_t @{ cl_I quotient; @var{type} remainder; @};
+@itemx @var{type}_div_t floor2 (const @var{type}& x)
+@itemx @var{type}_div_t ceiling2 (const @var{type}& x)
+@itemx @var{type}_div_t truncate2 (const @var{type}& x)
+@itemx @var{type}_div_t round2 (const @var{type}& x)
+@end table
+
+Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item struct @var{type}_div_t @{ cl_I quotient; @var{type} remainder; @};
+@itemx @var{type}_div_t floor2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{floor2 ()}
+@itemx @var{type}_div_t ceiling2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{ceiling2 ()}
+@itemx @var{type}_div_t truncate2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{truncate2 ()}
+@itemx @var{type}_div_t round2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{round2 ()}
+@end table
+
+Sometimes, one wants the quotient as a floating-point number (of the
+same format as the argument, if the argument is a float) instead of as
+an integer. The prefix @samp{f} indicates this.
+
+Each of the classes
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+
+@table @code
+@item @var{type} ffloor (const @var{type}& x)
+@cindex @code{ffloor ()}
+@itemx @var{type} fceiling (const @var{type}& x)
+@cindex @code{fceiling ()}
+@itemx @var{type} ftruncate (const @var{type}& x)
+@cindex @code{ftruncate ()}
+@itemx @var{type} fround (const @var{type}& x)
+@cindex @code{fround ()}
+@end table
+
+and similarly for class @code{cl_R}, but with return type @code{cl_F}.
+
+The class @code{cl_R} defines the following operations:
+
+@table @code
+@item cl_F ffloor (const @var{type}& x, const @var{type}& y)
+@itemx cl_F fceiling (const @var{type}& x, const @var{type}& y)
+@itemx cl_F ftruncate (const @var{type}& x, const @var{type}& y)
+@itemx cl_F fround (const @var{type}& x, const @var{type}& y)
+@end table
+
+These functions also exist in versions which return both the quotient
+and the remainder. The suffix @samp{2} indicates this.
+
+Each of the classes
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations:
+@cindex @code{cl_F_fdiv_t}
+@cindex @code{cl_SF_fdiv_t}
+@cindex @code{cl_FF_fdiv_t}
+@cindex @code{cl_DF_fdiv_t}
+@cindex @code{cl_LF_fdiv_t}
+
+@table @code
+@item struct @var{type}_fdiv_t @{ @var{type} quotient; @var{type} remainder; @};
+@itemx @var{type}_fdiv_t ffloor2 (const @var{type}& x)
+@cindex @code{ffloor2 ()}
+@itemx @var{type}_fdiv_t fceiling2 (const @var{type}& x)
+@cindex @code{fceiling2 ()}
+@itemx @var{type}_fdiv_t ftruncate2 (const @var{type}& x)
+@cindex @code{ftruncate2 ()}
+@itemx @var{type}_fdiv_t fround2 (const @var{type}& x)
+@cindex @code{fround2 ()}
+@end table
+and similarly for class @code{cl_R}, but with quotient type @code{cl_F}.
+@cindex @code{cl_R_fdiv_t}
+
+The class @code{cl_R} defines the following operations:
+
+@table @code
+@item struct @var{type}_fdiv_t @{ cl_F quotient; cl_R remainder; @};
+@itemx @var{type}_fdiv_t ffloor2 (const @var{type}& x, const @var{type}& y)
+@itemx @var{type}_fdiv_t fceiling2 (const @var{type}& x, const @var{type}& y)
+@itemx @var{type}_fdiv_t ftruncate2 (const @var{type}& x, const @var{type}& y)
+@itemx @var{type}_fdiv_t fround2 (const @var{type}& x, const @var{type}& y)
+@end table
+
+Other applications need only the remainder of a division.
+The remainder of @samp{floor} and @samp{ffloor} is called @samp{mod}
+(abbreviation of ``modulo''). The remainder @samp{truncate} and
+@samp{ftruncate} is called @samp{rem} (abbreviation of ``remainder'').
+
+@itemize @bullet
+@item
+@code{mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y}
+@item
+@code{rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y}
+@end itemize
+
+If @code{x} and @code{y} are both >= 0, @code{mod(x,y) = rem(x,y) >= 0}.
+In general, @code{mod(x,y)} has the sign of @code{y} or is zero,
+and @code{rem(x,y)} has the sign of @code{x} or is zero.
+
+The classes @code{cl_R}, @code{cl_I} define the following operations:
+
+@table @code
+@item @var{type} mod (const @var{type}& x, const @var{type}& y)
+@cindex @code{mod ()}
+@itemx @var{type} rem (const @var{type}& x, const @var{type}& y)
+@cindex @code{rem ()}
+@end table
+
+
+@section Roots
+
+Each of the classes @code{cl_R},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operation:
+
+@table @code
+@item @var{type} sqrt (const @var{type}& x)
+@cindex @code{sqrt ()}
+@code{x} must be >= 0. This function returns the square root of @code{x},
+normalized to be >= 0. If @code{x} is the square of a rational number,
+@code{sqrt(x)} will be a rational number, else it will return a
+floating-point approximation.
+@end table
+
+The classes @code{cl_RA}, @code{cl_I} define the following operation:
+
+@table @code
+@item bool sqrtp (const @var{type}& x, @var{type}* root)
+@cindex @code{sqrtp ()}
+This tests whether @code{x} is a perfect square. If so, it returns true
+and the exact square root in @code{*root}, else it returns false.
+@end table
+
+Furthermore, for integers, similarly:
+
+@table @code
+@item bool isqrt (const @var{type}& x, @var{type}* root)
+@cindex @code{isqrt ()}
+@code{x} should be >= 0. This function sets @code{*root} to
+@code{floor(sqrt(x))} and returns the same value as @code{sqrtp}:
+the boolean value @code{(expt(*root,2) == x)}.
+@end table
+
+For @code{n}th roots, the classes @code{cl_RA}, @code{cl_I}
+define the following operation:
+
+@table @code
+@item bool rootp (const @var{type}& x, const cl_I& n, @var{type}* root)
+@cindex @code{rootp ()}
+@code{x} must be >= 0. @code{n} must be > 0.
+This tests whether @code{x} is an @code{n}th power of a rational number.
+If so, it returns true and the exact root in @code{*root}, else it returns
+false.
+@end table
+
+The only square root function which accepts negative numbers is the one
+for class @code{cl_N}:
+
+@table @code
+@item cl_N sqrt (const cl_N& z)
+@cindex @code{sqrt ()}
+Returns the square root of @code{z}, as defined by the formula
+@code{sqrt(z) = exp(log(z)/2)}. Conversion to a floating-point type
+or to a complex number are done if necessary. The range of the result is the
+right half plane @code{realpart(sqrt(z)) >= 0}
+including the positive imaginary axis and 0, but excluding
+the negative imaginary axis.
+The result is an exact number only if @code{z} is an exact number.
+@end table
+
+
+@section Transcendental functions
+@cindex transcendental functions
+
+The transcendental functions return an exact result if the argument
+is exact and the result is exact as well. Otherwise they must return
+inexact numbers even if the argument is exact.
+For example, @code{cos(0) = 1} returns the rational number @code{1}.
+
+
+@subsection Exponential and logarithmic functions
+
+@table @code
+@item cl_R exp (const cl_R& x)
+@cindex @code{exp ()}
+@itemx cl_N exp (const cl_N& x)
+Returns the exponential function of @code{x}. This is @code{e^x} where
+@code{e} is the base of the natural logarithms. The range of the result
+is the entire complex plane excluding 0.
+
+@item cl_R ln (const cl_R& x)
+@cindex @code{ln ()}
+@code{x} must be > 0. Returns the (natural) logarithm of x.
+
+@item cl_N log (const cl_N& x)
+@cindex @code{log ()}
+Returns the (natural) logarithm of x. If @code{x} is real and positive,
+this is @code{ln(x)}. In general, @code{log(x) = log(abs(x)) + i*phase(x)}.
+The range of the result is the strip in the complex plane
+@code{-pi < imagpart(log(x)) <= pi}.
+
+@item cl_R phase (const cl_N& x)
+@cindex @code{phase ()}
+Returns the angle part of @code{x} in its polar representation as a
+complex number. That is, @code{phase(x) = atan(realpart(x),imagpart(x))}.
+This is also the imaginary part of @code{log(x)}.
+The range of the result is the interval @code{-pi < phase(x) <= pi}.
+The result will be an exact number only if @code{zerop(x)} or
+if @code{x} is real and positive.
+
+@item cl_R log (const cl_R& a, const cl_R& b)
+@code{a} and @code{b} must be > 0. Returns the logarithm of @code{a} with
+respect to base @code{b}. @code{log(a,b) = ln(a)/ln(b)}.
+The result can be exact only if @code{a = 1} or if @code{a} and @code{b}
+are both rational.
+
+@item cl_N log (const cl_N& a, const cl_N& b)
+Returns the logarithm of @code{a} with respect to base @code{b}.
+@code{log(a,b) = log(a)/log(b)}.
+
+@item cl_N expt (const cl_N& x, const cl_N& y)
+@cindex @code{expt ()}
+Exponentiation: Returns @code{x^y = exp(y*log(x))}.
+@end table
+
+The constant e = exp(1) = 2.71828@dots{} is returned by the following functions:
+
+@table @code
+@item cl_F exp1 (float_format_t f)
+@cindex @code{exp1 ()}
+Returns e as a float of format @code{f}.
+
+@item cl_F exp1 (const cl_F& y)
+Returns e in the float format of @code{y}.
+
+@item cl_F exp1 (void)
+Returns e as a float of format @code{default_float_format}.
+@end table
+
+
+@subsection Trigonometric functions
+
+@table @code
+@item cl_R sin (const cl_R& x)
+@cindex @code{sin ()}
+Returns @code{sin(x)}. The range of the result is the interval
+@code{-1 <= sin(x) <= 1}.
+
+@item cl_N sin (const cl_N& z)
+Returns @code{sin(z)}. The range of the result is the entire complex plane.
+
+@item cl_R cos (const cl_R& x)
+@cindex @code{cos ()}
+Returns @code{cos(x)}. The range of the result is the interval
+@code{-1 <= cos(x) <= 1}.
+
+@item cl_N cos (const cl_N& x)
+Returns @code{cos(z)}. The range of the result is the entire complex plane.
+
+@item struct cos_sin_t @{ cl_R cos; cl_R sin; @};
+@cindex @code{cos_sin_t}
+@itemx cos_sin_t cos_sin (const cl_R& x)
+Returns both @code{sin(x)} and @code{cos(x)}. This is more efficient than
+@cindex @code{cos_sin ()}
+computing them separately. The relation @code{cos^2 + sin^2 = 1} will
+hold only approximately.
+
+@item cl_R tan (const cl_R& x)
+@cindex @code{tan ()}
+@itemx cl_N tan (const cl_N& x)
+Returns @code{tan(x) = sin(x)/cos(x)}.
+
+@item cl_N cis (const cl_R& x)
+@cindex @code{cis ()}
+@itemx cl_N cis (const cl_N& x)
+Returns @code{exp(i*x)}. The name @samp{cis} means ``cos + i sin'', because
+@code{e^(i*x) = cos(x) + i*sin(x)}.
+
+@cindex @code{asin}
+@cindex @code{asin ()}
+@item cl_N asin (const cl_N& z)
+Returns @code{arcsin(z)}. This is defined as
+@code{arcsin(z) = log(iz+sqrt(1-z^2))/i} and satisfies
+@code{arcsin(-z) = -arcsin(z)}.
+The range of the result is the strip in the complex domain
+@code{-pi/2 <= realpart(arcsin(z)) <= pi/2}, excluding the numbers
+with @code{realpart = -pi/2} and @code{imagpart < 0} and the numbers
+with @code{realpart = pi/2} and @code{imagpart > 0}.
+@ignore
+Proof: This follows from arcsin(z) = arsinh(iz)/i and the corresponding
+results for arsinh.
+@end ignore
+
+@item cl_N acos (const cl_N& z)
+@cindex @code{acos ()}
+Returns @code{arccos(z)}. This is defined as
+@code{arccos(z) = pi/2 - arcsin(z) = log(z+i*sqrt(1-z^2))/i}
+@ignore
+ Kahan's formula:
+ @code{arccos(z) = 2*log(sqrt((1+z)/2)+i*sqrt((1-z)/2))/i}
+@end ignore
+and satisfies @code{arccos(-z) = pi - arccos(z)}.
+The range of the result is the strip in the complex domain
+@code{0 <= realpart(arcsin(z)) <= pi}, excluding the numbers
+with @code{realpart = 0} and @code{imagpart < 0} and the numbers
+with @code{realpart = pi} and @code{imagpart > 0}.
+@ignore
+Proof: This follows from the results about arcsin.
+@end ignore
+
+@cindex @code{atan}
+@cindex @code{atan ()}
+@item cl_R atan (const cl_R& x, const cl_R& y)
+Returns the angle of the polar representation of the complex number
+@code{x+iy}. This is @code{atan(y/x)} if @code{x>0}. The range of
+the result is the interval @code{-pi < atan(x,y) <= pi}. The result will
+be an exact number only if @code{x > 0} and @code{y} is the exact @code{0}.
+WARNING: In Common Lisp, this function is called as @code{(atan y x)},
+with reversed order of arguments.
+
+@item cl_R atan (const cl_R& x)
+Returns @code{arctan(x)}. This is the same as @code{atan(1,x)}. The range
+of the result is the interval @code{-pi/2 < atan(x) < pi/2}. The result
+will be an exact number only if @code{x} is the exact @code{0}.
+
+@item cl_N atan (const cl_N& z)
+Returns @code{arctan(z)}. This is defined as
+@code{arctan(z) = (log(1+iz)-log(1-iz)) / 2i} and satisfies
+@code{arctan(-z) = -arctan(z)}. The range of the result is
+the strip in the complex domain
+@code{-pi/2 <= realpart(arctan(z)) <= pi/2}, excluding the numbers
+with @code{realpart = -pi/2} and @code{imagpart >= 0} and the numbers
+with @code{realpart = pi/2} and @code{imagpart <= 0}.
+@ignore
+Proof: arctan(z) = artanh(iz)/i, we know the range of the artanh function.
+@end ignore
+
+@end table
+
+@cindex pi
+@cindex Archimedes' constant
+Archimedes' constant pi = 3.14@dots{} is returned by the following functions:
+
+@table @code
+@item cl_F pi (float_format_t f)
+@cindex @code{pi ()}
+Returns pi as a float of format @code{f}.
+
+@item cl_F pi (const cl_F& y)
+Returns pi in the float format of @code{y}.
+
+@item cl_F pi (void)
+Returns pi as a float of format @code{default_float_format}.
+@end table
+
+
+@subsection Hyperbolic functions
+
+@table @code
+@item cl_R sinh (const cl_R& x)
+@cindex @code{sinh ()}
+Returns @code{sinh(x)}.
+
+@item cl_N sinh (const cl_N& z)
+Returns @code{sinh(z)}. The range of the result is the entire complex plane.
+
+@item cl_R cosh (const cl_R& x)
+@cindex @code{cosh ()}
+Returns @code{cosh(x)}. The range of the result is the interval
+@code{cosh(x) >= 1}.
+
+@item cl_N cosh (const cl_N& z)
+Returns @code{cosh(z)}. The range of the result is the entire complex plane.
+
+@item struct cosh_sinh_t @{ cl_R cosh; cl_R sinh; @};
+@cindex @code{cosh_sinh_t}
+@itemx cosh_sinh_t cosh_sinh (const cl_R& x)
+@cindex @code{cosh_sinh ()}
+Returns both @code{sinh(x)} and @code{cosh(x)}. This is more efficient than
+computing them separately. The relation @code{cosh^2 - sinh^2 = 1} will
+hold only approximately.
+
+@item cl_R tanh (const cl_R& x)
+@cindex @code{tanh ()}
+@itemx cl_N tanh (const cl_N& x)
+Returns @code{tanh(x) = sinh(x)/cosh(x)}.
+
+@item cl_N asinh (const cl_N& z)
+@cindex @code{asinh ()}
+Returns @code{arsinh(z)}. This is defined as
+@code{arsinh(z) = log(z+sqrt(1+z^2))} and satisfies
+@code{arsinh(-z) = -arsinh(z)}.
+@ignore
+Proof: Knowing the range of log, we know -pi < imagpart(arsinh(z)) <= pi.
+Actually, z+sqrt(1+z^2) can never be real and <0, so
+-pi < imagpart(arsinh(z)) < pi.
+We have (z+sqrt(1+z^2))*(-z+sqrt(1+(-z)^2)) = (1+z^2)-z^2 = 1, hence the
+logs of both factors sum up to 0 mod 2*pi*i, hence to 0.
+@end ignore
+The range of the result is the strip in the complex domain
+@code{-pi/2 <= imagpart(arsinh(z)) <= pi/2}, excluding the numbers
+with @code{imagpart = -pi/2} and @code{realpart > 0} and the numbers
+with @code{imagpart = pi/2} and @code{realpart < 0}.
+@ignore
+Proof: Write z = x+iy. Because of arsinh(-z) = -arsinh(z), we may assume
+that z is in Range(sqrt), that is, x>=0 and, if x=0, then y>=0.
+If x > 0, then Re(z+sqrt(1+z^2)) = x + Re(sqrt(1+z^2)) >= x > 0,
+so -pi/2 < imagpart(log(z+sqrt(1+z^2))) < pi/2.
+If x = 0 and y >= 0, arsinh(z) = log(i*y+sqrt(1-y^2)).
+ If y <= 1, the realpart is 0 and the imagpart is >= 0 and <= pi/2.
+ If y >= 1, the imagpart is pi/2 and the realpart is
+ log(y+sqrt(y^2-1)) >= log(y) >= 0.
+@end ignore
+@ignore
+Moreover, if z is in Range(sqrt),
+log(sqrt(1+z^2)+z) = 2 artanh(z/(1+sqrt(1+z^2)))
+(for a proof, see file src/cl_C_asinh.cc).
+@end ignore
+
+@item cl_N acosh (const cl_N& z)
+@cindex @code{acosh ()}
+Returns @code{arcosh(z)}. This is defined as
+@code{arcosh(z) = 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))}.
+The range of the result is the half-strip in the complex domain
+@code{-pi < imagpart(arcosh(z)) <= pi, realpart(arcosh(z)) >= 0},
+excluding the numbers with @code{realpart = 0} and @code{-pi < imagpart < 0}.
+@ignore
+Proof: sqrt((z+1)/2) and sqrt((z-1)/2)) lie in Range(sqrt), hence does
+their sum, hence its log has an imagpart <= pi/2 and > -pi/2.
+If z is in Range(sqrt), we have
+ sqrt(z+1)*sqrt(z-1) = sqrt(z^2-1)
+ ==> (sqrt((z+1)/2)+sqrt((z-1)/2))^2 = (z+1)/2 + sqrt(z^2-1) + (z-1)/2
+ = z + sqrt(z^2-1)
+ ==> arcosh(z) = log(z+sqrt(z^2-1)) mod 2*pi*i
+ and since the imagpart of both expressions is > -pi, <= pi
+ ==> arcosh(z) = log(z+sqrt(z^2-1))
+ To prove that the realpart of this is >= 0, write z = x+iy with x>=0,
+ z^2-1 = u+iv with u = x^2-y^2-1, v = 2xy,
+ sqrt(z^2-1) = p+iq with p = sqrt((sqrt(u^2+v^2)+u)/2) >= 0,
+ q = sqrt((sqrt(u^2+v^2)-u)/2) * sign(v),
+ then |z+sqrt(z^2-1)|^2 = |x+iy + p+iq|^2
+ = (x+p)^2 + (y+q)^2
+ = x^2 + 2xp + p^2 + y^2 + 2yq + q^2
+ >= x^2 + p^2 + y^2 + q^2 (since x>=0, p>=0, yq>=0)
+ = x^2 + y^2 + sqrt(u^2+v^2)
+ >= x^2 + y^2 + |u|
+ >= x^2 + y^2 - u
+ = 1 + 2*y^2
+ >= 1
+ hence realpart(log(z+sqrt(z^2-1))) = log(|z+sqrt(z^2-1)|) >= 0.
+ Equality holds only if y = 0 and u <= 0, i.e. 0 <= x < 1.
+ In this case arcosh(z) = log(x+i*sqrt(1-x^2)) has imagpart >=0.
+Otherwise, -z is in Range(sqrt).
+ If y != 0, sqrt((z+1)/2) = i^sign(y) * sqrt((-z-1)/2),
+ sqrt((z-1)/2) = i^sign(y) * sqrt((-z+1)/2),
+ hence arcosh(z) = sign(y)*pi/2*i + arcosh(-z),
+ and this has realpart > 0.
+ If y = 0 and -1<=x<=0, we still have sqrt(z+1)*sqrt(z-1) = sqrt(z^2-1),
+ ==> arcosh(z) = log(z+sqrt(z^2-1)) = log(x+i*sqrt(1-x^2))
+ has realpart = 0 and imagpart > 0.
+ If y = 0 and x<=-1, however, sqrt(z+1)*sqrt(z-1) = - sqrt(z^2-1),
+ ==> arcosh(z) = log(z-sqrt(z^2-1)) = pi*i + arcosh(-z).
+ This has realpart >= 0 and imagpart = pi.
+@end ignore
+
+@item cl_N atanh (const cl_N& z)
+@cindex @code{atanh ()}
+Returns @code{artanh(z)}. This is defined as
+@code{artanh(z) = (log(1+z)-log(1-z)) / 2} and satisfies
+@code{artanh(-z) = -artanh(z)}. The range of the result is
+the strip in the complex domain
+@code{-pi/2 <= imagpart(artanh(z)) <= pi/2}, excluding the numbers
+with @code{imagpart = -pi/2} and @code{realpart <= 0} and the numbers
+with @code{imagpart = pi/2} and @code{realpart >= 0}.
+@ignore
+Proof: Write z = x+iy. Examine
+ imagpart(artanh(z)) = (atan(1+x,y) - atan(1-x,-y))/2.
+ Case 1: y = 0.
+ x > 1 ==> imagpart = -pi/2, realpart = 1/2 log((x+1)/(x-1)) > 0,
+ x < -1 ==> imagpart = pi/2, realpart = 1/2 log((-x-1)/(-x+1)) < 0,
+ |x| < 1 ==> imagpart = 0
+ Case 2: y > 0.
+ imagpart(artanh(z))
+ = (atan(1+x,y) - atan(1-x,-y))/2
+ = ((pi/2 - atan((1+x)/y)) - (-pi/2 - atan((1-x)/-y)))/2
+ = (pi - atan((1+x)/y) - atan((1-x)/y))/2
+ > (pi - pi/2 - pi/2 )/2 = 0
+ and (1+x)/y > (1-x)/y
+ ==> atan((1+x)/y) > atan((-1+x)/y) = - atan((1-x)/y)
+ ==> imagpart < pi/2.
+ Hence 0 < imagpart < pi/2.
+ Case 3: y < 0.
+ By artanh(z) = -artanh(-z) and case 2, -pi/2 < imagpart < 0.
+@end ignore
+@end table
+
+
+@subsection Euler gamma
+@cindex Euler's constant
+
+Euler's constant C = 0.577@dots{} is returned by the following functions:
+
+@table @code
+@item cl_F eulerconst (float_format_t f)
+@cindex @code{eulerconst ()}
+Returns Euler's constant as a float of format @code{f}.
+
+@item cl_F eulerconst (const cl_F& y)
+Returns Euler's constant in the float format of @code{y}.
+
+@item cl_F eulerconst (void)
+Returns Euler's constant as a float of format @code{default_float_format}.
+@end table
+
+Catalan's constant G = 0.915@dots{} is returned by the following functions:
+@cindex Catalan's constant
+
+@table @code
+@item cl_F catalanconst (float_format_t f)
+@cindex @code{catalanconst ()}
+Returns Catalan's constant as a float of format @code{f}.
+
+@item cl_F catalanconst (const cl_F& y)
+Returns Catalan's constant in the float format of @code{y}.
+
+@item cl_F catalanconst (void)
+Returns Catalan's constant as a float of format @code{default_float_format}.
+@end table
+
+
+@subsection Riemann zeta
+@cindex Riemann's zeta
+
+Riemann's zeta function at an integral point @code{s>1} is returned by the
+following functions:
+
+@table @code
+@item cl_F zeta (int s, float_format_t f)
+@cindex @code{zeta ()}
+Returns Riemann's zeta function at @code{s} as a float of format @code{f}.
+
+@item cl_F zeta (int s, const cl_F& y)
+Returns Riemann's zeta function at @code{s} in the float format of @code{y}.
+
+@item cl_F zeta (int s)
+Returns Riemann's zeta function at @code{s} as a float of format
+@code{default_float_format}.
+@end table
+
+
+@section Functions on integers
+
+@subsection Logical functions
+
+Integers, when viewed as in two's complement notation, can be thought as
+infinite bit strings where the bits' values eventually are constant.
+For example,
+@example
+ 17 = ......00010001
+ -6 = ......11111010
+@end example
+
+The logical operations view integers as such bit strings and operate
+on each of the bit positions in parallel.
+
+@table @code
+@item cl_I lognot (const cl_I& x)
+@cindex @code{lognot ()}
+@itemx cl_I operator ~ (const cl_I& x)
+@cindex @code{operator ~ ()}
+Logical not, like @code{~x} in C. This is the same as @code{-1-x}.
+
+@item cl_I logand (const cl_I& x, const cl_I& y)
+@cindex @code{logand ()}
+@itemx cl_I operator & (const cl_I& x, const cl_I& y)
+@cindex @code{operator & ()}
+Logical and, like @code{x & y} in C.
+
+@item cl_I logior (const cl_I& x, const cl_I& y)
+@cindex @code{logior ()}
+@itemx cl_I operator | (const cl_I& x, const cl_I& y)
+@cindex @code{operator | ()}
+Logical (inclusive) or, like @code{x | y} in C.
+
+@item cl_I logxor (const cl_I& x, const cl_I& y)
+@cindex @code{logxor ()}
+@itemx cl_I operator ^ (const cl_I& x, const cl_I& y)
+@cindex @code{operator ^ ()}
+Exclusive or, like @code{x ^ y} in C.
+
+@item cl_I logeqv (const cl_I& x, const cl_I& y)
+@cindex @code{logeqv ()}
+Bitwise equivalence, like @code{~(x ^ y)} in C.
+
+@item cl_I lognand (const cl_I& x, const cl_I& y)
+@cindex @code{lognand ()}
+Bitwise not and, like @code{~(x & y)} in C.
+
+@item cl_I lognor (const cl_I& x, const cl_I& y)
+@cindex @code{lognor ()}
+Bitwise not or, like @code{~(x | y)} in C.
+
+@item cl_I logandc1 (const cl_I& x, const cl_I& y)
+@cindex @code{logandc1 ()}
+Logical and, complementing the first argument, like @code{~x & y} in C.
+
+@item cl_I logandc2 (const cl_I& x, const cl_I& y)
+@cindex @code{logandc2 ()}
+Logical and, complementing the second argument, like @code{x & ~y} in C.
+
+@item cl_I logorc1 (const cl_I& x, const cl_I& y)
+@cindex @code{logorc1 ()}
+Logical or, complementing the first argument, like @code{~x | y} in C.
+
+@item cl_I logorc2 (const cl_I& x, const cl_I& y)
+@cindex @code{logorc2 ()}
+Logical or, complementing the second argument, like @code{x | ~y} in C.
+@end table
+
+These operations are all available though the function
+@table @code
+@item cl_I boole (cl_boole op, const cl_I& x, const cl_I& y)
+@cindex @code{boole ()}
+@end table
+where @code{op} must have one of the 16 values (each one stands for a function
+which combines two bits into one bit): @code{boole_clr}, @code{boole_set},
+@code{boole_1}, @code{boole_2}, @code{boole_c1}, @code{boole_c2},
+@code{boole_and}, @code{boole_ior}, @code{boole_xor}, @code{boole_eqv},
+@code{boole_nand}, @code{boole_nor}, @code{boole_andc1}, @code{boole_andc2},
+@code{boole_orc1}, @code{boole_orc2}.
+@cindex @code{boole_clr}
+@cindex @code{boole_set}
+@cindex @code{boole_1}
+@cindex @code{boole_2}
+@cindex @code{boole_c1}
+@cindex @code{boole_c2}
+@cindex @code{boole_and}
+@cindex @code{boole_xor}
+@cindex @code{boole_eqv}
+@cindex @code{boole_nand}
+@cindex @code{boole_nor}
+@cindex @code{boole_andc1}
+@cindex @code{boole_andc2}
+@cindex @code{boole_orc1}
+@cindex @code{boole_orc2}
+
+
+Other functions that view integers as bit strings:
+
+@table @code
+@item bool logtest (const cl_I& x, const cl_I& y)
+@cindex @code{logtest ()}
+Returns true if some bit is set in both @code{x} and @code{y}, i.e. if
+@code{logand(x,y) != 0}.
+
+@item bool logbitp (const cl_I& n, const cl_I& x)
+@cindex @code{logbitp ()}
+Returns true if the @code{n}th bit (from the right) of @code{x} is set.
+Bit 0 is the least significant bit.
+
+@item uintC logcount (const cl_I& x)
+@cindex @code{logcount ()}
+Returns the number of one bits in @code{x}, if @code{x} >= 0, or
+the number of zero bits in @code{x}, if @code{x} < 0.
+@end table
+
+The following functions operate on intervals of bits in integers.
+The type
+@example
+struct cl_byte @{ uintC size; uintC position; @};
+@end example
+@cindex @code{cl_byte}
+represents the bit interval containing the bits
+@code{position}@dots{}@code{position+size-1} of an integer.
+The constructor @code{cl_byte(size,position)} constructs a @code{cl_byte}.
+
+@table @code
+@item cl_I ldb (const cl_I& n, const cl_byte& b)
+@cindex @code{ldb ()}
+extracts the bits of @code{n} described by the bit interval @code{b}
+and returns them as a nonnegative integer with @code{b.size} bits.
+
+@item bool ldb_test (const cl_I& n, const cl_byte& b)
+@cindex @code{ldb_test ()}
+Returns true if some bit described by the bit interval @code{b} is set in
+@code{n}.
+
+@item cl_I dpb (const cl_I& newbyte, const cl_I& n, const cl_byte& b)
+@cindex @code{dpb ()}
+Returns @code{n}, with the bits described by the bit interval @code{b}
+replaced by @code{newbyte}. Only the lowest @code{b.size} bits of
+@code{newbyte} are relevant.
+@end table
+
+The functions @code{ldb} and @code{dpb} implicitly shift. The following
+functions are their counterparts without shifting:
+
+@table @code
+@item cl_I mask_field (const cl_I& n, const cl_byte& b)
+@cindex @code{mask_field ()}
+returns an integer with the bits described by the bit interval @code{b}
+copied from the corresponding bits in @code{n}, the other bits zero.
+
+@item cl_I deposit_field (const cl_I& newbyte, const cl_I& n, const cl_byte& b)
+@cindex @code{deposit_field ()}
+returns an integer where the bits described by the bit interval @code{b}
+come from @code{newbyte} and the other bits come from @code{n}.
+@end table
+
+The following relations hold:
+
+@itemize @asis
+@item
+@code{ldb (n, b) = mask_field(n, b) >> b.position},
+@item
+@code{dpb (newbyte, n, b) = deposit_field (newbyte << b.position, n, b)},
+@item
+@code{deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^ mask_field(new_byte,b)}.
+@end itemize
+
+The following operations on integers as bit strings are efficient shortcuts
+for common arithmetic operations:
+
+@table @code
+@item bool oddp (const cl_I& x)
+@cindex @code{oddp ()}
+Returns true if the least significant bit of @code{x} is 1. Equivalent to
+@code{mod(x,2) != 0}.
+
+@item bool evenp (const cl_I& x)
+@cindex @code{evenp ()}
+Returns true if the least significant bit of @code{x} is 0. Equivalent to
+@code{mod(x,2) == 0}.
+
+@item cl_I operator << (const cl_I& x, const cl_I& n)
+@cindex @code{operator << ()}
+Shifts @code{x} by @code{n} bits to the left. @code{n} should be >=0.
+Equivalent to @code{x * expt(2,n)}.
+
+@item cl_I operator >> (const cl_I& x, const cl_I& n)
+@cindex @code{operator >> ()}
+Shifts @code{x} by @code{n} bits to the right. @code{n} should be >=0.
+Bits shifted out to the right are thrown away.
+Equivalent to @code{floor(x / expt(2,n))}.
+
+@item cl_I ash (const cl_I& x, const cl_I& y)
+@cindex @code{ash ()}
+Shifts @code{x} by @code{y} bits to the left (if @code{y}>=0) or
+by @code{-y} bits to the right (if @code{y}<=0). In other words, this
+returns @code{floor(x * expt(2,y))}.
+
+@item uintC integer_length (const cl_I& x)
+@cindex @code{integer_length ()}
+Returns the number of bits (excluding the sign bit) needed to represent @code{x}
+in two's complement notation. This is the smallest n >= 0 such that
+-2^n <= x < 2^n. If x > 0, this is the unique n > 0 such that
+2^(n-1) <= x < 2^n.
+
+@item uintC ord2 (const cl_I& x)
+@cindex @code{ord2 ()}
+@code{x} must be non-zero. This function returns the number of 0 bits at the
+right of @code{x} in two's complement notation. This is the largest n >= 0
+such that 2^n divides @code{x}.
+
+@item uintC power2p (const cl_I& x)
+@cindex @code{power2p ()}
+@code{x} must be > 0. This function checks whether @code{x} is a power of 2.
+If @code{x} = 2^(n-1), it returns n. Else it returns 0.
+(See also the function @code{logp}.)
+@end table
+
+
+@subsection Number theoretic functions
+
+@table @code
+@item uint32 gcd (unsigned long a, unsigned long b)
+@cindex @code{gcd ()}
+@itemx cl_I gcd (const cl_I& a, const cl_I& b)
+This function returns the greatest common divisor of @code{a} and @code{b},
+normalized to be >= 0.
+
+@item cl_I xgcd (const cl_I& a, const cl_I& b, cl_I* u, cl_I* v)
+@cindex @code{xgcd ()}
+This function (``extended gcd'') returns the greatest common divisor @code{g} of
+@code{a} and @code{b} and at the same time the representation of @code{g}
+as an integral linear combination of @code{a} and @code{b}:
+@code{u} and @code{v} with @code{u*a+v*b = g}, @code{g} >= 0.
+@code{u} and @code{v} will be normalized to be of smallest possible absolute
+value, in the following sense: If @code{a} and @code{b} are non-zero, and
+@code{abs(a) != abs(b)}, @code{u} and @code{v} will satisfy the inequalities
+@code{abs(u) <= abs(b)/(2*g)}, @code{abs(v) <= abs(a)/(2*g)}.
+
+@item cl_I lcm (const cl_I& a, const cl_I& b)
+@cindex @code{lcm ()}
+This function returns the least common multiple of @code{a} and @code{b},
+normalized to be >= 0.
+
+@item bool logp (const cl_I& a, const cl_I& b, cl_RA* l)
+@cindex @code{logp ()}
+@itemx bool logp (const cl_RA& a, const cl_RA& b, cl_RA* l)
+@code{a} must be > 0. @code{b} must be >0 and != 1. If log(a,b) is
+rational number, this function returns true and sets *l = log(a,b), else
+it returns false.
+
+@item int jacobi (signed long a, signed long b)
+@cindex @code{jacobi()}
+@itemx int jacobi (const cl_I& a, const cl_I& b)
+Returns the Jacobi symbol
+@tex
+$\left({a\over b}\right)$,
+@end tex
+@ifnottex
+(a/b),
+@end ifnottex
+@code{a,b} must be integers, @code{b>0} and odd. The result is 0
+iff gcd(a,b)>1.
+
+@item bool isprobprime (const cl_I& n)
+@cindex prime
+@cindex @code{isprobprime()}
+Returns true if @code{n} is a small prime or passes the Miller-Rabin
+primality test. The probability of a false positive is 1:10^30.
+
+@item cl_I nextprobprime (const cl_R& x)
+@cindex @code{nextprobprime()}
+Returns the smallest probable prime >=@code{x}.
+@end table
+
+
+@subsection Combinatorial functions
+
+@table @code
+@item cl_I factorial (uintL n)
+@cindex @code{factorial ()}
+@code{n} must be a small integer >= 0. This function returns the factorial
+@code{n}! = @code{1*2*@dots{}*n}.
+
+@item cl_I doublefactorial (uintL n)
+@cindex @code{doublefactorial ()}
+@code{n} must be a small integer >= 0. This function returns the
+doublefactorial @code{n}!! = @code{1*3*@dots{}*n} or
+@code{n}!! = @code{2*4*@dots{}*n}, respectively.
+
+@item cl_I binomial (uintL n, uintL k)
+@cindex @code{binomial ()}
+@code{n} and @code{k} must be small integers >= 0. This function returns the
+binomial coefficient
+@tex
+${n \choose k} = {n! \over n! (n-k)!}$
+@end tex
+@ifinfo
+(@code{n} choose @code{k}) = @code{n}! / @code{k}! @code{(n-k)}!
+@end ifinfo
+for 0 <= k <= n, 0 else.
+@end table
+
+
+@section Functions on floating-point numbers
+
+Recall that a floating-point number consists of a sign @code{s}, an
+exponent @code{e} and a mantissa @code{m}. The value of the number is
+@code{(-1)^s * 2^e * m}.
+
+Each of the classes
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines the following operations.
+
+@table @code
+@item @var{type} scale_float (const @var{type}& x, sintC delta)
+@cindex @code{scale_float ()}
+@itemx @var{type} scale_float (const @var{type}& x, const cl_I& delta)
+Returns @code{x*2^delta}. This is more efficient than an explicit multiplication
+because it copies @code{x} and modifies the exponent.
+@end table
+
+The following functions provide an abstract interface to the underlying
+representation of floating-point numbers.
+
+@table @code
+@item sintE float_exponent (const @var{type}& x)
+@cindex @code{float_exponent ()}
+Returns the exponent @code{e} of @code{x}.
+For @code{x = 0.0}, this is 0. For @code{x} non-zero, this is the unique
+integer with @code{2^(e-1) <= abs(x) < 2^e}.
+
+@item sintL float_radix (const @var{type}& x)
+@cindex @code{float_radix ()}
+Returns the base of the floating-point representation. This is always @code{2}.
+
+@item @var{type} float_sign (const @var{type}& x)
+@cindex @code{float_sign ()}
+Returns the sign @code{s} of @code{x} as a float. The value is 1 for
+@code{x} >= 0, -1 for @code{x} < 0.
+
+@item uintC float_digits (const @var{type}& x)
+@cindex @code{float_digits ()}
+Returns the number of mantissa bits in the floating-point representation
+of @code{x}, including the hidden bit. The value only depends on the type
+of @code{x}, not on its value.
+
+@item uintC float_precision (const @var{type}& x)
+@cindex @code{float_precision ()}
+Returns the number of significant mantissa bits in the floating-point
+representation of @code{x}. Since denormalized numbers are not supported,
+this is the same as @code{float_digits(x)} if @code{x} is non-zero, and
+0 if @code{x} = 0.
+@end table
+
+The complete internal representation of a float is encoded in the type
+@cindex @code{decoded_float}
+@cindex @code{decoded_sfloat}
+@cindex @code{decoded_ffloat}
+@cindex @code{decoded_dfloat}
+@cindex @code{decoded_lfloat}
+@code{decoded_float} (or @code{decoded_sfloat}, @code{decoded_ffloat},
+@code{decoded_dfloat}, @code{decoded_lfloat}, respectively), defined by
+@example
+struct decoded_@var{type}float @{
+ @var{type} mantissa; cl_I exponent; @var{type} sign;
+@};
+@end example
+
+and returned by the function
+
+@table @code
+@item decoded_@var{type}float decode_float (const @var{type}& x)
+@cindex @code{decode_float ()}
+For @code{x} non-zero, this returns @code{(-1)^s}, @code{e}, @code{m} with
+@code{x = (-1)^s * 2^e * m} and @code{0.5 <= m < 1.0}. For @code{x} = 0,
+it returns @code{(-1)^s}=1, @code{e}=0, @code{m}=0.
+@code{e} is the same as returned by the function @code{float_exponent}.
+@end table
+
+A complete decoding in terms of integers is provided as type
+@cindex @code{cl_idecoded_float}
+@example
+struct cl_idecoded_float @{
+ cl_I mantissa; cl_I exponent; cl_I sign;
+@};
+@end example
+by the following function:
+
+@table @code
+@item cl_idecoded_float integer_decode_float (const @var{type}& x)
+@cindex @code{integer_decode_float ()}
+For @code{x} non-zero, this returns @code{(-1)^s}, @code{e}, @code{m} with
+@code{x = (-1)^s * 2^e * m} and @code{m} an integer with @code{float_digits(x)}
+bits. For @code{x} = 0, it returns @code{(-1)^s}=1, @code{e}=0, @code{m}=0.
+WARNING: The exponent @code{e} is not the same as the one returned by
+the functions @code{decode_float} and @code{float_exponent}.
+@end table
+
+Some other function, implemented only for class @code{cl_F}:
+
+@table @code
+@item cl_F float_sign (const cl_F& x, const cl_F& y)
+@cindex @code{float_sign ()}
+This returns a floating point number whose precision and absolute value
+is that of @code{y} and whose sign is that of @code{x}. If @code{x} is
+zero, it is treated as positive. Same for @code{y}.
+@end table
+
+
+@section Conversion functions
+@cindex conversion
+
+@subsection Conversion to floating-point numbers
+
+The type @code{float_format_t} describes a floating-point format.
+@cindex @code{float_format_t}
+
+@table @code
+@item float_format_t float_format (uintE n)
+@cindex @code{float_format ()}
+Returns the smallest float format which guarantees at least @code{n}
+decimal digits in the mantissa (after the decimal point).
+
+@item float_format_t float_format (const cl_F& x)
+Returns the floating point format of @code{x}.
+
+@item float_format_t default_float_format
+@cindex @code{default_float_format}
+Global variable: the default float format used when converting rational numbers
+to floats.
+@end table
+
+To convert a real number to a float, each of the types
+@code{cl_R}, @code{cl_F}, @code{cl_I}, @code{cl_RA},
+@code{int}, @code{unsigned int}, @code{float}, @code{double}
+defines the following operations:
+
+@table @code
+@item cl_F cl_float (const @var{type}&x, float_format_t f)
+@cindex @code{cl_float ()}
+Returns @code{x} as a float of format @code{f}.
+@item cl_F cl_float (const @var{type}&x, const cl_F& y)
+Returns @code{x} in the float format of @code{y}.
+@item cl_F cl_float (const @var{type}&x)
+Returns @code{x} as a float of format @code{default_float_format} if
+it is an exact number, or @code{x} itself if it is already a float.
+@end table
+
+Of course, converting a number to a float can lose precision.
+
+Every floating-point format has some characteristic numbers:
+
+@table @code
+@item cl_F most_positive_float (float_format_t f)
+@cindex @code{most_positive_float ()}
+Returns the largest (most positive) floating point number in float format @code{f}.
+
+@item cl_F most_negative_float (float_format_t f)
+@cindex @code{most_negative_float ()}
+Returns the smallest (most negative) floating point number in float format @code{f}.
+
+@item cl_F least_positive_float (float_format_t f)
+@cindex @code{least_positive_float ()}
+Returns the least positive floating point number (i.e. > 0 but closest to 0)
+in float format @code{f}.
+
+@item cl_F least_negative_float (float_format_t f)
+@cindex @code{least_negative_float ()}
+Returns the least negative floating point number (i.e. < 0 but closest to 0)
+in float format @code{f}.
+
+@item cl_F float_epsilon (float_format_t f)
+@cindex @code{float_epsilon ()}
+Returns the smallest floating point number e > 0 such that @code{1+e != 1}.
+
+@item cl_F float_negative_epsilon (float_format_t f)
+@cindex @code{float_negative_epsilon ()}
+Returns the smallest floating point number e > 0 such that @code{1-e != 1}.
+@end table
+
+
+@subsection Conversion to rational numbers
+
+Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_F}
+defines the following operation:
+
+@table @code
+@item cl_RA rational (const @var{type}& x)
+@cindex @code{rational ()}
+Returns the value of @code{x} as an exact number. If @code{x} is already
+an exact number, this is @code{x}. If @code{x} is a floating-point number,
+the value is a rational number whose denominator is a power of 2.
+@end table
+
+In order to convert back, say, @code{(cl_F)(cl_R)"1/3"} to @code{1/3}, there is
+the function
+
+@table @code
+@item cl_RA rationalize (const cl_R& x)
+@cindex @code{rationalize ()}
+If @code{x} is a floating-point number, it actually represents an interval
+of real numbers, and this function returns the rational number with
+smallest denominator (and smallest numerator, in magnitude)
+which lies in this interval.
+If @code{x} is already an exact number, this function returns @code{x}.
+@end table
+
+If @code{x} is any float, one has
+
+@itemize @asis
+@item
+@code{cl_float(rational(x),x) = x}
+@item
+@code{cl_float(rationalize(x),x) = x}
+@end itemize
+
+
+@section Random number generators
+
+
+A random generator is a machine which produces (pseudo-)random numbers.
+The include file @code{<cln/random.h>} defines a class @code{random_state}
+which contains the state of a random generator. If you make a copy
+of the random number generator, the original one and the copy will produce
+the same sequence of random numbers.
+
+The following functions return (pseudo-)random numbers in different formats.
+Calling one of these modifies the state of the random number generator in
+a complicated but deterministic way.
+
+The global variable
+@cindex @code{random_state}
+@cindex @code{default_random_state}
+@example
+random_state default_random_state
+@end example
+contains a default random number generator. It is used when the functions
+below are called without @code{random_state} argument.
+
+@table @code
+@item uint32 random32 (random_state& randomstate)
+@itemx uint32 random32 ()
+@cindex @code{random32 ()}
+Returns a random unsigned 32-bit number. All bits are equally random.
+
+@item cl_I random_I (random_state& randomstate, const cl_I& n)
+@itemx cl_I random_I (const cl_I& n)
+@cindex @code{random_I ()}
+@code{n} must be an integer > 0. This function returns a random integer @code{x}
+in the range @code{0 <= x < n}.
+
+@item cl_F random_F (random_state& randomstate, const cl_F& n)
+@itemx cl_F random_F (const cl_F& n)
+@cindex @code{random_F ()}
+@code{n} must be a float > 0. This function returns a random floating-point
+number of the same format as @code{n} in the range @code{0 <= x < n}.
+
+@item cl_R random_R (random_state& randomstate, const cl_R& n)
+@itemx cl_R random_R (const cl_R& n)
+@cindex @code{random_R ()}
+Behaves like @code{random_I} if @code{n} is an integer and like @code{random_F}
+if @code{n} is a float.
+@end table
+
+
+@section Obfuscating operators
+@cindex modifying operators
+
+The modifying C/C++ operators @code{+=}, @code{-=}, @code{*=}, @code{/=},
+@code{&=}, @code{|=}, @code{^=}, @code{<<=}, @code{>>=}
+are not available by default because their
+use tends to make programs unreadable. It is trivial to get away without
+them. However, if you feel that you absolutely need these operators
+to get happy, then add
+@example
+#define WANT_OBFUSCATING_OPERATORS
+@end example
+@cindex @code{WANT_OBFUSCATING_OPERATORS}
+to the beginning of your source files, before the inclusion of any CLN
+include files. This flag will enable the following operators:
+
+For the classes @code{cl_N}, @code{cl_R}, @code{cl_RA},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}:
+
+@table @code
+@item @var{type}& operator += (@var{type}&, const @var{type}&)
+@cindex @code{operator += ()}
+@itemx @var{type}& operator -= (@var{type}&, const @var{type}&)
+@cindex @code{operator -= ()}
+@itemx @var{type}& operator *= (@var{type}&, const @var{type}&)
+@cindex @code{operator *= ()}
+@itemx @var{type}& operator /= (@var{type}&, const @var{type}&)
+@cindex @code{operator /= ()}
+@end table
+
+For the class @code{cl_I}:
+
+@table @code
+@item @var{type}& operator += (@var{type}&, const @var{type}&)
+@itemx @var{type}& operator -= (@var{type}&, const @var{type}&)
+@itemx @var{type}& operator *= (@var{type}&, const @var{type}&)
+@itemx @var{type}& operator &= (@var{type}&, const @var{type}&)
+@cindex @code{operator &= ()}
+@itemx @var{type}& operator |= (@var{type}&, const @var{type}&)
+@cindex @code{operator |= ()}
+@itemx @var{type}& operator ^= (@var{type}&, const @var{type}&)
+@cindex @code{operator ^= ()}
+@itemx @var{type}& operator <<= (@var{type}&, const @var{type}&)
+@cindex @code{operator <<= ()}
+@itemx @var{type}& operator >>= (@var{type}&, const @var{type}&)
+@cindex @code{operator >>= ()}
+@end table
+
+For the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}:
+
+@table @code
+@item @var{type}& operator ++ (@var{type}& x)
+@cindex @code{operator ++ ()}
+The prefix operator @code{++x}.
+
+@item void operator ++ (@var{type}& x, int)
+The postfix operator @code{x++}.
+
+@item @var{type}& operator -- (@var{type}& x)
+@cindex @code{operator -- ()}
+The prefix operator @code{--x}.
+
+@item void operator -- (@var{type}& x, int)
+The postfix operator @code{x--}.
+@end table
+
+Note that by using these obfuscating operators, you wouldn't gain efficiency:
+In CLN @samp{x += y;} is exactly the same as @samp{x = x+y;}, not more
+efficient.
+
+
+@chapter Input/Output
+@cindex Input/Output
+
+@section Internal and printed representation
+@cindex representation
+
+All computations deal with the internal representations of the numbers.
+
+Every number has an external representation as a sequence of ASCII characters.
+Several external representations may denote the same number, for example,
+"20.0" and "20.000".
+
+Converting an internal to an external representation is called ``printing'',
+@cindex printing
+converting an external to an internal representation is called ``reading''.
+@cindex reading
+In CLN, it is always true that conversion of an internal to an external
+representation and then back to an internal representation will yield the
+same internal representation. Symbolically: @code{read(print(x)) == x}.
+This is called ``print-read consistency''.
+
+Different types of numbers have different external representations (case
+is insignificant):
+
+@table @asis
+@item Integers
+External representation: @var{sign}@{@var{digit}@}+. The reader also accepts the
+Common Lisp syntaxes @var{sign}@{@var{digit}@}+@code{.} with a trailing dot
+for decimal integers
+and the @code{#@var{n}R}, @code{#b}, @code{#o}, @code{#x} prefixes.
+
+@item Rational numbers
+External representation: @var{sign}@{@var{digit}@}+@code{/}@{@var{digit}@}+.
+The @code{#@var{n}R}, @code{#b}, @code{#o}, @code{#x} prefixes are allowed
+here as well.
+
+@item Floating-point numbers
+External representation: @var{sign}@{@var{digit}@}*@var{exponent} or
+@var{sign}@{@var{digit}@}*@code{.}@{@var{digit}@}*@var{exponent} or
+@var{sign}@{@var{digit}@}*@code{.}@{@var{digit}@}+. A precision specifier
+of the form _@var{prec} may be appended. There must be at least
+one digit in the non-exponent part. The exponent has the syntax
+@var{expmarker} @var{expsign} @{@var{digit}@}+.
+The exponent marker is
+
+@itemize @asis
+@item
+@samp{s} for short-floats,
+@item
+@samp{f} for single-floats,
+@item
+@samp{d} for double-floats,
+@item
+@samp{L} for long-floats,
+@end itemize
+
+or @samp{e}, which denotes a default float format. The precision specifying
+suffix has the syntax _@var{prec} where @var{prec} denotes the number of
+valid mantissa digits (in decimal, excluding leading zeroes), cf. also
+function @samp{float_format}.
+
+@item Complex numbers
+External representation:
+@itemize @asis
+@item
+In algebraic notation: @code{@var{realpart}+@var{imagpart}i}. Of course,
+if @var{imagpart} is negative, its printed representation begins with
+a @samp{-}, and the @samp{+} between @var{realpart} and @var{imagpart}
+may be omitted. Note that this notation cannot be used when the @var{imagpart}
+is rational and the rational number's base is >18, because the @samp{i}
+is then read as a digit.
+@item
+In Common Lisp notation: @code{#C(@var{realpart} @var{imagpart})}.
+@end itemize
+@end table
+
+
+@section Input functions
+
+Including @code{<cln/io.h>} defines a number of simple input functions
+that read from @code{std::istream&}:
+
+@table @code
+@item int freadchar (std::istream& stream)
+Reads a character from @code{stream}. Returns @code{cl_EOF} (not a @samp{char}!)
+if the end of stream was encountered or an error occurred.
+
+@item int funreadchar (std::istream& stream, int c)
+Puts back @code{c} onto @code{stream}. @code{c} must be the result of the
+last @code{freadchar} operation on @code{stream}.
+@end table
+
+Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines, in @code{<cln/@var{type}_io.h>}, the following input function:
+
+@table @code
+@item std::istream& operator>> (std::istream& stream, @var{type}& result)
+Reads a number from @code{stream} and stores it in the @code{result}.
+@end table
+
+The most flexible input functions, defined in @code{<cln/@var{type}_io.h>},
+are the following:
+
+@table @code
+@item cl_N read_complex (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_R read_real (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_F read_float (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_RA read_rational (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_I read_integer (std::istream& stream, const cl_read_flags& flags)
+Reads a number from @code{stream}. The @code{flags} are parameters which
+affect the input syntax. Whitespace before the number is silently skipped.
+
+@item cl_N read_complex (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
+@itemx cl_R read_real (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
+@itemx cl_F read_float (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
+@itemx cl_RA read_rational (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
+@itemx cl_I read_integer (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
+Reads a number from a string in memory. The @code{flags} are parameters which
+affect the input syntax. The string starts at @code{string} and ends at
+@code{string_limit} (exclusive limit). @code{string_limit} may also be
+@code{NULL}, denoting the entire string, i.e. equivalent to
+@code{string_limit = string + strlen(string)}. If @code{end_of_parse} is
+@code{NULL}, the string in memory must contain exactly one number and nothing
+more, else an exception will be thrown. If @code{end_of_parse}
+is not @code{NULL}, @code{*end_of_parse} will be assigned a pointer past
+the last parsed character (i.e. @code{string_limit} if nothing came after
+the number). Whitespace is not allowed.
+@end table
+
+The structure @code{cl_read_flags} contains the following fields:
+
+@table @code
+@item cl_read_syntax_t syntax
+The possible results of the read operation. Possible values are
+@code{syntax_number}, @code{syntax_real}, @code{syntax_rational},
+@code{syntax_integer}, @code{syntax_float}, @code{syntax_sfloat},
+@code{syntax_ffloat}, @code{syntax_dfloat}, @code{syntax_lfloat}.
+
+@item cl_read_lsyntax_t lsyntax
+Specifies the language-dependent syntax variant for the read operation.
+Possible values are
+
+@table @code
+@item lsyntax_standard
+accept standard algebraic notation only, no complex numbers,
+@item lsyntax_algebraic
+accept the algebraic notation @code{@var{x}+@var{y}i} for complex numbers,
+@item lsyntax_commonlisp
+accept the @code{#b}, @code{#o}, @code{#x} syntaxes for binary, octal,
+hexadecimal numbers,
+@code{#@var{base}R} for rational numbers in a given base,
+@code{#c(@var{realpart} @var{imagpart})} for complex numbers,
+@item lsyntax_all
+accept all of these extensions.
+@end table
+
+@item unsigned int rational_base
+The base in which rational numbers are read.
+
+@item float_format_t float_flags.default_float_format
+The float format used when reading floats with exponent marker @samp{e}.
+
+@item float_format_t float_flags.default_lfloat_format
+The float format used when reading floats with exponent marker @samp{l}.
+
+@item bool float_flags.mantissa_dependent_float_format
+When this flag is true, floats specified with more digits than corresponding
+to the exponent marker they contain, but without @var{_nnn} suffix, will get a
+precision corresponding to their number of significant digits.
+@end table
+
+
+@section Output functions
+
+Including @code{<cln/io.h>} defines a number of simple output functions
+that write to @code{std::ostream&}:
+
+@table @code
+@item void fprintchar (std::ostream& stream, char c)
+Prints the character @code{x} literally on the @code{stream}.
+
+@item void fprint (std::ostream& stream, const char * string)
+Prints the @code{string} literally on the @code{stream}.
+
+@item void fprintdecimal (std::ostream& stream, int x)
+@itemx void fprintdecimal (std::ostream& stream, const cl_I& x)
+Prints the integer @code{x} in decimal on the @code{stream}.
+
+@item void fprintbinary (std::ostream& stream, const cl_I& x)
+Prints the integer @code{x} in binary (base 2, without prefix)
+on the @code{stream}.
+
+@item void fprintoctal (std::ostream& stream, const cl_I& x)
+Prints the integer @code{x} in octal (base 8, without prefix)
+on the @code{stream}.
+
+@item void fprinthexadecimal (std::ostream& stream, const cl_I& x)
+Prints the integer @code{x} in hexadecimal (base 16, without prefix)
+on the @code{stream}.
+@end table
+
+Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
+@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
+defines, in @code{<cln/@var{type}_io.h>}, the following output functions:
+
+@table @code
+@item void fprint (std::ostream& stream, const @var{type}& x)
+@itemx std::ostream& operator<< (std::ostream& stream, const @var{type}& x)
+Prints the number @code{x} on the @code{stream}. The output may depend
+on the global printer settings in the variable @code{default_print_flags}.
+The @code{ostream} flags and settings (flags, width and locale) are
+ignored.
+@end table
+
+The most flexible output function, defined in @code{<cln/@var{type}_io.h>},
+are the following:
+@example
+void print_complex (std::ostream& stream, const cl_print_flags& flags,
+ const cl_N& z);
+void print_real (std::ostream& stream, const cl_print_flags& flags,
+ const cl_R& z);
+void print_float (std::ostream& stream, const cl_print_flags& flags,
+ const cl_F& z);
+void print_rational (std::ostream& stream, const cl_print_flags& flags,
+ const cl_RA& z);
+void print_integer (std::ostream& stream, const cl_print_flags& flags,
+ const cl_I& z);
+@end example
+Prints the number @code{x} on the @code{stream}. The @code{flags} are
+parameters which affect the output.
+
+The structure type @code{cl_print_flags} contains the following fields:
+
+@table @code
+@item unsigned int rational_base
+The base in which rational numbers are printed. Default is @code{10}.
+
+@item bool rational_readably
+If this flag is true, rational numbers are printed with radix specifiers in
+Common Lisp syntax (@code{#@var{n}R} or @code{#b} or @code{#o} or @code{#x}
+prefixes, trailing dot). Default is false.
+
+@item bool float_readably
+If this flag is true, type specific exponent markers have precedence over 'E'.
+Default is false.
+
+@item float_format_t default_float_format
+Floating point numbers of this format will be printed using the 'E' exponent
+marker. Default is @code{float_format_ffloat}.
+
+@item bool complex_readably
+If this flag is true, complex numbers will be printed using the Common Lisp
+syntax @code{#C(@var{realpart} @var{imagpart})}. Default is false.
+
+@item cl_string univpoly_varname
+Univariate polynomials with no explicit indeterminate name will be printed
+using this variable name. Default is @code{"x"}.
+@end table
+
+The global variable @code{default_print_flags} contains the default values,
+used by the function @code{fprint}.
+
+
+@chapter Rings
+
+CLN has a class of abstract rings.
+
+@example
+ Ring
+ cl_ring
+ <cln/ring.h>
+@end example
+
+Rings can be compared for equality:
+
+@table @code
+@item bool operator== (const cl_ring&, const cl_ring&)
+@itemx bool operator!= (const cl_ring&, const cl_ring&)
+These compare two rings for equality.
+@end table
+
+Given a ring @code{R}, the following members can be used.
+
+@table @code
+@item void R->fprint (std::ostream& stream, const cl_ring_element& x)
+@cindex @code{fprint ()}
+@itemx bool R->equal (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{equal ()}
+@itemx cl_ring_element R->zero ()
+@cindex @code{zero ()}
+@itemx bool R->zerop (const cl_ring_element& x)
+@cindex @code{zerop ()}
+@itemx cl_ring_element R->plus (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{plus ()}
+@itemx cl_ring_element R->minus (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{minus ()}
+@itemx cl_ring_element R->uminus (const cl_ring_element& x)
+@cindex @code{uminus ()}
+@itemx cl_ring_element R->one ()
+@cindex @code{one ()}
+@itemx cl_ring_element R->canonhom (const cl_I& x)
+@cindex @code{canonhom ()}
+@itemx cl_ring_element R->mul (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{mul ()}
+@itemx cl_ring_element R->square (const cl_ring_element& x)
+@cindex @code{square ()}
+@itemx cl_ring_element R->expt_pos (const cl_ring_element& x, const cl_I& y)
+@cindex @code{expt_pos ()}
+@end table
+
+The following rings are built-in.
+
+@table @code
+@item cl_null_ring cl_0_ring
+The null ring, containing only zero.
+
+@item cl_complex_ring cl_C_ring
+The ring of complex numbers. This corresponds to the type @code{cl_N}.
+
+@item cl_real_ring cl_R_ring
+The ring of real numbers. This corresponds to the type @code{cl_R}.
+
+@item cl_rational_ring cl_RA_ring
+The ring of rational numbers. This corresponds to the type @code{cl_RA}.
+
+@item cl_integer_ring cl_I_ring
+The ring of integers. This corresponds to the type @code{cl_I}.
+@end table
+
+Type tests can be performed for any of @code{cl_C_ring}, @code{cl_R_ring},
+@code{cl_RA_ring}, @code{cl_I_ring}:
+
+@table @code
+@item bool instanceof (const cl_number& x, const cl_number_ring& R)
+@cindex @code{instanceof ()}
+Tests whether the given number is an element of the number ring R.
+@end table
+
+
+@chapter Modular integers
+@cindex modular integer
+
+@section Modular integer rings
+@cindex ring
+
+CLN implements modular integers, i.e. integers modulo a fixed integer N.
+The modulus is explicitly part of every modular integer. CLN doesn't
+allow you to (accidentally) mix elements of different modular rings,
+e.g. @code{(3 mod 4) + (2 mod 5)} will result in a runtime error.
+(Ideally one would imagine a generic data type @code{cl_MI(N)}, but C++
+doesn't have generic types. So one has to live with runtime checks.)
+
+The class of modular integer rings is
+
+@example
+ Ring
+ cl_ring
+ <cln/ring.h>
+ |
+ |
+ Modular integer ring
+ cl_modint_ring
+ <cln/modinteger.h>
+@end example
+@cindex @code{cl_modint_ring}
+
+and the class of all modular integers (elements of modular integer rings) is
+
+@example
+ Modular integer
+ cl_MI
+ <cln/modinteger.h>
+@end example
+
+Modular integer rings are constructed using the function
+
+@table @code
+@item cl_modint_ring find_modint_ring (const cl_I& N)
+@cindex @code{find_modint_ring ()}
+This function returns the modular ring @samp{Z/NZ}. It takes care
+of finding out about special cases of @code{N}, like powers of two
+and odd numbers for which Montgomery multiplication will be a win,
+@cindex Montgomery multiplication
+and precomputes any necessary auxiliary data for computing modulo @code{N}.
+There is a cache table of rings, indexed by @code{N} (or, more precisely,
+by @code{abs(N)}). This ensures that the precomputation costs are reduced
+to a minimum.
+@end table
+
+Modular integer rings can be compared for equality:
+
+@table @code
+@item bool operator== (const cl_modint_ring&, const cl_modint_ring&)
+@cindex @code{operator == ()}
+@itemx bool operator!= (const cl_modint_ring&, const cl_modint_ring&)
+@cindex @code{operator != ()}
+These compare two modular integer rings for equality. Two different calls
+to @code{find_modint_ring} with the same argument necessarily return the
+same ring because it is memoized in the cache table.
+@end table
+
+@section Functions on modular integers
+
+Given a modular integer ring @code{R}, the following members can be used.
+
+@table @code
+@item cl_I R->modulus
+@cindex @code{modulus}
+This is the ring's modulus, normalized to be nonnegative: @code{abs(N)}.
+
+@item cl_MI R->zero()
+@cindex @code{zero ()}
+This returns @code{0 mod N}.
+
+@item cl_MI R->one()
+@cindex @code{one ()}
+This returns @code{1 mod N}.
+
+@item cl_MI R->canonhom (const cl_I& x)
+@cindex @code{canonhom ()}
+This returns @code{x mod N}.
+
+@item cl_I R->retract (const cl_MI& x)
+@cindex @code{retract ()}
+This is a partial inverse function to @code{R->canonhom}. It returns the
+standard representative (@code{>=0}, @code{<N}) of @code{x}.
+
+@item cl_MI R->random(random_state& randomstate)
+@itemx cl_MI R->random()
+@cindex @code{random ()}
+This returns a random integer modulo @code{N}.
+@end table
+
+The following operations are defined on modular integers.
+
+@table @code
+@item cl_modint_ring x.ring ()
+@cindex @code{ring ()}
+Returns the ring to which the modular integer @code{x} belongs.
+
+@item cl_MI operator+ (const cl_MI&, const cl_MI&)
+@cindex @code{operator + ()}
+Returns the sum of two modular integers. One of the arguments may also
+be a plain integer.
+
+@item cl_MI operator- (const cl_MI&, const cl_MI&)
+@cindex @code{operator - ()}
+Returns the difference of two modular integers. One of the arguments may also
+be a plain integer.
+
+@item cl_MI operator- (const cl_MI&)
+Returns the negative of a modular integer.
+
+@item cl_MI operator* (const cl_MI&, const cl_MI&)
+@cindex @code{operator * ()}
+Returns the product of two modular integers. One of the arguments may also
+be a plain integer.
+
+@item cl_MI square (const cl_MI&)
+@cindex @code{square ()}
+Returns the square of a modular integer.
+
+@item cl_MI recip (const cl_MI& x)
+@cindex @code{recip ()}
+Returns the reciprocal @code{x^-1} of a modular integer @code{x}. @code{x}
+must be coprime to the modulus, otherwise an error message is issued.
+
+@item cl_MI div (const cl_MI& x, const cl_MI& y)
+@cindex @code{div ()}
+Returns the quotient @code{x*y^-1} of two modular integers @code{x}, @code{y}.
+@code{y} must be coprime to the modulus, otherwise an error message is issued.
+
+@item cl_MI expt_pos (const cl_MI& x, const cl_I& y)
+@cindex @code{expt_pos ()}
+@code{y} must be > 0. Returns @code{x^y}.
+
+@item cl_MI expt (const cl_MI& x, const cl_I& y)
+@cindex @code{expt ()}
+Returns @code{x^y}. If @code{y} is negative, @code{x} must be coprime to the
+modulus, else an error message is issued.
+
+@item cl_MI operator<< (const cl_MI& x, const cl_I& y)
+@cindex @code{operator << ()}
+Returns @code{x*2^y}.
+
+@item cl_MI operator>> (const cl_MI& x, const cl_I& y)
+@cindex @code{operator >> ()}
+Returns @code{x*2^-y}. When @code{y} is positive, the modulus must be odd,
+or an error message is issued.
+
+@item bool operator== (const cl_MI&, const cl_MI&)
+@cindex @code{operator == ()}
+@itemx bool operator!= (const cl_MI&, const cl_MI&)
+@cindex @code{operator != ()}
+Compares two modular integers, belonging to the same modular integer ring,
+for equality.
+
+@item bool zerop (const cl_MI& x)
+@cindex @code{zerop ()}
+Returns true if @code{x} is @code{0 mod N}.
+@end table
+
+The following output functions are defined (see also the chapter on
+input/output).
+
+@table @code
+@item void fprint (std::ostream& stream, const cl_MI& x)
+@cindex @code{fprint ()}
+@itemx std::ostream& operator<< (std::ostream& stream, const cl_MI& x)
+@cindex @code{operator << ()}
+Prints the modular integer @code{x} on the @code{stream}. The output may depend
+on the global printer settings in the variable @code{default_print_flags}.
+@end table
+
+
+@chapter Symbolic data types
+@cindex symbolic type
+
+CLN implements two symbolic (non-numeric) data types: strings and symbols.
+
+@section Strings
+@cindex string
+@cindex @code{cl_string}
+
+The class
+
+@example
+ String
+ cl_string
+ <cln/string.h>
+@end example
+
+implements immutable strings.
+
+Strings are constructed through the following constructors:
+
+@table @code
+@item cl_string (const char * s)
+Returns an immutable copy of the (zero-terminated) C string @code{s}.
+
+@item cl_string (const char * ptr, unsigned long len)
+Returns an immutable copy of the @code{len} characters at
+@code{ptr[0]}, @dots{}, @code{ptr[len-1]}. NUL characters are allowed.
+@end table
+
+The following functions are available on strings:
+
+@table @code
+@item operator =
+Assignment from @code{cl_string} and @code{const char *}.
+
+@item s.length()
+@cindex @code{length ()}
+@itemx strlen(s)
+@cindex @code{strlen ()}
+Returns the length of the string @code{s}.
+
+@item s[i]
+@cindex @code{operator [] ()}
+Returns the @code{i}th character of the string @code{s}.
+@code{i} must be in the range @code{0 <= i < s.length()}.
+
+@item bool equal (const cl_string& s1, const cl_string& s2)
+@cindex @code{equal ()}
+Compares two strings for equality. One of the arguments may also be a
+plain @code{const char *}.
+@end table
+
+@section Symbols
+@cindex symbol
+@cindex @code{cl_symbol}
+
+Symbols are uniquified strings: all symbols with the same name are shared.
+This means that comparison of two symbols is fast (effectively just a pointer
+comparison), whereas comparison of two strings must in the worst case walk
+both strings until their end.
+Symbols are used, for example, as tags for properties, as names of variables
+in polynomial rings, etc.
+
+Symbols are constructed through the following constructor:
+
+@table @code
+@item cl_symbol (const cl_string& s)
+Looks up or creates a new symbol with a given name.
+@end table
+
+The following operations are available on symbols:
+
+@table @code
+@item cl_string (const cl_symbol& sym)
+Conversion to @code{cl_string}: Returns the string which names the symbol
+@code{sym}.
+
+@item bool equal (const cl_symbol& sym1, const cl_symbol& sym2)
+@cindex @code{equal ()}
+Compares two symbols for equality. This is very fast.
+@end table
+
+
+@chapter Univariate polynomials
+@cindex polynomial
+@cindex univariate polynomial
+
+@section Univariate polynomial rings
+
+CLN implements univariate polynomials (polynomials in one variable) over an
+arbitrary ring. The indeterminate variable may be either unnamed (and will be
+printed according to @code{default_print_flags.univpoly_varname}, which
+defaults to @samp{x}) or carry a given name. The base ring and the
+indeterminate are explicitly part of every polynomial. CLN doesn't allow you to
+(accidentally) mix elements of different polynomial rings, e.g.
+@code{(a^2+1) * (b^3-1)} will result in a runtime error. (Ideally this should
+return a multivariate polynomial, but they are not yet implemented in CLN.)
+
+The classes of univariate polynomial rings are
+
+@example
+ Ring
+ cl_ring
+ <cln/ring.h>
+ |
+ |
+ Univariate polynomial ring
+ cl_univpoly_ring
+ <cln/univpoly.h>
+ |
+ +----------------+-------------------+
+ | | |
+ Complex polynomial ring | Modular integer polynomial ring
+ cl_univpoly_complex_ring | cl_univpoly_modint_ring
+ <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
+ |
+ +----------------+
+ | |
+ Real polynomial ring |
+ cl_univpoly_real_ring |
+ <cln/univpoly_real.h> |
+ |
+ +----------------+
+ | |
+ Rational polynomial ring |
+ cl_univpoly_rational_ring |
+ <cln/univpoly_rational.h> |
+ |
+ +----------------+
+ |
+ Integer polynomial ring
+ cl_univpoly_integer_ring
+ <cln/univpoly_integer.h>
+@end example
+
+and the corresponding classes of univariate polynomials are
+
+@example
+ Univariate polynomial
+ cl_UP
+ <cln/univpoly.h>
+ |
+ +----------------+-------------------+
+ | | |
+ Complex polynomial | Modular integer polynomial
+ cl_UP_N | cl_UP_MI
+ <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
+ |
+ +----------------+
+ | |
+ Real polynomial |
+ cl_UP_R |
+ <cln/univpoly_real.h> |
+ |
+ +----------------+
+ | |
+ Rational polynomial |
+ cl_UP_RA |
+ <cln/univpoly_rational.h> |
+ |
+ +----------------+
+ |
+ Integer polynomial
+ cl_UP_I
+ <cln/univpoly_integer.h>
+@end example
+
+Univariate polynomial rings are constructed using the functions
+
+@table @code
+@item cl_univpoly_ring find_univpoly_ring (const cl_ring& R)
+@itemx cl_univpoly_ring find_univpoly_ring (const cl_ring& R, const cl_symbol& varname)
+This function returns the polynomial ring @samp{R[X]}, unnamed or named.
+@code{R} may be an arbitrary ring. This function takes care of finding out
+about special cases of @code{R}, such as the rings of complex numbers,
+real numbers, rational numbers, integers, or modular integer rings.
+There is a cache table of rings, indexed by @code{R} and @code{varname}.
+This ensures that two calls of this function with the same arguments will
+return the same polynomial ring.
+
+@itemx cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R)
+@cindex @code{find_univpoly_ring ()}
+@itemx cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)
+@itemx cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R)
+@itemx cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)
+@itemx cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R)
+@itemx cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)
+@itemx cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R)
+@itemx cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)
+@itemx cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R)
+@itemx cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname)
+These functions are equivalent to the general @code{find_univpoly_ring},
+only the return type is more specific, according to the base ring's type.
+@end table
+
+@section Functions on univariate polynomials
+
+Given a univariate polynomial ring @code{R}, the following members can be used.
+
+@table @code
+@item cl_ring R->basering()
+@cindex @code{basering ()}
+This returns the base ring, as passed to @samp{find_univpoly_ring}.
+
+@item cl_UP R->zero()
+@cindex @code{zero ()}
+This returns @code{0 in R}, a polynomial of degree -1.
+
+@item cl_UP R->one()
+@cindex @code{one ()}
+This returns @code{1 in R}, a polynomial of degree == 0.
+
+@item cl_UP R->canonhom (const cl_I& x)
+@cindex @code{canonhom ()}
+This returns @code{x in R}, a polynomial of degree <= 0.
+
+@item cl_UP R->monomial (const cl_ring_element& x, uintL e)
+@cindex @code{monomial ()}
+This returns a sparse polynomial: @code{x * X^e}, where @code{X} is the
+indeterminate.
+
+@item cl_UP R->create (sintL degree)
+@cindex @code{create ()}
+Creates a new polynomial with a given degree. The zero polynomial has degree
+@code{-1}. After creating the polynomial, you should put in the coefficients,
+using the @code{set_coeff} member function, and then call the @code{finalize}
+member function.
+@end table
+
+The following are the only destructive operations on univariate polynomials.
+
+@table @code
+@item void set_coeff (cl_UP& x, uintL index, const cl_ring_element& y)
+@cindex @code{set_coeff ()}
+This changes the coefficient of @code{X^index} in @code{x} to be @code{y}.
+After changing a polynomial and before applying any "normal" operation on it,
+you should call its @code{finalize} member function.
+
+@item void finalize (cl_UP& x)
+@cindex @code{finalize ()}
+This function marks the endpoint of destructive modifications of a polynomial.
+It normalizes the internal representation so that subsequent computations have
+less overhead. Doing normal computations on unnormalized polynomials may
+produce wrong results or crash the program.
+@end table
+
+The following operations are defined on univariate polynomials.
+
+@table @code
+@item cl_univpoly_ring x.ring ()
+@cindex @code{ring ()}
+Returns the ring to which the univariate polynomial @code{x} belongs.
+
+@item cl_UP operator+ (const cl_UP&, const cl_UP&)
+@cindex @code{operator + ()}
+Returns the sum of two univariate polynomials.
+
+@item cl_UP operator- (const cl_UP&, const cl_UP&)
+@cindex @code{operator - ()}
+Returns the difference of two univariate polynomials.
+
+@item cl_UP operator- (const cl_UP&)
+Returns the negative of a univariate polynomial.
+
+@item cl_UP operator* (const cl_UP&, const cl_UP&)
+@cindex @code{operator * ()}
+Returns the product of two univariate polynomials. One of the arguments may
+also be a plain integer or an element of the base ring.
+
+@item cl_UP square (const cl_UP&)
+@cindex @code{square ()}
+Returns the square of a univariate polynomial.
+
+@item cl_UP expt_pos (const cl_UP& x, const cl_I& y)
+@cindex @code{expt_pos ()}
+@code{y} must be > 0. Returns @code{x^y}.
+
+@item bool operator== (const cl_UP&, const cl_UP&)
+@cindex @code{operator == ()}
+@itemx bool operator!= (const cl_UP&, const cl_UP&)
+@cindex @code{operator != ()}
+Compares two univariate polynomials, belonging to the same univariate
+polynomial ring, for equality.
+
+@item bool zerop (const cl_UP& x)
+@cindex @code{zerop ()}
+Returns true if @code{x} is @code{0 in R}.
+
+@item sintL degree (const cl_UP& x)
+@cindex @code{degree ()}
+Returns the degree of the polynomial. The zero polynomial has degree @code{-1}.
+
+@item sintL ldegree (const cl_UP& x)
+@cindex @code{degree ()}
+Returns the low degree of the polynomial. This is the degree of the first
+non-vanishing polynomial coefficient. The zero polynomial has ldegree @code{-1}.
+
+@item cl_ring_element coeff (const cl_UP& x, uintL index)
+@cindex @code{coeff ()}
+Returns the coefficient of @code{X^index} in the polynomial @code{x}.
+
+@item cl_ring_element x (const cl_ring_element& y)
+@cindex @code{operator () ()}
+Evaluation: If @code{x} is a polynomial and @code{y} belongs to the base ring,
+then @samp{x(y)} returns the value of the substitution of @code{y} into
+@code{x}.
+
+@item cl_UP deriv (const cl_UP& x)
+@cindex @code{deriv ()}
+Returns the derivative of the polynomial @code{x} with respect to the
+indeterminate @code{X}.
+@end table
+
+The following output functions are defined (see also the chapter on
+input/output).
+
+@table @code
+@item void fprint (std::ostream& stream, const cl_UP& x)
+@cindex @code{fprint ()}
+@itemx std::ostream& operator<< (std::ostream& stream, const cl_UP& x)
+@cindex @code{operator << ()}
+Prints the univariate polynomial @code{x} on the @code{stream}. The output may
+depend on the global printer settings in the variable
+@code{default_print_flags}.
+@end table
+
+@section Special polynomials
+
+The following functions return special polynomials.
+
+@table @code
+@item cl_UP_I tschebychev (sintL n)
+@cindex @code{tschebychev ()}
+@cindex Chebyshev polynomial
+Returns the n-th Chebyshev polynomial (n >= 0).
+
+@item cl_UP_I hermite (sintL n)
+@cindex @code{hermite ()}
+@cindex Hermite polynomial
+Returns the n-th Hermite polynomial (n >= 0).
+
+@item cl_UP_RA legendre (sintL n)
+@cindex @code{legendre ()}
+@cindex Legende polynomial
+Returns the n-th Legendre polynomial (n >= 0).
+
+@item cl_UP_I laguerre (sintL n)
+@cindex @code{laguerre ()}
+@cindex Laguerre polynomial
+Returns the n-th Laguerre polynomial (n >= 0).
+@end table
+
+Information how to derive the differential equation satisfied by each
+of these polynomials from their definition can be found in the
+@code{doc/polynomial/} directory.
+
+
+@chapter Internals
+
+@section Why C++ ?
+@cindex advocacy
+
+Using C++ as an implementation language provides
+
+@itemize @bullet
+@item
+Efficiency: It compiles to machine code.
+
+@item
+@cindex portability
+Portability: It runs on all platforms supporting a C++ compiler. Because
+of the availability of GNU C++, this includes all currently used 32-bit and
+64-bit platforms, independently of the quality of the vendor's C++ compiler.
+
+@item
+Type safety: The C++ compilers knows about the number types and complains if,
+for example, you try to assign a float to an integer variable. However,
+a drawback is that C++ doesn't know about generic types, hence a restriction
+like that @code{operator+ (const cl_MI&, const cl_MI&)} requires that both
+arguments belong to the same modular ring cannot be expressed as a compile-time
+information.
+
+@item
+Algebraic syntax: The elementary operations @code{+}, @code{-}, @code{*},
+@code{=}, @code{==}, ... can be used in infix notation, which is more
+convenient than Lisp notation @samp{(+ x y)} or C notation @samp{add(x,y,&z)}.
+@end itemize
+
+With these language features, there is no need for two separate languages,
+one for the implementation of the library and one in which the library's users
+can program. This means that a prototype implementation of an algorithm
+can be integrated into the library immediately after it has been tested and
+debugged. No need to rewrite it in a low-level language after having prototyped
+in a high-level language.
+
+
+@section Memory efficiency
+
+In order to save memory allocations, CLN implements:
+
+@itemize @bullet
+@item
+Object sharing: An operation like @code{x+0} returns @code{x} without copying
+it.
+@item
+@cindex garbage collection
+@cindex reference counting
+Garbage collection: A reference counting mechanism makes sure that any
+number object's storage is freed immediately when the last reference to the
+object is gone.
+@item
+@cindex immediate numbers
+Small integers are represented as immediate values instead of pointers
+to heap allocated storage. This means that integers @code{>= -2^29},
+@code{< 2^29} don't consume heap memory, unless they were explicitly allocated
+on the heap.
+@end itemize
+
+
+@section Speed efficiency
+
+Speed efficiency is obtained by the combination of the following tricks
+and algorithms:
+
+@itemize @bullet
+@item
+Small integers, being represented as immediate values, don't require
+memory access, just a couple of instructions for each elementary operation.
+@item
+The kernel of CLN has been written in assembly language for some CPUs
+(@code{i386}, @code{m68k}, @code{sparc}, @code{mips}, @code{arm}).
+@item
+On all CPUs, CLN may be configured to use the superefficient low-level
+routines from GNU GMP version 3.
+@item
+For large numbers, CLN uses, instead of the standard @code{O(N^2)}
+algorithm, the Karatsuba multiplication, which is an
+@iftex
+@tex
+$O(N^{1.6})$
+@end tex
+@end iftex
+@ifinfo
+@code{O(N^1.6)}
+@end ifinfo
+algorithm.
+@item
+For very large numbers (more than 12000 decimal digits), CLN uses
+@iftex
+Sch{@"o}nhage-Strassen
+@cindex Sch{@"o}nhage-Strassen multiplication
+@end iftex
+@ifinfo
+Schoenhage-Strassen
+@cindex Schoenhage-Strassen multiplication
+@end ifinfo
+multiplication, which is an asymptotically optimal multiplication
+algorithm.
+@item
+These fast multiplication algorithms also give improvements in the speed
+of division and radix conversion.
+@end itemize
+
+
+@section Garbage collection
+@cindex garbage collection
+
+All the number classes are reference count classes: They only contain a pointer
+to an object in the heap. Upon construction, assignment and destruction of
+number objects, only the objects' reference count are manipulated.
+
+Memory occupied by number objects are automatically reclaimed as soon as
+their reference count drops to zero.
+
+For number rings, another strategy is implemented: There is a cache of,
+for example, the modular integer rings. A modular integer ring is destroyed
+only if its reference count dropped to zero and the cache is about to be
+resized. The effect of this strategy is that recently used rings remain
+cached, whereas undue memory consumption through cached rings is avoided.
+
+
+@chapter Using the library
+
+For the following discussion, we will assume that you have installed
+the CLN source in @code{$CLN_DIR} and built it in @code{$CLN_TARGETDIR}.
+For example, for me it's @code{CLN_DIR="$HOME/cln"} and
+@code{CLN_TARGETDIR="$HOME/cln/linuxelf"}. You might define these as
+environment variables, or directly substitute the appropriate values.
+
+
+@section Compiler options
+@cindex compiler options
+
+Until you have installed CLN in a public place, the following options are
+needed:
+
+When you compile CLN application code, add the flags
+@example
+ -I$CLN_DIR/include -I$CLN_TARGETDIR/include
+@end example
+to the C++ compiler's command line (@code{make} variable CFLAGS or CXXFLAGS).
+When you link CLN application code to form an executable, add the flags
+@example
+ $CLN_TARGETDIR/src/libcln.a
+@end example
+to the C/C++ compiler's command line (@code{make} variable LIBS).
+
+If you did a @code{make install}, the include files are installed in a
+public directory (normally @code{/usr/local/include}), hence you don't
+need special flags for compiling. The library has been installed to a
+public directory as well (normally @code{/usr/local/lib}), hence when
+linking a CLN application it is sufficient to give the flag @code{-lcln}.
+
+@cindex @code{pkg-config}
+To make the creation of software packages that use CLN easier, the
+@code{pkg-config} utility can be used. CLN provides all the necessary
+metainformation in a file called @code{cln.pc} (installed in
+@code{/usr/local/lib/pkgconfig} by default). A program using CLN can
+be compiled and linked using @footnote{If you installed CLN to
+non-standard location @var{prefix}, you need to set the
+@env{PKG_CONFIG_PATH} environment variable to @var{prefix}/lib/pkgconfig
+for this to work.}
+@example
+g++ `pkg-config --libs cln` `pkg-config --cflags cln` prog.cc -o prog
+@end example
+
+Software using GNU autoconf can check for CLN with the
+@code{PKG_CHECK_MODULES} macro supplied with @code{pkg-config}.
+@example
+PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}])
+@end example
+This will check for CLN version at least @var{MIN-VERSION}. If the
+required version was found, the variables @var{CLN_CFLAGS} and
+@var{CLN_LIBS} are set. Otherwise the configure script aborts. If this
+is not the desired behaviour, use the following code instead
+@footnote{See the @code{pkg-config} documentation for more details.}
+@example
+PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}], [],
+ [AC_MSG_WARNING([No suitable version of CLN can be found])])
+@end example
+
+
+@section Include files
+@cindex include files
+@cindex header files
+
+Here is a summary of the include files and their contents.
+
+@table @code
+@item <cln/object.h>
+General definitions, reference counting, garbage collection.
+@item <cln/number.h>
+The class cl_number.
+@item <cln/complex.h>
+Functions for class cl_N, the complex numbers.
+@item <cln/real.h>
+Functions for class cl_R, the real numbers.
+@item <cln/float.h>
+Functions for class cl_F, the floats.
+@item <cln/sfloat.h>
+Functions for class cl_SF, the short-floats.
+@item <cln/ffloat.h>
+Functions for class cl_FF, the single-floats.
+@item <cln/dfloat.h>
+Functions for class cl_DF, the double-floats.
+@item <cln/lfloat.h>
+Functions for class cl_LF, the long-floats.
+@item <cln/rational.h>
+Functions for class cl_RA, the rational numbers.
+@item <cln/integer.h>
+Functions for class cl_I, the integers.
+@item <cln/io.h>
+Input/Output.
+@item <cln/complex_io.h>
+Input/Output for class cl_N, the complex numbers.
+@item <cln/real_io.h>
+Input/Output for class cl_R, the real numbers.
+@item <cln/float_io.h>
+Input/Output for class cl_F, the floats.
+@item <cln/sfloat_io.h>
+Input/Output for class cl_SF, the short-floats.
+@item <cln/ffloat_io.h>
+Input/Output for class cl_FF, the single-floats.
+@item <cln/dfloat_io.h>
+Input/Output for class cl_DF, the double-floats.
+@item <cln/lfloat_io.h>
+Input/Output for class cl_LF, the long-floats.
+@item <cln/rational_io.h>
+Input/Output for class cl_RA, the rational numbers.
+@item <cln/integer_io.h>
+Input/Output for class cl_I, the integers.
+@item <cln/input.h>
+Flags for customizing input operations.
+@item <cln/output.h>
+Flags for customizing output operations.
+@item <cln/malloc.h>
+@code{malloc_hook}, @code{free_hook}.
+@item <cln/exception.h>
+Exception base class.
+@item <cln/condition.h>
+Conditions.
+@item <cln/string.h>
+Strings.
+@item <cln/symbol.h>
+Symbols.
+@item <cln/proplist.h>
+Property lists.
+@item <cln/ring.h>
+General rings.
+@item <cln/null_ring.h>
+The null ring.
+@item <cln/complex_ring.h>
+The ring of complex numbers.
+@item <cln/real_ring.h>
+The ring of real numbers.
+@item <cln/rational_ring.h>
+The ring of rational numbers.
+@item <cln/integer_ring.h>
+The ring of integers.
+@item <cln/numtheory.h>
+Number threory functions.
+@item <cln/modinteger.h>
+Modular integers.
+@item <cln/V.h>
+Vectors.
+@item <cln/GV.h>
+General vectors.
+@item <cln/GV_number.h>
+General vectors over cl_number.
+@item <cln/GV_complex.h>
+General vectors over cl_N.
+@item <cln/GV_real.h>
+General vectors over cl_R.
+@item <cln/GV_rational.h>
+General vectors over cl_RA.
+@item <cln/GV_integer.h>
+General vectors over cl_I.
+@item <cln/GV_modinteger.h>
+General vectors of modular integers.
+@item <cln/SV.h>
+Simple vectors.
+@item <cln/SV_number.h>
+Simple vectors over cl_number.
+@item <cln/SV_complex.h>
+Simple vectors over cl_N.
+@item <cln/SV_real.h>
+Simple vectors over cl_R.
+@item <cln/SV_rational.h>
+Simple vectors over cl_RA.
+@item <cln/SV_integer.h>
+Simple vectors over cl_I.
+@item <cln/SV_ringelt.h>
+Simple vectors of general ring elements.
+@item <cln/univpoly.h>
+Univariate polynomials.
+@item <cln/univpoly_integer.h>
+Univariate polynomials over the integers.
+@item <cln/univpoly_rational.h>
+Univariate polynomials over the rational numbers.
+@item <cln/univpoly_real.h>
+Univariate polynomials over the real numbers.
+@item <cln/univpoly_complex.h>
+Univariate polynomials over the complex numbers.
+@item <cln/univpoly_modint.h>
+Univariate polynomials over modular integer rings.
+@item <cln/timing.h>
+Timing facilities.
+@item <cln/cln.h>
+Includes all of the above.
+@end table
+
+
+@section An Example
+
+A function which computes the nth Fibonacci number can be written as follows.
+@cindex Fibonacci number
+
+@example
+#include <cln/integer.h>
+#include <cln/real.h>
+using namespace cln;
+
+// Returns F_n, computed as the nearest integer to
+// ((1+sqrt(5))/2)^n/sqrt(5). Assume n>=0.
+const cl_I fibonacci (int n)
+@{
+ // Need a precision of ((1+sqrt(5))/2)^-n.
+ float_format_t prec = float_format((int)(0.208987641*n+5));
+ cl_R sqrt5 = sqrt(cl_float(5,prec));
+ cl_R phi = (1+sqrt5)/2;
+ return round1( expt(phi,n)/sqrt5 );
+@}
+@end example
+
+Let's explain what is going on in detail.
+
+The include file @code{<cln/integer.h>} is necessary because the type
+@code{cl_I} is used in the function, and the include file @code{<cln/real.h>}
+is needed for the type @code{cl_R} and the floating point number functions.
+The order of the include files does not matter. In order not to write
+out @code{cln::}@var{foo} in this simple example we can safely import
+the whole namespace @code{cln}.
+
+Then comes the function declaration. The argument is an @code{int}, the
+result an integer. The return type is defined as @samp{const cl_I}, not
+simply @samp{cl_I}, because that allows the compiler to detect typos like
+@samp{fibonacci(n) = 100}. It would be possible to declare the return
+type as @code{const cl_R} (real number) or even @code{const cl_N} (complex
+number). We use the most specialized possible return type because functions
+which call @samp{fibonacci} will be able to profit from the compiler's type
+analysis: Adding two integers is slightly more efficient than adding the
+same objects declared as complex numbers, because it needs less type
+dispatch. Also, when linking to CLN as a non-shared library, this minimizes
+the size of the resulting executable program.
+
+The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
+integer. In order to get a correct result, the absolute error should be less
+than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
+To this end, the first line computes a floating point precision for sqrt(5)
+and phi.
+
+Then sqrt(5) is computed by first converting the integer 5 to a floating point
+number and than taking the square root. The converse, first taking the square
+root of 5, and then converting to the desired precision, would not work in
+CLN: The square root would be computed to a default precision (normally
+single-float precision), and the following conversion could not help about
+the lacking accuracy. This is because CLN is not a symbolic computer algebra
+system and does not represent sqrt(5) in a non-numeric way.
+
+The type @code{cl_R} for sqrt5 and, in the following line, phi is the only
+possible choice. You cannot write @code{cl_F} because the C++ compiler can
+only infer that @code{cl_float(5,prec)} is a real number. You cannot write
+@code{cl_N} because a @samp{round1} does not exist for general complex
+numbers.
+
+When the function returns, all the local variables in the function are
+automatically reclaimed (garbage collected). Only the result survives and
+gets passed to the caller.
+
+The file @code{fibonacci.cc} in the subdirectory @code{examples}
+contains this implementation together with an even faster algorithm.
+
+@section Debugging support
+@cindex debugging
+
+When debugging a CLN application with GNU @code{gdb}, two facilities are
+available from the library:
+
+@itemize @bullet
+@item The library does type checks, range checks, consistency checks at
+many places. When one of these fails, an exception of a type derived from
+@code{runtime_exception} is thrown. When an exception is cought, the stack
+has already been unwound, so it is may not be possible to tell at which
+point the exception was thrown. For debugging, it is best to set up a
+catchpoint at the event of throwning a C++ exception:
+@example
+(gdb) catch throw
+@end example
+When this catchpoint is hit, look at the stack's backtrace:
+@example
+(gdb) where
+@end example
+When control over the type of exception is required, it may be possible
+to set a breakpoint at the @code{g++} runtime library function
+@code{__raise_exception}. Refer to the documentation of GNU @code{gdb}
+for details.
+
+@item The debugger's normal @code{print} command doesn't know about
+CLN's types and therefore prints mostly useless hexadecimal addresses.
+CLN offers a function @code{cl_print}, callable from the debugger,
+for printing number objects. In order to get this function, you have
+to define the macro @samp{CL_DEBUG} and then include all the header files
+for which you want @code{cl_print} debugging support. For example:
+@cindex @code{CL_DEBUG}
+@example
+#define CL_DEBUG
+#include <cln/string.h>
+@end example
+Now, if you have in your program a variable @code{cl_string s}, and
+inspect it under @code{gdb}, the output may look like this:
+@example
+(gdb) print s
+$7 = @{<cl_gcpointer> = @{ = @{pointer = 0x8055b60, heappointer = 0x8055b60,
+ word = 134568800@}@}, @}
+(gdb) call cl_print(s)
+(cl_string) ""
+$8 = 134568800
+@end example
+Note that the output of @code{cl_print} goes to the program's error output,
+not to gdb's standard output.
+
+Note, however, that the above facility does not work with all CLN types,
+only with number objects and similar. Therefore CLN offers a member function
+@code{debug_print()} on all CLN types. The same macro @samp{CL_DEBUG}
+is needed for this member function to be implemented. Under @code{gdb},
+you call it like this:
+@cindex @code{debug_print ()}
+@example
+(gdb) print s
+$7 = @{<cl_gcpointer> = @{ = @{pointer = 0x8055b60, heappointer = 0x8055b60,
+ word = 134568800@}@}, @}
+(gdb) call s.debug_print()
+(cl_string) ""
+(gdb) define cprint
+>call ($1).debug_print()
+>end
+(gdb) cprint s
+(cl_string) ""
+@end example
+Unfortunately, this feature does not seem to work under all circumstances.
+@end itemize
+
+@section Reporting Problems
+@cindex bugreports
+@cindex mailing list
+
+If you encounter any problem, please don't hesitate to send a detailed
+bugreport to the @code{cln-list@@ginac.de} mailing list. Please think
+about your bug: consider including a short description of your operating
+system and compilation environment with corresponding version numbers. A
+description of your configuration options may also be helpful. Also, a
+short test program together with the output you get and the output you
+expect will help us to reproduce it quickly. Finally, do not forget to
+report the version number of CLN.
+
+
+@chapter Customizing
+@cindex customizing
+
+@section Error handling
+@cindex exception
+@cindex error handling
+
+@cindex @code{runtime_exception}
+CLN signals abnormal situations by throwning exceptions. All exceptions
+thrown by the library are of type @code{runtime_exception} or of a
+derived type. Class @code{cln::runtime_exception} in turn is derived
+from the C++ standard library class @code{std::runtime_error} and
+inherits the @code{.what()} member function that can be used to query
+details about the cause of error.
+
+The most important classes thrown by the library are
+
+@cindex @code{floating_point_exception}
+@cindex @code{read_number_exception}
+@example
+ Exception base class
+ runtime_exception
+ <cln/exception.h>
+ |
+ +----------------+----------------+
+ | |
+ Malformed number input Floating-point error
+ read_number_exception floating_poing_exception
+ <cln/number_io.h> <cln/float.h>
+@end example
+
+CLN has many more exception classes that allow for more fine-grained
+control but I refrain from documenting them all here. They are all
+declared in the public header files and they are all subclasses of the
+above exceptions, so catching those you are always on the safe side.
+
+
+@section Floating-point underflow
+@cindex underflow
+
+@cindex @code{floating_point_underflow_exception}
+Floating point underflow denotes the situation when a floating-point
+number is to be created which is so close to @code{0} that its exponent
+is too low to be represented internally. By default, this causes the
+exception @code{floating_point_underflow_exception} (subclass of
+@code{floating_point_exception}) to be thrown. If you set the global
+variable
+@example
+bool cl_inhibit_floating_point_underflow
+@end example
+to @code{true}, the exception will be inhibited, and a floating-point
+zero will be generated instead. The default value of
+@code{cl_inhibit_floating_point_underflow} is @code{false}.
+
+
+@section Customizing I/O
+
+The output of the function @code{fprint} may be customized by changing the
+value of the global variable @code{default_print_flags}.
+@cindex @code{default_print_flags}
+
+
+@section Customizing the memory allocator
+
+Every memory allocation of CLN is done through the function pointer
+@code{malloc_hook}. Freeing of this memory is done through the function
+pointer @code{free_hook}. The default versions of these functions,
+provided in the library, call @code{malloc} and @code{free} and check
+the @code{malloc} result against @code{NULL}.
+If you want to provide another memory allocator, you need to define
+the variables @code{malloc_hook} and @code{free_hook} yourself,
+like this:
+@example
+#include <cln/malloc.h>
+namespace cln @{
+ void* (*malloc_hook) (size_t size) = @dots{};
+ void (*free_hook) (void* ptr) = @dots{};
+@}
+@end example
+@cindex @code{malloc_hook ()}
+@cindex @code{free_hook ()}
+The @code{cl_malloc_hook} function must not return a @code{NULL} pointer.
+
+It is not possible to change the memory allocator at runtime, because
+it is already called at program startup by the constructors of some
+global variables.
+
+
+
+
+@c Indices
+
+@unnumbered Index
+
+@printindex my
+
+
+@bye
git://www.ginac.de / cln.git / commitdiff