@setfilename cln.info
@settitle CLN, a Class Library for Numbers
@c @setchapternewpage off
-@c For `info' only.
-@paragraphindent 0
-@c For TeX only.
-@iftex
@c I hate putting "@noindent" in front of every paragraph.
-@parindent=0pt
-@end iftex
+@c For `info' and TeX only.
+@paragraphindent 0
@c %**end of header
+@dircategory Mathematics
@direntry
* CLN: (cln). Class Library for Numbers (C++).
@end direntry
This file documents @sc{cln}, a Class Library for Numbers.
Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
-Richard Kreckel, @code{<kreckel@@ginac.de>}.
+Richard B. Kreckel, @code{<kreckel@@ginac.de>}.
-Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000.
+Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007.
+Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@author by Bruno Haible
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000.
+Copyright @copyright{} Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007.
+@sp 0
+Copyright @copyright{} Richard Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007.
@sp 2
Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
@page
+@c Table of contents
+@contents
+
+
@node Top, Introduction, (dir), (dir)
@c @menu
@cindex Sch{@"o}nhage-Strassen multiplication
@end iftex
@ifinfo
-Schönhage-Strassen
-@cindex Schönhage-Strassen multiplication
+Schnhage-Strassen
+@cindex Schnhage-Strassen multiplication
@end ifinfo
multiplication, which is an asymptotically optimal multiplication
algorithm, for multiplication, division and radix conversion.
@item
The garbage collection imposes no burden on the main application.
@item
-The library provides hooks for memory allocation and exceptions.
+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
@subsection C++ compiler
To build CLN, you need a C++ compiler.
-Actually, you need GNU @code{g++ 2.90} or newer, the EGCS compilers will
-do.
-I recommend GNU @code{g++ 2.95} or newer.
+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,
templates and namespaces.
The following C++ features are not used:
-@code{new}, @code{delete}, virtual inheritance, exceptions.
-
-CLN relies on semi-automatic ordering of initializations
-of static and global variables, a feature which I could
-implement for GNU g++ only.
-
-@ignore
-@comment cl_modules.h requires g++
-Therefore nearly any C++ compiler will do.
-
-The following C++ compilers are known to compile CLN:
-@itemize @minus
-@item
-GNU @code{g++ 2.7.0}, @code{g++ 2.7.2}
-@item
-SGI @code{CC 4}
-@end itemize
+@code{new}, @code{delete}, virtual inheritance.
-The following C++ compilers are known to be unusable for CLN:
-@itemize @minus
-@item
-On SunOS 4, @code{CC 2.1}, because it doesn't grok @code{//} comments
-in lines containing @code{#if} or @code{#elif} preprocessor commands.
-@item
-On AIX 3.2.5, @code{xlC}, because it doesn't grok the template syntax
-in @code{cl_SV.h} and @code{cl_GV.h}, because it forces most class types
-to have default constructors, and because it probably miscompiles the
-integer multiplication routines.
-@item
-On AIX 4.1.4.0, @code{xlC}, because when optimizing, it sometimes converts
-@code{short}s to @code{int}s by zero-extend.
-@item
-GNU @code{g++ 2.5.8}
-@item
-On HPPA, GNU @code{g++ 2.7.x}, because the semi-automatic ordering of
-initializations will not work.
-@end itemize
-@end ignore
+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}
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 4 hours on an average workstation.
+builds the library. This step may take about an hour on an average workstation.
The @code{make check} runs some test to check that no important subroutine
has been miscompiled.
@example
$ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
-$ CC="gcc -V egcs-2.91.60" CFLAGS="-O -g" \
- CXX="g++ -V egcs-2.91.60" CXXFLAGS="-O -g" ./configure
-$ CC="gcc -V 2.95.2" CFLAGS="-O2 -fno-exceptions" \
- CXX="g++ -V 2.95.2" CFLAGS="-O2 -fno-exceptions" ./configure
-@end example
-@ignore
-@comment cl_modules.h requires g++
-You should not mix GNU and non-GNU compilers. So, if @code{CXX} is a non-GNU
-compiler, @code{CC} should be set to a non-GNU compiler as well. Examples:
-
-@example
-$ CC="cc" CFLAGS="-O" CXX="CC" CXXFLAGS="-O" ./configure
-$ CC="gcc -V 2.7.0" CFLAGS="-g" CXX="g++ -V 2.7.0" CXXFLAGS="-g" ./configure
-@end example
-
-On SGI Irix 5, if you wish not to use @code{g++}:
-
-@example
-$ CC="cc" CFLAGS="-O" CXX="CC" CXXFLAGS="-O -Olimit 16000" ./configure
+$ CC="gcc -V 3.0.4" CFLAGS="-O2 -finline-limit=1000" \
+ CXX="g++ -V 3.0.4" CXXFLAGS="-O2 -finline-limit=1000" \
+ ./configure
+$ CC="gcc-4.1" CFLAGS="-O2" CXX="g++-4.1" CXXFLAGS="-O2" ./configure
@end example
-On SGI Irix 6, if you wish not to use @code{g++}:
-
-@example
-$ CC="cc -32" CFLAGS="-O" CXX="CC -32" CXXFLAGS="-O -Olimit 34000" \
- ./configure --without-gmp
-$ CC="cc -n32" CFLAGS="-O" CXX="CC -n32" CXXFLAGS="-O \
- -OPT:const_copy_limit=32400 -OPT:global_limit=32400 -OPT:fprop_limit=4000" \
- ./configure --without-gmp
-@end example
-@end ignore
-
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
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 use @code{-O}.)
-If you use @code{g++} gcc-2.95.x or gcc-3.0, I recommend adding
-@samp{-fno-exceptions} to the CXXFLAGS. This will likely generate better code.
+If you use @code{g++} 3.x, I recommend adding @samp{-finline-limit=1000}
+to the CXXFLAGS. This is essential for good code.
-If you use @code{g++} from gcc-2.95.x 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, on OSF/1 or
-Tru64 using gcc-2.95.x, you should specify @samp{--disable-shared} because of
-linker problems with duplicate symbols in shared libraries.
+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.
+
+If you use @code{g++} from gcc-3.1, it will need 235 MB of virtual 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
problems. Also, they are generally somewhat slower than static
libraries so runtime-critical applications should be linked statically.
+If you use @code{g++} from gcc-3.1 with option @samp{-g}, you will need
+some disk space: 335 MB for building as both a shared and a static library,
+or 130 MB when building as a shared library only.
+
@subsection Using the GNU MP Library
@cindex GMP
an example:
@example
-$ CC="gcc" CFLAGS="-O2" CXX="g++" CXXFLAGS="-O2 -fno-exceptions" \
+$ CC="gcc" CFLAGS="-O2" CXX="g++" CXXFLAGS="-O2" \
CPPFLAGS="-I/opt/gmp/include" LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
@end example
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. Their range is therefore limited:
+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.
+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.
+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}.
+@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}.
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.
the same according to @code{==}. This hash code depends on the number's value,
not its type or precision.
-@item cl_boolean zerop (const @var{type}& x)
+@item bool zerop (const @var{type}& x)
@cindex @code{zerop ()}
Compare against zero: @code{x == 0}
@end table
@cindex @code{operator > ()}
Comparison, as in C and C++.
-@item cl_boolean minusp (const @var{type}& x)
+@item bool minusp (const @var{type}& x)
@cindex @code{minusp ()}
Compare against zero: @code{x < 0}
-@item cl_boolean plusp (const @var{type}& x)
+@item bool plusp (const @var{type}& x)
@cindex @code{plusp ()}
Compare against zero: @code{x > 0}
The classes @code{cl_RA}, @code{cl_I} define the following operation:
@table @code
-@item cl_boolean sqrtp (const @var{type}& x, @var{type}* root)
+@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.
Furthermore, for integers, similarly:
@table @code
-@item cl_boolean isqrt (const @var{type}& x, @var{type}* root)
+@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}:
define the following operation:
@table @code
-@item cl_boolean rootp (const @var{type}& x, const cl_I& n, @var{type}* root)
+@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.
Other functions that view integers as bit strings:
@table @code
-@item cl_boolean logtest (const cl_I& x, const cl_I& y)
+@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 cl_boolean logbitp (const cl_I& n, const cl_I& x)
+@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 uintL logcount (const cl_I& x)
+@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.
The following functions operate on intervals of bits in integers.
The type
@example
-struct cl_byte @{ uintL size; uintL position; @};
+struct cl_byte @{ uintC size; uintC position; @};
@end example
@cindex @code{cl_byte}
represents the bit interval containing the bits
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 cl_boolean ldb_test (const cl_I& n, const cl_byte& b)
+@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}.
for common arithmetic operations:
@table @code
-@item cl_boolean oddp (const cl_I& x)
+@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 cl_boolean evenp (const cl_I& x)
+@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}.
by @code{-y} bits to the right (if @code{y}<=0). In other words, this
returns @code{floor(x * expt(2,y))}.
-@item uintL integer_length (const cl_I& x)
+@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 uintL ord2 (const cl_I& x)
+@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 uintL power2p (const cl_I& 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.
@subsection Number theoretic functions
@table @code
-@item uint32 gcd (uint32 a, uint32 b)
+@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},
This function returns the least common multiple of @code{a} and @code{b},
normalized to be >= 0.
-@item cl_boolean logp (const cl_I& a, const cl_I& b, cl_RA* l)
+@item bool logp (const cl_I& a, const cl_I& b, cl_RA* l)
@cindex @code{logp ()}
-@itemx cl_boolean logp (const cl_RA& a, const cl_RA& b, cl_RA* l)
+@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
defines the following operations.
@table @code
-@item @var{type} scale_float (const @var{type}& x, sintL delta)
+@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
representation of floating-point numbers.
@table @code
-@item sintL float_exponent (const @var{type}& x)
+@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
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 uintL float_digits (const @var{type}& x)
+@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 uintL float_precision (const @var{type}& x)
+@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,
@cindex @code{float_format_t}
@table @code
-@item float_format_t float_format (uintL n)
+@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).
@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 a fatal error will be signalled. If @code{end_of_parse}
+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.
@item float_format_t float_flags.default_lfloat_format
The float format used when reading floats with exponent marker @samp{l}.
-@item cl_boolean float_flags.mantissa_dependent_float_format
+@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.
@item unsigned int rational_base
The base in which rational numbers are printed. Default is @code{10}.
-@item cl_boolean rational_readably
+@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 cl_boolean float_readably
+@item bool float_readably
If this flag is true, type specific exponent markers have precedence over 'E'.
Default is false.
Floating point numbers of this format will be printed using the 'E' exponent
marker. Default is @code{float_format_ffloat}.
-@item cl_boolean complex_readably
+@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.
@table @code
@item void R->fprint (std::ostream& stream, const cl_ring_element& x)
@cindex @code{fprint ()}
-@itemx cl_boolean R->equal (const cl_ring_element& x, const cl_ring_element& y)
+@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 cl_boolean R->zerop (const cl_ring_element& x)
+@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 ()}
@code{cl_RA_ring}, @code{cl_I_ring}:
@table @code
-@item cl_boolean instanceof (const cl_number& x, const cl_number_ring& R)
+@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
Compares two modular integers, belonging to the same modular integer ring,
for equality.
-@item cl_boolean zerop (const cl_MI& x)
+@item bool zerop (const cl_MI& x)
@cindex @code{zerop ()}
Returns true if @code{x} is @code{0 mod N}.
@end table
@item cl_UP R->one()
@cindex @code{one ()}
-This returns @code{1 in R}, a polynomial of degree <= 0.
+This returns @code{1 in R}, a polynomial of degree == 0.
@item cl_UP R->canonhom (const cl_I& x)
@cindex @code{canonhom ()}
Compares two univariate polynomials, belonging to the same univariate
polynomial ring, for equality.
-@item cl_boolean zerop (const cl_UP& x)
+@item bool zerop (const cl_UP& x)
@cindex @code{zerop ()}
Returns true if @code{x} is @code{0 in R}.
@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
@cindex immediate numbers
Small integers are represented as immediate values instead of pointers
-to heap allocated storage. This means that integers @code{> -2^29},
+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
@cindex Sch{@"o}nhage-Strassen multiplication
@end iftex
@ifinfo
-Schönhage-Strassen
-@cindex Schönhage-Strassen multiplication
+Schnhage-Strassen
+@cindex Schnhage-Strassen multiplication
@end ifinfo
multiplication, which is an asymptotically optimal multiplication
algorithm.
public directory as well (normally @code{/usr/local/lib}), hence when
linking a CLN application it is sufficient to give the flag @code{-lcln}.
-Since CLN version 1.1, there are two tools to make the creation of
-software packages that use CLN easier:
-@itemize @bullet
-@item
-@cindex @code{cln-config}
-@code{cln-config} is a shell script that you can use to determine the
-compiler and linker command line options required to compile and link a
-program with CLN. Start it with @code{--help} to learn about its options
-or consult the manpage that comes with it.
-@item
-@cindex @code{AC_PATH_CLN}
-@code{AC_PATH_CLN} is for packages configured using GNU automake.
-The synopsis is:
+@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
-@code{AC_PATH_CLN([@var{MIN-VERSION}, [@var{ACTION-IF-FOUND} [, @var{ACTION-IF-NOT-FOUND}]]])}
+PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}])
@end example
-This macro determines the location of CLN using @code{cln-config}, which
-is either found in the user's path, or from the environment variable
-@code{CLN_CONFIG}. It tests the installed libraries to make sure that
-their version is not earlier than @var{MIN-VERSION} (a default version
-will be used if not specified). If the required version was found, sets
-the @env{CLN_CPPFLAGS} and the @env{CLN_LIBS} variables. This
-macro is in the file @file{cln.m4} which is installed in
-@file{$datadir/aclocal}. Note that if automake was installed with a
-different @samp{--prefix} than CLN, you will either have to manually
-move @file{cln.m4} to automake's @file{$datadir/aclocal}, or give
-aclocal the @samp{-I} option when running it. Here is a possible example
-to be included in your package's @file{configure.in}:
+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
-AC_PATH_CLN(1.1.0, [
- LIBS="$LIBS $CLN_LIBS"
- CPPFLAGS="$CPPFLAGS $CLN_CPPFLAGS"
-], AC_MSG_ERROR([No suitable installed version of CLN could be found.]))
+PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}], [],
+ [AC_MSG_WARNING([No suitable version of CLN can be found])])
@end example
-@end itemize
-
-
-@section Compatibility to old CLN versions
-@cindex namespace
-@cindex compatibility
-
-As of CLN version 1.1 all non-macro identifiers were hidden in namespace
-@code{cln} in order to avoid potential name clashes with other C++
-libraries. If you have an old application, you will have to manually
-port it to the new scheme. The following principles will help during
-the transition:
-@itemize @bullet
-@item
-All headers are now in a separate subdirectory. Instead of including
-@code{cl_}@var{something}@code{.h}, include
-@code{cln/}@var{something}@code{.h} now.
-@item
-All public identifiers (typenames and functions) have lost their
-@code{cl_} prefix. Exceptions are all the typenames of number types,
-(cl_N, cl_I, cl_MI, @dots{}), rings, symbolic types (cl_string,
-cl_symbol) and polynomials (cl_UP_@var{type}). (This is because their
-names would not be mnemonic enough once the namespace @code{cln} is
-imported. Even in a namespace we favor @code{cl_N} over @code{N}.)
-@item
-All public @emph{functions} that had by a @code{cl_} in their name still
-carry that @code{cl_} if it is intrinsic part of a typename (as in
-@code{cl_I_to_int ()}).
-@end itemize
-When developing other libraries, please keep in mind not to import the
-namespace @code{cln} in one of your public header files by saying
-@code{using namespace cln;}. This would propagate to other applications
-and can cause name clashes there.
@section Include files
Flags for customizing output operations.
@item <cln/malloc.h>
@code{malloc_hook}, @code{free_hook}.
-@item <cln/abort.h>
-@code{cl_abort}.
+@item <cln/exception.h>
+Exception base class.
@item <cln/condition.h>
-Conditions/exceptions.
+Conditions.
@item <cln/string.h>
Strings.
@item <cln/symbol.h>
@itemize @bullet
@item The library does type checks, range checks, consistency checks at
-many places. When one of these fails, the function @code{cl_abort()} is
-called. Its default implementation is to perform an @code{exit(1)}, so
-you won't have a core dump. But for debugging, it is best to set a
-breakpoint at this function:
+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) break cl_abort
+(gdb) catch throw
@end example
-When this breakpoint is hit, look at the stack's backtrace:
+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.
@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.
-When a fatal error occurs, an error message is output to the standard error
-output stream, and the function @code{cl_abort} is called. The default
-version of this function (provided in the library) terminates the application.
-To catch such a fatal error, you need to define the function @code{cl_abort}
-yourself, with the prototype
+The most important classes thrown by the library are
+
+@cindex @code{floating_point_exception}
+@cindex @code{read_number_exception}
@example
-#include <cln/abort.h>
-void cl_abort (void);
+ 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
-@cindex @code{cl_abort ()}
-This function must not return control to its caller.
+
+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
-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 a fatal error.
-If you set the global variable
+@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
-cl_boolean cl_inhibit_floating_point_underflow
+bool cl_inhibit_floating_point_underflow
@end example
-to @code{cl_true}, the error will be inhibited, and a floating-point zero
-will be generated instead. The default value of
-@code{cl_inhibit_floating_point_underflow} is @code{cl_false}.
+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
@printindex my
-@c Table of contents
-@contents
-
-
@bye
git://www.ginac.de / cln.git / blobdiff