@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
@c My own index.
@defindex my
@synindex pg my
@synindex tp my
+@ifnottex
+@node Top
+@top CLN
+@end ifnottex
@c For `info' only.
-@ifinfo
-This file documents @sc{cln}, a Class Library for Numbers.
+@ifnottex
+This manual 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, 2008.
+Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2017.
+Copyright (C) Alexei Sheplyakov 2008, 2010.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
-@end ifinfo
+@end ifnottex
@c For TeX only.
@titlepage
@title CLN, a Class Library for Numbers
-@author by Bruno Haible
+@author @uref{http://www.ginac.de/CLN}
@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, 2008.
+@sp 0
+Copyright @copyright{} Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014.
+@sp 0
+Copyright @copyright{} Alexei Sheplyakov 2008, 2010.
@sp 2
Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
-Richard Kreckel, @code{<kreckel@@ginac.de>}.
+Richard B. Kreckel, @code{<kreckel@@ginac.de>}.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
-by the author.
+by the authors.
@end titlepage
@page
+@iftex
+@c Table of contents
+@contents
+@end iftex
-@node Top, Introduction, (dir), (dir)
-
-@c @menu
-@c * Introduction:: Introduction
-@c @end menu
@menu
* Introduction::
* Internals::
* Using the library::
* Customizing::
-* Index::
+* Index::
+@detailmenu
--- The Detailed Node Listing ---
Installation
* Make utility::
* Sed utility::
+Building the library
+
+* Using the GNU MP Library::
+
Ordinary number types
* Exact numbers::
* Functions on floating-point numbers::
* Conversion functions::
* Random number generators::
-* Obfuscating operators::
+* Modifying operators::
Constructing numbers
* Include files::
* An Example::
* Debugging support::
+* Reporting Problems::
Customizing
* Floating-point underflow::
* Customizing I/O::
* Customizing the memory allocator::
+
+@end detailmenu
@end menu
-@node Introduction, Installation, Top, Top
-@comment node-name, next, previous, up
+@node Introduction
@chapter Introduction
@noindent
The kernel of CLN has been written in assembly language for some CPUs
(@code{i386}, @code{m68k}, @code{sparc}, @code{mips}, @code{arm}).
@item
-On all CPUs, CLN uses the superefficient low-level routines from GNU
-GMP version 2.
+@cindex GMP
+On all CPUs, CLN may be configured to use the superefficient low-level
+routines from GNU GMP version 3.
@item
It uses Karatsuba multiplication, which is significantly faster
for large numbers than the standard multiplication algorithm.
For very large numbers (more than 12000 decimal digits), it uses
@iftex
Sch{@"o}nhage-Strassen
+@cindex Sch{@"o}nhage-Strassen multiplication
@end iftex
@ifinfo
-Schönhage-Strassen
+Schoenhage-Strassen
+@cindex Schoenhage-Strassen multiplication
@end ifinfo
-multiplication, which is an asymptotically
-optimal multiplication algorithm, for multiplication, division and
-radix conversion.
+multiplication, which is an asymptotically optimal multiplication
+algorithm, for multiplication, division and radix conversion.
+@item
+@cindex binary splitting
+It uses binary splitting for fast evaluation of series of rational
+numbers as they occur in the evaluation of elementary functions and some
+constants.
@end itemize
@noindent
@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
+order to avoid name clashes.
@end itemize
-@node Installation, Ordinary number types, Introduction, Top
+@node Installation
@chapter Installation
This section describes how to install the CLN package on your system.
* Sed utility::
@end menu
-@node C++ compiler, Make utility, Prerequisites, Prerequisites
+@node C++ compiler
@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{egcs 1.1} or newer.
+To build CLN, you need a C++11 compiler.
+GNU @code{g++ 4.8.1} or newer is recommended.
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.
-
-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.
+@code{new}, @code{delete}, virtual inheritance.
-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
+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.
-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
-
-@node Make utility, Sed utility, C++ compiler, Prerequisites
+@node Make utility
@subsection Make utility
+@cindex @code{make}
To build CLN, you also need to have GNU @code{make} installed.
-@node Sed utility, , Make utility, Prerequisites
+@node Sed utility
@subsection Sed utility
+@cindex @code{sed}
To build CLN on HP-UX, you also need to have GNU @code{sed} installed.
This is because the libtool script, which creates the CLN library, relies
limited.
-@node Building the library, Installing the library, Prerequisites, Installation
+@node Building the library
@section Building the library
As with any autoconfiguring GNU software, installation is as easy as this:
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.
-The @code{make check} runs some test to check that no important subroutine
-has been miscompiled.
+builds the library. This step may take about half an hour on an average
+workstation. The @code{make check} runs some test to check that no
+important subroutine has been miscompiled.
The @code{configure} command accepts options. To get a summary of them, try
@item CXXFLAGS
Flags to be given to the C++ compiler when compiling programs (not when linking).
+
+@item CPPFLAGS
+Flags to be given to the C/C++ preprocessor.
+
+@item LDFLAGS
+Flags to be given to the linker.
@end table
Examples:
@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
@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
+$ CC=gcc CFLAGS="-O2 -finline-limit=1000" \
+ CXX=g++ CXXFLAGS="-O2 -finline-limit=1000" \
+ CPPFLAGS="-DNO_ASM" ./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-9" CFLAGS="-O2" CXX="g++-9" 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
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 be
+compiled with @code{-O}.
+
+The assembler language kernel can be turned off by specifying
+@code{-DNO_ASM} in the CPPFLAGS. If @code{make check} reports any
+problems, you may try to clean up (see @ref{Cleaning up}) and configure
+and compile again, this time with @code{-DNO_ASM}.
-If you use @code{g++} 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++} 3.2.x or earlier, I recommend adding
+@samp{-finline-limit=1000} to the CXXFLAGS. This is essential for good
+code.
-If you use @code{g++} 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. 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.
+Also, please do not compile CLN with @code{g++} using the @code{-O3}
+optimization level. This leads to inferior code quality.
-On MIPS (SGI Irix 6), pass option @code{--without-gmp} to configure. gmp does
-not work when compiled in @samp{n32} binary format on Irix.
+Some newer versions of @code{g++} require quite an amount of memory.
+You might need some swap space if your machine doesn't have 512 MB of
+RAM.
-By default, 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}.
+By default, both a shared and a static library are built. You can build
+CLN as a static (or shared) library only, by calling @code{configure}
+with the option @samp{--disable-shared} (or @samp{--disable-static}).
+While shared libraries are usually more convenient to use, they may not
+work on all architectures. Try disabling them if you run into linker
+problems. Also, they are generally slightly slower than static
+libraries so runtime-critical applications should be linked statically.
-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.
+@menu
+* Using the GNU MP Library::
+@end menu
+
+@node Using the GNU MP Library
+@subsection Using the GNU MP Library
+@cindex GMP
+
+CLN may be configured to make use of a preinstalled @code{gmp} library
+for some low-level routines. Please make sure that you have at least
+@code{gmp} version 3.0 installed since earlier versions are unsupported
+and likely not to work. Using @code{gmp} is known to be quite a boost
+for CLN's performance.
+
+By default, CLN will autodetect @code{gmp} and use it. If you do not
+want CLN to make use of a preinstalled @code{gmp} library, then you can
+explicitly specify so by calling @code{configure} with the option
+@samp{--without-gmp}.
+
+If you have installed the @code{gmp} library and its header files in
+some place where the compiler cannot find it by default, you must help
+@code{configure} and specify the prefix that was used when @code{gmp}
+was configured. Here is an example:
+
+@example
+$ ./configure --with-gmp=/opt/gmp-4.2.2
+@end example
-@node Installing the library, Cleaning up, Building the library, Installation
+This assumes that the @code{gmp} header files have been installed in
+@file{/opt/gmp-4.2.2/include/} and the library in
+@file{/opt/gmp-4.2.2/lib/}. More uncommon GMP installations can be
+handled by setting CPPFLAGS and LDFLAGS appropriately prior to running
+@code{configure}.
+
+
+@node Installing the library
@section Installing the library
+@cindex installation
As with any autoconfiguring GNU software, installation is as easy as this:
the @code{--prefix=@dots{}} option.
-@node Cleaning up, , Installing the library, Installation
+@node Cleaning up
@section Cleaning up
You can remove system-dependent files generated by @code{make} through
@end example
-@node Ordinary number types, Functions on numbers, Installation, Top
+@node Ordinary number types
@chapter Ordinary number types
CLN implements the following class hierarchy:
@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}
+@cindex abstract class
The base class @code{cl_number} is an abstract base class.
It is not useful to declare a variable of this type except if you want
to completely disable compile-time type checking and use run-time type
checking instead.
+@cindex @code{cl_N}
+@cindex real number
+@cindex complex number
The class @code{cl_N} comprises real and complex numbers. There is
no special class for complex numbers since complex numbers with imaginary
part @code{0} are automatically converted to real numbers.
+@cindex @code{cl_R}
The class @code{cl_R} comprises real numbers of different kinds. It is an
abstract class.
+@cindex @code{cl_RA}
+@cindex rational number
+@cindex integer
The class @code{cl_RA} comprises exact real numbers: rational numbers, including
integers. There is no special class for non-integral rational numbers
since rational numbers with denominator @code{1} are automatically converted
to integers.
+@cindex @code{cl_F}
The class @code{cl_F} implements floating-point approximations to real numbers.
It is an abstract class.
* Conversions::
@end menu
-@node Exact numbers, Floating-point numbers, Ordinary number types, Ordinary number types
+@node Exact numbers
@section Exact numbers
+@cindex exact number
Some numbers are represented as exact numbers: there is no loss of information
when such a number is converted from its mathematical value to its internal
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'')
is completely transparent.
-@node Floating-point numbers, Complex numbers, Exact numbers, Ordinary number types
+@node Floating-point numbers
@section Floating-point numbers
+@cindex floating-point number
Not all real numbers can be represented exactly. (There is an easy mathematical
proof for this: Only a countable set of numbers can be stored exactly in
are uncountably many real numbers.) So some approximation is needed.
CLN implements ordinary floating-point numbers, with mantissa and exponent.
+@cindex rounding error
The elementary operations (@code{+}, @code{-}, @code{*}, @code{/}, @dots{})
only return approximate results. For example, the value of the expression
@code{(cl_F) 0.3 + (cl_F) 0.4} prints as @samp{0.70000005}, not as
@itemize @bullet
@item
+@cindex @code{cl_SF}
Short floats, type @code{cl_SF}.
They have 1 sign bit, 8 exponent bits (including the exponent's sign),
and 17 mantissa bits (including the ``hidden'' bit).
They don't consume heap allocation.
@item
+@cindex @code{cl_FF}
Single floats, type @code{cl_FF}.
They have 1 sign bit, 8 exponent bits (including the exponent's sign),
and 24 mantissa bits (including the ``hidden'' bit).
This corresponds closely to the C/C++ type @samp{float}.
@item
+@cindex @code{cl_DF}
Double floats, type @code{cl_DF}.
They have 1 sign bit, 11 exponent bits (including the exponent's sign),
and 53 mantissa bits (including the ``hidden'' bit).
This corresponds closely to the C/C++ type @samp{double}.
@item
+@cindex @code{cl_LF}
Long floats, type @code{cl_LF}.
They have 1 sign bit, 32 exponent bits (including the exponent's sign),
and n mantissa bits (including the ``hidden'' bit), where n >= 64.
is too limited for your application, choose another floating-point type
with larger exponent range.
+@cindex @code{cl_F}
As a user of CLN, you can forget about the differences between the
four floating-point types and just declare all your floating-point
variables as being of type @code{cl_F}. This has the advantage that
the floating point contagion rule happened to change in the future.)
-@node Complex numbers, Conversions, Floating-point numbers, Ordinary number types
+@node Complex numbers
@section Complex numbers
+@cindex complex number
Complex numbers, as implemented by the class @code{cl_N}, have a real
part and an imaginary part, both real numbers. A complex number whose
through application of @code{sqrt} or transcendental functions.
-@node Conversions, , Complex numbers, Ordinary number types
+@node Conversions
@section Conversions
+@cindex conversion
Conversions from any class to any its superclasses (``base classes'' in
C++ terminology) is done automatically.
Conversions from the C built-in types @samp{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}.
@code{cl_R}, @code{cl_N}.
The easiest way to specify a value which is outside of the range of the
C++ built-in types is therefore to specify it as a string, like this:
+@cindex Rubik's cube
@example
cl_I order_of_rubiks_cube_group = "43252003274489856000";
@end example
@table @code
@item int cl_I_to_int (const cl_I& x)
+@cindex @code{cl_I_to_int ()}
@itemx unsigned int cl_I_to_uint (const cl_I& x)
+@cindex @code{cl_I_to_uint ()}
@itemx long cl_I_to_long (const cl_I& x)
+@cindex @code{cl_I_to_long ()}
@itemx unsigned long cl_I_to_ulong (const cl_I& x)
+@cindex @code{cl_I_to_ulong ()}
Returns @code{x} as element of the C type @var{ctype}. If @code{x} is not
representable in the range of @var{ctype}, a runtime error occurs.
@end table
the functions
@table @code
-@item float cl_float_approx (const @var{type}& x)
-@itemx double cl_double_approx (const @var{type}& x)
+@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
-@node Functions on numbers, Input/Output, Ordinary number types, Top
+@node Functions on numbers
@chapter Functions on numbers
Each of the number classes declares its mathematical operations in the
corresponding include file. For example, if your code operates with
-objects of type @code{cl_I}, it should @code{#include <cl_integer.h>}.
+objects of type @code{cl_I}, it should @code{#include <cln/integer.h>}.
@menu
* Functions on floating-point numbers::
* Conversion functions::
* Random number generators::
-* Obfuscating operators::
+* Modifying operators::
@end menu
-@node Constructing numbers, Elementary functions, Functions on numbers, Functions on numbers
+@node Constructing numbers
@section Constructing numbers
Here is how to create number objects ``from nothing''.
* Constructing complex numbers::
@end menu
-@node Constructing integers, Constructing rational numbers, Constructing numbers, Constructing numbers
+@node Constructing integers
@subsection Constructing integers
@code{cl_I} objects are most easily constructed from C integers and from
strings. See @ref{Conversions}.
-@node Constructing rational numbers, Constructing floating-point numbers, Constructing integers, Constructing numbers
+@node Constructing rational numbers
@subsection Constructing rational numbers
@code{cl_RA} objects can be constructed from strings. The syntax
of @samp{operator /} or @samp{recip} on integers.
-@node Constructing floating-point numbers, Constructing complex numbers, Constructing rational numbers, Constructing numbers
+@node Constructing floating-point numbers
@subsection Constructing floating-point numbers
@code{cl_F} objects with low precision are most easily constructed from
@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
-@node Constructing complex numbers, , Constructing floating-point numbers, Constructing numbers
+@node Constructing complex numbers
@subsection Constructing complex numbers
Non-real @code{cl_N} objects are normally constructed through the function
See @ref{Elementary complex functions}.
-@node Elementary functions, Elementary rational functions, Constructing numbers, Functions on numbers
+@node Elementary functions
@section Elementary functions
Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
@table @code
@item @var{type} operator + (const @var{type}&, const @var{type}&)
+@cindex @code{operator + ()}
Addition.
@item @var{type} operator - (const @var{type}&, const @var{type}&)
+@cindex @code{operator - ()}
Subtraction.
@item @var{type} operator - (const @var{type}&)
Returns the negative of the argument.
@item @var{type} plus1 (const @var{type}& x)
+@cindex @code{plus1 ()}
Returns @code{x + 1}.
@item @var{type} minus1 (const @var{type}& x)
+@cindex @code{minus1 ()}
Returns @code{x - 1}.
@item @var{type} operator * (const @var{type}&, const @var{type}&)
+@cindex @code{operator * ()}
Multiplication.
@item @var{type} square (const @var{type}& x)
+@cindex @code{square ()}
Returns @code{x * x}.
@end table
@table @code
@item @var{type} operator / (const @var{type}&, const @var{type}&)
+@cindex @code{operator / ()}
Division.
@item @var{type} recip (const @var{type}&)
+@cindex @code{recip ()}
Returns the reciprocal of the argument.
@end table
The class @code{cl_I} doesn't define a @samp{/} operation because
in the C/C++ language this operator, applied to integral types,
denotes the @samp{floor} or @samp{truncate} operation (which one of these,
-is implementation dependent). (@xref{Rounding functions})
+is implementation dependent). (@xref{Rounding functions}.)
Instead, @code{cl_I} defines an ``exact quotient'' function:
@table @code
@item cl_I exquo (const cl_I& x, const cl_I& y)
+@cindex @code{exquo ()}
Checks that @code{y} divides @code{x}, and returns the quotient @code{x}/@code{y}.
@end table
@table @code
@item cl_I expt_pos (const cl_I& x, const cl_I& y)
+@cindex @code{expt_pos ()}
@itemx cl_RA expt_pos (const cl_RA& x, const cl_I& y)
@code{y} must be > 0. Returns @code{x^y}.
@item cl_RA expt (const cl_RA& x, const cl_I& y)
+@cindex @code{expt ()}
@itemx cl_R expt (const cl_R& x, const cl_I& y)
@itemx cl_N expt (const cl_N& x, const cl_I& y)
Returns @code{x^y}.
@table @code
@item @var{type} abs (const @var{type}& x)
+@cindex @code{abs ()}
Returns the absolute value of @code{x}.
This is @code{x} if @code{x >= 0}, and @code{-x} if @code{x <= 0}.
@end table
@table @code
@item @var{type} signum (const @var{type}& x)
+@cindex @code{signum ()}
Returns the sign of @code{x}, in the same number format as @code{x}.
This is defined as @code{x / abs(x)} if @code{x} is non-zero, and
@code{x} if @code{x} is zero. If @code{x} is real, the value is either
@end table
-@node Elementary rational functions, Elementary complex functions, Elementary functions, Functions on numbers
+@node Elementary rational functions
@section Elementary rational functions
Each of the classes @code{cl_RA}, @code{cl_I} defines the following operations:
@table @code
@item cl_I numerator (const @var{type}& x)
+@cindex @code{numerator ()}
Returns the numerator of @code{x}.
@item cl_I denominator (const @var{type}& x)
+@cindex @code{denominator ()}
Returns the denominator of @code{x}.
@end table
a way that they have no factor in common and the denominator is positive.
-@node Elementary complex functions, Comparisons, Elementary rational functions, Functions on numbers
+@node Elementary complex functions
@section Elementary complex functions
The class @code{cl_N} defines the following operation:
@table @code
@item cl_N complex (const cl_R& a, const cl_R& b)
+@cindex @code{complex ()}
Returns the complex number @code{a+bi}, that is, the complex number with
real part @code{a} and imaginary part @code{b}.
@end table
@table @code
@item cl_R realpart (const @var{type}& x)
+@cindex @code{realpart ()}
Returns the real part of @code{x}.
@item cl_R imagpart (const @var{type}& x)
+@cindex @code{imagpart ()}
Returns the imaginary part of @code{x}.
@item @var{type} conjugate (const @var{type}& x)
+@cindex @code{conjugate ()}
Returns the complex conjugate of @code{x}.
@end table
We have the relations
-@itemize @asis
+@itemize @w{}
@item
@code{x = complex(realpart(x), imagpart(x))}
@item
@end itemize
-@node Comparisons, Rounding functions, Elementary complex functions, Functions on numbers
+@node Comparisons
@section Comparisons
+@cindex comparison
Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
@table @code
@item bool operator == (const @var{type}&, const @var{type}&)
+@cindex @code{operator == ()}
@itemx bool operator != (const @var{type}&, const @var{type}&)
+@cindex @code{operator != ()}
Comparison, as in C and C++.
-@item uint32 cl_equal_hashcode (const @var{type}&)
+@item uint32 equal_hashcode (const @var{type}&)
+@cindex @code{equal_hashcode ()}
Returns a 32-bit hash code that is the same for any two numbers which are
the same according to @code{==}. This hash code depends on the number's value,
not its type or precision.
-@item 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
defines the following operations:
@table @code
-@item cl_signean cl_compare (const @var{type}& x, const @var{type}& y)
+@item cl_signean compare (const @var{type}& x, const @var{type}& y)
+@cindex @code{compare ()}
Compares @code{x} and @code{y}. Returns +1 if @code{x}>@code{y},
-1 if @code{x}<@code{y}, 0 if @code{x}=@code{y}.
@item bool operator <= (const @var{type}&, const @var{type}&)
+@cindex @code{operator <= ()}
@itemx bool operator < (const @var{type}&, const @var{type}&)
+@cindex @code{operator < ()}
@itemx bool operator >= (const @var{type}&, const @var{type}&)
+@cindex @code{operator >= ()}
@itemx bool operator > (const @var{type}&, const @var{type}&)
+@cindex @code{operator > ()}
Comparison, as in C and C++.
-@item 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}
@item @var{type} max (const @var{type}& x, const @var{type}& y)
+@cindex @code{max ()}
Return the maximum of @code{x} and @code{y}.
@item @var{type} min (const @var{type}& x, const @var{type}& y)
+@cindex @code{min ()}
Return the minimum of @code{x} and @code{y}.
@end table
there is no floating point number whose value is exactly @code{1/3}.
-@node Rounding functions, Roots, Comparisons, Functions on numbers
+@node Rounding functions
@section Rounding functions
+@cindex rounding
When a real number is to be converted to an integer, there is no ``best''
rounding. The desired rounding function depends on the application.
The functions are related like this:
-@itemize @asis
+@itemize @w{}
@item
@code{ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1}
for rational numbers @code{m/n} (@code{m}, @code{n} integers, @code{n}>0), and
@table @code
@item cl_I floor1 (const @var{type}& x)
+@cindex @code{floor1 ()}
Returns @code{floor(x)}.
@item cl_I ceiling1 (const @var{type}& x)
+@cindex @code{ceiling1 ()}
Returns @code{ceiling(x)}.
@item cl_I truncate1 (const @var{type}& x)
+@cindex @code{truncate1 ()}
Returns @code{truncate(x)}.
@item cl_I round1 (const @var{type}& x)
+@cindex @code{round1 ()}
Returns @code{round(x)}.
@end table
@table @code
@item struct @var{type}_div_t @{ cl_I quotient; @var{type} remainder; @};
@itemx @var{type}_div_t floor2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{floor2 ()}
@itemx @var{type}_div_t ceiling2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{ceiling2 ()}
@itemx @var{type}_div_t truncate2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{truncate2 ()}
@itemx @var{type}_div_t round2 (const @var{type}& x, const @var{type}& y)
+@cindex @code{round2 ()}
@end table
Sometimes, one wants the quotient as a floating-point number (of the
@table @code
@item @var{type} ffloor (const @var{type}& x)
+@cindex @code{ffloor ()}
@itemx @var{type} fceiling (const @var{type}& x)
+@cindex @code{fceiling ()}
@itemx @var{type} ftruncate (const @var{type}& x)
+@cindex @code{ftruncate ()}
@itemx @var{type} fround (const @var{type}& x)
+@cindex @code{fround ()}
@end table
and similarly for class @code{cl_R}, but with return type @code{cl_F}.
Each of the classes
@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
defines the following operations:
+@cindex @code{cl_F_fdiv_t}
+@cindex @code{cl_SF_fdiv_t}
+@cindex @code{cl_FF_fdiv_t}
+@cindex @code{cl_DF_fdiv_t}
+@cindex @code{cl_LF_fdiv_t}
@table @code
@item struct @var{type}_fdiv_t @{ @var{type} quotient; @var{type} remainder; @};
@itemx @var{type}_fdiv_t ffloor2 (const @var{type}& x)
+@cindex @code{ffloor2 ()}
@itemx @var{type}_fdiv_t fceiling2 (const @var{type}& x)
+@cindex @code{fceiling2 ()}
@itemx @var{type}_fdiv_t ftruncate2 (const @var{type}& x)
+@cindex @code{ftruncate2 ()}
@itemx @var{type}_fdiv_t fround2 (const @var{type}& x)
+@cindex @code{fround2 ()}
@end table
and similarly for class @code{cl_R}, but with quotient type @code{cl_F}.
+@cindex @code{cl_R_fdiv_t}
The class @code{cl_R} defines the following operations:
@table @code
@item @var{type} mod (const @var{type}& x, const @var{type}& y)
+@cindex @code{mod ()}
@itemx @var{type} rem (const @var{type}& x, const @var{type}& y)
+@cindex @code{rem ()}
@end table
-@node Roots, Transcendental functions, Rounding functions, Functions on numbers
+@node Roots
@section Roots
Each of the classes @code{cl_R},
@table @code
@item @var{type} sqrt (const @var{type}& x)
+@cindex @code{sqrt ()}
@code{x} must be >= 0. This function returns the square root of @code{x},
normalized to be >= 0. If @code{x} is the square of a rational number,
@code{sqrt(x)} will be a rational number, else it will return a
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.
@end table
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}:
the boolean value @code{(expt(*root,2) == x)}.
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.
If so, it returns true and the exact root in @code{*root}, else it returns
@table @code
@item cl_N sqrt (const cl_N& z)
+@cindex @code{sqrt ()}
Returns the square root of @code{z}, as defined by the formula
@code{sqrt(z) = exp(log(z)/2)}. Conversion to a floating-point type
or to a complex number are done if necessary. The range of the result is the
@end table
-@node Transcendental functions, Functions on integers, Roots, Functions on numbers
+@node Transcendental functions
@section Transcendental functions
-
+@cindex transcendental functions
The transcendental functions return an exact result if the argument
is exact and the result is exact as well. Otherwise they must return
* Riemann zeta::
@end menu
-@node Exponential and logarithmic functions, Trigonometric functions, Transcendental functions, Transcendental functions
+@node Exponential and logarithmic functions
@subsection Exponential and logarithmic functions
@table @code
@item cl_R exp (const cl_R& x)
+@cindex @code{exp ()}
@itemx cl_N exp (const cl_N& x)
Returns the exponential function of @code{x}. This is @code{e^x} where
@code{e} is the base of the natural logarithms. The range of the result
is the entire complex plane excluding 0.
@item cl_R ln (const cl_R& x)
+@cindex @code{ln ()}
@code{x} must be > 0. Returns the (natural) logarithm of x.
@item cl_N log (const cl_N& x)
+@cindex @code{log ()}
Returns the (natural) logarithm of x. If @code{x} is real and positive,
this is @code{ln(x)}. In general, @code{log(x) = log(abs(x)) + i*phase(x)}.
The range of the result is the strip in the complex plane
@code{-pi < imagpart(log(x)) <= pi}.
@item cl_R phase (const cl_N& x)
+@cindex @code{phase ()}
Returns the angle part of @code{x} in its polar representation as a
complex number. That is, @code{phase(x) = atan(realpart(x),imagpart(x))}.
This is also the imaginary part of @code{log(x)}.
@code{log(a,b) = log(a)/log(b)}.
@item cl_N expt (const cl_N& x, const cl_N& y)
+@cindex @code{expt ()}
Exponentiation: Returns @code{x^y = exp(y*log(x))}.
@end table
The constant e = exp(1) = 2.71828@dots{} is returned by the following functions:
@table @code
-@item cl_F 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
-@node Trigonometric functions, Hyperbolic functions, Exponential and logarithmic functions, Transcendental functions
+@node Trigonometric functions
@subsection Trigonometric functions
@table @code
@item cl_R sin (const cl_R& x)
+@cindex @code{sin ()}
Returns @code{sin(x)}. The range of the result is the interval
@code{-1 <= sin(x) <= 1}.
Returns @code{sin(z)}. The range of the result is the entire complex plane.
@item cl_R cos (const cl_R& x)
+@cindex @code{cos ()}
Returns @code{cos(x)}. The range of the result is the interval
@code{-1 <= cos(x) <= 1}.
@item cl_N cos (const cl_N& x)
Returns @code{cos(z)}. The range of the result is the entire complex plane.
-@item struct cl_cos_sin_t @{ cl_R cos; cl_R sin; @};
-@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{cos_sin ()}
computing them separately. The relation @code{cos^2 + sin^2 = 1} will
hold only approximately.
@item cl_R tan (const cl_R& x)
+@cindex @code{tan ()}
@itemx cl_N tan (const cl_N& x)
Returns @code{tan(x) = sin(x)/cos(x)}.
@item cl_N cis (const cl_R& x)
+@cindex @code{cis ()}
@itemx cl_N cis (const cl_N& x)
Returns @code{exp(i*x)}. The name @samp{cis} means ``cos + i sin'', because
@code{e^(i*x) = cos(x) + i*sin(x)}.
+@cindex @code{asin}
+@cindex @code{asin ()}
@item cl_N asin (const cl_N& z)
Returns @code{arcsin(z)}. This is defined as
@code{arcsin(z) = log(iz+sqrt(1-z^2))/i} and satisfies
@end ignore
@item cl_N acos (const cl_N& z)
+@cindex @code{acos ()}
Returns @code{arccos(z)}. This is defined as
@code{arccos(z) = pi/2 - arcsin(z) = log(z+i*sqrt(1-z^2))/i}
@ignore
Proof: This follows from the results about arcsin.
@end ignore
+@cindex @code{atan}
+@cindex @code{atan ()}
@item cl_R atan (const cl_R& x, const cl_R& y)
Returns the angle of the polar representation of the complex number
@code{x+iy}. This is @code{atan(y/x)} if @code{x>0}. The range of
@end table
-The constant pi = 3.14@dots{} is returned by the following functions:
+@cindex pi
+@cindex Archimedes' constant
+Archimedes' constant pi = 3.14@dots{} is returned by the following functions:
@table @code
-@item cl_F cl_pi (cl_float_format_t f)
+@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
-@node Hyperbolic functions, Euler gamma, Trigonometric functions, Transcendental functions
+@node Hyperbolic functions
@subsection Hyperbolic functions
@table @code
@item cl_R sinh (const cl_R& x)
+@cindex @code{sinh ()}
Returns @code{sinh(x)}.
@item cl_N sinh (const cl_N& z)
Returns @code{sinh(z)}. The range of the result is the entire complex plane.
@item cl_R cosh (const cl_R& x)
+@cindex @code{cosh ()}
Returns @code{cosh(x)}. The range of the result is the interval
@code{cosh(x) >= 1}.
@item cl_N cosh (const cl_N& z)
Returns @code{cosh(z)}. The range of the result is the entire complex plane.
-@item struct cl_cosh_sinh_t @{ cl_R cosh; cl_R sinh; @};
-@itemx cl_cosh_sinh_t cl_cosh_sinh (const cl_R& x)
+@item struct cosh_sinh_t @{ cl_R cosh; cl_R sinh; @};
+@cindex @code{cosh_sinh_t}
+@itemx cosh_sinh_t cosh_sinh (const cl_R& x)
+@cindex @code{cosh_sinh ()}
Returns both @code{sinh(x)} and @code{cosh(x)}. This is more efficient than
computing them separately. The relation @code{cosh^2 - sinh^2 = 1} will
hold only approximately.
@item cl_R tanh (const cl_R& x)
+@cindex @code{tanh ()}
@itemx cl_N tanh (const cl_N& x)
Returns @code{tanh(x) = sinh(x)/cosh(x)}.
@item cl_N asinh (const cl_N& z)
+@cindex @code{asinh ()}
Returns @code{arsinh(z)}. This is defined as
@code{arsinh(z) = log(z+sqrt(1+z^2))} and satisfies
@code{arsinh(-z) = -arsinh(z)}.
@end ignore
@item cl_N acosh (const cl_N& z)
+@cindex @code{acosh ()}
Returns @code{arcosh(z)}. This is defined as
@code{arcosh(z) = 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))}.
The range of the result is the half-strip in the complex domain
@end ignore
@item cl_N atanh (const cl_N& z)
+@cindex @code{atanh ()}
Returns @code{artanh(z)}. This is defined as
@code{artanh(z) = (log(1+z)-log(1-z)) / 2} and satisfies
@code{artanh(-z) = -artanh(z)}. The range of the result is
@end table
-@node Euler gamma, Riemann zeta, Hyperbolic functions, Transcendental functions
+@node Euler gamma
@subsection Euler gamma
+@cindex Euler's constant
Euler's constant C = 0.577@dots{} is returned by the following functions:
@table @code
-@item cl_F cl_eulerconst (cl_float_format_t f)
+@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)
+@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
-@node Riemann zeta, , Euler gamma, Transcendental functions
+@node Riemann zeta
@subsection Riemann zeta
+@cindex Riemann's zeta
Riemann's zeta function at an integral point @code{s>1} is returned by the
following functions:
@table @code
-@item cl_F cl_zeta (int s, cl_float_format_t f)
+@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
-@node Functions on integers, Functions on floating-point numbers, Transcendental functions, Functions on numbers
+@node Functions on integers
@section Functions on integers
@menu
* Combinatorial functions::
@end menu
-@node Logical functions, Number theoretic functions, Functions on integers, Functions on integers
+@node Logical functions
@subsection Logical functions
Integers, when viewed as in two's complement notation, can be thought as
@table @code
@item cl_I lognot (const cl_I& x)
+@cindex @code{lognot ()}
@itemx cl_I operator ~ (const cl_I& x)
+@cindex @code{operator ~ ()}
Logical not, like @code{~x} in C. This is the same as @code{-1-x}.
@item cl_I logand (const cl_I& x, const cl_I& y)
+@cindex @code{logand ()}
@itemx cl_I operator & (const cl_I& x, const cl_I& y)
+@cindex @code{operator & ()}
Logical and, like @code{x & y} in C.
@item cl_I logior (const cl_I& x, const cl_I& y)
+@cindex @code{logior ()}
@itemx cl_I operator | (const cl_I& x, const cl_I& y)
+@cindex @code{operator | ()}
Logical (inclusive) or, like @code{x | y} in C.
@item cl_I logxor (const cl_I& x, const cl_I& y)
+@cindex @code{logxor ()}
@itemx cl_I operator ^ (const cl_I& x, const cl_I& y)
+@cindex @code{operator ^ ()}
Exclusive or, like @code{x ^ y} in C.
@item cl_I logeqv (const cl_I& x, const cl_I& y)
+@cindex @code{logeqv ()}
Bitwise equivalence, like @code{~(x ^ y)} in C.
@item cl_I lognand (const cl_I& x, const cl_I& y)
+@cindex @code{lognand ()}
Bitwise not and, like @code{~(x & y)} in C.
@item cl_I lognor (const cl_I& x, const cl_I& y)
+@cindex @code{lognor ()}
Bitwise not or, like @code{~(x | y)} in C.
@item cl_I logandc1 (const cl_I& x, const cl_I& y)
+@cindex @code{logandc1 ()}
Logical and, complementing the first argument, like @code{~x & y} in C.
@item cl_I logandc2 (const cl_I& x, const cl_I& y)
+@cindex @code{logandc2 ()}
Logical and, complementing the second argument, like @code{x & ~y} in C.
@item cl_I logorc1 (const cl_I& x, const cl_I& y)
+@cindex @code{logorc1 ()}
Logical or, complementing the first argument, like @code{~x | y} in C.
@item cl_I logorc2 (const cl_I& x, const cl_I& y)
+@cindex @code{logorc2 ()}
Logical or, complementing the second argument, like @code{x | ~y} in C.
@end table
These operations are all available though the function
@table @code
@item cl_I boole (cl_boole op, const cl_I& x, const cl_I& y)
+@cindex @code{boole ()}
@end table
where @code{op} must have one of the 16 values (each one stands for a function
which combines two bits into one bit): @code{boole_clr}, @code{boole_set},
@code{boole_and}, @code{boole_ior}, @code{boole_xor}, @code{boole_eqv},
@code{boole_nand}, @code{boole_nor}, @code{boole_andc1}, @code{boole_andc2},
@code{boole_orc1}, @code{boole_orc2}.
+@cindex @code{boole_clr}
+@cindex @code{boole_set}
+@cindex @code{boole_1}
+@cindex @code{boole_2}
+@cindex @code{boole_c1}
+@cindex @code{boole_c2}
+@cindex @code{boole_and}
+@cindex @code{boole_xor}
+@cindex @code{boole_eqv}
+@cindex @code{boole_nand}
+@cindex @code{boole_nor}
+@cindex @code{boole_andc1}
+@cindex @code{boole_andc2}
+@cindex @code{boole_orc1}
+@cindex @code{boole_orc2}
+
Other functions that view integers as bit strings:
@table @code
-@item 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.
@end table
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
@code{position}@dots{}@code{position+size-1} of an integer.
The constructor @code{cl_byte(size,position)} constructs a @code{cl_byte}.
@table @code
@item cl_I ldb (const cl_I& n, const cl_byte& b)
+@cindex @code{ldb ()}
extracts the bits of @code{n} described by the bit interval @code{b}
and returns them as a nonnegative integer with @code{b.size} bits.
-@item 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}.
@item cl_I dpb (const cl_I& newbyte, const cl_I& n, const cl_byte& b)
+@cindex @code{dpb ()}
Returns @code{n}, with the bits described by the bit interval @code{b}
replaced by @code{newbyte}. Only the lowest @code{b.size} bits of
@code{newbyte} are relevant.
@table @code
@item cl_I mask_field (const cl_I& n, const cl_byte& b)
+@cindex @code{mask_field ()}
returns an integer with the bits described by the bit interval @code{b}
copied from the corresponding bits in @code{n}, the other bits zero.
@item cl_I deposit_field (const cl_I& newbyte, const cl_I& n, const cl_byte& b)
+@cindex @code{deposit_field ()}
returns an integer where the bits described by the bit interval @code{b}
come from @code{newbyte} and the other bits come from @code{n}.
@end table
The following relations hold:
-@itemize @asis
+@itemize @w{}
@item
@code{ldb (n, b) = mask_field(n, b) >> b.position},
@item
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}.
@item cl_I operator << (const cl_I& x, const cl_I& n)
+@cindex @code{operator << ()}
Shifts @code{x} by @code{n} bits to the left. @code{n} should be >=0.
Equivalent to @code{x * expt(2,n)}.
@item cl_I operator >> (const cl_I& x, const cl_I& n)
+@cindex @code{operator >> ()}
Shifts @code{x} by @code{n} bits to the right. @code{n} should be >=0.
Bits shifted out to the right are thrown away.
Equivalent to @code{floor(x / expt(2,n))}.
@item cl_I ash (const cl_I& x, const cl_I& y)
+@cindex @code{ash ()}
Shifts @code{x} by @code{y} bits to the left (if @code{y}>=0) or
by @code{-y} bits to the right (if @code{y}<=0). In other words, this
returns @code{floor(x * expt(2,y))}.
-@item 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.
(See also the function @code{logp}.)
@end table
-@node Number theoretic functions, Combinatorial functions, Logical functions, Functions on integers
+@node Number theoretic functions
@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},
normalized to be >= 0.
@item cl_I xgcd (const cl_I& a, const cl_I& b, cl_I* u, cl_I* v)
+@cindex @code{xgcd ()}
This function (``extended gcd'') returns the greatest common divisor @code{g} of
@code{a} and @code{b} and at the same time the representation of @code{g}
as an integral linear combination of @code{a} and @code{b}:
@code{abs(u) <= abs(b)/(2*g)}, @code{abs(v) <= abs(a)/(2*g)}.
@item cl_I lcm (const cl_I& a, const cl_I& b)
+@cindex @code{lcm ()}
This function returns the least common multiple of @code{a} and @code{b},
normalized to be >= 0.
-@item cl_boolean logp (const cl_I& a, const cl_I& b, cl_RA* l)
-@itemx cl_boolean logp (const cl_RA& a, const cl_RA& b, cl_RA* l)
+@item bool logp (const cl_I& a, const cl_I& b, cl_RA* l)
+@cindex @code{logp ()}
+@itemx bool logp (const cl_RA& a, const cl_RA& b, cl_RA* l)
@code{a} must be > 0. @code{b} must be >0 and != 1. If log(a,b) is
rational number, this function returns true and sets *l = log(a,b), else
it returns false.
+
+@item int jacobi (signed long a, signed long b)
+@cindex @code{jacobi()}
+@itemx int jacobi (const cl_I& a, const cl_I& b)
+Returns the Jacobi symbol
+@tex
+$\left({a\over b}\right)$,
+@end tex
+@ifnottex
+(a/b),
+@end ifnottex
+@code{a,b} must be integers, @code{b>0} and odd. The result is 0
+iff gcd(a,b)>1.
+
+@item bool isprobprime (const cl_I& n)
+@cindex prime
+@cindex @code{isprobprime()}
+Returns true if @code{n} is a small prime or passes the Miller-Rabin
+primality test. The probability of a false positive is 1:10^30.
+
+@item cl_I nextprobprime (const cl_R& x)
+@cindex @code{nextprobprime()}
+Returns the smallest probable prime >=@code{x}.
@end table
-@node Combinatorial functions, , Number theoretic functions, Functions on integers
+@node Combinatorial functions
@subsection Combinatorial functions
@table @code
@item cl_I factorial (uintL n)
+@cindex @code{factorial ()}
@code{n} must be a small integer >= 0. This function returns the factorial
@code{n}! = @code{1*2*@dots{}*n}.
@item cl_I doublefactorial (uintL n)
+@cindex @code{doublefactorial ()}
@code{n} must be a small integer >= 0. This function returns the
doublefactorial @code{n}!! = @code{1*3*@dots{}*n} or
@code{n}!! = @code{2*4*@dots{}*n}, respectively.
@item cl_I binomial (uintL n, uintL k)
+@cindex @code{binomial ()}
@code{n} and @code{k} must be small integers >= 0. This function returns the
binomial coefficient
@tex
-${n \choose k} = {n! \over n! (n-k)!}$
+${n \choose k} = {n! \over k! (n-k)!}$
@end tex
@ifinfo
(@code{n} choose @code{k}) = @code{n}! / @code{k}! @code{(n-k)}!
@end table
-@node Functions on floating-point numbers, Conversion functions, Functions on integers, Functions on numbers
+@node Functions on floating-point numbers
@section Functions on floating-point numbers
Recall that a floating-point number consists of a sign @code{s}, an
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
because it copies @code{x} and modifies the exponent.
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
integer with @code{2^(e-1) <= abs(x) < 2^e}.
@item sintL float_radix (const @var{type}& x)
+@cindex @code{float_radix ()}
Returns the base of the floating-point representation. This is always @code{2}.
@item @var{type} float_sign (const @var{type}& x)
+@cindex @code{float_sign ()}
Returns the sign @code{s} of @code{x} as a float. The value is 1 for
@code{x} >= 0, -1 for @code{x} < 0.
-@item 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,
this is the same as @code{float_digits(x)} if @code{x} is non-zero, and
@end table
The complete internal representation of a float is encoded in the type
-@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,
it returns @code{(-1)^s}=1, @code{e}=0, @code{m}=0.
@end table
A complete decoding in terms of integers is provided as type
+@cindex @code{cl_idecoded_float}
@example
struct cl_idecoded_float @{
cl_I mantissa; cl_I exponent; cl_I sign;
@table @code
@item cl_idecoded_float integer_decode_float (const @var{type}& x)
+@cindex @code{integer_decode_float ()}
For @code{x} non-zero, this returns @code{(-1)^s}, @code{e}, @code{m} with
@code{x = (-1)^s * 2^e * m} and @code{m} an integer with @code{float_digits(x)}
bits. For @code{x} = 0, it returns @code{(-1)^s}=1, @code{e}=0, @code{m}=0.
@table @code
@item cl_F float_sign (const cl_F& x, const cl_F& y)
+@cindex @code{float_sign ()}
This returns a floating point number whose precision and absolute value
is that of @code{y} and whose sign is that of @code{x}. If @code{x} is
zero, it is treated as positive. Same for @code{y}.
@end table
-@node Conversion functions, Random number generators, Functions on floating-point numbers, Functions on numbers
+@node Conversion functions
@section Conversion functions
+@cindex conversion
@menu
* Conversion to floating-point numbers::
* Conversion to rational numbers::
@end menu
-@node Conversion to floating-point numbers, Conversion to rational numbers, Conversion functions, Conversion functions
+@node Conversion to floating-point numbers
@subsection Conversion to floating-point numbers
-The type @code{cl_float_format_t} describes a floating-point format.
+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)
+@item float_format_t float_format (uintE n)
+@cindex @code{float_format ()}
Returns the smallest float format which guarantees at least @code{n}
decimal digits in the mantissa (after the decimal point).
-@item 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
+@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
-@node Conversion to rational numbers, , Conversion to floating-point numbers, Conversion functions
+@node Conversion to rational numbers
@subsection Conversion to rational numbers
Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_F}
@table @code
@item cl_RA rational (const @var{type}& x)
+@cindex @code{rational ()}
Returns the value of @code{x} as an exact number. If @code{x} is already
an exact number, this is @code{x}. If @code{x} is a floating-point number,
the value is a rational number whose denominator is a power of 2.
@table @code
@item cl_RA rationalize (const cl_R& x)
+@cindex @code{rationalize ()}
If @code{x} is a floating-point number, it actually represents an interval
of real numbers, and this function returns the rational number with
smallest denominator (and smallest numerator, in magnitude)
If @code{x} is any float, one has
-@itemize @asis
+@itemize @w{}
@item
@code{cl_float(rational(x),x) = x}
@item
@end itemize
-@node Random number generators, Obfuscating operators, Conversion functions, Functions on numbers
+@node Random number generators
@section Random number generators
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{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}
if @code{n} is a float.
@end table
-@node Obfuscating operators, , Random number generators, Functions on numbers
-@section Obfuscating operators
+@node Modifying operators
+@section Modifying operators
+@cindex modifying operators
The modifying C/C++ operators @code{+=}, @code{-=}, @code{*=}, @code{/=},
@code{&=}, @code{|=}, @code{^=}, @code{<<=}, @code{>>=}
-are not available by default because their
-use tends to make programs unreadable. It is trivial to get away without
-them. However, if you feel that you absolutely need these operators
-to get happy, then add
-@example
-#define WANT_OBFUSCATING_OPERATORS
-@end example
-to the beginning of your source files, before the inclusion of any CLN
-include files. This flag will enable the following operators:
+are all available.
For the classes @code{cl_N}, @code{cl_R}, @code{cl_RA},
@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}:
@table @code
@item @var{type}& operator += (@var{type}&, const @var{type}&)
+@cindex @code{operator += ()}
@itemx @var{type}& operator -= (@var{type}&, const @var{type}&)
+@cindex @code{operator -= ()}
@itemx @var{type}& operator *= (@var{type}&, const @var{type}&)
+@cindex @code{operator *= ()}
@itemx @var{type}& operator /= (@var{type}&, const @var{type}&)
+@cindex @code{operator /= ()}
@end table
For the class @code{cl_I}:
@itemx @var{type}& operator -= (@var{type}&, const @var{type}&)
@itemx @var{type}& operator *= (@var{type}&, const @var{type}&)
@itemx @var{type}& operator &= (@var{type}&, const @var{type}&)
+@cindex @code{operator &= ()}
@itemx @var{type}& operator |= (@var{type}&, const @var{type}&)
+@cindex @code{operator |= ()}
@itemx @var{type}& operator ^= (@var{type}&, const @var{type}&)
+@cindex @code{operator ^= ()}
@itemx @var{type}& operator <<= (@var{type}&, const @var{type}&)
+@cindex @code{operator <<= ()}
@itemx @var{type}& operator >>= (@var{type}&, const @var{type}&)
+@cindex @code{operator >>= ()}
@end table
For the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
@table @code
@item @var{type}& operator ++ (@var{type}& x)
+@cindex @code{operator ++ ()}
The prefix operator @code{++x}.
@item void operator ++ (@var{type}& x, int)
The postfix operator @code{x++}.
@item @var{type}& operator -- (@var{type}& x)
+@cindex @code{operator -- ()}
The prefix operator @code{--x}.
@item void operator -- (@var{type}& x, int)
The postfix operator @code{x--}.
@end table
-Note that by using these obfuscating operators, you wouldn't gain efficiency:
+Note that by using these modifying operators, you don't gain efficiency:
In CLN @samp{x += y;} is exactly the same as @samp{x = x+y;}, not more
efficient.
-@node Input/Output, Rings, Functions on numbers, Top
+@node Input/Output
@chapter Input/Output
+@cindex Input/Output
@menu
* Internal and printed representation::
* Output functions::
@end menu
-@node Internal and printed representation, Input functions, Input/Output, Input/Output
+@node Internal and printed representation
@section Internal and printed representation
+@cindex representation
All computations deal with the internal representations of the numbers.
"20.0" and "20.000".
Converting an internal to an external representation is called ``printing'',
+@cindex printing
converting an external to an internal representation is called ``reading''.
-In CLN, is it always true that conversion of an internal to an external
+@cindex reading
+In CLN, it is always true that conversion of an internal to an external
representation and then back to an internal representation will yield the
same internal representation. Symbolically: @code{read(print(x)) == x}.
This is called ``print-read consistency''.
@var{expmarker} @var{expsign} @{@var{digit}@}+.
The exponent marker is
-@itemize @asis
+@itemize @w{}
@item
@samp{s} for short-floats,
@item
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:
-@itemize @asis
+@itemize @w{}
@item
In algebraic notation: @code{@var{realpart}+@var{imagpart}i}. Of course,
if @var{imagpart} is negative, its printed representation begins with
@end table
-@node Input functions, Output functions, Internal and printed representation, Input/Output
+@node Input functions
@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:
-
-@table @code
-@item int freadchar (cl_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)
-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:
-
-@table @code
-@item cl_istream operator>> (cl_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>},
-are the following:
+Including @code{<cln/io.h>} defines flexible input functions:
@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.
@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 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
+@item bool float_flags.mantissa_dependent_float_format
When this flag is true, floats specified with more digits than corresponding
to the exponent marker they contain, but without @var{_nnn} suffix, will get a
precision corresponding to their number of significant digits.
@end table
-@node Output functions, , Input functions, Input/Output
+@node Output functions
@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
@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.
-@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
+@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.
using this variable name. Default is @code{"x"}.
@end table
-The global variable @code{cl_default_print_flags} contains the default values,
-used by the function @code{fprint},
+The global variable @code{default_print_flags} contains the default values,
+used by the function @code{fprint}.
-@node Rings, Modular integers, Input/Output, Top
+@node Rings
@chapter Rings
CLN has a class of abstract rings.
@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)
-@itemx cl_boolean R->equal (const cl_ring_element& x, const cl_ring_element& y)
+@item void R->fprint (std::ostream& stream, const cl_ring_element& x)
+@cindex @code{fprint ()}
+@itemx bool R->equal (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{equal ()}
@itemx cl_ring_element R->zero ()
-@itemx cl_boolean R->zerop (const cl_ring_element& x)
+@cindex @code{zero ()}
+@itemx bool R->zerop (const cl_ring_element& x)
+@cindex @code{zerop ()}
@itemx cl_ring_element R->plus (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{plus ()}
@itemx cl_ring_element R->minus (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{minus ()}
@itemx cl_ring_element R->uminus (const cl_ring_element& x)
+@cindex @code{uminus ()}
@itemx cl_ring_element R->one ()
+@cindex @code{one ()}
@itemx cl_ring_element R->canonhom (const cl_I& x)
+@cindex @code{canonhom ()}
@itemx cl_ring_element R->mul (const cl_ring_element& x, const cl_ring_element& y)
+@cindex @code{mul ()}
@itemx cl_ring_element R->square (const cl_ring_element& x)
+@cindex @code{square ()}
@itemx cl_ring_element R->expt_pos (const cl_ring_element& x, const cl_I& y)
+@cindex @code{expt_pos ()}
@end table
The following rings are built-in.
@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
-@node Modular integers, Symbolic data types, Rings, Top
+@node Modular integers
@chapter Modular integers
+@cindex modular integer
@menu
* Modular integer rings::
* Functions on modular integers::
@end menu
-@node Modular integer rings, Functions on modular integers, Modular integers, Modular integers
+@node Modular integer rings
@section Modular integer rings
+@cindex ring
CLN implements modular integers, i.e. integers modulo a fixed integer N.
The modulus is explicitly part of every modular integer. CLN doesn't
@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}
and the class of all modular integers (elements of modular integer rings) is
@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)
+@item cl_modint_ring find_modint_ring (const cl_I& N)
+@cindex @code{find_modint_ring ()}
This function returns the modular ring @samp{Z/NZ}. It takes care
of finding out about special cases of @code{N}, like powers of two
and odd numbers for which Montgomery multiplication will be a win,
+@cindex Montgomery multiplication
and precomputes any necessary auxiliary data for computing modulo @code{N}.
There is a cache table of rings, indexed by @code{N} (or, more precisely,
by @code{abs(N)}). This ensures that the precomputation costs are reduced
@table @code
@item bool operator== (const cl_modint_ring&, const cl_modint_ring&)
+@cindex @code{operator == ()}
@itemx bool operator!= (const cl_modint_ring&, const cl_modint_ring&)
+@cindex @code{operator != ()}
These compare two modular integer rings for equality. Two different calls
-to @code{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
-@node Functions on modular integers, , Modular integer rings, Modular integers
+@node Functions on modular integers
@section Functions on modular integers
Given a modular integer ring @code{R}, the following members can be used.
@table @code
@item cl_I R->modulus
+@cindex @code{modulus}
This is the ring's modulus, normalized to be nonnegative: @code{abs(N)}.
@item cl_MI R->zero()
+@cindex @code{zero ()}
This returns @code{0 mod N}.
@item cl_MI R->one()
+@cindex @code{one ()}
This returns @code{1 mod N}.
@item cl_MI R->canonhom (const cl_I& x)
+@cindex @code{canonhom ()}
This returns @code{x mod N}.
@item cl_I R->retract (const cl_MI& x)
+@cindex @code{retract ()}
This is a partial inverse function to @code{R->canonhom}. It returns the
standard representative (@code{>=0}, @code{<N}) of @code{x}.
-@item cl_MI R->random(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}.
@end table
@table @code
@item cl_modint_ring x.ring ()
+@cindex @code{ring ()}
Returns the ring to which the modular integer @code{x} belongs.
@item cl_MI operator+ (const cl_MI&, const cl_MI&)
-Returns the sum of two modular integers. One of the arguments may also be
-a plain integer.
+@cindex @code{operator + ()}
+Returns the sum of two modular integers. One of the arguments may also
+be a plain integer.
@item cl_MI operator- (const cl_MI&, const cl_MI&)
-Returns the difference of two modular integers. One of the arguments may also be
-a plain integer.
+@cindex @code{operator - ()}
+Returns the difference of two modular integers. One of the arguments may also
+be a plain integer.
@item cl_MI operator- (const cl_MI&)
Returns the negative of a modular integer.
@item cl_MI operator* (const cl_MI&, const cl_MI&)
-Returns the product of two modular integers. One of the arguments may also be
-a plain integer.
+@cindex @code{operator * ()}
+Returns the product of two modular integers. One of the arguments may also
+be a plain integer.
@item cl_MI square (const cl_MI&)
+@cindex @code{square ()}
Returns the square of a modular integer.
@item cl_MI recip (const cl_MI& x)
+@cindex @code{recip ()}
Returns the reciprocal @code{x^-1} of a modular integer @code{x}. @code{x}
must be coprime to the modulus, otherwise an error message is issued.
@item cl_MI div (const cl_MI& x, const cl_MI& y)
+@cindex @code{div ()}
Returns the quotient @code{x*y^-1} of two modular integers @code{x}, @code{y}.
@code{y} must be coprime to the modulus, otherwise an error message is issued.
@item cl_MI expt_pos (const cl_MI& x, const cl_I& y)
+@cindex @code{expt_pos ()}
@code{y} must be > 0. Returns @code{x^y}.
@item cl_MI expt (const cl_MI& x, const cl_I& y)
+@cindex @code{expt ()}
Returns @code{x^y}. If @code{y} is negative, @code{x} must be coprime to the
modulus, else an error message is issued.
@item cl_MI operator<< (const cl_MI& x, const cl_I& y)
+@cindex @code{operator << ()}
Returns @code{x*2^y}.
@item cl_MI operator>> (const cl_MI& x, const cl_I& y)
+@cindex @code{operator >> ()}
Returns @code{x*2^-y}. When @code{y} is positive, the modulus must be odd,
or an error message is issued.
@item bool operator== (const cl_MI&, const cl_MI&)
+@cindex @code{operator == ()}
@itemx bool operator!= (const cl_MI&, const cl_MI&)
+@cindex @code{operator != ()}
Compares two modular integers, belonging to the same modular integer ring,
for equality.
-@item 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
input/output).
@table @code
-@item void fprint (cl_ostream stream, const cl_MI& x)
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_MI& x)
+@item void fprint (std::ostream& stream, const cl_MI& x)
+@cindex @code{fprint ()}
+@itemx std::ostream& operator<< (std::ostream& stream, const cl_MI& x)
+@cindex @code{operator << ()}
Prints the modular integer @code{x} on the @code{stream}. The output may depend
-on the global printer settings in the variable @code{cl_default_print_flags}.
+on the global printer settings in the variable @code{default_print_flags}.
@end table
-@node Symbolic data types, Univariate polynomials, Modular integers, Top
+@node Symbolic data types
@chapter Symbolic data types
+@cindex symbolic type
CLN implements two symbolic (non-numeric) data types: strings and symbols.
* Symbols::
@end menu
-@node Strings, Symbols, Symbolic data types, Symbolic data types
+@node Strings
@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.
@item operator =
Assignment from @code{cl_string} and @code{const char *}.
-@item s.length()
+@item s.size()
+@cindex @code{size()}
@itemx strlen(s)
+@cindex @code{strlen ()}
Returns the length of the string @code{s}.
@item s[i]
+@cindex @code{operator [] ()}
Returns the @code{i}th character of the string @code{s}.
-@code{i} must be in the range @code{0 <= i < s.length()}.
+@code{i} must be in the range @code{0 <= i < s.size()}.
@item bool equal (const cl_string& s1, const cl_string& s2)
+@cindex @code{equal ()}
Compares two strings for equality. One of the arguments may also be a
plain @code{const char *}.
@end table
-@node Symbols, , Strings, Symbolic data types
+@node Symbols
@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
@code{sym}.
@item bool equal (const cl_symbol& sym1, const cl_symbol& sym2)
+@cindex @code{equal ()}
Compares two symbols for equality. This is very fast.
@end table
-@node Univariate polynomials, Internals, Symbolic data types, Top
+@node Univariate polynomials
@chapter Univariate polynomials
+@cindex polynomial
+@cindex univariate polynomial
@menu
* Univariate polynomial rings::
* Special polynomials::
@end menu
-@node Univariate polynomial rings, Functions on univariate polynomials, Univariate polynomials, Univariate polynomials
+@node Univariate polynomial rings
@section Univariate polynomial rings
CLN implements univariate polynomials (polynomials in one variable) over an
arbitrary ring. The indeterminate variable may be either unnamed (and will be
-printed according to @code{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.
-@item cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring& R)
-@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},
+@item cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R)
+@cindex @code{find_univpoly_ring ()}
+@item cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)
+@item cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R)
+@item cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)
+@item cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R)
+@item cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)
+@item cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R)
+@item cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)
+@item cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R)
+@item 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
-@node Functions on univariate polynomials, Special polynomials, Univariate polynomial rings, Univariate polynomials
+@node Functions on univariate polynomials
@section Functions on univariate polynomials
Given a univariate polynomial ring @code{R}, the following members can be used.
@table @code
@item cl_ring R->basering()
-This returns the base ring, as passed to @samp{cl_find_univpoly_ring}.
+@cindex @code{basering ()}
+This returns the base ring, as passed to @samp{find_univpoly_ring}.
@item cl_UP R->zero()
+@cindex @code{zero ()}
This returns @code{0 in R}, a polynomial of degree -1.
@item cl_UP R->one()
-This returns @code{1 in R}, a polynomial of degree <= 0.
+@cindex @code{one ()}
+This returns @code{1 in R}, a polynomial of degree == 0.
@item cl_UP R->canonhom (const cl_I& x)
+@cindex @code{canonhom ()}
This returns @code{x in R}, a polynomial of degree <= 0.
@item cl_UP R->monomial (const cl_ring_element& x, uintL e)
+@cindex @code{monomial ()}
This returns a sparse polynomial: @code{x * X^e}, where @code{X} is the
indeterminate.
@item cl_UP R->create (sintL degree)
+@cindex @code{create ()}
Creates a new polynomial with a given degree. The zero polynomial has degree
@code{-1}. After creating the polynomial, you should put in the coefficients,
using the @code{set_coeff} member function, and then call the @code{finalize}
@table @code
@item void set_coeff (cl_UP& x, uintL index, const cl_ring_element& y)
+@cindex @code{set_coeff ()}
This changes the coefficient of @code{X^index} in @code{x} to be @code{y}.
After changing a polynomial and before applying any "normal" operation on it,
you should call its @code{finalize} member function.
@item void finalize (cl_UP& x)
+@cindex @code{finalize ()}
This function marks the endpoint of destructive modifications of a polynomial.
It normalizes the internal representation so that subsequent computations have
less overhead. Doing normal computations on unnormalized polynomials may
@table @code
@item cl_univpoly_ring x.ring ()
+@cindex @code{ring ()}
Returns the ring to which the univariate polynomial @code{x} belongs.
@item cl_UP operator+ (const cl_UP&, const cl_UP&)
+@cindex @code{operator + ()}
Returns the sum of two univariate polynomials.
@item cl_UP operator- (const cl_UP&, const cl_UP&)
+@cindex @code{operator - ()}
Returns the difference of two univariate polynomials.
@item cl_UP operator- (const cl_UP&)
Returns the negative of a univariate polynomial.
@item cl_UP operator* (const cl_UP&, const cl_UP&)
+@cindex @code{operator * ()}
Returns the product of two univariate polynomials. One of the arguments may
also be a plain integer or an element of the base ring.
@item cl_UP square (const cl_UP&)
+@cindex @code{square ()}
Returns the square of a univariate polynomial.
@item cl_UP expt_pos (const cl_UP& x, const cl_I& y)
+@cindex @code{expt_pos ()}
@code{y} must be > 0. Returns @code{x^y}.
@item bool operator== (const cl_UP&, const cl_UP&)
+@cindex @code{operator == ()}
@itemx bool operator!= (const cl_UP&, const cl_UP&)
+@cindex @code{operator != ()}
Compares two univariate polynomials, belonging to the same univariate
polynomial ring, for equality.
-@item 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}.
@item sintL degree (const cl_UP& x)
+@cindex @code{degree ()}
Returns the degree of the polynomial. The zero polynomial has degree @code{-1}.
+@item sintL ldegree (const cl_UP& x)
+@cindex @code{degree ()}
+Returns the low degree of the polynomial. This is the degree of the first
+non-vanishing polynomial coefficient. The zero polynomial has ldegree @code{-1}.
+
@item cl_ring_element coeff (const cl_UP& x, uintL index)
+@cindex @code{coeff ()}
Returns the coefficient of @code{X^index} in the polynomial @code{x}.
@item cl_ring_element x (const cl_ring_element& y)
+@cindex @code{operator () ()}
Evaluation: If @code{x} is a polynomial and @code{y} belongs to the base ring,
then @samp{x(y)} returns the value of the substitution of @code{y} into
@code{x}.
@item cl_UP deriv (const cl_UP& x)
+@cindex @code{deriv ()}
Returns the derivative of the polynomial @code{x} with respect to the
indeterminate @code{X}.
@end table
input/output).
@table @code
-@item void fprint (cl_ostream stream, const cl_UP& x)
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_UP& x)
+@item void fprint (std::ostream& stream, const cl_UP& x)
+@cindex @code{fprint ()}
+@itemx std::ostream& operator<< (std::ostream& stream, const cl_UP& x)
+@cindex @code{operator << ()}
Prints the univariate polynomial @code{x} on the @code{stream}. The output may
depend on the global printer settings in the variable
-@code{cl_default_print_flags}.
+@code{default_print_flags}.
@end table
-@node Special polynomials, , Functions on univariate polynomials, Univariate polynomials
+@node Special polynomials
@section Special polynomials
The following functions return special polynomials.
@table @code
-@item cl_UP_I cl_tschebychev (sintL n)
-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)
+@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)
+@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)
+@item cl_UP_I laguerre (sintL n)
+@cindex @code{laguerre ()}
+@cindex Laguerre polynomial
Returns the n-th Laguerre polynomial (n >= 0).
@end table
@code{doc/polynomial/} directory.
-@node Internals, Using the library, Univariate polynomials, Top
+@node Internals
@chapter Internals
@menu
* Garbage collection::
@end menu
-@node Why C++ ?, Memory efficiency, Internals, Internals
+@node Why C++ ?
@section Why C++ ?
+@cindex advocacy
Using C++ as an implementation language provides
Efficiency: It compiles to machine code.
@item
+@cindex portability
Portability: It runs on all platforms supporting a C++ compiler. Because
of the availability of GNU C++, this includes all currently used 32-bit and
64-bit platforms, independently of the quality of the vendor's C++ compiler.
Type safety: The C++ compilers knows about the number types and complains if,
for example, you try to assign a float to an integer variable. However,
a drawback is that C++ doesn't know about generic types, hence a restriction
-like that @code{operation+ (const cl_MI&, const cl_MI&)} requires that both
+like that @code{operator+ (const cl_MI&, const cl_MI&)} requires that both
arguments belong to the same modular ring cannot be expressed as a compile-time
information.
in a high-level language.
-@node Memory efficiency, Speed efficiency, Why C++ ?, Internals
+@node Memory efficiency
@section Memory efficiency
In order to save memory allocations, CLN implements:
Object sharing: An operation like @code{x+0} returns @code{x} without copying
it.
@item
+@cindex garbage collection
+@cindex reference counting
Garbage collection: A reference counting mechanism makes sure that any
number object's storage is freed immediately when the last reference to the
object is gone.
@item
+@cindex immediate numbers
Small integers are represented as immediate values instead of pointers
-to heap allocated storage. This means that integers @code{> -2^29},
+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
-@node Speed efficiency, Garbage collection, Memory efficiency, Internals
+@node Speed efficiency
@section Speed efficiency
Speed efficiency is obtained by the combination of the following tricks
The kernel of CLN has been written in assembly language for some CPUs
(@code{i386}, @code{m68k}, @code{sparc}, @code{mips}, @code{arm}).
@item
-On all CPUs, CLN uses the superefficient low-level routines from GNU
-GMP version 2.
+On all CPUs, CLN may be configured to use the superefficient low-level
+routines from GNU GMP version 3.
@item
For large numbers, CLN uses, instead of the standard @code{O(N^2)}
algorithm, the Karatsuba multiplication, which is an
For very large numbers (more than 12000 decimal digits), CLN uses
@iftex
Sch{@"o}nhage-Strassen
+@cindex Sch{@"o}nhage-Strassen multiplication
@end iftex
@ifinfo
-Schönhage-Strassen
+Schoenhage-Strassen
+@cindex Schoenhage-Strassen multiplication
@end ifinfo
-multiplication, which is an asymptotically
-optimal multiplication algorithm.
+multiplication, which is an asymptotically optimal multiplication
+algorithm.
@item
These fast multiplication algorithms also give improvements in the speed
of division and radix conversion.
@end itemize
-@node Garbage collection, , Speed efficiency, Internals
+@node Garbage collection
@section Garbage collection
+@cindex garbage collection
All the number classes are reference count classes: They only contain a pointer
to an object in the heap. Upon construction, assignment and destruction of
cached, whereas undue memory consumption through cached rings is avoided.
-@node Using the library, Customizing, Internals, Top
+@node Using the library
@chapter Using the library
For the following discussion, we will assume that you have installed
* Include files::
* An Example::
* Debugging support::
+* Reporting Problems::
@end menu
-@node Compiler options, Include files, Using the library, Using the library
+@node Compiler options
@section Compiler options
+@cindex compiler options
Until you have installed CLN in a public place, the following options are
needed:
public directory as well (normally @code{/usr/local/lib}), hence when
linking a CLN application it is sufficient to give the flag @code{-lcln}.
+@cindex @code{pkg-config}
+To make the creation of software packages that use CLN easier, the
+@code{pkg-config} utility can be used. CLN provides all the necessary
+metainformation in a file called @code{cln.pc} (installed in
+@code{/usr/local/lib/pkgconfig} by default). A program using CLN can
+be compiled and linked using @footnote{If you installed CLN to
+non-standard location @var{prefix}, you need to set the
+@env{PKG_CONFIG_PATH} environment variable to @var{prefix}/lib/pkgconfig
+for this to work.}
+@example
+g++ `pkg-config --libs cln` `pkg-config --cflags cln` prog.cc -o prog
+@end example
-@node Include files, An Example, Compiler options, Using the library
+Software using GNU autoconf can check for CLN with the
+@code{PKG_CHECK_MODULES} macro supplied with @code{pkg-config}.
+@example
+PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}])
+@end example
+This will check for CLN version at least @var{MIN-VERSION}. If the
+required version was found, the variables @var{CLN_CFLAGS} and
+@var{CLN_LIBS} are set. Otherwise the configure script aborts. If this
+is not the desired behaviour, use the following code instead
+@footnote{See the @code{pkg-config} documentation for more details.}
+@example
+PKG_CHECK_MODULES([CLN], [cln >= @var{MIN-VERSION}], [],
+ [AC_MSG_WARNING([No suitable version of CLN can be found])])
+@end example
+
+
+@node Include files
@section Include files
+@cindex include files
+@cindex header 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>
-@code{cl_abort}.
-@item <cl_condition.h>
-Conditions/exceptions.
-@item <cl_string.h>
+@item <cln/malloc.h>
+@code{malloc_hook}, @code{free_hook}.
+@item <cln/exception.h>
+Exception base class.
+@item <cln/condition.h>
+Conditions.
+@item <cln/string.h>
Strings.
-@item <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
-@node An Example, Debugging support, Include files, Using the library
+@node An Example
@section An Example
A function which computes the nth Fibonacci number can be written as follows.
+@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
automatically reclaimed (garbage collected). Only the result survives and
gets passed to the caller.
+The file @code{fibonacci.cc} in the subdirectory @code{examples}
+contains this implementation together with an even faster algorithm.
-@node Debugging support, , An Example, Using the library
+@node Debugging support
@section Debugging support
+@cindex debugging
When debugging a CLN application with GNU @code{gdb}, two facilities are
available from the library:
@itemize @bullet
@item The library does type checks, range checks, consistency checks at
-many places. When one of these fails, 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.
for printing number objects. In order to get this function, you have
to define the macro @samp{CL_DEBUG} and then include all the header files
for which you want @code{cl_print} debugging support. For example:
+@cindex @code{CL_DEBUG}
@example
#define CL_DEBUG
-#include <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:
@code{debug_print()} on all CLN types. The same macro @samp{CL_DEBUG}
is needed for this member function to be implemented. Under @code{gdb},
you call it like this:
+@cindex @code{debug_print ()}
@example
(gdb) print s
$7 = @{<cl_gcpointer> = @{ = @{pointer = 0x8055b60, heappointer = 0x8055b60,
Unfortunately, this feature does not seem to work under all circumstances.
@end itemize
+@node Reporting Problems
+@section Reporting Problems
+@cindex bugreports
+@cindex mailing list
+
+If you encounter any problem, please don't hesitate to send a detailed
+bugreport to the @code{cln-list@@ginac.de} mailing list. Please think
+about your bug: consider including a short description of your operating
+system and compilation environment with corresponding version numbers. A
+description of your configuration options may also be helpful. Also, a
+short test program together with the output you get and the output you
+expect will help us to reproduce it quickly. Finally, do not forget to
+report the version number of CLN.
+
-@node Customizing, Index, Using the library, Top
+@node Customizing
@chapter Customizing
+@cindex customizing
@menu
* Error handling::
* Customizing the memory allocator::
@end menu
-@node Error handling, Floating-point underflow, Customizing, Customizing
+@node Error handling
@section Error handling
+@cindex exception
+@cindex error handling
-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
+@cindex @code{runtime_exception}
+CLN signals abnormal situations by throwning exceptions. All exceptions
+thrown by the library are of type @code{runtime_exception} or of a
+derived type. Class @code{cln::runtime_exception} in turn is derived
+from the C++ standard library class @code{std::runtime_error} and
+inherits the @code{.what()} member function that can be used to query
+details about the cause of error.
+
+The most important classes thrown by the library are
+
+@cindex @code{floating_point_exception}
+@cindex @code{read_number_exception}
@example
-#include <cl_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
-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.
-@node Floating-point underflow, Customizing I/O, Error handling, Customizing
-@section Floating-point 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
+@node Floating-point underflow
+@section Floating-point underflow
+@cindex underflow
+
+@cindex @code{floating_point_underflow_exception}
+Floating point underflow denotes the situation when a floating-point
+number is to be created which is so close to @code{0} that its exponent
+is too low to be represented internally. By default, this causes the
+exception @code{floating_point_underflow_exception} (subclass of
+@code{floating_point_exception}) to be thrown. If you set the global
+variable
@example
-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}.
-@node Customizing I/O, Customizing the memory allocator, Floating-point underflow, Customizing
+@node Customizing I/O
@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}.
+value of the global variable @code{default_print_flags}.
+@cindex @code{default_print_flags}
-@node Customizing the memory allocator, , Customizing I/O, Customizing
+@node Customizing the memory allocator
@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{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