@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.
@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++ 2.95} or newer.
The following C++ features are used:
classes, member functions, overloading of functions and operators,
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.
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++
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++} 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++} 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 egcs-2.91.x (egcs-1.1) or 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, if you have @code{g++} version egcs-1.1.1 or older on Sparc, you must
-specify @samp{--disable-shared} because @code{g++} would miscompile parts of
-the library.
+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++} 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++} 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).
+
+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
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'')
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.
@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
@section Input functions
-Including @code{<cln/io.h>} defines a type @code{cl_istream}, which is
-the type of the first argument to all input functions. @code{cl_istream}
-is the same as @code{std::istream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_istream 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
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
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.
@section Output functions
-Including @code{<cln/io.h>} defines a type @code{cl_ostream}, which is
-the type of the first argument to all output functions. @code{cl_ostream}
-is the same as @code{std::ostream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream stdout}
-@end itemize
-contains the standard output stream.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream 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
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{default_print_flags}.
The @code{ostream} flags and settings (flags, width and locale) are
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
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 ()}
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{default_print_flags}.
@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
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
@printindex my
-@c Table of contents
-@contents
-
-
@bye
git://www.ginac.de / cln.git / blobdiff