@end titlepage
@page
-
+@iftex
@c Table of contents
@contents
+@end iftex
+
+@ifinfo
+@node Top
+@top CLN
+@end ifinfo
+
+
+@menu
+* Introduction::
+* Installation::
+* Ordinary number types::
+* Functions on numbers::
+* Input/Output::
+* Rings::
+* Modular integers::
+* Symbolic data types::
+* Univariate polynomials::
+* Internals::
+* Using the library::
+* Customizing::
+* Index::
+
+ --- The Detailed Node Listing ---
+
+Installation
+
+* Prerequisites::
+* Building the library::
+* Installing the library::
+* Cleaning up::
+
+Prerequisites
+
+* C++ compiler::
+* Make utility::
+* Sed utility::
+
+Building the library
+
+* Using the GNU MP Library::
+
+Ordinary number types
+
+* Exact numbers::
+* Floating-point numbers::
+* Complex numbers::
+* Conversions::
+
+Functions on numbers
+
+* Constructing numbers::
+* Elementary functions::
+* Elementary rational functions::
+* Elementary complex functions::
+* Comparisons::
+* Rounding functions::
+* Roots::
+* Transcendental functions::
+* Functions on integers::
+* Functions on floating-point numbers::
+* Conversion functions::
+* Random number generators::
+* Modifying operators::
+
+Constructing numbers
+
+* Constructing integers::
+* Constructing rational numbers::
+* Constructing floating-point numbers::
+* Constructing complex numbers::
+
+Transcendental functions
+
+* Exponential and logarithmic functions::
+* Trigonometric functions::
+* Hyperbolic functions::
+* Euler gamma::
+* Riemann zeta::
+
+Functions on integers
+
+* Logical functions::
+* Number theoretic functions::
+* Combinatorial functions::
+
+Conversion functions
+
+* Conversion to floating-point numbers::
+* Conversion to rational numbers::
+
+Input/Output
+
+* Internal and printed representation::
+* Input functions::
+* Output functions::
+Modular integers
-@node Top, Introduction, (dir), (dir)
+* Modular integer rings::
+* Functions on modular integers::
-@c @menu
-@c * Introduction:: Introduction
-@c @end menu
+Symbolic data types
+* Strings::
+* Symbols::
-@node Introduction, Top, Top, Top
-@comment node-name, next, previous, up
+Univariate polynomials
+
+* Univariate polynomial rings::
+* Functions on univariate polynomials::
+* Special polynomials::
+
+Internals
+
+* Why C++ ?::
+* Memory efficiency::
+* Speed efficiency::
+* Garbage collection::
+
+Using the library
+
+* Compiler options::
+* Include files::
+* An Example::
+* Debugging support::
+* Reporting Problems::
+
+Customizing
+
+* Error handling::
+* Floating-point underflow::
+* Customizing I/O::
+* Customizing the memory allocator::
+
+@end menu
+
+@node Introduction
@chapter Introduction
@noindent
@end itemize
+@node Installation
@chapter Installation
This section describes how to install the CLN package on your system.
+@menu
+* Prerequisites::
+* Building the library::
+* Installing the library::
+* Cleaning up::
+@end menu
+
+@node Prerequisites, Building the library, Installation, Installation
@section Prerequisites
+@menu
+* C++ compiler::
+* Make utility::
+* Sed utility::
+@end menu
+
+@node C++ compiler
@subsection C++ compiler
To build CLN, you need a C++ compiler.
only. Also, it is not known whether this semi-automatic ordering works
on all platforms when a non-GNU assembler is being used.
+@node Make utility
@subsection Make utility
@cindex @code{make}
Only GNU @code{make} 3.77 is unusable for CLN; other versions work fine.
+@node Sed utility
@subsection Sed utility
@cindex @code{sed}
limited.
+@node Building the library
@section Building the library
As with any autoconfiguring GNU software, installation is as easy as this:
@item CPPFLAGS
Flags to be given to the C/C++ preprocessor.
+
+@item LDFLAGS
+Flags to be given to the linker.
@end table
Examples:
libraries so runtime-critical applications should be linked statically.
+@menu
+* Using the GNU MP Library::
+@end menu
+
+@node Using the GNU MP Library
@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.
+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. Using @code{gmp} is known to be quite a boost
+for CLN's performance.
+
+By default, CLN will autodetect @code{gmp} and use it. 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}.
-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:
+If you have installed the @code{gmp} library and its header files in
+some place where the compiler cannot find it by default, you must help
+@code{configure} and specify the prefix that was used when @code{gmp}
+was configured. Here is an example:
@example
-$ CFLAGS="-O2" CXXFLAGS="-O2" CPPFLAGS="-I/opt/gmp/include" \
- LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
+$ ./configure --with-gmp=/opt/gmp-4.2.2
@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}.
+This assumes that the @code{gmp} header files have been installed in
+@file{/opt/gmp-4.2.2/include/} and the library in
+@file{/opt/gmp-4.2.2/lib/}. More uncommon GMP installations can be
+handled by setting CPPFLAGS and LDFLAGS appropriately prior to running
+@code{configure}.
+@node Installing the library
@section Installing the library
@cindex installation
the @code{--prefix=@dots{}} option.
+@node Cleaning up
@section Cleaning up
You can remove system-dependent files generated by @code{make} through
@end example
+@node Ordinary number types
@chapter Ordinary number types
CLN implements the following class hierarchy:
It is an abstract class.
+@menu
+* Exact numbers::
+* Floating-point numbers::
+* Complex numbers::
+* Conversions::
+@end menu
+
+@node Exact numbers
@section Exact numbers
@cindex exact number
is completely transparent.
+@node Floating-point numbers
@section Floating-point numbers
@cindex floating-point number
the floating point contagion rule happened to change in the future.)
+@node Complex numbers
@section Complex numbers
@cindex complex number
through application of @code{sqrt} or transcendental functions.
+@node Conversions
@section Conversions
@cindex conversion
@end example
+@node Functions on numbers
@chapter Functions on numbers
Each of the number classes declares its mathematical operations in the
objects of type @code{cl_I}, it should @code{#include <cln/integer.h>}.
+@menu
+* Constructing numbers::
+* Elementary functions::
+* Elementary rational functions::
+* Elementary complex functions::
+* Comparisons::
+* Rounding functions::
+* Roots::
+* Transcendental functions::
+* Functions on integers::
+* Functions on floating-point numbers::
+* Conversion functions::
+* Random number generators::
+* Modifying operators::
+@end menu
+
+@node Constructing numbers
@section Constructing numbers
Here is how to create number objects ``from nothing''.
+@menu
+* Constructing integers::
+* Constructing rational numbers::
+* Constructing floating-point numbers::
+* Constructing complex numbers::
+@end menu
+
+@node Constructing integers
@subsection Constructing integers
@code{cl_I} objects are most easily constructed from C integers and from
strings. See @ref{Conversions}.
+@node Constructing rational numbers
@subsection Constructing rational numbers
@code{cl_RA} objects can be constructed from strings. The syntax
of @samp{operator /} or @samp{recip} on integers.
+@node Constructing floating-point numbers
@subsection Constructing floating-point numbers
@code{cl_F} objects with low precision are most easily constructed from
@end example
+@node Constructing complex numbers
@subsection Constructing complex numbers
Non-real @code{cl_N} objects are normally constructed through the function
See @ref{Elementary complex functions}.
+@node Elementary functions
@section Elementary functions
Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
@end table
+@node Elementary rational functions
@section Elementary rational functions
Each of the classes @code{cl_RA}, @code{cl_I} defines the following operations:
a way that they have no factor in common and the denominator is positive.
+@node Elementary complex functions
@section Elementary complex functions
The class @code{cl_N} defines the following operation:
@end itemize
+@node Comparisons
@section Comparisons
@cindex comparison
there is no floating point number whose value is exactly @code{1/3}.
+@node Rounding functions
@section Rounding functions
@cindex rounding
@end table
+@node Roots
@section Roots
Each of the classes @code{cl_R},
@end table
+@node Transcendental functions
@section Transcendental functions
@cindex transcendental functions
For example, @code{cos(0) = 1} returns the rational number @code{1}.
+@menu
+* Exponential and logarithmic functions::
+* Trigonometric functions::
+* Hyperbolic functions::
+* Euler gamma::
+* Riemann zeta::
+@end menu
+
+@node Exponential and logarithmic functions
@subsection Exponential and logarithmic functions
@table @code
@end table
+@node Trigonometric functions
@subsection Trigonometric functions
@table @code
@end table
+@node Hyperbolic functions
@subsection Hyperbolic functions
@table @code
@end table
+@node Euler gamma
@subsection Euler gamma
@cindex Euler's constant
@end table
+@node Riemann zeta
@subsection Riemann zeta
@cindex Riemann's zeta
@end table
+@node Functions on integers
@section Functions on integers
+@menu
+* Logical functions::
+* Number theoretic functions::
+* Combinatorial functions::
+@end menu
+
+@node Logical functions
@subsection Logical functions
Integers, when viewed as in two's complement notation, can be thought as
@end table
+@node Number theoretic functions
@subsection Number theoretic functions
@table @code
@end table
+@node Combinatorial functions
@subsection Combinatorial functions
@table @code
@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)!}$
+${n \choose k} = {n! \over k! (n-k)!}$
@end tex
@ifinfo
(@code{n} choose @code{k}) = @code{n}! / @code{k}! @code{(n-k)}!
@end table
+@node Functions on floating-point numbers
@section Functions on floating-point numbers
Recall that a floating-point number consists of a sign @code{s}, an
@end table
+@node Conversion functions
@section Conversion functions
@cindex conversion
+@menu
+* Conversion to floating-point numbers::
+* Conversion to rational numbers::
+@end menu
+
+@node Conversion to floating-point numbers
@subsection Conversion to floating-point numbers
The type @code{float_format_t} describes a floating-point format.
@end table
+@node Conversion to rational numbers
@subsection Conversion to rational numbers
Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_F}
@end itemize
+@node Random number generators
@section Random number generators
@end table
-@section Obfuscating operators
+@node Modifying operators
+@section Modifying 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:
+are all available.
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}:
The postfix operator @code{x--}.
@end table
-Note that by using these obfuscating operators, you wouldn't gain efficiency:
+Note that by using these modifying operators, you don't gain efficiency:
In CLN @samp{x += y;} is exactly the same as @samp{x = x+y;}, not more
efficient.
+@node Input/Output
@chapter Input/Output
@cindex Input/Output
+@menu
+* Internal and printed representation::
+* Input functions::
+* Output functions::
+@end menu
+
+@node Internal and printed representation
@section Internal and printed representation
@cindex representation
@end table
+@node Input functions
@section Input functions
Including @code{<cln/io.h>} defines a number of simple input functions
@end table
+@node Output functions
@section Output functions
Including @code{<cln/io.h>} defines a number of simple output functions
used by the function @code{fprint}.
+@node Rings
@chapter Rings
CLN has a class of abstract rings.
@end table
+@node Modular integers
@chapter Modular integers
@cindex modular integer
+@menu
+* Modular integer rings::
+* Functions on modular integers::
+@end menu
+
+@node Modular integer rings
@section Modular integer rings
@cindex ring
same ring because it is memoized in the cache table.
@end table
+@node Functions on modular integers
@section Functions on modular integers
Given a modular integer ring @code{R}, the following members can be used.
@end table
+@node Symbolic data types
@chapter Symbolic data types
@cindex symbolic type
CLN implements two symbolic (non-numeric) data types: strings and symbols.
+@menu
+* Strings::
+* Symbols::
+@end menu
+
+@node Strings
@section Strings
@cindex string
@cindex @code{cl_string}
plain @code{const char *}.
@end table
+@node Symbols
@section Symbols
@cindex symbol
@cindex @code{cl_symbol}
@end table
+@node Univariate polynomials
@chapter Univariate polynomials
@cindex polynomial
@cindex univariate polynomial
+@menu
+* Univariate polynomial rings::
+* Functions on univariate polynomials::
+* Special polynomials::
+@end menu
+
+@node Univariate polynomial rings
@section Univariate polynomial rings
CLN implements univariate polynomials (polynomials in one variable) over an
only the return type is more specific, according to the base ring's type.
@end table
+@node Functions on univariate polynomials
@section Functions on univariate polynomials
Given a univariate polynomial ring @code{R}, the following members can be used.
@code{default_print_flags}.
@end table
+@node Special polynomials
@section Special polynomials
The following functions return special polynomials.
@code{doc/polynomial/} directory.
+@node Internals
@chapter Internals
+@menu
+* Why C++ ?::
+* Memory efficiency::
+* Speed efficiency::
+* Garbage collection::
+@end menu
+
+@node Why C++ ?
@section Why C++ ?
@cindex advocacy
in a high-level language.
+@node Memory efficiency
@section Memory efficiency
In order to save memory allocations, CLN implements:
@end itemize
+@node Speed efficiency
@section Speed efficiency
Speed efficiency is obtained by the combination of the following tricks
@end itemize
+@node Garbage collection
@section Garbage collection
@cindex garbage collection
cached, whereas undue memory consumption through cached rings is avoided.
+@node Using the library
@chapter Using the library
For the following discussion, we will assume that you have installed
environment variables, or directly substitute the appropriate values.
+@menu
+* Compiler options::
+* Include files::
+* An Example::
+* Debugging support::
+* Reporting Problems::
+@end menu
+
+@node Compiler options
@section Compiler options
@cindex compiler options
@end example
+@node Include files
@section Include files
@cindex include files
@cindex header files
@end table
+@node An Example
@section An Example
A function which computes the nth Fibonacci number can be written as follows.
The file @code{fibonacci.cc} in the subdirectory @code{examples}
contains this implementation together with an even faster algorithm.
+@node Debugging support
@section Debugging support
@cindex debugging
Unfortunately, this feature does not seem to work under all circumstances.
@end itemize
+@node Reporting Problems
@section Reporting Problems
@cindex bugreports
@cindex mailing list
report the version number of CLN.
+@node Customizing
@chapter Customizing
@cindex customizing
+@menu
+* Error handling::
+* Floating-point underflow::
+* Customizing I/O::
+* Customizing the memory allocator::
+@end menu
+
+@node Error handling
@section Error handling
@cindex exception
@cindex error handling
above exceptions, so catching those you are always on the safe side.
+@node Floating-point underflow
@section Floating-point underflow
@cindex underflow
@code{cl_inhibit_floating_point_underflow} is @code{false}.
+@node Customizing I/O
@section Customizing I/O
The output of the function @code{fprint} may be customized by changing the
@cindex @code{default_print_flags}
+@node Customizing the memory allocator
@section Customizing the memory allocator
Every memory allocation of CLN is done through the function pointer
@c Indices
+@node Index, , Customizing, Top
@unnumbered Index
@printindex my