@end iftex
@c %**end of header
+@direntry
+* CLN: (cln). Class Library for Numbers (C++).
+@end direntry
@c My own index.
@defindex my
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.
+Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004.
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.
+@sp 0
+Copyright @copyright{} Richard Kreckel 2000, 2001, 2002, 2003, 2004.
@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.
The garbage collection imposes no burden on the main application.
@item
The library provides hooks for memory allocation and exceptions.
+@item
+@cindex namespace
+All non-macro identifiers are hidden in namespace @code{cln} in
+order to avoid name clashes.
@end itemize
@subsection C++ compiler
To build CLN, you need a C++ compiler.
-Actually, you need GNU @code{g++ 2.7.0} or newer.
-On HPPA, you need GNU @code{g++ 2.8.0} or newer.
-I recommend GNU @code{g++ 2.95} or newer.
+Actually, you need GNU @code{g++ 2.95} or newer.
The following C++ features are used:
-classes, member functions,
-overloading of functions and operators,
-constructors and destructors, inline, const,
-multiple inheritance, templates.
+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,
-exceptions.
+@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
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 2.7.2" CFLAGS="-O -g" \
- CXX="g++ -V 2.7.2" CXXFLAGS="-O -g" ./configure
-$ CC="gcc -V 2.8.1" CFLAGS="-O -fno-exceptions" \
- CXX="g++ -V 2.8.1" CXXFLAGS="-O -fno-exceptions" ./configure
-$ CC="gcc -V egcs-2.91.60" CFLAGS="-O2 -fno-exceptions" \
- CXX="g++ -V egcs-2.91.60" CFLAGS="-O2 -fno-exceptions" ./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
+$ CC="gcc -V 3.0.4" CFLAGS="-O2 -finline-limit=1000 -fno-exceptions" \
+ CXX="g++ -V 3.0.4" CFLAGS="-O2 -finline-limit=1000 -fno-exceptions" \
+ ./configure
@end example
@ignore
@comment cl_modules.h requires g++
calling @code{configure}. In a @code{csh} shell, you have to use the
@samp{setenv} command for setting each of the environment variables.
-On Linux, @code{g++} needs 15 MB to compile the tests. So you should better
-have 17 MB swap space and 1 MB room in $TMPDIR.
+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 use @code{-O}.)
+
+If you use @code{g++} 3.0.x or 3.1, I recommend adding
+@samp{-finline-limit=1000} to the CXXFLAGS. This is essential for good code.
-If you use @code{g++} version 2.7.x, don't add @samp{-O2} to the CXXFLAGS,
-because @samp{g++ -O} generates better code for CLN than @samp{g++ -O2}.
+If you use @code{g++} gcc-2.95.x or gcc-3.x , I recommend adding
+@samp{-fno-exceptions} to the CXXFLAGS. This will likely generate better code.
-If you use @code{g++} version 2.8.x or egcs-2.91.x (a.k.a. egcs-1.1) or
-gcc-2.95.x, I recommend adding @samp{-fno-exceptions} to the CXXFLAGS.
-This will likely generate better 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. If you use @code{g++} older than 2.95.3 on Sparc you should
+also specify @samp{--disable-shared} because of bad code produced in the
+shared library. Also, do not use gcc-3.0 on Sparc for compiling CLN, it
+won't work at all.
-If you use @code{g++} version egcs-2.91.x (egcs-1.1) or gcc-2.95.x on Sparc,
-add either @samp{-O} or @samp{-O2 -fno-schedule-insns} to the CXXFLAGS.
-With full @samp{-O2}, @code{g++} miscompiles the division routines. Also, for
---enable-shared to work, you need egcs-1.1.2 or newer.
+If you use @code{g++} 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.n, with n larger than 1, you should @emph{not} add
+@samp{-fno-exceptions} to the CXXFLAGS, since that will generate wrong
+code (gcc-3.1 is okay again, as is gcc-3.0).
-By default, only a static library is built. You can build CLN as a shared
-library too, by calling @code{configure} with the option @samp{--enable-shared}.
-To get it built as a shared library only, call @code{configure} with the options
-@samp{--enable-shared --disable-static}.
+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++} version egcs-2.91.x (egcs-1.1) on Sparc, you cannot
-use @samp{--enable-shared} because @code{g++} would miscompile parts of the
-library.
+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
+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 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
-Starting with version 1.0.4, CLN may be configured to make use of a
+Starting with version 1.1, CLN may be configured to make use of a
preinstalled @code{gmp} library. Please make sure that you have at
least @code{gmp} version 3.0 installed since earlier versions are
unsupported and likely not to work. Enabling this feature by calling
@example
Number
- cl_number
- <cl_number.h>
+ cl_number
+ <cln/number.h>
|
|
Real or complex number
cl_N
- <cl_complex.h>
+ <cln/complex.h>
|
|
Real number
cl_R
- <cl_real.h>
+ <cln/real.h>
|
+-------------------+-------------------+
| |
Rational number Floating-point number
cl_RA cl_F
-<cl_rational.h> <cl_float.h>
+<cln/rational.h> <cln/float.h>
| |
- | +-------------+-------------+-------------+
- Integer | | | |
- cl_I Short-Float Single-Float Double-Float Long-Float
- <cl_integer.h> cl_SF cl_FF cl_DF cl_LF
- <cl_sfloat.h> <cl_ffloat.h> <cl_dfloat.h> <cl_lfloat.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}
are coprime integers and the denominator is positive. If the resulting
denominator is @code{1}, the rational number is converted to an integer.
-Small integers (typically in the range @code{-2^30}@dots{}@code{2^30-1},
+@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'')
the functions
@table @code
-@item float cl_float_approx (const @var{type}& x)
-@cindex @code{cl_float_approx ()}
-@itemx double cl_double_approx (const @var{type}& x)
-@cindex @code{cl_double_approx ()}
+@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.
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.
+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 = The(cl_I)(expt(10,x)); // If x >= 0, 10^x is an integer.
+ 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
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 <cl_integer.h>}.
+objects of type @code{cl_I}, it should @code{#include <cln/integer.h>}.
@section Constructing numbers
@code{e} to 40 decimal places, first construct 1.0 to 40 decimal places
and then apply the exponential function:
@example
- cl_float_format_t precision = cl_float_format(40);
+ float_format_t precision = float_format(40);
cl_F e = exp(cl_float(1,precision));
@end example
@cindex @code{operator != ()}
Comparison, as in C and C++.
-@item uint32 cl_equal_hashcode (const @var{type}&)
-@cindex @code{cl_equal_hashcode ()}
+@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.
defines the following operations:
@table @code
-@item cl_signean cl_compare (const @var{type}& x, const @var{type}& y)
-@cindex @code{cl_compare ()}
+@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}.
The constant e = exp(1) = 2.71828@dots{} is returned by the following functions:
@table @code
-@item cl_F cl_exp1 (cl_float_format_t f)
+@item cl_F exp1 (float_format_t f)
@cindex @code{exp1 ()}
Returns e as a float of format @code{f}.
-@item cl_F cl_exp1 (const cl_F& y)
+@item cl_F exp1 (const cl_F& y)
Returns e in the float format of @code{y}.
-@item cl_F cl_exp1 (void)
-Returns e as a float of format @code{cl_default_float_format}.
+@item cl_F exp1 (void)
+Returns e as a float of format @code{default_float_format}.
@end table
@item cl_N cos (const cl_N& x)
Returns @code{cos(z)}. The range of the result is the entire complex plane.
-@item struct cl_cos_sin_t @{ cl_R cos; cl_R sin; @};
-@cindex @code{cl_cos_sin_t}
-@itemx cl_cos_sin_t cl_cos_sin (const cl_R& x)
+@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{cl_cos_sin ()}
+@cindex @code{cos_sin ()}
computing them separately. The relation @code{cos^2 + sin^2 = 1} will
hold only approximately.
Archimedes' constant pi = 3.14@dots{} is returned by the following functions:
@table @code
-@item cl_F cl_pi (cl_float_format_t f)
-@cindex @code{cl_pi ()}
+@item cl_F pi (float_format_t f)
+@cindex @code{pi ()}
Returns pi as a float of format @code{f}.
-@item cl_F cl_pi (const cl_F& y)
+@item cl_F pi (const cl_F& y)
Returns pi in the float format of @code{y}.
-@item cl_F cl_pi (void)
-Returns pi as a float of format @code{cl_default_float_format}.
+@item cl_F pi (void)
+Returns pi as a float of format @code{default_float_format}.
@end table
@item cl_N cosh (const cl_N& z)
Returns @code{cosh(z)}. The range of the result is the entire complex plane.
-@item struct cl_cosh_sinh_t @{ cl_R cosh; cl_R sinh; @};
-@cindex @code{cl_cosh_sinh_t}
-@itemx cl_cosh_sinh_t cl_cosh_sinh (const cl_R& x)
-@cindex @code{cl_cosh_sinh ()}
+@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.
Euler's constant C = 0.577@dots{} is returned by the following functions:
@table @code
-@item cl_F cl_eulerconst (cl_float_format_t f)
-@cindex @code{cl_eulerconst ()}
+@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 cl_eulerconst (const cl_F& y)
+@item cl_F eulerconst (const cl_F& y)
Returns Euler's constant in the float format of @code{y}.
-@item cl_F cl_eulerconst (void)
-Returns Euler's constant as a float of format @code{cl_default_float_format}.
+@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 cl_catalanconst (cl_float_format_t f)
-@cindex @code{cl_catalanconst ()}
+@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 cl_catalanconst (const cl_F& y)
+@item cl_F catalanconst (const cl_F& y)
Returns Catalan's constant in the float format of @code{y}.
-@item cl_F cl_catalanconst (void)
-Returns Catalan's constant as a float of format @code{cl_default_float_format}.
+@item cl_F catalanconst (void)
+Returns Catalan's constant as a float of format @code{default_float_format}.
@end table
following functions:
@table @code
-@item cl_F cl_zeta (int s, cl_float_format_t f)
-@cindex @code{cl_zeta ()}
+@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 cl_zeta (int s, const cl_F& y)
+@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 cl_zeta (int s)
+@item cl_F zeta (int s)
Returns Riemann's zeta function at @code{s} as a float of format
-@code{cl_default_float_format}.
+@code{default_float_format}.
@end table
@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 (sint32 a, sint32 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 cl_boolean 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
@end table
The complete internal representation of a float is encoded in the type
-@cindex @code{cl_decoded_float}
-@cindex @code{cl_decoded_sfloat}
-@cindex @code{cl_decoded_ffloat}
-@cindex @code{cl_decoded_dfloat}
-@cindex @code{cl_decoded_lfloat}
-@code{cl_decoded_float} (or @code{cl_decoded_sfloat}, @code{cl_decoded_ffloat},
-@code{cl_decoded_dfloat}, @code{cl_decoded_lfloat}, respectively), defined by
+@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 cl_decoded_@var{type}float @{
+struct decoded_@var{type}float @{
@var{type} mantissa; cl_I exponent; @var{type} sign;
@};
@end example
and returned by the function
@table @code
-@item cl_decoded_@var{type}float decode_float (const @var{type}& x)
+@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,
@end table
A complete decoding in terms of integers is provided as type
-@example
@cindex @code{cl_idecoded_float}
+@example
struct cl_idecoded_float @{
cl_I mantissa; cl_I exponent; cl_I sign;
@};
@subsection Conversion to floating-point numbers
-The type @code{cl_float_format_t} describes a floating-point format.
-@cindex @code{cl_float_format_t}
+The type @code{float_format_t} describes a floating-point format.
+@cindex @code{float_format_t}
@table @code
-@item cl_float_format_t cl_float_format (uintL n)
-@cindex @code{cl_float_format ()}
+@item float_format_t float_format (uintL 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 cl_float_format_t cl_float_format (const cl_F& x)
+@item float_format_t float_format (const cl_F& x)
Returns the floating point format of @code{x}.
-@item cl_float_format_t cl_default_float_format
-@cindex @code{cl_default_float_format}
+@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
defines the following operations:
@table @code
-@item cl_F cl_float (const @var{type}&x, cl_float_format_t f)
+@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{cl_default_float_format} if
+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
Every floating-point format has some characteristic numbers:
@table @code
-@item cl_F most_positive_float (cl_float_format_t f)
+@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 (cl_float_format_t 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 (cl_float_format_t 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 (cl_float_format_t 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 (cl_float_format_t 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 (cl_float_format_t f)
+@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
A random generator is a machine which produces (pseudo-)random numbers.
-The include file @code{<cl_random.h>} defines a class @code{cl_random_state}
+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.
a complicated but deterministic way.
The global variable
-@cindex @code{cl_random_state}
-@cindex @code{cl_default_random_state}
+@cindex @code{random_state}
+@cindex @code{default_random_state}
@example
-cl_random_state cl_default_random_state
+random_state default_random_state
@end example
contains a default random number generator. It is used when the functions
-below are called without @code{cl_random_state} argument.
+below are called without @code{random_state} argument.
@table @code
-@item uint32 random32 (cl_random_state& randomstate)
+@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 (cl_random_state& randomstate, const cl_I& n)
+@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 (cl_random_state& randomstate, const cl_F& 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 (cl_random_state& randomstate, const cl_R& 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}
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{cl_float_format}.
+function @samp{float_format}.
@item Complex numbers
External representation:
@section Input functions
-Including @code{<cl_io.h>} defines a type @code{cl_istream}, which is
-the type of the first argument to all input functions. Unless you build
-and use CLN with the macro CL_IO_STDIO being defined, @code{cl_istream}
-is the same as @code{istream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_istream cl_stdin}
-@end itemize
-contains the standard input stream.
-
-These are the simple 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 (cl_istream stream)
+@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 (cl_istream stream, int c)
+@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{<cl_@var{type}_io.h>}, the following input function:
+defines, in @code{<cln/@var{type}_io.h>}, the following input function:
@table @code
-@item cl_istream operator>> (cl_istream stream, @var{type}& result)
+@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{<cl_@var{type}_io.h>},
+The most flexible input functions, defined in @code{<cln/@var{type}_io.h>},
are the following:
@table @code
-@item cl_N read_complex (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_R read_real (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_F read_float (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_I read_integer (cl_istream stream, const cl_read_flags& flags)
+@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 unsigned int rational_base
The base in which rational numbers are read.
-@item cl_float_format_t float_flags.default_float_format
+@item float_format_t float_flags.default_float_format
The float format used when reading floats with exponent marker @samp{e}.
-@item cl_float_format_t float_flags.default_lfloat_format
+@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
@section Output functions
-Including @code{<cl_io.h>} defines a type @code{cl_ostream}, which is
-the type of the first argument to all output functions. Unless you build
-and use CLN with the macro CL_IO_STDIO being defined, @code{cl_ostream}
-is the same as @code{ostream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream cl_stdout}
-@end itemize
-contains the standard output stream.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream cl_stderr}
-@end itemize
-contains the standard error output stream.
-
-These are the simple 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 (cl_ostream stream, char c)
+@item void fprintchar (std::ostream& stream, char c)
Prints the character @code{x} literally on the @code{stream}.
-@item void fprint (cl_ostream stream, const char * string)
+@item void fprint (std::ostream& stream, const char * string)
Prints the @code{string} literally on the @code{stream}.
-@item void fprintdecimal (cl_ostream stream, int x)
-@itemx void fprintdecimal (cl_ostream stream, const cl_I& x)
+@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 (cl_ostream stream, const cl_I& x)
+@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 (cl_ostream stream, const cl_I& x)
+@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 (cl_ostream stream, const cl_I& x)
+@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{<cl_@var{type}_io.h>}, the following output functions:
+defines, in @code{<cln/@var{type}_io.h>}, the following output functions:
@table @code
-@item void fprint (cl_ostream stream, const @var{type}& x)
-@itemx cl_ostream operator<< (cl_ostream stream, const @var{type}& x)
+@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{cl_default_print_flags}.
+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{<cl_@var{type}_io.h>},
+The most flexible output function, defined in @code{<cln/@var{type}_io.h>},
are the following:
@example
-void print_complex (cl_ostream stream, const cl_print_flags& flags,
+void print_complex (std::ostream& stream, const cl_print_flags& flags,
const cl_N& z);
-void print_real (cl_ostream stream, const cl_print_flags& flags,
+void print_real (std::ostream& stream, const cl_print_flags& flags,
const cl_R& z);
-void print_float (cl_ostream stream, const cl_print_flags& flags,
+void print_float (std::ostream& stream, const cl_print_flags& flags,
const cl_F& z);
-void print_rational (cl_ostream stream, const cl_print_flags& flags,
+void print_rational (std::ostream& stream, const cl_print_flags& flags,
const cl_RA& z);
-void print_integer (cl_ostream stream, const cl_print_flags& flags,
+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
If this flag is true, type specific exponent markers have precedence over 'E'.
Default is false.
-@item cl_float_format_t default_float_format
+@item float_format_t default_float_format
Floating point numbers of this format will be printed using the 'E' exponent
-marker. Default is @code{cl_float_format_ffloat}.
+marker. Default is @code{float_format_ffloat}.
@item cl_boolean complex_readably
If this flag is true, complex numbers will be printed using the Common Lisp
using this variable name. Default is @code{"x"}.
@end table
-The global variable @code{cl_default_print_flags} contains the default values,
+The global variable @code{default_print_flags} contains the default values,
used by the function @code{fprint}.
@example
Ring
cl_ring
- <cl_ring.h>
+ <cln/ring.h>
@end example
Rings can be compared for equality:
Given a ring @code{R}, the following members can be used.
@table @code
-@item void R->fprint (cl_ostream stream, const cl_ring_element& x)
+@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)
+@cindex @code{equal ()}
@itemx cl_ring_element R->zero ()
+@cindex @code{zero ()}
@itemx cl_boolean 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_boolean 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
@example
Ring
cl_ring
- <cl_ring.h>
+ <cln/ring.h>
|
|
Modular integer ring
cl_modint_ring
- <cl_modinteger.h>
+ <cln/modinteger.h>
@end example
@cindex @code{cl_modint_ring}
@example
Modular integer
cl_MI
- <cl_modinteger.h>
+ <cln/modinteger.h>
@end example
Modular integer rings are constructed using the function
@table @code
-@item cl_modint_ring cl_find_modint_ring (const cl_I& N)
-@cindex @code{cl_find_modint_ring ()}
+@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,
@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{cl_find_modint_ring} with the same argument necessarily return the
+to @code{find_modint_ring} with the same argument necessarily return the
same ring because it is memoized in the cache table.
@end table
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(cl_random_state& randomstate)
+@item cl_MI R->random(random_state& randomstate)
@itemx cl_MI R->random()
@cindex @code{random ()}
This returns a random integer modulo @code{N}.
@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.
+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.
+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.
+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 ()}
input/output).
@table @code
-@item void fprint (cl_ostream stream, const cl_MI& x)
+@item void fprint (std::ostream& stream, const cl_MI& x)
@cindex @code{fprint ()}
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_MI& x)
+@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{cl_default_print_flags}.
+on the global printer settings in the variable @code{default_print_flags}.
@end table
@section Strings
@cindex string
+@cindex @code{cl_string}
The class
@example
String
cl_string
- <cl_string.h>
+ <cln/string.h>
@end example
implements immutable strings.
@table @code
@item cl_string (const char * s)
-@cindex @code{cl_string ()}
Returns an immutable copy of the (zero-terminated) C string @code{s}.
@item cl_string (const char * ptr, unsigned long len)
@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
@table @code
@item cl_symbol (const cl_string& s)
-@cindex @code{cl_symbol ()}
Looks up or creates a new symbol with a given name.
@end table
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{cl_default_print_flags.univpoly_varname}, which
+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.
@example
Ring
cl_ring
- <cl_ring.h>
+ <cln/ring.h>
|
|
Univariate polynomial ring
cl_univpoly_ring
- <cl_univpoly.h>
+ <cln/univpoly.h>
|
+----------------+-------------------+
| | |
Complex polynomial ring | Modular integer polynomial ring
cl_univpoly_complex_ring | cl_univpoly_modint_ring
- <cl_univpoly_complex.h> | <cl_univpoly_modint.h>
+ <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
|
+----------------+
| |
Real polynomial ring |
cl_univpoly_real_ring |
- <cl_univpoly_real.h> |
+ <cln/univpoly_real.h> |
|
+----------------+
| |
Rational polynomial ring |
cl_univpoly_rational_ring |
- <cl_univpoly_rational.h> |
+ <cln/univpoly_rational.h> |
|
+----------------+
|
Integer polynomial ring
cl_univpoly_integer_ring
- <cl_univpoly_integer.h>
+ <cln/univpoly_integer.h>
@end example
and the corresponding classes of univariate polynomials are
@example
Univariate polynomial
cl_UP
- <cl_univpoly.h>
+ <cln/univpoly.h>
|
+----------------+-------------------+
| | |
Complex polynomial | Modular integer polynomial
cl_UP_N | cl_UP_MI
- <cl_univpoly_complex.h> | <cl_univpoly_modint.h>
+ <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
|
+----------------+
| |
Real polynomial |
cl_UP_R |
- <cl_univpoly_real.h> |
+ <cln/univpoly_real.h> |
|
+----------------+
| |
Rational polynomial |
cl_UP_RA |
- <cl_univpoly_rational.h> |
+ <cln/univpoly_rational.h> |
|
+----------------+
|
Integer polynomial
cl_UP_I
- <cl_univpoly_integer.h>
+ <cln/univpoly_integer.h>
@end example
Univariate polynomial rings are constructed using the functions
@table @code
-@item cl_univpoly_ring cl_find_univpoly_ring (const cl_ring& R)
-@itemx cl_univpoly_ring cl_find_univpoly_ring (const cl_ring& R, const cl_symbol& varname)
+@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,
This ensures that two calls of this function with the same arguments will
return the same polynomial ring.
-@itemx cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring& R)
-@cindex @code{cl_find_univpoly_ring ()}
-@itemx cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring& R)
-@itemx cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring& R)
-@itemx cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring& R)
-@itemx cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring& R)
-@itemx cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname)
-These functions are equivalent to the general @code{cl_find_univpoly_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
@table @code
@item cl_ring R->basering()
@cindex @code{basering ()}
-This returns the base ring, as passed to @samp{cl_find_univpoly_ring}.
+This returns the base ring, as passed to @samp{find_univpoly_ring}.
@item cl_UP R->zero()
@cindex @code{zero ()}
@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 ()}
@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}.
input/output).
@table @code
-@item void fprint (cl_ostream stream, const cl_UP& x)
+@item void fprint (std::ostream& stream, const cl_UP& x)
@cindex @code{fprint ()}
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_UP& x)
+@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{cl_default_print_flags}.
+@code{default_print_flags}.
@end table
@section Special polynomials
The following functions return special polynomials.
@table @code
-@item cl_UP_I cl_tschebychev (sintL n)
-@cindex @code{cl_tschebychev ()}
-@cindex Tschebychev polynomial
-Returns the n-th Tchebychev polynomial (n >= 0).
+@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 cl_hermite (sintL n)
-@cindex @code{cl_hermite ()}
+@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 cl_legendre (sintL n)
-@cindex @code{cl_legendre ()}
+@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 cl_laguerre (sintL n)
-@cindex @code{cl_laguerre ()}
+@item cl_UP_I laguerre (sintL n)
+@cindex @code{laguerre ()}
@cindex Laguerre polynomial
Returns the n-th Laguerre polynomial (n >= 0).
@end table
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
@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:
+@example
+@code{AC_PATH_CLN([@var{MIN-VERSION}, [@var{ACTION-IF-FOUND} [, @var{ACTION-IF-NOT-FOUND}]]])}
+@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.ac}:
+@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.]))
+@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
@cindex include files
Here is a summary of the include files and their contents.
@table @code
-@item <cl_object.h>
+@item <cln/object.h>
General definitions, reference counting, garbage collection.
-@item <cl_number.h>
+@item <cln/number.h>
The class cl_number.
-@item <cl_complex.h>
+@item <cln/complex.h>
Functions for class cl_N, the complex numbers.
-@item <cl_real.h>
+@item <cln/real.h>
Functions for class cl_R, the real numbers.
-@item <cl_float.h>
+@item <cln/float.h>
Functions for class cl_F, the floats.
-@item <cl_sfloat.h>
+@item <cln/sfloat.h>
Functions for class cl_SF, the short-floats.
-@item <cl_ffloat.h>
+@item <cln/ffloat.h>
Functions for class cl_FF, the single-floats.
-@item <cl_dfloat.h>
+@item <cln/dfloat.h>
Functions for class cl_DF, the double-floats.
-@item <cl_lfloat.h>
+@item <cln/lfloat.h>
Functions for class cl_LF, the long-floats.
-@item <cl_rational.h>
+@item <cln/rational.h>
Functions for class cl_RA, the rational numbers.
-@item <cl_integer.h>
+@item <cln/integer.h>
Functions for class cl_I, the integers.
-@item <cl_io.h>
+@item <cln/io.h>
Input/Output.
-@item <cl_complex_io.h>
+@item <cln/complex_io.h>
Input/Output for class cl_N, the complex numbers.
-@item <cl_real_io.h>
+@item <cln/real_io.h>
Input/Output for class cl_R, the real numbers.
-@item <cl_float_io.h>
+@item <cln/float_io.h>
Input/Output for class cl_F, the floats.
-@item <cl_sfloat_io.h>
+@item <cln/sfloat_io.h>
Input/Output for class cl_SF, the short-floats.
-@item <cl_ffloat_io.h>
+@item <cln/ffloat_io.h>
Input/Output for class cl_FF, the single-floats.
-@item <cl_dfloat_io.h>
+@item <cln/dfloat_io.h>
Input/Output for class cl_DF, the double-floats.
-@item <cl_lfloat_io.h>
+@item <cln/lfloat_io.h>
Input/Output for class cl_LF, the long-floats.
-@item <cl_rational_io.h>
+@item <cln/rational_io.h>
Input/Output for class cl_RA, the rational numbers.
-@item <cl_integer_io.h>
+@item <cln/integer_io.h>
Input/Output for class cl_I, the integers.
-@item <cl_input.h>
+@item <cln/input.h>
Flags for customizing input operations.
-@item <cl_output.h>
+@item <cln/output.h>
Flags for customizing output operations.
-@item <cl_malloc.h>
-@code{cl_malloc_hook}, @code{cl_free_hook}.
-@item <cl_abort.h>
+@item <cln/malloc.h>
+@code{malloc_hook}, @code{free_hook}.
+@item <cln/abort.h>
@code{cl_abort}.
-@item <cl_condition.h>
+@item <cln/condition.h>
Conditions/exceptions.
-@item <cl_string.h>
+@item <cln/string.h>
Strings.
-@item <cl_symbol.h>
+@item <cln/symbol.h>
Symbols.
-@item <cl_proplist.h>
+@item <cln/proplist.h>
Property lists.
-@item <cl_ring.h>
+@item <cln/ring.h>
General rings.
-@item <cl_null_ring.h>
+@item <cln/null_ring.h>
The null ring.
-@item <cl_complex_ring.h>
+@item <cln/complex_ring.h>
The ring of complex numbers.
-@item <cl_real_ring.h>
+@item <cln/real_ring.h>
The ring of real numbers.
-@item <cl_rational_ring.h>
+@item <cln/rational_ring.h>
The ring of rational numbers.
-@item <cl_integer_ring.h>
+@item <cln/integer_ring.h>
The ring of integers.
-@item <cl_numtheory.h>
+@item <cln/numtheory.h>
Number threory functions.
-@item <cl_modinteger.h>
+@item <cln/modinteger.h>
Modular integers.
-@item <cl_V.h>
+@item <cln/V.h>
Vectors.
-@item <cl_GV.h>
+@item <cln/GV.h>
General vectors.
-@item <cl_GV_number.h>
+@item <cln/GV_number.h>
General vectors over cl_number.
-@item <cl_GV_complex.h>
+@item <cln/GV_complex.h>
General vectors over cl_N.
-@item <cl_GV_real.h>
+@item <cln/GV_real.h>
General vectors over cl_R.
-@item <cl_GV_rational.h>
+@item <cln/GV_rational.h>
General vectors over cl_RA.
-@item <cl_GV_integer.h>
+@item <cln/GV_integer.h>
General vectors over cl_I.
-@item <cl_GV_modinteger.h>
+@item <cln/GV_modinteger.h>
General vectors of modular integers.
-@item <cl_SV.h>
+@item <cln/SV.h>
Simple vectors.
-@item <cl_SV_number.h>
+@item <cln/SV_number.h>
Simple vectors over cl_number.
-@item <cl_SV_complex.h>
+@item <cln/SV_complex.h>
Simple vectors over cl_N.
-@item <cl_SV_real.h>
+@item <cln/SV_real.h>
Simple vectors over cl_R.
-@item <cl_SV_rational.h>
+@item <cln/SV_rational.h>
Simple vectors over cl_RA.
-@item <cl_SV_integer.h>
+@item <cln/SV_integer.h>
Simple vectors over cl_I.
-@item <cl_SV_ringelt.h>
+@item <cln/SV_ringelt.h>
Simple vectors of general ring elements.
-@item <cl_univpoly.h>
+@item <cln/univpoly.h>
Univariate polynomials.
-@item <cl_univpoly_integer.h>
+@item <cln/univpoly_integer.h>
Univariate polynomials over the integers.
-@item <cl_univpoly_rational.h>
+@item <cln/univpoly_rational.h>
Univariate polynomials over the rational numbers.
-@item <cl_univpoly_real.h>
+@item <cln/univpoly_real.h>
Univariate polynomials over the real numbers.
-@item <cl_univpoly_complex.h>
+@item <cln/univpoly_complex.h>
Univariate polynomials over the complex numbers.
-@item <cl_univpoly_modint.h>
+@item <cln/univpoly_modint.h>
Univariate polynomials over modular integer rings.
-@item <cl_timing.h>
+@item <cln/timing.h>
Timing facilities.
-@item <cln.h>
+@item <cln/cln.h>
Includes all of the above.
@end table
@cindex Fibonacci number
@example
-#include <cl_integer.h>
-#include <cl_real.h>
+#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.
- cl_float_format_t prec = cl_float_format((int)(0.208987641*n+5));
+ 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 );
Let's explain what is going on in detail.
-The include file @code{<cl_integer.h>} is necessary because the type
-@code{cl_I} is used in the function, and the include file @code{<cl_real.h>}
+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.
+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
@cindex @code{CL_DEBUG}
@example
#define CL_DEBUG
-#include <cl_string.h>
+#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:
To catch such a fatal error, you need to define the function @code{cl_abort}
yourself, with the prototype
@example
-#include <cl_abort.h>
+#include <cln/abort.h>
void cl_abort (void);
@end example
@cindex @code{cl_abort ()}
@section Customizing I/O
The output of the function @code{fprint} may be customized by changing the
-value of the global variable @code{cl_default_print_flags}.
-@cindex @code{cl_default_print_flags}
+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{cl_malloc_hook}. Freeing of this memory is done through the function
-pointer @code{cl_free_hook}. The default versions of these functions,
+@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{cl_malloc_hook} and @code{cl_free_hook} yourself,
+the variables @code{malloc_hook} and @code{free_hook} yourself,
like this:
@example
-#include <cl_malloc.h>
-void* (*cl_malloc_hook) (size_t size) = @dots{};
-void (*cl_free_hook) (void* ptr) = @dots{};
+#include <cln/malloc.h>
+namespace cln @{
+ void* (*malloc_hook) (size_t size) = @dots{};
+ void (*free_hook) (void* ptr) = @dots{};
+@}
@end example
-@cindex @code{cl_malloc_hook ()}
-@cindex @code{cl_free_hook ()}
+@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
@printindex my
-@c Table of contents
-@contents
-
-
@bye
git://www.ginac.de / cln.git / blobdiff