+2000-08-30 Richard Kreckel <kreckel@ginac.de>
+
+ * include/cln/number.h, cl_number::_as_cl_private_thing(): removed.
+ Rearranged for a clearer distinction between macros and remaining
+ identifiers, so Cint can parse it smoothly.
+
2000-08-29 Richard Kreckel <kreckel@ginac.de>
* include/cln/number.h, the(const cl_number& x): New template
function.
+2000-08-29 Richard Kreckel <kreckel@ginac.de>
+
+ * TODO: DESCRIBE NAMESPACE CHANGES HERE!!!
+
2000-08-26 Bruno Haible <haible@clisp.cons.org>
* autoconf/acgeneral.m4 (AC_OUTPUT): Use braces in exec_prefix default
* src/float/sfloat/cl_SF.h: Use cl_pointer_size instead of
cl_word_size.
-2000-06-05 Richard Kreckel <kreckel@ginac.de>
-
- * doc/*, INSTALL: Mention that both shared and static library are
- are now build by default.
-
2000-05-31 Bruno Haible <haible@clisp.cons.org>
* tests/exam_I_floor.cc (integer_floor_tests): Add one more entry.
* INSTALL.generic: Clarified behaviour of --with-gmp.
* autoconf/config.guess: updated from Clisp-2000-03-06 sources.
-2000-05-05 Richard Kreckel <kreckel@ginac.de>
-
- * doc/cln.tex: Added index entries.
- * doc/texinfo.tex: Upgraded to newer version 1999-10-01.07.
- * doc/*: Changes triggered.
-
2000-05-04 Richard Kreckel <kreckel@ginac.de>
* gmp/: removed completely. From now on we are going to link
+++ /dev/null
-This is cln.info, produced by makeinfo version 4.0 from cln.texi.
-
-This file documents CLN, a Class Library for Numbers.
-
-Published by Bruno Haible, `<haible@clisp.cons.org>' and Richard
-Kreckel, `<kreckel@ginac.de>'.
-
-Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-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.
-
-\1f
-File: cln.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
-
-* Menu:
-
-* Introduction::
-* Installation::
-* Ordinary number types::
-* Functions on numbers::
-* Input/Output::
-* Rings::
-* Modular integers::
-* Symbolic data types::
-* Univariate polynomials::
-* Internals::
-* Using the library::
-* Customizing::
-* Index::
-
-
- --- The Detailed Node Listing ---
-
-Installation
-
-* Prerequisites::
-* Building the library::
-* Installing the library::
-* Cleaning up::
-
-Prerequisites
-
-* C++ compiler::
-* Make utility::
-* Sed utility::
-
-Building the library
-
-* Using the GNU MP Library::
-
-Ordinary number types
-
-* Exact numbers::
-* Floating-point numbers::
-* Complex numbers::
-* Conversions::
-
-Functions on numbers
-
-* Constructing numbers::
-* Elementary functions::
-* Elementary rational functions::
-* Elementary complex functions::
-* Comparisons::
-* Rounding functions::
-* Roots::
-* Transcendental functions::
-* Functions on integers::
-* Functions on floating-point numbers::
-* Conversion functions::
-* Random number generators::
-* Obfuscating operators::
-
-Constructing numbers
-
-* Constructing integers::
-* Constructing rational numbers::
-* Constructing floating-point numbers::
-* Constructing complex numbers::
-
-Transcendental functions
-
-* Exponential and logarithmic functions::
-* Trigonometric functions::
-* Hyperbolic functions::
-* Euler gamma::
-* Riemann zeta::
-
-Functions on integers
-
-* Logical functions::
-* Number theoretic functions::
-* Combinatorial functions::
-
-Conversion functions
-
-* Conversion to floating-point numbers::
-* Conversion to rational numbers::
-
-Input/Output
-
-* Internal and printed representation::
-* Input functions::
-* Output functions::
-
-Modular integers
-
-* Modular integer rings::
-* Functions on modular integers::
-
-Symbolic data types
-
-* Strings::
-* Symbols::
-
-Univariate polynomials
-
-* Univariate polynomial rings::
-* Functions on univariate polynomials::
-* Special polynomials::
-
-Internals
-
-* Why C++ ?::
-* Memory efficiency::
-* Speed efficiency::
-* Garbage collection::
-
-Using the library
-
-* Compiler options::
-* Compatibility to old CLN versions::
-* Include files::
-* An Example::
-* Debugging support::
-
-Customizing
-
-* Error handling::
-* Floating-point underflow::
-* Customizing I/O::
-* Customizing the memory allocator::
-
-\1f
-File: cln.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
-
-Introduction
-************
-
-CLN is a library for computations with all kinds of numbers. It has a
-rich set of number classes:
-
- * Integers (with unlimited precision),
-
- * Rational numbers,
-
- * Floating-point numbers:
-
- - Short float,
-
- - Single float,
-
- - Double float,
-
- - Long float (with unlimited precision),
-
- * Complex numbers,
-
- * Modular integers (integers modulo a fixed integer),
-
- * Univariate polynomials.
-
-The subtypes of the complex numbers among these are exactly the types
-of numbers known to the Common Lisp language. Therefore `CLN' can be
-used for Common Lisp implementations, giving `CLN' another meaning: it
-becomes an abbreviation of "Common Lisp Numbers".
-
-The CLN package implements
-
- * Elementary functions (`+', `-', `*', `/', `sqrt', comparisons,
- ...),
-
- * Logical functions (logical `and', `or', `not', ...),
-
- * Transcendental functions (exponential, logarithmic, trigonometric,
- hyperbolic functions and their inverse functions).
-
-CLN is a C++ library. Using C++ as an implementation language provides
-
- * efficiency: it compiles to machine code,
-
- * type safety: the C++ compiler knows about the number types and
- complains if, for example, you try to assign a float to an integer
- variable.
-
- * algebraic syntax: You can use the `+', `-', `*', `=', `==', ...
- operators as in C or C++.
-
-CLN is memory efficient:
-
- * Small integers and short floats are immediate, not heap allocated.
-
- * Heap-allocated memory is reclaimed through an automatic,
- non-interruptive garbage collection.
-
-CLN is speed efficient:
-
- * The kernel of CLN has been written in assembly language for some
- CPUs (`i386', `m68k', `sparc', `mips', `arm').
-
- * On all CPUs, CLN may be configured to use the superefficient
- low-level routines from GNU GMP version 3.
-
- * 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
- Schönhage-Strassen multiplication, which is an asymptotically
- optimal multiplication algorithm, for multiplication, division and
- radix conversion.
-
-CLN aims at being easily integrated into larger software packages:
-
- * The garbage collection imposes no burden on the main application.
-
- * The library provides hooks for memory allocation and exceptions.
-
- * All non-macro identifiers are hidden in namespace `cln' in order
- to avoid name clashes.
-
-\1f
-File: cln.info, Node: Installation, Next: Ordinary number types, Prev: Introduction, Up: Top
-
-Installation
-************
-
-This section describes how to install the CLN package on your system.
-
-* Menu:
-
-* Prerequisites::
-* Building the library::
-* Installing the library::
-* Cleaning up::
-
-\1f
-File: cln.info, Node: Prerequisites, Next: Building the library, Prev: Installation, Up: Installation
-
-Prerequisites
-=============
-
-* Menu:
-
-* C++ compiler::
-* Make utility::
-* Sed utility::
-
-\1f
-File: cln.info, Node: C++ compiler, Next: Make utility, Prev: Prerequisites, Up: Prerequisites
-
-C++ compiler
-------------
-
-To build CLN, you need a C++ compiler. Actually, you need GNU `g++
-2.90' or newer, the EGCS compilers will do. I recommend GNU `g++ 2.95'
-or newer.
-
-The following C++ features are used: classes, member functions,
-overloading of functions and operators, constructors and destructors,
-inline, const, multiple inheritance, templates and namespaces.
-
-The following C++ features are not used: `new', `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.
-
-\1f
-File: cln.info, Node: Make utility, Next: Sed utility, Prev: C++ compiler, Up: Prerequisites
-
-Make utility
-------------
-
-To build CLN, you also need to have GNU `make' installed.
-
-\1f
-File: cln.info, Node: Sed utility, Prev: Make utility, Up: Prerequisites
-
-Sed utility
------------
-
-To build CLN on HP-UX, you also need to have GNU `sed' installed. This
-is because the libtool script, which creates the CLN library, relies on
-`sed', and the vendor's `sed' utility on these systems is too limited.
-
-\1f
-File: cln.info, Node: Building the library, Next: Installing the library, Prev: Prerequisites, Up: Installation
-
-Building the library
-====================
-
-As with any autoconfiguring GNU software, installation is as easy as
-this:
-
- $ ./configure
- $ make
- $ make check
-
-If on your system, `make' is not GNU `make', you have to use `gmake'
-instead of `make' above.
-
-The `configure' command checks out some features of your system and C++
-compiler and builds the `Makefile's. The `make' command builds the
-library. This step may take 4 hours on an average workstation. The
-`make check' runs some test to check that no important subroutine has
-been miscompiled.
-
-The `configure' command accepts options. To get a summary of them, try
-
- $ ./configure --help
-
-Some of the options are explained in detail in the `INSTALL.generic'
-file.
-
-You can specify the C compiler, the C++ compiler and their options
-through the following environment variables when running `configure':
-
-`CC'
- Specifies the C compiler.
-
-`CFLAGS'
- Flags to be given to the C compiler when compiling programs (not
- when linking).
-
-`CXX'
- Specifies the C++ compiler.
-
-`CXXFLAGS'
- Flags to be given to the C++ compiler when compiling programs (not
- when linking).
-
-Examples:
-
- $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
- $ CC="gcc -V egcs-2.91.60" CFLAGS="-O -g" \
- CXX="g++ -V egcs-2.91.60" CXXFLAGS="-O -g" ./configure
- $ CC="gcc -V 2.95.2" CFLAGS="-O2 -fno-exceptions" \
- CXX="g++ -V 2.95.2" CFLAGS="-O2 -fno-exceptions" ./configure
-
-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
-`configure' command. If you made the settings in earlier shell
-commands, you have to `export' the environment variables before calling
-`configure'. In a `csh' shell, you have to use the `setenv' command for
-setting each of the environment variables.
-
-Currently CLN works only with the GNU `g++' compiler, and only in
-optimizing mode. So you should specify at least `-O' in the CXXFLAGS,
-or no CXXFLAGS at all. (If CXXFLAGS is not set, CLN will use `-O'.)
-
-If you use `g++' version 2.8.x or egcs-2.91.x (a.k.a. egcs-1.1) or
-gcc-2.95.x, I recommend adding `-fno-exceptions' to the CXXFLAGS. This
-will likely generate better code.
-
-If you use `g++' version egcs-2.91.x (egcs-1.1) or gcc-2.95.x on Sparc,
-add either `-O', `-O1' or `-O2 -fno-schedule-insns' to the CXXFLAGS.
-With full `-O2', `g++' miscompiles the division routines. Also, if you
-have `g++' version egcs-1.1.1 or older on Sparc, you must specify
-`--disable-shared' because `g++' would miscompile parts of the library.
-
-By default, both a shared and a static library are built. You can build
-CLN as a static (or shared) library only, by calling `configure' with
-the option `--disable-shared' (or `--disable-static'). While shared
-libraries are usually more convenient to use, they may not work on all
-architectures. Try disabling them if you run into linker problems.
-Also, they are generally somewhat slower than static libraries so
-runtime-critical applications should be linked statically.
-
-* Menu:
-
-* Using the GNU MP Library::
-
-\1f
-File: cln.info, Node: Using the GNU MP Library, Prev: Building the library, Up: Building the library
-
-Using the GNU MP Library
-------------------------
-
-Starting with version 1.1, CLN may be configured to make use of a
-preinstalled `gmp' library. Please make sure that you have at least
-`gmp' version 3.0 installed since earlier versions are unsupported and
-likely not to work. Enabling this feature by calling `configure' with
-the option `--with-gmp' is known to be quite a boost for CLN's
-performance.
-
-If you have installed the `gmp' library and its header file in some
-place where your compiler cannot find it by default, you must help
-`configure' by setting `CPPFLAGS' and `LDFLAGS'. Here is an example:
-
- $ CC="gcc" CFLAGS="-O2" CXX="g++" CXXFLAGS="-O2 -fno-exceptions" \
- CPPFLAGS="-I/opt/gmp/include" LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
-
-\1f
-File: cln.info, Node: Installing the library, Next: Cleaning up, Prev: Building the library, Up: Installation
-
-Installing the library
-======================
-
-As with any autoconfiguring GNU software, installation is as easy as
-this:
-
- $ make install
-
-The `make install' command installs the library and the include files
-into public places (`/usr/local/lib/' and `/usr/local/include/', if you
-haven't specified a `--prefix' option to `configure'). This step may
-require superuser privileges.
-
-If you have already built the library and wish to install it, but didn't
-specify `--prefix=...' at configure time, just re-run `configure',
-giving it the same options as the first time, plus the `--prefix=...'
-option.
-
-\1f
-File: cln.info, Node: Cleaning up, Prev: Installing the library, Up: Installation
-
-Cleaning up
-===========
-
-You can remove system-dependent files generated by `make' through
-
- $ make clean
-
-You can remove all files generated by `make', thus reverting to a
-virgin distribution of CLN, through
-
- $ make distclean
-
-\1f
-File: cln.info, Node: Ordinary number types, Next: Functions on numbers, Prev: Installation, Up: Top
-
-Ordinary number types
-*********************
-
-CLN implements the following class hierarchy:
-
- Number
- cl_number
- <cln/number.h>
- |
- |
- Real or complex number
- cl_N
- <cln/complex.h>
- |
- |
- Real number
- cl_R
- <cln/real.h>
- |
- +-------------------+-------------------+
- | |
- Rational number Floating-point number
- cl_RA cl_F
- <cln/rational.h> <cln/float.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>
-
-The base class `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.
-
-The class `cl_N' comprises real and complex numbers. There is no
-special class for complex numbers since complex numbers with imaginary
-part `0' are automatically converted to real numbers.
-
-The class `cl_R' comprises real numbers of different kinds. It is an
-abstract class.
-
-The class `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 `1' are automatically
-converted to integers.
-
-The class `cl_F' implements floating-point approximations to real
-numbers. It is an abstract class.
-
-* Menu:
-
-* Exact numbers::
-* Floating-point numbers::
-* Complex numbers::
-* Conversions::
-
-\1f
-File: cln.info, Node: Exact numbers, Next: Floating-point numbers, Prev: Ordinary number types, Up: Ordinary number types
-
-Exact numbers
-=============
-
-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 representation. On exact numbers, the elementary
-operations (`+', `-', `*', `/', comparisons, ...) compute the completely
-correct result.
-
-In CLN, the exact numbers are:
-
- * rational numbers (including integers),
-
- * complex numbers whose real and imaginary parts are both rational
- numbers.
-
-Rational numbers are always normalized to the form
-`NUMERATOR/DENOMINATOR' where the numerator and denominator are coprime
-integers and the denominator is positive. If the resulting denominator
-is `1', the rational number is converted to an integer.
-
-Small integers (typically in the range `-2^30'...`2^30-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.
-
-\1f
-File: cln.info, Node: Floating-point numbers, Next: Complex numbers, Prev: Exact numbers, Up: Ordinary number types
-
-Floating-point numbers
-======================
-
-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 a computer, even if one assumes that it has unlimited
-storage. But there are uncountably many real numbers.) So some
-approximation is needed. CLN implements ordinary floating-point
-numbers, with mantissa and exponent.
-
-The elementary operations (`+', `-', `*', `/', ...) only return
-approximate results. For example, the value of the expression `(cl_F)
-0.3 + (cl_F) 0.4' prints as `0.70000005', not as `0.7'. Rounding errors
-like this one are inevitable when computing with floating-point numbers.
-
-Nevertheless, CLN rounds the floating-point results of the operations
-`+', `-', `*', `/', `sqrt' according to the "round-to-even" rule: It
-first computes the exact mathematical result and then returns the
-floating-point number which is nearest to this. If two floating-point
-numbers are equally distant from the ideal result, the one with a `0'
-in its least significant mantissa bit is chosen.
-
-Similarly, testing floating point numbers for equality `x == y' is
-gambling with random errors. Better check for `abs(x - y) < epsilon'
-for some well-chosen `epsilon'.
-
-Floating point numbers come in four flavors:
-
- * Short floats, type `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.
-
- * Single floats, type `cl_FF'. They have 1 sign bit, 8 exponent
- bits (including the exponent's sign), and 24 mantissa bits
- (including the "hidden" bit). In CLN, they are represented as
- IEEE single-precision floating point numbers. This corresponds
- closely to the C/C++ type `float'.
-
- * Double floats, type `cl_DF'. They have 1 sign bit, 11 exponent
- bits (including the exponent's sign), and 53 mantissa bits
- (including the "hidden" bit). In CLN, they are represented as
- IEEE double-precision floating point numbers. This corresponds
- closely to the C/C++ type `double'.
-
- * Long floats, type `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. The precision of a long float
- is unlimited, but once created, a long float has a fixed
- precision. (No "lazy recomputation".)
-
-Of course, computations with long floats are more expensive than those
-with smaller floating-point formats.
-
-CLN does not implement features like NaNs, denormalized numbers and
-gradual underflow. If the exponent range of some floating-point type is
-too limited for your application, choose another floating-point type
-with larger exponent range.
-
-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 `cl_F'. This has the advantage that when you change
-the precision of some computation (say, from `cl_DF' to `cl_LF'), you
-don't have to change the code, only the precision of the initial
-values. Also, many transcendental functions have been declared as
-returning a `cl_F' when the argument is a `cl_F', but such declarations
-are missing for the types `cl_SF', `cl_FF', `cl_DF', `cl_LF'. (Such
-declarations would be wrong if the floating point contagion rule
-happened to change in the future.)
-
-\1f
-File: cln.info, Node: Complex numbers, Next: Conversions, Prev: Floating-point numbers, Up: Ordinary number types
-
-Complex numbers
-===============
-
-Complex numbers, as implemented by the class `cl_N', have a real part
-and an imaginary part, both real numbers. A complex number whose
-imaginary part is the exact number `0' is automatically converted to a
-real number.
-
-Complex numbers can arise from real numbers alone, for example through
-application of `sqrt' or transcendental functions.
-
-\1f
-File: cln.info, Node: Conversions, Prev: Complex numbers, Up: Ordinary number types
-
-Conversions
-===========
-
-Conversions from any class to any its superclasses ("base classes" in
-C++ terminology) is done automatically.
-
-Conversions from the C built-in types `long' and `unsigned long' are
-provided for the classes `cl_I', `cl_RA', `cl_R', `cl_N' and
-`cl_number'.
-
-Conversions from the C built-in types `int' and `unsigned int' are
-provided for the classes `cl_I', `cl_RA', `cl_R', `cl_N' and
-`cl_number'. However, these conversions emphasize efficiency. Their
-range is therefore limited:
-
- - The conversion from `int' works only if the argument is < 2^29 and
- > -2^29.
-
- - The conversion from `unsigned int' works only if the argument is <
- 2^29.
-
-In a declaration like `cl_I x = 10;' the C++ compiler is able to do the
-conversion of `10' from `int' to `cl_I' at compile time already. On the
-other hand, code like `cl_I x = 1000000000;' is in error. So, if you
-want to be sure that an `int' whose magnitude is not guaranteed to be <
-2^29 is correctly converted to a `cl_I', first convert it to a `long'.
-Similarly, if a large `unsigned int' is to be converted to a `cl_I',
-first convert it to an `unsigned long'.
-
-Conversions from the C built-in type `float' are provided for the
-classes `cl_FF', `cl_F', `cl_R', `cl_N' and `cl_number'.
-
-Conversions from the C built-in type `double' are provided for the
-classes `cl_DF', `cl_F', `cl_R', `cl_N' and `cl_number'.
-
-Conversions from `const char *' are provided for the classes `cl_I',
-`cl_RA', `cl_SF', `cl_FF', `cl_DF', `cl_LF', `cl_F', `cl_R', `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:
- cl_I order_of_rubiks_cube_group = "43252003274489856000";
-Note that this conversion is done at runtime, not at compile-time.
-
-Conversions from `cl_I' to the C built-in types `int', `unsigned int',
-`long', `unsigned long' are provided through the functions
-
-`int cl_I_to_int (const cl_I& x)'
-`unsigned int cl_I_to_uint (const cl_I& x)'
-`long cl_I_to_long (const cl_I& x)'
-`unsigned long cl_I_to_ulong (const cl_I& x)'
- Returns `x' as element of the C type CTYPE. If `x' is not
- representable in the range of CTYPE, a runtime error occurs.
-
-Conversions from the classes `cl_I', `cl_RA', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF', `cl_F' and `cl_R' to the C built-in types `float' and
-`double' are provided through the functions
-
-`float float_approx (const TYPE& x)'
-`double double_approx (const TYPE& x)'
- Returns an approximation of `x' of C type CTYPE. If `abs(x)' is
- too close to 0 (underflow), 0 is returned. If `abs(x)' is too
- large (overflow), an IEEE infinity is returned.
-
-Conversions from any class to any of its subclasses ("derived classes"
-in 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 `As' and `The' macros. `As(TYPE)(VALUE)' checks
-that VALUE belongs to TYPE and returns it as such. `The(TYPE)(VALUE)'
-assumes that VALUE belongs to TYPE and returns it as such. It is your
-responsibility to ensure that this assumption is valid. Example:
-
- cl_I x = ...;
- if (!(x >= 0)) abort();
- cl_I ten_x = The(cl_I)(expt(10,x)); // If x >= 0, 10^x is an integer.
- // In general, it would be a rational number.
-
-\1f
-File: cln.info, Node: Functions on numbers, Next: Input/Output, Prev: Ordinary number types, Up: Top
-
-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 `cl_I', it should `#include <cln/integer.h>'.
-
-* Menu:
-
-* Constructing numbers::
-* Elementary functions::
-* Elementary rational functions::
-* Elementary complex functions::
-* Comparisons::
-* Rounding functions::
-* Roots::
-* Transcendental functions::
-* Functions on integers::
-* Functions on floating-point numbers::
-* Conversion functions::
-* Random number generators::
-* Obfuscating operators::
-
-\1f
-File: cln.info, Node: Constructing numbers, Next: Elementary functions, Prev: Functions on numbers, Up: Functions on numbers
-
-Constructing numbers
-====================
-
-Here is how to create number objects "from nothing".
-
-* Menu:
-
-* Constructing integers::
-* Constructing rational numbers::
-* Constructing floating-point numbers::
-* Constructing complex numbers::
-
-\1f
-File: cln.info, Node: Constructing integers, Next: Constructing rational numbers, Prev: Constructing numbers, Up: Constructing numbers
-
-Constructing integers
----------------------
-
-`cl_I' objects are most easily constructed from C integers and from
-strings. See *Note Conversions::.
-
-\1f
-File: cln.info, Node: Constructing rational numbers, Next: Constructing floating-point numbers, Prev: Constructing integers, Up: Constructing numbers
-
-Constructing rational numbers
------------------------------
-
-`cl_RA' objects can be constructed from strings. The syntax for
-rational numbers is described in *Note Internal and printed
-representation::. Another standard way to produce a rational number is
-through application of `operator /' or `recip' on integers.
-
-\1f
-File: cln.info, Node: Constructing floating-point numbers, Next: Constructing complex numbers, Prev: Constructing rational numbers, Up: Constructing numbers
-
-Constructing floating-point numbers
------------------------------------
-
-`cl_F' objects with low precision are most easily constructed from C
-`float' and `double'. See *Note Conversions::.
-
-To construct a `cl_F' with high precision, you can use the conversion
-from `const char *', but you have to specify the desired precision
-within the string. (See *Note Internal and printed representation::.)
-Example:
- cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
-will set `e' to the given value, with a precision of 40 decimal digits.
-
-The programmatic way to construct a `cl_F' with high precision is
-through the `cl_float' conversion function, see *Note Conversion to
-floating-point numbers::. For example, to compute `e' to 40 decimal
-places, first construct 1.0 to 40 decimal places and then apply the
-exponential function:
- cl_float_format_t precision = cl_float_format(40);
- cl_F e = exp(cl_float(1,precision));
-
-\1f
-File: cln.info, Node: Constructing complex numbers, Prev: Constructing floating-point numbers, Up: Constructing numbers
-
-Constructing complex numbers
-----------------------------
-
-Non-real `cl_N' objects are normally constructed through the function
- cl_N complex (const cl_R& realpart, const cl_R& imagpart)
-See *Note Elementary complex functions::.
-
-\1f
-File: cln.info, Node: Elementary functions, Next: Elementary rational functions, Prev: Constructing numbers, Up: Functions on numbers
-
-Elementary functions
-====================
-
-Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
-`cl_FF', `cl_DF', `cl_LF' defines the following operations:
-
-`TYPE operator + (const TYPE&, const TYPE&)'
- Addition.
-
-`TYPE operator - (const TYPE&, const TYPE&)'
- Subtraction.
-
-`TYPE operator - (const TYPE&)'
- Returns the negative of the argument.
-
-`TYPE plus1 (const TYPE& x)'
- Returns `x + 1'.
-
-`TYPE minus1 (const TYPE& x)'
- Returns `x - 1'.
-
-`TYPE operator * (const TYPE&, const TYPE&)'
- Multiplication.
-
-`TYPE square (const TYPE& x)'
- Returns `x * x'.
-
-Each of the classes `cl_N', `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF' defines the following operations:
-
-`TYPE operator / (const TYPE&, const TYPE&)'
- Division.
-
-`TYPE recip (const TYPE&)'
- Returns the reciprocal of the argument.
-
-The class `cl_I' doesn't define a `/' operation because in the C/C++
-language this operator, applied to integral types, denotes the `floor'
-or `truncate' operation (which one of these, is implementation
-dependent). (*Note Rounding functions::.) Instead, `cl_I' defines an
-"exact quotient" function:
-
-`cl_I exquo (const cl_I& x, const cl_I& y)'
- Checks that `y' divides `x', and returns the quotient `x'/`y'.
-
-The following exponentiation functions are defined:
-
-`cl_I expt_pos (const cl_I& x, const cl_I& y)'
-`cl_RA expt_pos (const cl_RA& x, const cl_I& y)'
- `y' must be > 0. Returns `x^y'.
-
-`cl_RA expt (const cl_RA& x, const cl_I& y)'
-`cl_R expt (const cl_R& x, const cl_I& y)'
-`cl_N expt (const cl_N& x, const cl_I& y)'
- Returns `x^y'.
-
-Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF' defines the following operation:
-
-`TYPE abs (const TYPE& x)'
- Returns the absolute value of `x'. This is `x' if `x >= 0', and
- `-x' if `x <= 0'.
-
-The class `cl_N' implements this as follows:
-
-`cl_R abs (const cl_N x)'
- Returns the absolute value of `x'.
-
-Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
-`cl_FF', `cl_DF', `cl_LF' defines the following operation:
-
-`TYPE signum (const TYPE& x)'
- Returns the sign of `x', in the same number format as `x'. This
- is defined as `x / abs(x)' if `x' is non-zero, and `x' if `x' is
- zero. If `x' is real, the value is either 0 or 1 or -1.
-
-\1f
-File: cln.info, Node: Elementary rational functions, Next: Elementary complex functions, Prev: Elementary functions, Up: Functions on numbers
-
-Elementary rational functions
-=============================
-
-Each of the classes `cl_RA', `cl_I' defines the following operations:
-
-`cl_I numerator (const TYPE& x)'
- Returns the numerator of `x'.
-
-`cl_I denominator (const TYPE& x)'
- Returns the denominator of `x'.
-
-The numerator and denominator of a rational number are normalized in
-such a way that they have no factor in common and the denominator is
-positive.
-
-\1f
-File: cln.info, Node: Elementary complex functions, Next: Comparisons, Prev: Elementary rational functions, Up: Functions on numbers
-
-Elementary complex functions
-============================
-
-The class `cl_N' defines the following operation:
-
-`cl_N complex (const cl_R& a, const cl_R& b)'
- Returns the complex number `a+bi', that is, the complex number with
- real part `a' and imaginary part `b'.
-
-Each of the classes `cl_N', `cl_R' defines the following operations:
-
-`cl_R realpart (const TYPE& x)'
- Returns the real part of `x'.
-
-`cl_R imagpart (const TYPE& x)'
- Returns the imaginary part of `x'.
-
-`TYPE conjugate (const TYPE& x)'
- Returns the complex conjugate of `x'.
-
-We have the relations
-
- `x = complex(realpart(x), imagpart(x))'
-
- `conjugate(x) = complex(realpart(x), -imagpart(x))'
-
-\1f
-File: cln.info, Node: Comparisons, Next: Rounding functions, Prev: Elementary complex functions, Up: Functions on numbers
-
-Comparisons
-===========
-
-Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
-`cl_FF', `cl_DF', `cl_LF' defines the following operations:
-
-`bool operator == (const TYPE&, const TYPE&)'
-`bool operator != (const TYPE&, const TYPE&)'
- Comparison, as in C and C++.
-
-`uint32 equal_hashcode (const TYPE&)'
- Returns a 32-bit hash code that is the same for any two numbers
- which are the same according to `=='. This hash code depends on
- the number's value, not its type or precision.
-
-`cl_boolean zerop (const TYPE& x)'
- Compare against zero: `x == 0'
-
-Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF' defines the following operations:
-
-`cl_signean compare (const TYPE& x, const TYPE& y)'
- Compares `x' and `y'. Returns +1 if `x'>`y', -1 if `x'<`y', 0 if
- `x'=`y'.
-
-`bool operator <= (const TYPE&, const TYPE&)'
-`bool operator < (const TYPE&, const TYPE&)'
-`bool operator >= (const TYPE&, const TYPE&)'
-`bool operator > (const TYPE&, const TYPE&)'
- Comparison, as in C and C++.
-
-`cl_boolean minusp (const TYPE& x)'
- Compare against zero: `x < 0'
-
-`cl_boolean plusp (const TYPE& x)'
- Compare against zero: `x > 0'
-
-`TYPE max (const TYPE& x, const TYPE& y)'
- Return the maximum of `x' and `y'.
-
-`TYPE min (const TYPE& x, const TYPE& y)'
- Return the minimum of `x' and `y'.
-
-When a floating point number and a rational number are compared, the
-float is first converted to a rational number using the function
-`rational'. Since a floating point number actually represents an
-interval of real numbers, the result might be surprising. For example,
-`(cl_F)(cl_R)"1/3" == (cl_R)"1/3"' returns false because there is no
-floating point number whose value is exactly `1/3'.
-
-\1f
-File: cln.info, Node: Rounding functions, Next: Roots, Prev: Comparisons, Up: Functions on numbers
-
-Rounding functions
-==================
-
-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 Common Lisp and ISO Lisp standards offer four rounding functions:
-
-`floor(x)'
- This is the largest integer <=`x'.
-
-`ceiling(x)'
- This is the smallest integer >=`x'.
-
-`truncate(x)'
- Among the integers between 0 and `x' (inclusive) the one nearest
- to `x'.
-
-`round(x)'
- The integer nearest to `x'. If `x' is exactly halfway between two
- integers, choose the even one.
-
-These functions have different advantages:
-
-`floor' and `ceiling' are translation invariant: `floor(x+n) = floor(x)
-+ n' and `ceiling(x+n) = ceiling(x) + n' for every `x' and every
-integer `n'.
-
-On the other hand, `truncate' and `round' are symmetric: `truncate(-x)
-= -truncate(x)' and `round(-x) = -round(x)', and furthermore `round' is
-unbiased: on the "average", it rounds down exactly as often as it
-rounds up.
-
-The functions are related like this:
-
- `ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1' for rational
- numbers `m/n' (`m', `n' integers, `n'>0), and
-
- `truncate(x) = sign(x) * floor(abs(x))'
-
-Each of the classes `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF', `cl_DF',
-`cl_LF' defines the following operations:
-
-`cl_I floor1 (const TYPE& x)'
- Returns `floor(x)'.
-
-`cl_I ceiling1 (const TYPE& x)'
- Returns `ceiling(x)'.
-
-`cl_I truncate1 (const TYPE& x)'
- Returns `truncate(x)'.
-
-`cl_I round1 (const TYPE& x)'
- Returns `round(x)'.
-
-Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF' defines the following operations:
-
-`cl_I floor1 (const TYPE& x, const TYPE& y)'
- Returns `floor(x/y)'.
-
-`cl_I ceiling1 (const TYPE& x, const TYPE& y)'
- Returns `ceiling(x/y)'.
-
-`cl_I truncate1 (const TYPE& x, const TYPE& y)'
- Returns `truncate(x/y)'.
-
-`cl_I round1 (const TYPE& x, const TYPE& y)'
- Returns `round(x/y)'.
-
-These functions are called `floor1', ... here instead of `floor', ...,
-because on some systems, system dependent include files define `floor'
-and `ceiling' as macros.
-
-In many cases, one needs both the quotient and the remainder of a
-division. It is more efficient to compute both at the same time than
-to perform two divisions, one for quotient and the next one for the
-remainder. The following functions therefore return a structure
-containing both the quotient and the remainder. The suffix `2'
-indicates the number of "return values". The remainder is defined as
-follows:
-
- * for the computation of `quotient = floor(x)', `remainder = x -
- quotient',
-
- * for the computation of `quotient = floor(x,y)', `remainder = x -
- quotient*y',
-
-and similarly for the other three operations.
-
-Each of the classes `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF', `cl_DF',
-`cl_LF' defines the following operations:
-
-`struct TYPE_div_t { cl_I quotient; TYPE remainder; };'
-`TYPE_div_t floor2 (const TYPE& x)'
-`TYPE_div_t ceiling2 (const TYPE& x)'
-`TYPE_div_t truncate2 (const TYPE& x)'
-`TYPE_div_t round2 (const TYPE& x)'
-Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF' defines the following operations:
-
-`struct TYPE_div_t { cl_I quotient; TYPE remainder; };'
-`TYPE_div_t floor2 (const TYPE& x, const TYPE& y)'
-`TYPE_div_t ceiling2 (const TYPE& x, const TYPE& y)'
-`TYPE_div_t truncate2 (const TYPE& x, const TYPE& y)'
-`TYPE_div_t round2 (const TYPE& x, const TYPE& y)'
-Sometimes, one wants the quotient as a floating-point number (of the
-same format as the argument, if the argument is a float) instead of as
-an integer. The prefix `f' indicates this.
-
-Each of the classes `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF' defines
-the following operations:
-
-`TYPE ffloor (const TYPE& x)'
-`TYPE fceiling (const TYPE& x)'
-`TYPE ftruncate (const TYPE& x)'
-`TYPE fround (const TYPE& x)'
-and similarly for class `cl_R', but with return type `cl_F'.
-
-The class `cl_R' defines the following operations:
-
-`cl_F ffloor (const TYPE& x, const TYPE& y)'
-`cl_F fceiling (const TYPE& x, const TYPE& y)'
-`cl_F ftruncate (const TYPE& x, const TYPE& y)'
-`cl_F fround (const TYPE& x, const TYPE& y)'
-These functions also exist in versions which return both the quotient
-and the remainder. The suffix `2' indicates this.
-
-Each of the classes `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF' defines
-the following operations:
-
-`struct TYPE_fdiv_t { TYPE quotient; TYPE remainder; };'
-`TYPE_fdiv_t ffloor2 (const TYPE& x)'
-`TYPE_fdiv_t fceiling2 (const TYPE& x)'
-`TYPE_fdiv_t ftruncate2 (const TYPE& x)'
-`TYPE_fdiv_t fround2 (const TYPE& x)'
-and similarly for class `cl_R', but with quotient type `cl_F'.
-
-The class `cl_R' defines the following operations:
-
-`struct TYPE_fdiv_t { cl_F quotient; cl_R remainder; };'
-`TYPE_fdiv_t ffloor2 (const TYPE& x, const TYPE& y)'
-`TYPE_fdiv_t fceiling2 (const TYPE& x, const TYPE& y)'
-`TYPE_fdiv_t ftruncate2 (const TYPE& x, const TYPE& y)'
-`TYPE_fdiv_t fround2 (const TYPE& x, const TYPE& y)'
-Other applications need only the remainder of a division. The
-remainder of `floor' and `ffloor' is called `mod' (abbreviation of
-"modulo"). The remainder `truncate' and `ftruncate' is called `rem'
-(abbreviation of "remainder").
-
- * `mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y'
-
- * `rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y'
-
-If `x' and `y' are both >= 0, `mod(x,y) = rem(x,y) >= 0'. In general,
-`mod(x,y)' has the sign of `y' or is zero, and `rem(x,y)' has the sign
-of `x' or is zero.
-
-The classes `cl_R', `cl_I' define the following operations:
-
-`TYPE mod (const TYPE& x, const TYPE& y)'
-`TYPE rem (const TYPE& x, const TYPE& y)'
-\1f
-File: cln.info, Node: Roots, Next: Transcendental functions, Prev: Rounding functions, Up: Functions on numbers
-
-Roots
-=====
-
-Each of the classes `cl_R', `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF'
-defines the following operation:
-
-`TYPE sqrt (const TYPE& x)'
- `x' must be >= 0. This function returns the square root of `x',
- normalized to be >= 0. If `x' is the square of a rational number,
- `sqrt(x)' will be a rational number, else it will return a
- floating-point approximation.
-
-The classes `cl_RA', `cl_I' define the following operation:
-
-`cl_boolean sqrtp (const TYPE& x, TYPE* root)'
- This tests whether `x' is a perfect square. If so, it returns true
- and the exact square root in `*root', else it returns false.
-
-Furthermore, for integers, similarly:
-
-`cl_boolean isqrt (const TYPE& x, TYPE* root)'
- `x' should be >= 0. This function sets `*root' to `floor(sqrt(x))'
- and returns the same value as `sqrtp': the boolean value
- `(expt(*root,2) == x)'.
-
-For `n'th roots, the classes `cl_RA', `cl_I' define the following
-operation:
-
-`cl_boolean rootp (const TYPE& x, const cl_I& n, TYPE* root)'
- `x' must be >= 0. `n' must be > 0. This tests whether `x' is an
- `n'th power of a rational number. If so, it returns true and the
- exact root in `*root', else it returns false.
-
-The only square root function which accepts negative numbers is the one
-for class `cl_N':
-
-`cl_N sqrt (const cl_N& z)'
- Returns the square root of `z', as defined by the formula `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 right half plane `realpart(sqrt(z)) >= 0' including the
- positive imaginary axis and 0, but excluding the negative
- imaginary axis. The result is an exact number only if `z' is an
- exact number.
-
-\1f
-File: cln.info, Node: Transcendental functions, Next: Functions on integers, Prev: Roots, Up: Functions on numbers
-
-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
-inexact numbers even if the argument is exact. For example, `cos(0) =
-1' returns the rational number `1'.
-
-* Menu:
-
-* Exponential and logarithmic functions::
-* Trigonometric functions::
-* Hyperbolic functions::
-* Euler gamma::
-* Riemann zeta::
-
-\1f
-File: cln.info, Node: Exponential and logarithmic functions, Next: Trigonometric functions, Prev: Transcendental functions, Up: Transcendental functions
-
-Exponential and logarithmic functions
--------------------------------------
-
-`cl_R exp (const cl_R& x)'
-`cl_N exp (const cl_N& x)'
- Returns the exponential function of `x'. This is `e^x' where `e'
- is the base of the natural logarithms. The range of the result is
- the entire complex plane excluding 0.
-
-`cl_R ln (const cl_R& x)'
- `x' must be > 0. Returns the (natural) logarithm of x.
-
-`cl_N log (const cl_N& x)'
- Returns the (natural) logarithm of x. If `x' is real and positive,
- this is `ln(x)'. In general, `log(x) = log(abs(x)) + i*phase(x)'.
- The range of the result is the strip in the complex plane `-pi <
- imagpart(log(x)) <= pi'.
-
-`cl_R phase (const cl_N& x)'
- Returns the angle part of `x' in its polar representation as a
- complex number. That is, `phase(x) =
- atan(realpart(x),imagpart(x))'. This is also the imaginary part
- of `log(x)'. The range of the result is the interval `-pi <
- phase(x) <= pi'. The result will be an exact number only if
- `zerop(x)' or if `x' is real and positive.
-
-`cl_R log (const cl_R& a, const cl_R& b)'
- `a' and `b' must be > 0. Returns the logarithm of `a' with respect
- to base `b'. `log(a,b) = ln(a)/ln(b)'. The result can be exact
- only if `a = 1' or if `a' and `b' are both rational.
-
-`cl_N log (const cl_N& a, const cl_N& b)'
- Returns the logarithm of `a' with respect to base `b'. `log(a,b)
- = log(a)/log(b)'.
-
-`cl_N expt (const cl_N& x, const cl_N& y)'
- Exponentiation: Returns `x^y = exp(y*log(x))'.
-
-The constant e = exp(1) = 2.71828... is returned by the following
-functions:
-
-`cl_F exp1 (cl_float_format_t f)'
- Returns e as a float of format `f'.
-
-`cl_F exp1 (const cl_F& y)'
- Returns e in the float format of `y'.
-
-`cl_F exp1 (void)'
- Returns e as a float of format `default_float_format'.
-
-\1f
-File: cln.info, Node: Trigonometric functions, Next: Hyperbolic functions, Prev: Exponential and logarithmic functions, Up: Transcendental functions
-
-Trigonometric functions
------------------------
-
-`cl_R sin (const cl_R& x)'
- Returns `sin(x)'. The range of the result is the interval `-1 <=
- sin(x) <= 1'.
-
-`cl_N sin (const cl_N& z)'
- Returns `sin(z)'. The range of the result is the entire complex
- plane.
-
-`cl_R cos (const cl_R& x)'
- Returns `cos(x)'. The range of the result is the interval `-1 <=
- cos(x) <= 1'.
-
-`cl_N cos (const cl_N& x)'
- Returns `cos(z)'. The range of the result is the entire complex
- plane.
-
-`struct cos_sin_t { cl_R cos; cl_R sin; };'
-`cos_sin_t cos_sin (const cl_R& x)'
- Returns both `sin(x)' and `cos(x)'. This is more efficient than
- computing them separately. The relation `cos^2 + sin^2 = 1' will
- hold only approximately.
-
-`cl_R tan (const cl_R& x)'
-`cl_N tan (const cl_N& x)'
- Returns `tan(x) = sin(x)/cos(x)'.
-
-`cl_N cis (const cl_R& x)'
-`cl_N cis (const cl_N& x)'
- Returns `exp(i*x)'. The name `cis' means "cos + i sin", because
- `e^(i*x) = cos(x) + i*sin(x)'.
-
-`cl_N asin (const cl_N& z)'
- Returns `arcsin(z)'. This is defined as `arcsin(z) =
- log(iz+sqrt(1-z^2))/i' and satisfies `arcsin(-z) = -arcsin(z)'.
- The range of the result is the strip in the complex domain `-pi/2
- <= realpart(arcsin(z)) <= pi/2', excluding the numbers with
- `realpart = -pi/2' and `imagpart < 0' and the numbers with
- `realpart = pi/2' and `imagpart > 0'.
-
-`cl_N acos (const cl_N& z)'
- Returns `arccos(z)'. This is defined as `arccos(z) = pi/2 -
- arcsin(z) = log(z+i*sqrt(1-z^2))/i' and satisfies `arccos(-z) = pi
- - arccos(z)'. The range of the result is the strip in the complex
- domain `0 <= realpart(arcsin(z)) <= pi', excluding the numbers
- with `realpart = 0' and `imagpart < 0' and the numbers with
- `realpart = pi' and `imagpart > 0'.
-
-`cl_R atan (const cl_R& x, const cl_R& y)'
- Returns the angle of the polar representation of the complex number
- `x+iy'. This is `atan(y/x)' if `x>0'. The range of the result is
- the interval `-pi < atan(x,y) <= pi'. The result will be an exact
- number only if `x > 0' and `y' is the exact `0'. WARNING: In
- Common Lisp, this function is called as `(atan y x)', with
- reversed order of arguments.
-
-`cl_R atan (const cl_R& x)'
- Returns `arctan(x)'. This is the same as `atan(1,x)'. The range of
- the result is the interval `-pi/2 < atan(x) < pi/2'. The result
- will be an exact number only if `x' is the exact `0'.
-
-`cl_N atan (const cl_N& z)'
- Returns `arctan(z)'. This is defined as `arctan(z) =
- (log(1+iz)-log(1-iz)) / 2i' and satisfies `arctan(-z) =
- -arctan(z)'. The range of the result is the strip in the complex
- domain `-pi/2 <= realpart(arctan(z)) <= pi/2', excluding the
- numbers with `realpart = -pi/2' and `imagpart >= 0' and the numbers
- with `realpart = pi/2' and `imagpart <= 0'.
-
-Archimedes' constant pi = 3.14... is returned by the following
-functions:
-
-`cl_F pi (cl_float_format_t f)'
- Returns pi as a float of format `f'.
-
-`cl_F pi (const cl_F& y)'
- Returns pi in the float format of `y'.
-
-`cl_F pi (void)'
- Returns pi as a float of format `default_float_format'.
-
-\1f
-File: cln.info, Node: Hyperbolic functions, Next: Euler gamma, Prev: Trigonometric functions, Up: Transcendental functions
-
-Hyperbolic functions
---------------------
-
-`cl_R sinh (const cl_R& x)'
- Returns `sinh(x)'.
-
-`cl_N sinh (const cl_N& z)'
- Returns `sinh(z)'. The range of the result is the entire complex
- plane.
-
-`cl_R cosh (const cl_R& x)'
- Returns `cosh(x)'. The range of the result is the interval
- `cosh(x) >= 1'.
-
-`cl_N cosh (const cl_N& z)'
- Returns `cosh(z)'. The range of the result is the entire complex
- plane.
-
-`struct cosh_sinh_t { cl_R cosh; cl_R sinh; };'
-`cosh_sinh_t cosh_sinh (const cl_R& x)'
- Returns both `sinh(x)' and `cosh(x)'. This is more efficient than
- computing them separately. The relation `cosh^2 - sinh^2 = 1' will
- hold only approximately.
-
-`cl_R tanh (const cl_R& x)'
-`cl_N tanh (const cl_N& x)'
- Returns `tanh(x) = sinh(x)/cosh(x)'.
-
-`cl_N asinh (const cl_N& z)'
- Returns `arsinh(z)'. This is defined as `arsinh(z) =
- log(z+sqrt(1+z^2))' and satisfies `arsinh(-z) = -arsinh(z)'. The
- range of the result is the strip in the complex domain `-pi/2 <=
- imagpart(arsinh(z)) <= pi/2', excluding the numbers with `imagpart
- = -pi/2' and `realpart > 0' and the numbers with `imagpart = pi/2'
- and `realpart < 0'.
-
-`cl_N acosh (const cl_N& z)'
- Returns `arcosh(z)'. This is defined as `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 `-pi < imagpart(arcosh(z)) <=
- pi, realpart(arcosh(z)) >= 0', excluding the numbers with
- `realpart = 0' and `-pi < imagpart < 0'.
-
-`cl_N atanh (const cl_N& z)'
- Returns `artanh(z)'. This is defined as `artanh(z) =
- (log(1+z)-log(1-z)) / 2' and satisfies `artanh(-z) = -artanh(z)'.
- The range of the result is the strip in the complex domain `-pi/2
- <= imagpart(artanh(z)) <= pi/2', excluding the numbers with
- `imagpart = -pi/2' and `realpart <= 0' and the numbers with
- `imagpart = pi/2' and `realpart >= 0'.
-
-\1f
-File: cln.info, Node: Euler gamma, Next: Riemann zeta, Prev: Hyperbolic functions, Up: Transcendental functions
-
-Euler gamma
------------
-
-Euler's constant C = 0.577... is returned by the following functions:
-
-`cl_F eulerconst (cl_float_format_t f)'
- Returns Euler's constant as a float of format `f'.
-
-`cl_F eulerconst (const cl_F& y)'
- Returns Euler's constant in the float format of `y'.
-
-`cl_F eulerconst (void)'
- Returns Euler's constant as a float of format
- `default_float_format'.
-
-Catalan's constant G = 0.915... is returned by the following functions:
-
-`cl_F catalanconst (cl_float_format_t f)'
- Returns Catalan's constant as a float of format `f'.
-
-`cl_F catalanconst (const cl_F& y)'
- Returns Catalan's constant in the float format of `y'.
-
-`cl_F catalanconst (void)'
- Returns Catalan's constant as a float of format
- `default_float_format'.
-
-\1f
-File: cln.info, Node: Riemann zeta, Prev: Euler gamma, Up: Transcendental functions
-
-Riemann zeta
-------------
-
-Riemann's zeta function at an integral point `s>1' is returned by the
-following functions:
-
-`cl_F zeta (int s, cl_float_format_t f)'
- Returns Riemann's zeta function at `s' as a float of format `f'.
-
-`cl_F zeta (int s, const cl_F& y)'
- Returns Riemann's zeta function at `s' in the float format of `y'.
-
-`cl_F zeta (int s)'
- Returns Riemann's zeta function at `s' as a float of format
- `default_float_format'.
-
-\1f
-File: cln.info, Node: Functions on integers, Next: Functions on floating-point numbers, Prev: Transcendental functions, Up: Functions on numbers
-
-Functions on integers
-=====================
-
-* Menu:
-
-* Logical functions::
-* Number theoretic functions::
-* Combinatorial functions::
-
-\1f
-File: cln.info, Node: Logical functions, Next: Number theoretic functions, Prev: Functions on integers, Up: Functions on integers
-
-Logical functions
------------------
-
-Integers, when viewed as in two's complement notation, can be thought as
-infinite bit strings where the bits' values eventually are constant.
-For example,
- 17 = ......00010001
- -6 = ......11111010
-
-The logical operations view integers as such bit strings and operate on
-each of the bit positions in parallel.
-
-`cl_I lognot (const cl_I& x)'
-`cl_I operator ~ (const cl_I& x)'
- Logical not, like `~x' in C. This is the same as `-1-x'.
-
-`cl_I logand (const cl_I& x, const cl_I& y)'
-`cl_I operator & (const cl_I& x, const cl_I& y)'
- Logical and, like `x & y' in C.
-
-`cl_I logior (const cl_I& x, const cl_I& y)'
-`cl_I operator | (const cl_I& x, const cl_I& y)'
- Logical (inclusive) or, like `x | y' in C.
-
-`cl_I logxor (const cl_I& x, const cl_I& y)'
-`cl_I operator ^ (const cl_I& x, const cl_I& y)'
- Exclusive or, like `x ^ y' in C.
-
-`cl_I logeqv (const cl_I& x, const cl_I& y)'
- Bitwise equivalence, like `~(x ^ y)' in C.
-
-`cl_I lognand (const cl_I& x, const cl_I& y)'
- Bitwise not and, like `~(x & y)' in C.
-
-`cl_I lognor (const cl_I& x, const cl_I& y)'
- Bitwise not or, like `~(x | y)' in C.
-
-`cl_I logandc1 (const cl_I& x, const cl_I& y)'
- Logical and, complementing the first argument, like `~x & y' in C.
-
-`cl_I logandc2 (const cl_I& x, const cl_I& y)'
- Logical and, complementing the second argument, like `x & ~y' in C.
-
-`cl_I logorc1 (const cl_I& x, const cl_I& y)'
- Logical or, complementing the first argument, like `~x | y' in C.
-
-`cl_I logorc2 (const cl_I& x, const cl_I& y)'
- Logical or, complementing the second argument, like `x | ~y' in C.
-
-These operations are all available though the function
-`cl_I boole (cl_boole op, const cl_I& x, const cl_I& y)'
-where `op' must have one of the 16 values (each one stands for a
-function which combines two bits into one bit): `boole_clr',
-`boole_set', `boole_1', `boole_2', `boole_c1', `boole_c2', `boole_and',
-`boole_ior', `boole_xor', `boole_eqv', `boole_nand', `boole_nor',
-`boole_andc1', `boole_andc2', `boole_orc1', `boole_orc2'.
-
-Other functions that view integers as bit strings:
-
-`cl_boolean logtest (const cl_I& x, const cl_I& y)'
- Returns true if some bit is set in both `x' and `y', i.e. if
- `logand(x,y) != 0'.
-
-`cl_boolean logbitp (const cl_I& n, const cl_I& x)'
- Returns true if the `n'th bit (from the right) of `x' is set. Bit
- 0 is the least significant bit.
-
-`uintL logcount (const cl_I& x)'
- Returns the number of one bits in `x', if `x' >= 0, or the number
- of zero bits in `x', if `x' < 0.
-
-The following functions operate on intervals of bits in integers. The
-type
- struct cl_byte { uintL size; uintL position; };
-represents the bit interval containing the bits
-`position'...`position+size-1' of an integer. The constructor
-`cl_byte(size,position)' constructs a `cl_byte'.
-
-`cl_I ldb (const cl_I& n, const cl_byte& b)'
- extracts the bits of `n' described by the bit interval `b' and
- returns them as a nonnegative integer with `b.size' bits.
-
-`cl_boolean ldb_test (const cl_I& n, const cl_byte& b)'
- Returns true if some bit described by the bit interval `b' is set
- in `n'.
-
-`cl_I dpb (const cl_I& newbyte, const cl_I& n, const cl_byte& b)'
- Returns `n', with the bits described by the bit interval `b'
- replaced by `newbyte'. Only the lowest `b.size' bits of `newbyte'
- are relevant.
-
-The functions `ldb' and `dpb' implicitly shift. The following functions
-are their counterparts without shifting:
-
-`cl_I mask_field (const cl_I& n, const cl_byte& b)'
- returns an integer with the bits described by the bit interval `b'
- copied from the corresponding bits in `n', the other bits zero.
-
-`cl_I deposit_field (const cl_I& newbyte, const cl_I& n, const cl_byte& b)'
- returns an integer where the bits described by the bit interval `b'
- come from `newbyte' and the other bits come from `n'.
-
-The following relations hold:
-
- `ldb (n, b) = mask_field(n, b) >> b.position',
-
- `dpb (newbyte, n, b) = deposit_field (newbyte << b.position, n,
- b)',
-
- `deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^
- mask_field(new_byte,b)'.
-
-The following operations on integers as bit strings are efficient
-shortcuts for common arithmetic operations:
-
-`cl_boolean oddp (const cl_I& x)'
- Returns true if the least significant bit of `x' is 1. Equivalent
- to `mod(x,2) != 0'.
-
-`cl_boolean evenp (const cl_I& x)'
- Returns true if the least significant bit of `x' is 0. Equivalent
- to `mod(x,2) == 0'.
-
-`cl_I operator << (const cl_I& x, const cl_I& n)'
- Shifts `x' by `n' bits to the left. `n' should be >=0. Equivalent
- to `x * expt(2,n)'.
-
-`cl_I operator >> (const cl_I& x, const cl_I& n)'
- Shifts `x' by `n' bits to the right. `n' should be >=0. Bits
- shifted out to the right are thrown away. Equivalent to `floor(x
- / expt(2,n))'.
-
-`cl_I ash (const cl_I& x, const cl_I& y)'
- Shifts `x' by `y' bits to the left (if `y'>=0) or by `-y' bits to
- the right (if `y'<=0). In other words, this returns `floor(x *
- expt(2,y))'.
-
-`uintL integer_length (const cl_I& x)'
- Returns the number of bits (excluding the sign bit) needed to
- represent `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.
-
-`uintL ord2 (const cl_I& x)'
- `x' must be non-zero. This function returns the number of 0 bits
- at the right of `x' in two's complement notation. This is the
- largest n >= 0 such that 2^n divides `x'.
-
-`uintL power2p (const cl_I& x)'
- `x' must be > 0. This function checks whether `x' is a power of 2.
- If `x' = 2^(n-1), it returns n. Else it returns 0. (See also the
- function `logp'.)
-
-\1f
-File: cln.info, Node: Number theoretic functions, Next: Combinatorial functions, Prev: Logical functions, Up: Functions on integers
-
-Number theoretic functions
---------------------------
-
-`uint32 gcd (uint32 a, uint32 b)'
-`cl_I gcd (const cl_I& a, const cl_I& b)'
- This function returns the greatest common divisor of `a' and `b',
- normalized to be >= 0.
-
-`cl_I xgcd (const cl_I& a, const cl_I& b, cl_I* u, cl_I* v)'
- This function ("extended gcd") returns the greatest common divisor
- `g' of `a' and `b' and at the same time the representation of `g'
- as an integral linear combination of `a' and `b': `u' and `v' with
- `u*a+v*b = g', `g' >= 0. `u' and `v' will be normalized to be of
- smallest possible absolute value, in the following sense: If `a'
- and `b' are non-zero, and `abs(a) != abs(b)', `u' and `v' will
- satisfy the inequalities `abs(u) <= abs(b)/(2*g)', `abs(v) <=
- abs(a)/(2*g)'.
-
-`cl_I lcm (const cl_I& a, const cl_I& b)'
- This function returns the least common multiple of `a' and `b',
- normalized to be >= 0.
-
-`cl_boolean logp (const cl_I& a, const cl_I& b, cl_RA* l)'
-`cl_boolean logp (const cl_RA& a, const cl_RA& b, cl_RA* l)'
- `a' must be > 0. `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.
-
-\1f
-File: cln.info, Node: Combinatorial functions, Prev: Number theoretic functions, Up: Functions on integers
-
-Combinatorial functions
------------------------
-
-`cl_I factorial (uintL n)'
- `n' must be a small integer >= 0. This function returns the
- factorial `n'! = `1*2*...*n'.
-
-`cl_I doublefactorial (uintL n)'
- `n' must be a small integer >= 0. This function returns the
- doublefactorial `n'!! = `1*3*...*n' or `n'!! = `2*4*...*n',
- respectively.
-
-`cl_I binomial (uintL n, uintL k)'
- `n' and `k' must be small integers >= 0. This function returns the
- binomial coefficient (`n' choose `k') = `n'! / `k'! `(n-k)'! for
- 0 <= k <= n, 0 else.
-
-\1f
-File: cln.info, Node: Functions on floating-point numbers, Next: Conversion functions, Prev: Functions on integers, Up: Functions on numbers
-
-Functions on floating-point numbers
-===================================
-
-Recall that a floating-point number consists of a sign `s', an exponent
-`e' and a mantissa `m'. The value of the number is `(-1)^s * 2^e * m'.
-
-Each of the classes `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF' defines
-the following operations.
-
-`TYPE scale_float (const TYPE& x, sintL delta)'
-`TYPE scale_float (const TYPE& x, const cl_I& delta)'
- Returns `x*2^delta'. This is more efficient than an explicit
- multiplication because it copies `x' and modifies the exponent.
-
-The following functions provide an abstract interface to the underlying
-representation of floating-point numbers.
-
-`sintL float_exponent (const TYPE& x)'
- Returns the exponent `e' of `x'. For `x = 0.0', this is 0. For
- `x' non-zero, this is the unique integer with `2^(e-1) <= abs(x) <
- 2^e'.
-
-`sintL float_radix (const TYPE& x)'
- Returns the base of the floating-point representation. This is
- always `2'.
-
-`TYPE float_sign (const TYPE& x)'
- Returns the sign `s' of `x' as a float. The value is 1 for `x' >=
- 0, -1 for `x' < 0.
-
-`uintL float_digits (const TYPE& x)'
- Returns the number of mantissa bits in the floating-point
- representation of `x', including the hidden bit. The value only
- depends on the type of `x', not on its value.
-
-`uintL float_precision (const TYPE& x)'
- Returns the number of significant mantissa bits in the
- floating-point representation of `x'. Since denormalized numbers
- are not supported, this is the same as `float_digits(x)' if `x' is
- non-zero, and 0 if `x' = 0.
-
-The complete internal representation of a float is encoded in the type
-`decoded_float' (or `decoded_sfloat', `decoded_ffloat',
-`decoded_dfloat', `decoded_lfloat', respectively), defined by
- struct decoded_TYPEfloat {
- TYPE mantissa; cl_I exponent; TYPE sign;
- };
-
-and returned by the function
-
-`decoded_TYPEfloat decode_float (const TYPE& x)'
- For `x' non-zero, this returns `(-1)^s', `e', `m' with `x = (-1)^s
- * 2^e * m' and `0.5 <= m < 1.0'. For `x' = 0, it returns
- `(-1)^s'=1, `e'=0, `m'=0. `e' is the same as returned by the
- function `float_exponent'.
-
-A complete decoding in terms of integers is provided as type
- struct cl_idecoded_float {
- cl_I mantissa; cl_I exponent; cl_I sign;
- };
-by the following function:
-
-`cl_idecoded_float integer_decode_float (const TYPE& x)'
- For `x' non-zero, this returns `(-1)^s', `e', `m' with `x = (-1)^s
- * 2^e * m' and `m' an integer with `float_digits(x)' bits. For `x'
- = 0, it returns `(-1)^s'=1, `e'=0, `m'=0. WARNING: The exponent
- `e' is not the same as the one returned by the functions
- `decode_float' and `float_exponent'.
-
-Some other function, implemented only for class `cl_F':
-
-`cl_F float_sign (const cl_F& x, const cl_F& y)'
- This returns a floating point number whose precision and absolute
- value is that of `y' and whose sign is that of `x'. If `x' is
- zero, it is treated as positive. Same for `y'.
-
-\1f
-File: cln.info, Node: Conversion functions, Next: Random number generators, Prev: Functions on floating-point numbers, Up: Functions on numbers
-
-Conversion functions
-====================
-
-* Menu:
-
-* Conversion to floating-point numbers::
-* Conversion to rational numbers::
-
-\1f
-File: cln.info, Node: Conversion to floating-point numbers, Next: Conversion to rational numbers, Prev: Conversion functions, Up: Conversion functions
-
-Conversion to floating-point numbers
-------------------------------------
-
-The type `cl_float_format_t' describes a floating-point format.
-
-`cl_float_format_t cl_float_format (uintL n)'
- Returns the smallest float format which guarantees at least `n'
- decimal digits in the mantissa (after the decimal point).
-
-`cl_float_format_t cl_float_format (const cl_F& x)'
- Returns the floating point format of `x'.
-
-`cl_float_format_t default_float_format'
- Global variable: the default float format used when converting
- rational numbers to floats.
-
-To convert a real number to a float, each of the types `cl_R', `cl_F',
-`cl_I', `cl_RA', `int', `unsigned int', `float', `double' defines the
-following operations:
-
-`cl_F cl_float (const TYPE&x, cl_float_format_t f)'
- Returns `x' as a float of format `f'.
-
-`cl_F cl_float (const TYPE&x, const cl_F& y)'
- Returns `x' in the float format of `y'.
-
-`cl_F cl_float (const TYPE&x)'
- Returns `x' as a float of format `default_float_format' if it is
- an exact number, or `x' itself if it is already a float.
-
-Of course, converting a number to a float can lose precision.
-
-Every floating-point format has some characteristic numbers:
-
-`cl_F most_positive_float (cl_float_format_t f)'
- Returns the largest (most positive) floating point number in float
- format `f'.
-
-`cl_F most_negative_float (cl_float_format_t f)'
- Returns the smallest (most negative) floating point number in
- float format `f'.
-
-`cl_F least_positive_float (cl_float_format_t f)'
- Returns the least positive floating point number (i.e. > 0 but
- closest to 0) in float format `f'.
-
-`cl_F least_negative_float (cl_float_format_t f)'
- Returns the least negative floating point number (i.e. < 0 but
- closest to 0) in float format `f'.
-
-`cl_F float_epsilon (cl_float_format_t f)'
- Returns the smallest floating point number e > 0 such that `1+e !=
- 1'.
-
-`cl_F float_negative_epsilon (cl_float_format_t f)'
- Returns the smallest floating point number e > 0 such that `1-e !=
- 1'.
-
-\1f
-File: cln.info, Node: Conversion to rational numbers, Prev: Conversion to floating-point numbers, Up: Conversion functions
-
-Conversion to rational numbers
-------------------------------
-
-Each of the classes `cl_R', `cl_RA', `cl_F' defines the following
-operation:
-
-`cl_RA rational (const TYPE& x)'
- Returns the value of `x' as an exact number. If `x' is already an
- exact number, this is `x'. If `x' is a floating-point number, the
- value is a rational number whose denominator is a power of 2.
-
-In order to convert back, say, `(cl_F)(cl_R)"1/3"' to `1/3', there is
-the function
-
-`cl_RA rationalize (const cl_R& x)'
- If `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) which lies in this interval. If `x' is already an
- exact number, this function returns `x'.
-
-If `x' is any float, one has
-
- `cl_float(rational(x),x) = x'
-
- `cl_float(rationalize(x),x) = x'
-
-\1f
-File: cln.info, Node: Random number generators, Next: Obfuscating operators, Prev: Conversion functions, Up: Functions on numbers
-
-Random number generators
-========================
-
-A random generator is a machine which produces (pseudo-)random numbers.
-The include file `<cln/random.h>' defines a class `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.
-
-The following functions return (pseudo-)random numbers in different
-formats. Calling one of these modifies the state of the random number
-generator in a complicated but deterministic way.
-
-The global variable
- random_state default_random_state
-contains a default random number generator. It is used when the
-functions below are called without `random_state' argument.
-
-`uint32 random32 (random_state& randomstate)'
-`uint32 random32 ()'
- Returns a random unsigned 32-bit number. All bits are equally
- random.
-
-`cl_I random_I (random_state& randomstate, const cl_I& n)'
-`cl_I random_I (const cl_I& n)'
- `n' must be an integer > 0. This function returns a random integer
- `x' in the range `0 <= x < n'.
-
-`cl_F random_F (random_state& randomstate, const cl_F& n)'
-`cl_F random_F (const cl_F& n)'
- `n' must be a float > 0. This function returns a random
- floating-point number of the same format as `n' in the range `0 <=
- x < n'.
-
-`cl_R random_R (random_state& randomstate, const cl_R& n)'
-`cl_R random_R (const cl_R& n)'
- Behaves like `random_I' if `n' is an integer and like `random_F'
- if `n' is a float.
-
-\1f
-File: cln.info, Node: Obfuscating operators, Prev: Random number generators, Up: Functions on numbers
-
-Obfuscating operators
-=====================
-
-The modifying C/C++ operators `+=', `-=', `*=', `/=', `&=', `|=', `^=',
-`<<=', `>>=' 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
- #define WANT_OBFUSCATING_OPERATORS
-to the beginning of your source files, before the inclusion of any CLN
-include files. This flag will enable the following operators:
-
-For the classes `cl_N', `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF',
-`cl_DF', `cl_LF':
-
-`TYPE& operator += (TYPE&, const TYPE&)'
-`TYPE& operator -= (TYPE&, const TYPE&)'
-`TYPE& operator *= (TYPE&, const TYPE&)'
-`TYPE& operator /= (TYPE&, const TYPE&)'
-For the class `cl_I':
-
-`TYPE& operator += (TYPE&, const TYPE&)'
-`TYPE& operator -= (TYPE&, const TYPE&)'
-`TYPE& operator *= (TYPE&, const TYPE&)'
-`TYPE& operator &= (TYPE&, const TYPE&)'
-`TYPE& operator |= (TYPE&, const TYPE&)'
-`TYPE& operator ^= (TYPE&, const TYPE&)'
-`TYPE& operator <<= (TYPE&, const TYPE&)'
-`TYPE& operator >>= (TYPE&, const TYPE&)'
-For the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
-`cl_FF', `cl_DF', `cl_LF':
-
-`TYPE& operator ++ (TYPE& x)'
- The prefix operator `++x'.
-
-`void operator ++ (TYPE& x, int)'
- The postfix operator `x++'.
-
-`TYPE& operator -- (TYPE& x)'
- The prefix operator `--x'.
-
-`void operator -- (TYPE& x, int)'
- The postfix operator `x--'.
-
-Note that by using these obfuscating operators, you wouldn't gain
-efficiency: In CLN `x += y;' is exactly the same as `x = x+y;', not
-more efficient.
-
-\1f
-File: cln.info, Node: Input/Output, Next: Rings, Prev: Functions on numbers, Up: Top
-
-Input/Output
-************
-
-* Menu:
-
-* Internal and printed representation::
-* Input functions::
-* Output functions::
-
-\1f
-File: cln.info, Node: Internal and printed representation, Next: Input functions, Prev: Input/Output, Up: Input/Output
-
-Internal and printed representation
-===================================
-
-All computations deal with the internal representations of the numbers.
-
-Every number has an external representation as a sequence of ASCII
-characters. Several external representations may denote the same
-number, for example, "20.0" and "20.000".
-
-Converting an internal to an external representation is called
-"printing", converting an external to an internal representation is
-called "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: `read(print(x)) == x'. This is called "print-read
-consistency".
-
-Different types of numbers have different external representations (case
-is insignificant):
-
-Integers
- External representation: SIGN{DIGIT}+. The reader also accepts the
- Common Lisp syntaxes SIGN{DIGIT}+`.' with a trailing dot for
- decimal integers and the `#NR', `#b', `#o', `#x' prefixes.
-
-Rational numbers
- External representation: SIGN{DIGIT}+`/'{DIGIT}+. The `#NR',
- `#b', `#o', `#x' prefixes are allowed here as well.
-
-Floating-point numbers
- External representation: SIGN{DIGIT}*EXPONENT or
- SIGN{DIGIT}*`.'{DIGIT}*EXPONENT or SIGN{DIGIT}*`.'{DIGIT}+. A
- precision specifier of the form _PREC may be appended. There must
- be at least one digit in the non-exponent part. The exponent has
- the syntax EXPMARKER EXPSIGN {DIGIT}+. The exponent marker is
-
- `s' for short-floats,
-
- `f' for single-floats,
-
- `d' for double-floats,
-
- `L' for long-floats,
-
- or `e', which denotes a default float format. The precision
- specifying suffix has the syntax _PREC where PREC denotes the
- number of valid mantissa digits (in decimal, excluding leading
- zeroes), cf. also function `cl_float_format'.
-
-Complex numbers
- External representation:
- In algebraic notation: `REALPART+IMAGPARTi'. Of course, if
- IMAGPART is negative, its printed representation begins with
- a `-', and the `+' between REALPART and IMAGPART may be
- omitted. Note that this notation cannot be used when the
- IMAGPART is rational and the rational number's base is >18,
- because the `i' is then read as a digit.
-
- In Common Lisp notation: `#C(REALPART IMAGPART)'.
-
-\1f
-File: cln.info, Node: Input functions, Next: Output functions, Prev: Internal and printed representation, Up: Input/Output
-
-Input functions
-===============
-
-Including `<cln/io.h>' defines a type `cl_istream', which is the type
-of the first argument to all input functions. `cl_istream' is the same
-as `std::istream&'.
-
-The variable
- `cl_istream stdin'
-contains the standard input stream.
-
-These are the simple input functions:
-
-`int freadchar (cl_istream stream)'
- Reads a character from `stream'. Returns `cl_EOF' (not a `char'!)
- if the end of stream was encountered or an error occurred.
-
-`int funreadchar (cl_istream stream, int c)'
- Puts back `c' onto `stream'. `c' must be the result of the last
- `freadchar' operation on `stream'.
-
-Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
-`cl_FF', `cl_DF', `cl_LF' defines, in `<cln/TYPE_io.h>', the following
-input function:
-
-`cl_istream operator>> (cl_istream stream, TYPE& result)'
- Reads a number from `stream' and stores it in the `result'.
-
-The most flexible input functions, defined in `<cln/TYPE_io.h>', are
-the following:
-
-`cl_N read_complex (cl_istream stream, const cl_read_flags& flags)'
-`cl_R read_real (cl_istream stream, const cl_read_flags& flags)'
-`cl_F read_float (cl_istream stream, const cl_read_flags& flags)'
-`cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)'
-`cl_I read_integer (cl_istream stream, const cl_read_flags& flags)'
- Reads a number from `stream'. The `flags' are parameters which
- affect the input syntax. Whitespace before the number is silently
- skipped.
-
-`cl_N read_complex (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
-`cl_R read_real (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
-`cl_F read_float (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
-`cl_RA read_rational (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
-`cl_I read_integer (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
- Reads a number from a string in memory. The `flags' are parameters
- which affect the input syntax. The string starts at `string' and
- ends at `string_limit' (exclusive limit). `string_limit' may also
- be `NULL', denoting the entire string, i.e. equivalent to
- `string_limit = string + strlen(string)'. If `end_of_parse' is
- `NULL', the string in memory must contain exactly one number and
- nothing more, else a fatal error will be signalled. If
- `end_of_parse' is not `NULL', `*end_of_parse' will be assigned a
- pointer past the last parsed character (i.e. `string_limit' if
- nothing came after the number). Whitespace is not allowed.
-
-The structure `cl_read_flags' contains the following fields:
-
-`cl_read_syntax_t syntax'
- The possible results of the read operation. Possible values are
- `syntax_number', `syntax_real', `syntax_rational',
- `syntax_integer', `syntax_float', `syntax_sfloat',
- `syntax_ffloat', `syntax_dfloat', `syntax_lfloat'.
-
-`cl_read_lsyntax_t lsyntax'
- Specifies the language-dependent syntax variant for the read
- operation. Possible values are
-
- `lsyntax_standard'
- accept standard algebraic notation only, no complex numbers,
-
- `lsyntax_algebraic'
- accept the algebraic notation `X+Yi' for complex numbers,
-
- `lsyntax_commonlisp'
- accept the `#b', `#o', `#x' syntaxes for binary, octal,
- hexadecimal numbers, `#BASER' for rational numbers in a given
- base, `#c(REALPART IMAGPART)' for complex numbers,
-
- `lsyntax_all'
- accept all of these extensions.
-
-`unsigned int rational_base'
- The base in which rational numbers are read.
-
-`cl_float_format_t float_flags.default_float_format'
- The float format used when reading floats with exponent marker `e'.
-
-`cl_float_format_t float_flags.default_lfloat_format'
- The float format used when reading floats with exponent marker `l'.
-
-`cl_boolean 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
- _NNN suffix, will get a precision corresponding to their number of
- significant digits.
-
-\1f
-File: cln.info, Node: Output functions, Prev: Input functions, Up: Input/Output
-
-Output functions
-================
-
-Including `<cln/io.h>' defines a type `cl_ostream', which is the type
-of the first argument to all output functions. `cl_ostream' is the same
-as `std::ostream&'.
-
-The variable
- `cl_ostream stdout'
-contains the standard output stream.
-
-The variable
- `cl_ostream stderr'
-contains the standard error output stream.
-
-These are the simple output functions:
-
-`void fprintchar (cl_ostream stream, char c)'
- Prints the character `x' literally on the `stream'.
-
-`void fprint (cl_ostream stream, const char * string)'
- Prints the `string' literally on the `stream'.
-
-`void fprintdecimal (cl_ostream stream, int x)'
-`void fprintdecimal (cl_ostream stream, const cl_I& x)'
- Prints the integer `x' in decimal on the `stream'.
-
-`void fprintbinary (cl_ostream stream, const cl_I& x)'
- Prints the integer `x' in binary (base 2, without prefix) on the
- `stream'.
-
-`void fprintoctal (cl_ostream stream, const cl_I& x)'
- Prints the integer `x' in octal (base 8, without prefix) on the
- `stream'.
-
-`void fprinthexadecimal (cl_ostream stream, const cl_I& x)'
- Prints the integer `x' in hexadecimal (base 16, without prefix) on
- the `stream'.
-
-Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
-`cl_FF', `cl_DF', `cl_LF' defines, in `<cln/TYPE_io.h>', the following
-output functions:
-
-`void fprint (cl_ostream stream, const TYPE& x)'
-`cl_ostream operator<< (cl_ostream stream, const TYPE& x)'
- Prints the number `x' on the `stream'. The output may depend on
- the global printer settings in the variable `default_print_flags'.
- The `ostream' flags and settings (flags, width and locale) are
- ignored.
-
-The most flexible output function, defined in `<cln/TYPE_io.h>', are
-the following:
- void print_complex (cl_ostream stream, const cl_print_flags& flags,
- const cl_N& z);
- void print_real (cl_ostream stream, const cl_print_flags& flags,
- const cl_R& z);
- void print_float (cl_ostream stream, const cl_print_flags& flags,
- const cl_F& z);
- void print_rational (cl_ostream stream, const cl_print_flags& flags,
- const cl_RA& z);
- void print_integer (cl_ostream stream, const cl_print_flags& flags,
- const cl_I& z);
-Prints the number `x' on the `stream'. The `flags' are parameters which
-affect the output.
-
-The structure type `cl_print_flags' contains the following fields:
-
-`unsigned int rational_base'
- The base in which rational numbers are printed. Default is `10'.
-
-`cl_boolean rational_readably'
- If this flag is true, rational numbers are printed with radix
- specifiers in Common Lisp syntax (`#NR' or `#b' or `#o' or `#x'
- prefixes, trailing dot). Default is false.
-
-`cl_boolean float_readably'
- If this flag is true, type specific exponent markers have
- precedence over 'E'. Default is false.
-
-`cl_float_format_t default_float_format'
- Floating point numbers of this format will be printed using the
- 'E' exponent marker. Default is `cl_float_format_ffloat'.
-
-`cl_boolean complex_readably'
- If this flag is true, complex numbers will be printed using the
- Common Lisp syntax `#C(REALPART IMAGPART)'. Default is false.
-
-`cl_string univpoly_varname'
- Univariate polynomials with no explicit indeterminate name will be
- printed using this variable name. Default is `"x"'.
-
-The global variable `default_print_flags' contains the default values,
-used by the function `fprint'.
-
-\1f
-File: cln.info, Node: Rings, Next: Modular integers, Prev: Input/Output, Up: Top
-
-Rings
-*****
-
-CLN has a class of abstract rings.
-
- Ring
- cl_ring
- <cln/ring.h>
-
-Rings can be compared for equality:
-
-`bool operator== (const cl_ring&, const cl_ring&)'
-`bool operator!= (const cl_ring&, const cl_ring&)'
- These compare two rings for equality.
-
-Given a ring `R', the following members can be used.
-
-`void R->fprint (cl_ostream stream, const cl_ring_element& x)'
-`cl_boolean R->equal (const cl_ring_element& x, const cl_ring_element& y)'
-`cl_ring_element R->zero ()'
-`cl_boolean R->zerop (const cl_ring_element& x)'
-`cl_ring_element R->plus (const cl_ring_element& x, const cl_ring_element& y)'
-`cl_ring_element R->minus (const cl_ring_element& x, const cl_ring_element& y)'
-`cl_ring_element R->uminus (const cl_ring_element& x)'
-`cl_ring_element R->one ()'
-`cl_ring_element R->canonhom (const cl_I& x)'
-`cl_ring_element R->mul (const cl_ring_element& x, const cl_ring_element& y)'
-`cl_ring_element R->square (const cl_ring_element& x)'
-`cl_ring_element R->expt_pos (const cl_ring_element& x, const cl_I& y)'
-The following rings are built-in.
-
-`cl_null_ring cl_0_ring'
- The null ring, containing only zero.
-
-`cl_complex_ring cl_C_ring'
- The ring of complex numbers. This corresponds to the type `cl_N'.
-
-`cl_real_ring cl_R_ring'
- The ring of real numbers. This corresponds to the type `cl_R'.
-
-`cl_rational_ring cl_RA_ring'
- The ring of rational numbers. This corresponds to the type `cl_RA'.
-
-`cl_integer_ring cl_I_ring'
- The ring of integers. This corresponds to the type `cl_I'.
-
-Type tests can be performed for any of `cl_C_ring', `cl_R_ring',
-`cl_RA_ring', `cl_I_ring':
-
-`cl_boolean instanceof (const cl_number& x, const cl_number_ring& R)'
- Tests whether the given number is an element of the number ring R.
-
-\1f
-File: cln.info, Node: Modular integers, Next: Symbolic data types, Prev: Rings, Up: Top
-
-Modular integers
-****************
-
-* Menu:
-
-* Modular integer rings::
-* Functions on modular integers::
-
-\1f
-File: cln.info, Node: Modular integer rings, Next: Functions on modular integers, Prev: Modular integers, Up: Modular integers
-
-Modular integer rings
-=====================
-
-CLN implements modular integers, i.e. integers modulo a fixed integer N.
-The modulus is explicitly part of every modular integer. CLN doesn't
-allow you to (accidentally) mix elements of different modular rings,
-e.g. `(3 mod 4) + (2 mod 5)' will result in a runtime error. (Ideally
-one would imagine a generic data type `cl_MI(N)', but C++ doesn't have
-generic types. So one has to live with runtime checks.)
-
-The class of modular integer rings is
-
- Ring
- cl_ring
- <cln/ring.h>
- |
- |
- Modular integer ring
- cl_modint_ring
- <cln/modinteger.h>
-
-and the class of all modular integers (elements of modular integer
-rings) is
-
- Modular integer
- cl_MI
- <cln/modinteger.h>
-
-Modular integer rings are constructed using the function
-
-`cl_modint_ring find_modint_ring (const cl_I& N)'
- This function returns the modular ring `Z/NZ'. It takes care of
- finding out about special cases of `N', like powers of two and odd
- numbers for which Montgomery multiplication will be a win, and
- precomputes any necessary auxiliary data for computing modulo `N'.
- There is a cache table of rings, indexed by `N' (or, more
- precisely, by `abs(N)'). This ensures that the precomputation
- costs are reduced to a minimum.
-
-Modular integer rings can be compared for equality:
-
-`bool operator== (const cl_modint_ring&, const cl_modint_ring&)'
-`bool operator!= (const cl_modint_ring&, const cl_modint_ring&)'
- These compare two modular integer rings for equality. Two
- different calls to `find_modint_ring' with the same argument
- necessarily return the same ring because it is memoized in the
- cache table.
-
-\1f
-File: cln.info, Node: Functions on modular integers, Prev: Modular integer rings, Up: Modular integers
-
-Functions on modular integers
-=============================
-
-Given a modular integer ring `R', the following members can be used.
-
-`cl_I R->modulus'
- This is the ring's modulus, normalized to be nonnegative: `abs(N)'.
-
-`cl_MI R->zero()'
- This returns `0 mod N'.
-
-`cl_MI R->one()'
- This returns `1 mod N'.
-
-`cl_MI R->canonhom (const cl_I& x)'
- This returns `x mod N'.
-
-`cl_I R->retract (const cl_MI& x)'
- This is a partial inverse function to `R->canonhom'. It returns the
- standard representative (`>=0', `<N') of `x'.
-
-`cl_MI R->random(random_state& randomstate)'
-`cl_MI R->random()'
- This returns a random integer modulo `N'.
-
-The following operations are defined on modular integers.
-
-`cl_modint_ring x.ring ()'
- Returns the ring to which the modular integer `x' belongs.
-
-`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.
-
-`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.
-
-`cl_MI operator- (const cl_MI&)'
- Returns the negative of a modular integer.
-
-`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.
-
-`cl_MI square (const cl_MI&)'
- Returns the square of a modular integer.
-
-`cl_MI recip (const cl_MI& x)'
- Returns the reciprocal `x^-1' of a modular integer `x'. `x' must
- be coprime to the modulus, otherwise an error message is issued.
-
-`cl_MI div (const cl_MI& x, const cl_MI& y)'
- Returns the quotient `x*y^-1' of two modular integers `x', `y'.
- `y' must be coprime to the modulus, otherwise an error message is
- issued.
-
-`cl_MI expt_pos (const cl_MI& x, const cl_I& y)'
- `y' must be > 0. Returns `x^y'.
-
-`cl_MI expt (const cl_MI& x, const cl_I& y)'
- Returns `x^y'. If `y' is negative, `x' must be coprime to the
- modulus, else an error message is issued.
-
-`cl_MI operator<< (const cl_MI& x, const cl_I& y)'
- Returns `x*2^y'.
-
-`cl_MI operator>> (const cl_MI& x, const cl_I& y)'
- Returns `x*2^-y'. When `y' is positive, the modulus must be odd,
- or an error message is issued.
-
-`bool operator== (const cl_MI&, const cl_MI&)'
-`bool operator!= (const cl_MI&, const cl_MI&)'
- Compares two modular integers, belonging to the same modular
- integer ring, for equality.
-
-`cl_boolean zerop (const cl_MI& x)'
- Returns true if `x' is `0 mod N'.
-
-The following output functions are defined (see also the chapter on
-input/output).
-
-`void fprint (cl_ostream stream, const cl_MI& x)'
-`cl_ostream operator<< (cl_ostream stream, const cl_MI& x)'
- Prints the modular integer `x' on the `stream'. The output may
- depend on the global printer settings in the variable
- `default_print_flags'.
-
-\1f
-File: cln.info, Node: Symbolic data types, Next: Univariate polynomials, Prev: Modular integers, Up: Top
-
-Symbolic data types
-*******************
-
-CLN implements two symbolic (non-numeric) data types: strings and
-symbols.
-
-* Menu:
-
-* Strings::
-* Symbols::
-
-\1f
-File: cln.info, Node: Strings, Next: Symbols, Prev: Symbolic data types, Up: Symbolic data types
-
-Strings
-=======
-
-The class
-
- String
- cl_string
- <cln/string.h>
-
-implements immutable strings.
-
-Strings are constructed through the following constructors:
-
-`cl_string (const char * s)'
- Returns an immutable copy of the (zero-terminated) C string `s'.
-
-`cl_string (const char * ptr, unsigned long len)'
- Returns an immutable copy of the `len' characters at `ptr[0]',
- ..., `ptr[len-1]'. NUL characters are allowed.
-
-The following functions are available on strings:
-
-`operator ='
- Assignment from `cl_string' and `const char *'.
-
-`s.length()'
-`strlen(s)'
- Returns the length of the string `s'.
-
-`s[i]'
- Returns the `i'th character of the string `s'. `i' must be in the
- range `0 <= i < s.length()'.
-
-`bool equal (const cl_string& s1, const cl_string& s2)'
- Compares two strings for equality. One of the arguments may also
- be a plain `const char *'.
-
-\1f
-File: cln.info, Node: Symbols, Prev: Strings, Up: Symbolic data types
-
-Symbols
-=======
-
-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 comparison), whereas comparison of two strings must in
-the worst case walk both strings until their end. Symbols are used,
-for example, as tags for properties, as names of variables in
-polynomial rings, etc.
-
-Symbols are constructed through the following constructor:
-
-`cl_symbol (const cl_string& s)'
- Looks up or creates a new symbol with a given name.
-
-The following operations are available on symbols:
-
-`cl_string (const cl_symbol& sym)'
- Conversion to `cl_string': Returns the string which names the
- symbol `sym'.
-
-`bool equal (const cl_symbol& sym1, const cl_symbol& sym2)'
- Compares two symbols for equality. This is very fast.
-
-\1f
-File: cln.info, Node: Univariate polynomials, Next: Internals, Prev: Symbolic data types, Up: Top
-
-Univariate polynomials
-**********************
-
-* Menu:
-
-* Univariate polynomial rings::
-* Functions on univariate polynomials::
-* Special polynomials::
-
-\1f
-File: cln.info, Node: Univariate polynomial rings, Next: Functions on univariate polynomials, Prev: Univariate polynomials, Up: Univariate polynomials
-
-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
-`default_print_flags.univpoly_varname', which defaults to `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. `(a^2+1) * (b^3-1)' will
-result in a runtime error. (Ideally this should return a multivariate
-polynomial, but they are not yet implemented in CLN.)
-
-The classes of univariate polynomial rings are
-
- Ring
- cl_ring
- <cln/ring.h>
- |
- |
- Univariate polynomial ring
- cl_univpoly_ring
- <cln/univpoly.h>
- |
- +----------------+-------------------+
- | | |
- Complex polynomial ring | Modular integer polynomial ring
- cl_univpoly_complex_ring | cl_univpoly_modint_ring
- <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
- |
- +----------------+
- | |
- Real polynomial ring |
- cl_univpoly_real_ring |
- <cln/univpoly_real.h> |
- |
- +----------------+
- | |
- Rational polynomial ring |
- cl_univpoly_rational_ring |
- <cln/univpoly_rational.h> |
- |
- +----------------+
- |
- Integer polynomial ring
- cl_univpoly_integer_ring
- <cln/univpoly_integer.h>
-
-and the corresponding classes of univariate polynomials are
-
- Univariate polynomial
- cl_UP
- <cln/univpoly.h>
- |
- +----------------+-------------------+
- | | |
- Complex polynomial | Modular integer polynomial
- cl_UP_N | cl_UP_MI
- <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
- |
- +----------------+
- | |
- Real polynomial |
- cl_UP_R |
- <cln/univpoly_real.h> |
- |
- +----------------+
- | |
- Rational polynomial |
- cl_UP_RA |
- <cln/univpoly_rational.h> |
- |
- +----------------+
- |
- Integer polynomial
- cl_UP_I
- <cln/univpoly_integer.h>
-
-Univariate polynomial rings are constructed using the functions
-
-`cl_univpoly_ring find_univpoly_ring (const cl_ring& R)'
-`cl_univpoly_ring find_univpoly_ring (const cl_ring& R, const cl_symbol& varname)'
- This function returns the polynomial ring `R[X]', unnamed or named.
- `R' may be an arbitrary ring. This function takes care of finding
- out about special cases of `R', such as the rings of complex
- numbers, real numbers, rational numbers, integers, or modular
- integer rings. There is a cache table of rings, indexed by `R'
- and `varname'. This ensures that two calls of this function with
- the same arguments will return the same polynomial ring.
-
-`cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R)'
-`cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)'
-`cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R)'
-`cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)'
-`cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R)'
-`cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)'
-`cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R)'
-`cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)'
-`cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R)'
-`cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname)'
- These functions are equivalent to the general `find_univpoly_ring',
- only the return type is more specific, according to the base
- ring's type.
-
-\1f
-File: cln.info, Node: Functions on univariate polynomials, Next: Special polynomials, Prev: Univariate polynomial rings, Up: Univariate polynomials
-
-Functions on univariate polynomials
-===================================
-
-Given a univariate polynomial ring `R', the following members can be
-used.
-
-`cl_ring R->basering()'
- This returns the base ring, as passed to `find_univpoly_ring'.
-
-`cl_UP R->zero()'
- This returns `0 in R', a polynomial of degree -1.
-
-`cl_UP R->one()'
- This returns `1 in R', a polynomial of degree <= 0.
-
-`cl_UP R->canonhom (const cl_I& x)'
- This returns `x in R', a polynomial of degree <= 0.
-
-`cl_UP R->monomial (const cl_ring_element& x, uintL e)'
- This returns a sparse polynomial: `x * X^e', where `X' is the
- indeterminate.
-
-`cl_UP R->create (sintL degree)'
- Creates a new polynomial with a given degree. The zero polynomial
- has degree `-1'. After creating the polynomial, you should put in
- the coefficients, using the `set_coeff' member function, and then
- call the `finalize' member function.
-
-The following are the only destructive operations on univariate
-polynomials.
-
-`void set_coeff (cl_UP& x, uintL index, const cl_ring_element& y)'
- This changes the coefficient of `X^index' in `x' to be `y'. After
- changing a polynomial and before applying any "normal" operation
- on it, you should call its `finalize' member function.
-
-`void finalize (cl_UP& x)'
- 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 produce wrong results
- or crash the program.
-
-The following operations are defined on univariate polynomials.
-
-`cl_univpoly_ring x.ring ()'
- Returns the ring to which the univariate polynomial `x' belongs.
-
-`cl_UP operator+ (const cl_UP&, const cl_UP&)'
- Returns the sum of two univariate polynomials.
-
-`cl_UP operator- (const cl_UP&, const cl_UP&)'
- Returns the difference of two univariate polynomials.
-
-`cl_UP operator- (const cl_UP&)'
- Returns the negative of a univariate polynomial.
-
-`cl_UP operator* (const cl_UP&, const cl_UP&)'
- Returns the product of two univariate polynomials. One of the
- arguments may also be a plain integer or an element of the base
- ring.
-
-`cl_UP square (const cl_UP&)'
- Returns the square of a univariate polynomial.
-
-`cl_UP expt_pos (const cl_UP& x, const cl_I& y)'
- `y' must be > 0. Returns `x^y'.
-
-`bool operator== (const cl_UP&, const cl_UP&)'
-`bool operator!= (const cl_UP&, const cl_UP&)'
- Compares two univariate polynomials, belonging to the same
- univariate polynomial ring, for equality.
-
-`cl_boolean zerop (const cl_UP& x)'
- Returns true if `x' is `0 in R'.
-
-`sintL degree (const cl_UP& x)'
- Returns the degree of the polynomial. The zero polynomial has
- degree `-1'.
-
-`cl_ring_element coeff (const cl_UP& x, uintL index)'
- Returns the coefficient of `X^index' in the polynomial `x'.
-
-`cl_ring_element x (const cl_ring_element& y)'
- Evaluation: If `x' is a polynomial and `y' belongs to the base
- ring, then `x(y)' returns the value of the substitution of `y' into
- `x'.
-
-`cl_UP deriv (const cl_UP& x)'
- Returns the derivative of the polynomial `x' with respect to the
- indeterminate `X'.
-
-The following output functions are defined (see also the chapter on
-input/output).
-
-`void fprint (cl_ostream stream, const cl_UP& x)'
-`cl_ostream operator<< (cl_ostream stream, const cl_UP& x)'
- Prints the univariate polynomial `x' on the `stream'. The output
- may depend on the global printer settings in the variable
- `default_print_flags'.
-
-\1f
-File: cln.info, Node: Special polynomials, Prev: Functions on univariate polynomials, Up: Univariate polynomials
-
-Special polynomials
-===================
-
-The following functions return special polynomials.
-
-`cl_UP_I tschebychev (sintL n)'
- Returns the n-th Chebyshev polynomial (n >= 0).
-
-`cl_UP_I hermite (sintL n)'
- Returns the n-th Hermite polynomial (n >= 0).
-
-`cl_UP_RA legendre (sintL n)'
- Returns the n-th Legendre polynomial (n >= 0).
-
-`cl_UP_I laguerre (sintL n)'
- Returns the n-th Laguerre polynomial (n >= 0).
-
-Information how to derive the differential equation satisfied by each
-of these polynomials from their definition can be found in the
-`doc/polynomial/' directory.
-
-\1f
-File: cln.info, Node: Internals, Next: Using the library, Prev: Univariate polynomials, Up: Top
-
-Internals
-*********
-
-* Menu:
-
-* Why C++ ?::
-* Memory efficiency::
-* Speed efficiency::
-* Garbage collection::
-
-\1f
-File: cln.info, Node: Why C++ ?, Next: Memory efficiency, Prev: Internals, Up: Internals
-
-Why C++ ?
-=========
-
-Using C++ as an implementation language provides
-
- * Efficiency: It compiles to machine code.
-
- * 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 `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.
-
- * Algebraic syntax: The elementary operations `+', `-', `*', `=',
- `==', ... can be used in infix notation, which is more convenient
- than Lisp notation `(+ x y)' or C notation `add(x,y,&z)'.
-
-With these language features, there is no need for two separate
-languages, one for the implementation of the library and one in which
-the library's users can program. This means that a prototype
-implementation of an algorithm can be integrated into the library
-immediately after it has been tested and debugged. No need to rewrite
-it in a low-level language after having prototyped in a high-level
-language.
-
-\1f
-File: cln.info, Node: Memory efficiency, Next: Speed efficiency, Prev: Why C++ ?, Up: Internals
-
-Memory efficiency
-=================
-
-In order to save memory allocations, CLN implements:
-
- * Object sharing: An operation like `x+0' returns `x' without copying
- it.
-
- * 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.
-
- * Small integers are represented as immediate values instead of
- pointers to heap allocated storage. This means that integers `>
- -2^29', `< 2^29' don't consume heap memory, unless they were
- explicitly allocated on the heap.
-
-\1f
-File: cln.info, Node: Speed efficiency, Next: Garbage collection, Prev: Memory efficiency, Up: Internals
-
-Speed efficiency
-================
-
-Speed efficiency is obtained by the combination of the following tricks
-and algorithms:
-
- * Small integers, being represented as immediate values, don't
- require memory access, just a couple of instructions for each
- elementary operation.
-
- * The kernel of CLN has been written in assembly language for some
- CPUs (`i386', `m68k', `sparc', `mips', `arm').
-
- * On all CPUs, CLN may be configured to use the superefficient
- low-level routines from GNU GMP version 3.
-
- * For large numbers, CLN uses, instead of the standard `O(N^2)'
- algorithm, the Karatsuba multiplication, which is an `O(N^1.6)'
- algorithm.
-
- * For very large numbers (more than 12000 decimal digits), CLN uses
- Schönhage-Strassen multiplication, which is an asymptotically
- optimal multiplication algorithm.
-
- * These fast multiplication algorithms also give improvements in the
- speed of division and radix conversion.
-
-\1f
-File: cln.info, Node: Garbage collection, Prev: Speed efficiency, Up: Internals
-
-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 number objects, only the objects' reference count are
-manipulated.
-
-Memory occupied by number objects are automatically reclaimed as soon as
-their reference count drops to zero.
-
-For number rings, another strategy is implemented: There is a cache of,
-for example, the modular integer rings. A modular integer ring is
-destroyed only if its reference count dropped to zero and the cache is
-about to be resized. The effect of this strategy is that recently used
-rings remain cached, whereas undue memory consumption through cached
-rings is avoided.
-
-\1f
-File: cln.info, Node: Using the library, Next: Customizing, Prev: Internals, Up: Top
-
-Using the library
-*****************
-
-For the following discussion, we will assume that you have installed
-the CLN source in `$CLN_DIR' and built it in `$CLN_TARGETDIR'. For
-example, for me it's `CLN_DIR="$HOME/cln"' and
-`CLN_TARGETDIR="$HOME/cln/linuxelf"'. You might define these as
-environment variables, or directly substitute the appropriate values.
-
-* Menu:
-
-* Compiler options::
-* Compatibility to old CLN versions::
-* Include files::
-* An Example::
-* Debugging support::
-
-\1f
-File: cln.info, Node: Compiler options, Next: Compatibility to old CLN versions, Prev: Using the library, Up: Using the library
-
-Compiler options
-================
-
-Until you have installed CLN in a public place, the following options
-are needed:
-
-When you compile CLN application code, add the flags
- -I$CLN_DIR/include -I$CLN_TARGETDIR/include
-to the C++ compiler's command line (`make' variable CFLAGS or CXXFLAGS).
-When you link CLN application code to form an executable, add the flags
- $CLN_TARGETDIR/src/libcln.a
-to the C/C++ compiler's command line (`make' variable LIBS).
-
-If you did a `make install', the include files are installed in a
-public directory (normally `/usr/local/include'), hence you don't need
-special flags for compiling. The library has been installed to a public
-directory as well (normally `/usr/local/lib'), hence when linking a CLN
-application it is sufficient to give the flag `-lcln'.
-
-\1f
-File: cln.info, Node: Compatibility to old CLN versions, Next: Include files, Prev: Compiler options, Up: Using the library
-
-Compatibility to old CLN versions
-=================================
-
-As of CLN version 1.1 all non-macro identifiers were hidden in namespace
-`cln' in order to avoid potential name clashes with other C++
-libraries. If you have an old application, you will have to manually
-port it to the new scheme. The following principles will help during
-the transition:
- * All headers are now in a separate subdirectory. Instead of
- including `cl_'SOMETHING`.h', include `cln/'SOMETHING`.h' now.
-
- * All public identifiers (typenames and functions) have lost their
- `cl_' prefix. Exceptions are all the typenames of number types,
- (cl_N, cl_I, cl_MI, ...), rings, symbolic types (cl_string,
- cl_symbol) and polynomials (cl_UP_TYPE). (This is because their
- names would not be mnemonic enough once the namespace `cln' is
- imported. Even in a namespace we favor `cl_N' over `N'.)
-
- * All public _functions_ that had by a `cl_' in their name still
- carry that `cl_' if it is intrinsic part of a typename (as in
- `cl_I_to_int ()').
-When developing other libraries, please keep in mind not to import the
-namespace `cln' in one of your public header files by saying `using
-namespace cln;'. This would propagate to other applications and can
-cause name clashes there.
-
-\1f
-File: cln.info, Node: Include files, Next: An Example, Prev: Compatibility to old CLN versions, Up: Using the library
-
-Include files
-=============
-
-Here is a summary of the include files and their contents.
-
-`<cln/object.h>'
- General definitions, reference counting, garbage collection.
-
-`<cln/number.h>'
- The class cl_number.
-
-`<cln/complex.h>'
- Functions for class cl_N, the complex numbers.
-
-`<cln/real.h>'
- Functions for class cl_R, the real numbers.
-
-`<cln/float.h>'
- Functions for class cl_F, the floats.
-
-`<cln/sfloat.h>'
- Functions for class cl_SF, the short-floats.
-
-`<cln/ffloat.h>'
- Functions for class cl_FF, the single-floats.
-
-`<cln/dfloat.h>'
- Functions for class cl_DF, the double-floats.
-
-`<cln/lfloat.h>'
- Functions for class cl_LF, the long-floats.
-
-`<cln/rational.h>'
- Functions for class cl_RA, the rational numbers.
-
-`<cln/integer.h>'
- Functions for class cl_I, the integers.
-
-`<cln/io.h>'
- Input/Output.
-
-`<cln/complex_io.h>'
- Input/Output for class cl_N, the complex numbers.
-
-`<cln/real_io.h>'
- Input/Output for class cl_R, the real numbers.
-
-`<cln/float_io.h>'
- Input/Output for class cl_F, the floats.
-
-`<cln/sfloat_io.h>'
- Input/Output for class cl_SF, the short-floats.
-
-`<cln/ffloat_io.h>'
- Input/Output for class cl_FF, the single-floats.
-
-`<cln/dfloat_io.h>'
- Input/Output for class cl_DF, the double-floats.
-
-`<cln/lfloat_io.h>'
- Input/Output for class cl_LF, the long-floats.
-
-`<cln/rational_io.h>'
- Input/Output for class cl_RA, the rational numbers.
-
-`<cln/integer_io.h>'
- Input/Output for class cl_I, the integers.
-
-`<cln/input.h>'
- Flags for customizing input operations.
-
-`<cln/output.h>'
- Flags for customizing output operations.
-
-`<cln/malloc.h>'
- `malloc_hook', `free_hook'.
-
-`<cln/abort.h>'
- `cl_abort'.
-
-`<cln/condition.h>'
- Conditions/exceptions.
-
-`<cln/string.h>'
- Strings.
-
-`<cln/symbol.h>'
- Symbols.
-
-`<cln/proplist.h>'
- Property lists.
-
-`<cln/ring.h>'
- General rings.
-
-`<cln/null_ring.h>'
- The null ring.
-
-`<cln/complex_ring.h>'
- The ring of complex numbers.
-
-`<cln/real_ring.h>'
- The ring of real numbers.
-
-`<cln/rational_ring.h>'
- The ring of rational numbers.
-
-`<cln/integer_ring.h>'
- The ring of integers.
-
-`<cln/numtheory.h>'
- Number threory functions.
-
-`<cln/modinteger.h>'
- Modular integers.
-
-`<cln/V.h>'
- Vectors.
-
-`<cln/GV.h>'
- General vectors.
-
-`<cln/GV_number.h>'
- General vectors over cl_number.
-
-`<cln/GV_complex.h>'
- General vectors over cl_N.
-
-`<cln/GV_real.h>'
- General vectors over cl_R.
-
-`<cln/GV_rational.h>'
- General vectors over cl_RA.
-
-`<cln/GV_integer.h>'
- General vectors over cl_I.
-
-`<cln/GV_modinteger.h>'
- General vectors of modular integers.
-
-`<cln/SV.h>'
- Simple vectors.
-
-`<cln/SV_number.h>'
- Simple vectors over cl_number.
-
-`<cln/SV_complex.h>'
- Simple vectors over cl_N.
-
-`<cln/SV_real.h>'
- Simple vectors over cl_R.
-
-`<cln/SV_rational.h>'
- Simple vectors over cl_RA.
-
-`<cln/SV_integer.h>'
- Simple vectors over cl_I.
-
-`<cln/SV_ringelt.h>'
- Simple vectors of general ring elements.
-
-`<cln/univpoly.h>'
- Univariate polynomials.
-
-`<cln/univpoly_integer.h>'
- Univariate polynomials over the integers.
-
-`<cln/univpoly_rational.h>'
- Univariate polynomials over the rational numbers.
-
-`<cln/univpoly_real.h>'
- Univariate polynomials over the real numbers.
-
-`<cln/univpoly_complex.h>'
- Univariate polynomials over the complex numbers.
-
-`<cln/univpoly_modint.h>'
- Univariate polynomials over modular integer rings.
-
-`<cln/timing.h>'
- Timing facilities.
-
-`<cln/cln.h>'
- Includes all of the above.
-
-\1f
-File: cln.info, Node: An Example, Next: Debugging support, Prev: Include files, Up: Using the library
-
-An Example
-==========
-
-A function which computes the nth Fibonacci number can be written as
-follows.
-
- #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));
- 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 `<cln/integer.h>' is necessary because the type `cl_I'
-is used in the function, and the include file `<cln/real.h>' is needed
-for the type `cl_R' and the floating point number functions. The order
-of the include files does not matter. In order not to write out
-`cln::'FOO we can safely import the whole namespace `cln'.
-
-Then comes the function declaration. The argument is an `int', the
-result an integer. The return type is defined as `const cl_I', not
-simply `cl_I', because that allows the compiler to detect typos like
-`fibonacci(n) = 100'. It would be possible to declare the return type
-as `const cl_R' (real number) or even `const cl_N' (complex number). We
-use the most specialized possible return type because functions which
-call `fibonacci' will be able to profit from the compiler's type
-analysis: Adding two integers is slightly more efficient than adding the
-same objects declared as complex numbers, because it needs less type
-dispatch. Also, when linking to CLN as a non-shared library, this
-minimizes the size of the resulting executable program.
-
-The result will be computed as expt(phi,n)/sqrt(5), rounded to the
-nearest integer. In order to get a correct result, the absolute error
-should be less than 1/2, i.e. the relative error should be less than
-sqrt(5)/(2*expt(phi,n)). To this end, the first line computes a
-floating point precision for sqrt(5) and phi.
-
-Then sqrt(5) is computed by first converting the integer 5 to a
-floating point number and than taking the square root. The converse,
-first taking the square root of 5, and then converting to the desired
-precision, would not work in CLN: The square root would be computed to
-a default precision (normally single-float precision), and the
-following conversion could not help about the lacking accuracy. This is
-because CLN is not a symbolic computer algebra system and does not
-represent sqrt(5) in a non-numeric way.
-
-The type `cl_R' for sqrt5 and, in the following line, phi is the only
-possible choice. You cannot write `cl_F' because the C++ compiler can
-only infer that `cl_float(5,prec)' is a real number. You cannot write
-`cl_N' because a `round1' does not exist for general complex numbers.
-
-When the function returns, all the local variables in the function are
-automatically reclaimed (garbage collected). Only the result survives
-and gets passed to the caller.
-
-The file `fibonacci.cc' in the subdirectory `examples' contains this
-implementation together with an even faster algorithm.
-
-\1f
-File: cln.info, Node: Debugging support, Prev: An Example, Up: Using the library
-
-Debugging support
-=================
-
-When debugging a CLN application with GNU `gdb', two facilities are
-available from the library:
-
- * The library does type checks, range checks, consistency checks at
- many places. When one of these fails, the function `cl_abort()' is
- called. Its default implementation is to perform an `exit(1)', so
- you won't have a core dump. But for debugging, it is best to set a
- breakpoint at this function:
- (gdb) break cl_abort
- When this breakpoint is hit, look at the stack's backtrace:
- (gdb) where
-
- * The debugger's normal `print' command doesn't know about CLN's
- types and therefore prints mostly useless hexadecimal addresses.
- CLN offers a function `cl_print', callable from the debugger, for
- printing number objects. In order to get this function, you have
- to define the macro `CL_DEBUG' and then include all the header
- files for which you want `cl_print' debugging support. For example:
- #define CL_DEBUG
- #include <cln/string.h>
- Now, if you have in your program a variable `cl_string s', and
- inspect it under `gdb', the output may look like this:
- (gdb) print s
- $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
- word = 134568800}}, }
- (gdb) call cl_print(s)
- (cl_string) ""
- $8 = 134568800
- Note that the output of `cl_print' goes to the program's error
- output, not to gdb's standard output.
-
- Note, however, that the above facility does not work with all CLN
- types, only with number objects and similar. Therefore CLN offers
- a member function `debug_print()' on all CLN types. The same macro
- `CL_DEBUG' is needed for this member function to be implemented.
- Under `gdb', you call it like this:
- (gdb) print s
- $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
- word = 134568800}}, }
- (gdb) call s.debug_print()
- (cl_string) ""
- (gdb) define cprint
- >call ($1).debug_print()
- >end
- (gdb) cprint s
- (cl_string) ""
- Unfortunately, this feature does not seem to work under all
- circumstances.
-
-\1f
-File: cln.info, Node: Customizing, Next: Index, Prev: Using the library, Up: Top
-
-Customizing
-***********
-
-* Menu:
-
-* Error handling::
-* Floating-point underflow::
-* Customizing I/O::
-* Customizing the memory allocator::
-
-\1f
-File: cln.info, Node: Error handling, Next: Floating-point underflow, Prev: Customizing, Up: Customizing
-
-Error handling
-==============
-
-When a fatal error occurs, an error message is output to the standard
-error output stream, and the function `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 `cl_abort' yourself, with the prototype
- #include <cln/abort.h>
- void cl_abort (void);
-This function must not return control to its caller.
-
-\1f
-File: cln.info, Node: Floating-point underflow, Next: Customizing I/O, Prev: Error handling, Up: Customizing
-
-Floating-point underflow
-========================
-
-Floating point underflow denotes the situation when a floating-point
-number is to be created which is so close to `0' that its exponent is
-too low to be represented internally. By default, this causes a fatal
-error. If you set the global variable
- cl_boolean cl_inhibit_floating_point_underflow
-to `cl_true', the error will be inhibited, and a floating-point zero
-will be generated instead. The default value of
-`cl_inhibit_floating_point_underflow' is `cl_false'.
-
-\1f
-File: cln.info, Node: Customizing I/O, Next: Customizing the memory allocator, Prev: Floating-point underflow, Up: Customizing
-
-Customizing I/O
-===============
-
-The output of the function `fprint' may be customized by changing the
-value of the global variable `default_print_flags'.
-
-\1f
-File: cln.info, Node: Customizing the memory allocator, Prev: Customizing I/O, Up: Customizing
-
-Customizing the memory allocator
-================================
-
-Every memory allocation of CLN is done through the function pointer
-`malloc_hook'. Freeing of this memory is done through the function
-pointer `free_hook'. The default versions of these functions, provided
-in the library, call `malloc' and `free' and check the `malloc' result
-against `NULL'. If you want to provide another memory allocator, you
-need to define the variables `malloc_hook' and `free_hook' yourself,
-like this:
- #include <cln/malloc.h>
- namespace cln {
- void* (*malloc_hook) (size_t size) = ...;
- void (*free_hook) (void* ptr) = ...;
- }
-The `cl_malloc_hook' function must not return a `NULL' pointer.
-
-It is not possible to change the memory allocator at runtime, because
-it is already called at program startup by the constructors of some
-global variables.
-
-\1f
-File: cln.info, Node: Index, Prev: Customizing, Up: Top
-
-Index
-*****
-
-* Menu:
-
-* abs (): Elementary functions.
-* abstract class: Ordinary number types.
-* acos (): Trigonometric functions.
-* acosh (): Hyperbolic functions.
-* advocacy: Why C++ ?.
-* Archimedes' constant: Trigonometric functions.
-* As()(): Conversions.
-* ash (): Logical functions.
-* asin: Trigonometric functions.
-* asin (): Trigonometric functions.
-* asinh (): Hyperbolic functions.
-* atan: Trigonometric functions.
-* atan (): Trigonometric functions.
-* atanh (): Hyperbolic functions.
-* basering (): Functions on univariate polynomials.
-* binomial (): Combinatorial functions.
-* boole (): Logical functions.
-* boole_1: Logical functions.
-* boole_2: Logical functions.
-* boole_and: Logical functions.
-* boole_andc1: Logical functions.
-* boole_andc2: Logical functions.
-* boole_c1: Logical functions.
-* boole_c2: Logical functions.
-* boole_clr: Logical functions.
-* boole_eqv: Logical functions.
-* boole_nand: Logical functions.
-* boole_nor: Logical functions.
-* boole_orc1: Logical functions.
-* boole_orc2: Logical functions.
-* boole_set: Logical functions.
-* boole_xor: Logical functions.
-* canonhom () <1>: Functions on univariate polynomials.
-* canonhom () <2>: Functions on modular integers.
-* canonhom (): Rings.
-* Catalan's constant: Euler gamma.
-* catalanconst (): Euler gamma.
-* ceiling1 (): Rounding functions.
-* ceiling2 (): Rounding functions.
-* Chebyshev polynomial: Special polynomials.
-* cis (): Trigonometric functions.
-* cl_abort (): Error handling.
-* cl_byte: Logical functions.
-* CL_DEBUG: Debugging support.
-* cl_DF: Floating-point numbers.
-* cl_DF_fdiv_t: Rounding functions.
-* cl_F <1>: Floating-point numbers.
-* cl_F: Ordinary number types.
-* cl_F_fdiv_t: Rounding functions.
-* cl_FF: Floating-point numbers.
-* cl_FF_fdiv_t: Rounding functions.
-* cl_float (): Conversion to floating-point numbers.
-* cl_float_format (): Conversion to floating-point numbers.
-* cl_float_format_t: Conversion to floating-point numbers.
-* cl_I_to_int (): Conversions.
-* cl_I_to_long (): Conversions.
-* cl_I_to_uint (): Conversions.
-* cl_I_to_ulong (): Conversions.
-* cl_idecoded_float: Functions on floating-point numbers.
-* cl_LF: Floating-point numbers.
-* cl_LF_fdiv_t: Rounding functions.
-* cl_modint_ring: Modular integer rings.
-* cl_N: Ordinary number types.
-* cl_number: Ordinary number types.
-* cl_R: Ordinary number types.
-* cl_R_fdiv_t: Rounding functions.
-* cl_RA: Ordinary number types.
-* cl_SF: Floating-point numbers.
-* cl_SF_fdiv_t: Rounding functions.
-* cl_string: Strings.
-* cl_symbol: Symbols.
-* coeff (): Functions on univariate polynomials.
-* compare (): Comparisons.
-* comparison: Comparisons.
-* compatibility: Compatibility to old CLN versions.
-* compiler options: Compiler options.
-* complex (): Elementary complex functions.
-* complex number <1>: Complex numbers.
-* complex number: Ordinary number types.
-* conjugate (): Elementary complex functions.
-* conversion <1>: Conversion functions.
-* conversion: Conversions.
-* cos (): Trigonometric functions.
-* cos_sin (): Trigonometric functions.
-* cos_sin_t: Trigonometric functions.
-* cosh (): Hyperbolic functions.
-* cosh_sinh (): Hyperbolic functions.
-* cosh_sinh_t: Hyperbolic functions.
-* create (): Functions on univariate polynomials.
-* customizing: Customizing.
-* debug_print (): Debugging support.
-* debugging: Debugging support.
-* decode_float (): Functions on floating-point numbers.
-* decoded_dfloat: Functions on floating-point numbers.
-* decoded_ffloat: Functions on floating-point numbers.
-* decoded_float: Functions on floating-point numbers.
-* decoded_lfloat: Functions on floating-point numbers.
-* decoded_sfloat: Functions on floating-point numbers.
-* default_float_format: Conversion to floating-point numbers.
-* default_print_flags: Customizing I/O.
-* default_random_state: Random number generators.
-* degree (): Functions on univariate polynomials.
-* denominator (): Elementary rational functions.
-* deposit_field (): Logical functions.
-* deriv (): Functions on univariate polynomials.
-* div (): Functions on modular integers.
-* double_approx (): Conversions.
-* doublefactorial (): Combinatorial functions.
-* dpb (): Logical functions.
-* equal () <1>: Symbols.
-* equal () <2>: Strings.
-* equal (): Rings.
-* equal_hashcode (): Comparisons.
-* Euler's constant: Euler gamma.
-* eulerconst (): Euler gamma.
-* evenp (): Logical functions.
-* exact number: Exact numbers.
-* exp (): Exponential and logarithmic functions.
-* exp1 (): Exponential and logarithmic functions.
-* expt () <1>: Functions on modular integers.
-* expt () <2>: Exponential and logarithmic functions.
-* expt (): Elementary functions.
-* expt_pos () <1>: Functions on univariate polynomials.
-* expt_pos () <2>: Functions on modular integers.
-* expt_pos () <3>: Rings.
-* expt_pos (): Elementary functions.
-* exquo (): Elementary functions.
-* factorial (): Combinatorial functions.
-* fceiling (): Rounding functions.
-* fceiling2 (): Rounding functions.
-* ffloor (): Rounding functions.
-* ffloor2 (): Rounding functions.
-* Fibonacci number: An Example.
-* finalize (): Functions on univariate polynomials.
-* find_modint_ring (): Modular integer rings.
-* find_univpoly_ring (): Univariate polynomial rings.
-* float_approx (): Conversions.
-* float_digits (): Functions on floating-point numbers.
-* float_epsilon (): Conversion to floating-point numbers.
-* float_exponent (): Functions on floating-point numbers.
-* float_negative_epsilon (): Conversion to floating-point numbers.
-* float_precision (): Functions on floating-point numbers.
-* float_radix (): Functions on floating-point numbers.
-* float_sign (): Functions on floating-point numbers.
-* floating-point number: Floating-point numbers.
-* floor1 (): Rounding functions.
-* floor2 (): Rounding functions.
-* fprint () <1>: Functions on univariate polynomials.
-* fprint () <2>: Functions on modular integers.
-* fprint (): Rings.
-* free_hook (): Customizing the memory allocator.
-* fround (): Rounding functions.
-* fround2 (): Rounding functions.
-* ftruncate (): Rounding functions.
-* ftruncate2 (): Rounding functions.
-* garbage collection <1>: Garbage collection.
-* garbage collection: Memory efficiency.
-* gcd (): Number theoretic functions.
-* GMP <1>: Using the GNU MP Library.
-* GMP: Introduction.
-* header files: Include files.
-* hermite (): Special polynomials.
-* Hermite polynomial: Special polynomials.
-* imagpart (): Elementary complex functions.
-* include files: Include files.
-* Input/Output: Input/Output.
-* installation: Installing the library.
-* instanceof (): Rings.
-* integer: Ordinary number types.
-* integer_decode_float (): Functions on floating-point numbers.
-* integer_length (): Logical functions.
-* isqrt (): Roots.
-* laguerre (): Special polynomials.
-* Laguerre polynomial: Special polynomials.
-* lcm (): Number theoretic functions.
-* ldb (): Logical functions.
-* ldb_test (): Logical functions.
-* least_negative_float (): Conversion to floating-point numbers.
-* least_positive_float (): Conversion to floating-point numbers.
-* Legende polynomial: Special polynomials.
-* legendre (): Special polynomials.
-* length (): Strings.
-* ln (): Exponential and logarithmic functions.
-* log (): Exponential and logarithmic functions.
-* logand (): Logical functions.
-* logandc1 (): Logical functions.
-* logandc2 (): Logical functions.
-* logbitp (): Logical functions.
-* logcount (): Logical functions.
-* logeqv (): Logical functions.
-* logior (): Logical functions.
-* lognand (): Logical functions.
-* lognor (): Logical functions.
-* lognot (): Logical functions.
-* logorc1 (): Logical functions.
-* logorc2 (): Logical functions.
-* logp (): Number theoretic functions.
-* logtest (): Logical functions.
-* logxor (): Logical functions.
-* make: Make utility.
-* malloc_hook (): Customizing the memory allocator.
-* mask_field (): Logical functions.
-* max (): Comparisons.
-* min (): Comparisons.
-* minus (): Rings.
-* minus1 (): Elementary functions.
-* minusp (): Comparisons.
-* mod (): Rounding functions.
-* modifying operators: Obfuscating operators.
-* modular integer: Modular integers.
-* modulus: Functions on modular integers.
-* monomial (): Functions on univariate polynomials.
-* Montgomery multiplication: Modular integer rings.
-* most_negative_float (): Conversion to floating-point numbers.
-* most_positive_float (): Conversion to floating-point numbers.
-* mul (): Rings.
-* namespace <1>: Compatibility to old CLN versions.
-* namespace: Introduction.
-* numerator (): Elementary rational functions.
-* oddp (): Logical functions.
-* one () <1>: Functions on univariate polynomials.
-* one () <2>: Functions on modular integers.
-* one (): Rings.
-* operator != () <1>: Functions on univariate polynomials.
-* operator != () <2>: Functions on modular integers.
-* operator != () <3>: Modular integer rings.
-* operator != (): Comparisons.
-* operator & (): Logical functions.
-* operator &= (): Obfuscating operators.
-* operator () (): Functions on univariate polynomials.
-* operator * () <1>: Functions on univariate polynomials.
-* operator * () <2>: Functions on modular integers.
-* operator * (): Elementary functions.
-* operator *= (): Obfuscating operators.
-* operator + () <1>: Functions on univariate polynomials.
-* operator + () <2>: Functions on modular integers.
-* operator + (): Elementary functions.
-* operator ++ (): Obfuscating operators.
-* operator += (): Obfuscating operators.
-* operator - () <1>: Functions on univariate polynomials.
-* operator - () <2>: Functions on modular integers.
-* operator - (): Elementary functions.
-* operator -- (): Obfuscating operators.
-* operator -= (): Obfuscating operators.
-* operator / (): Elementary functions.
-* operator /= (): Obfuscating operators.
-* operator < (): Comparisons.
-* operator << () <1>: Functions on univariate polynomials.
-* operator << () <2>: Functions on modular integers.
-* operator << (): Logical functions.
-* operator <<= (): Obfuscating operators.
-* operator <= (): Comparisons.
-* operator == () <1>: Functions on univariate polynomials.
-* operator == () <2>: Functions on modular integers.
-* operator == () <3>: Modular integer rings.
-* operator == (): Comparisons.
-* operator > (): Comparisons.
-* operator >= (): Comparisons.
-* operator >> () <1>: Functions on modular integers.
-* operator >> (): Logical functions.
-* operator >>= (): Obfuscating operators.
-* operator [] (): Strings.
-* operator ^ (): Logical functions.
-* operator ^= (): Obfuscating operators.
-* operator | (): Logical functions.
-* operator |= (): Obfuscating operators.
-* operator ~ (): Logical functions.
-* ord2 (): Logical functions.
-* phase (): Exponential and logarithmic functions.
-* pi: Trigonometric functions.
-* pi (): Trigonometric functions.
-* plus (): Rings.
-* plus1 (): Elementary functions.
-* plusp (): Comparisons.
-* polynomial: Univariate polynomials.
-* portability: Why C++ ?.
-* power2p (): Logical functions.
-* printing: Internal and printed representation.
-* random (): Functions on modular integers.
-* random32 (): Random number generators.
-* random_F (): Random number generators.
-* random_I (): Random number generators.
-* random_R (): Random number generators.
-* random_state: Random number generators.
-* rational (): Conversion to rational numbers.
-* rational number: Ordinary number types.
-* rationalize (): Conversion to rational numbers.
-* reading: Internal and printed representation.
-* real number: Ordinary number types.
-* realpart (): Elementary complex functions.
-* recip () <1>: Functions on modular integers.
-* recip (): Elementary functions.
-* reference counting: Memory efficiency.
-* rem (): Rounding functions.
-* representation: Internal and printed representation.
-* retract (): Functions on modular integers.
-* Riemann's zeta: Riemann zeta.
-* ring: Modular integer rings.
-* ring () <1>: Functions on univariate polynomials.
-* ring (): Functions on modular integers.
-* rootp (): Roots.
-* round1 (): Rounding functions.
-* round2 (): Rounding functions.
-* rounding: Rounding functions.
-* rounding error: Floating-point numbers.
-* Rubik's cube: Conversions.
-* scale_float (): Functions on floating-point numbers.
-* Schönhage-Strassen multiplication <1>: Speed efficiency.
-* Schönhage-Strassen multiplication: Introduction.
-* sed: Sed utility.
-* set_coeff (): Functions on univariate polynomials.
-* signum (): Elementary functions.
-* sin (): Trigonometric functions.
-* sinh (): Hyperbolic functions.
-* sqrt (): Roots.
-* sqrtp (): Roots.
-* square () <1>: Functions on univariate polynomials.
-* square () <2>: Functions on modular integers.
-* square () <3>: Rings.
-* square (): Elementary functions.
-* string: Strings.
-* strlen (): Strings.
-* symbol: Symbols.
-* symbolic type: Symbolic data types.
-* tan (): Trigonometric functions.
-* tanh (): Hyperbolic functions.
-* The()(): Conversions.
-* transcendental functions: Transcendental functions.
-* truncate1 (): Rounding functions.
-* truncate2 (): Rounding functions.
-* tschebychev (): Special polynomials.
-* uminus (): Rings.
-* underflow: Floating-point underflow.
-* univariate polynomial: Univariate polynomials.
-* WANT_OBFUSCATING_OPERATORS: Obfuscating operators.
-* xgcd (): Number theoretic functions.
-* zero () <1>: Functions on univariate polynomials.
-* zero () <2>: Functions on modular integers.
-* zero (): Rings.
-* zerop () <1>: Functions on univariate polynomials.
-* zerop () <2>: Functions on modular integers.
-* zerop () <3>: Rings.
-* zerop (): Comparisons.
-* zeta (): Riemann zeta.
-
-
-\1f
-Tag Table:
-Node: Top\7f931
-Node: Introduction\7f3191
-Node: Installation\7f5812
-Node: Prerequisites\7f6106
-Node: C++ compiler\7f6304
-Node: Make utility\7f7016
-Node: Sed utility\7f7202
-Node: Building the library\7f7522
-Node: Using the GNU MP Library\7f10745
-Node: Installing the library\7f11621
-Node: Cleaning up\7f12344
-Node: Ordinary number types\7f12669
-Node: Exact numbers\7f15022
-Node: Floating-point numbers\7f16187
-Node: Complex numbers\7f19766
-Node: Conversions\7f20263
-Node: Functions on numbers\7f23723
-Node: Constructing numbers\7f24427
-Node: Constructing integers\7f24799
-Node: Constructing rational numbers\7f25089
-Node: Constructing floating-point numbers\7f25564
-Node: Constructing complex numbers\7f26684
-Node: Elementary functions\7f27048
-Node: Elementary rational functions\7f29517
-Node: Elementary complex functions\7f30089
-Node: Comparisons\7f30917
-Node: Rounding functions\7f32810
-Node: Roots\7f38587
-Node: Transcendental functions\7f40468
-Node: Exponential and logarithmic functions\7f41024
-Node: Trigonometric functions\7f43029
-Node: Hyperbolic functions\7f46359
-Node: Euler gamma\7f48423
-Node: Riemann zeta\7f49315
-Node: Functions on integers\7f49859
-Node: Logical functions\7f50147
-Node: Number theoretic functions\7f56100
-Node: Combinatorial functions\7f57467
-Node: Functions on floating-point numbers\7f58145
-Node: Conversion functions\7f61355
-Node: Conversion to floating-point numbers\7f61635
-Node: Conversion to rational numbers\7f63852
-Node: Random number generators\7f64906
-Node: Obfuscating operators\7f66557
-Node: Input/Output\7f68287
-Node: Internal and printed representation\7f68497
-Node: Input functions\7f71039
-Node: Output functions\7f75524
-Node: Rings\7f79184
-Node: Modular integers\7f81108
-Node: Modular integer rings\7f81308
-Node: Functions on modular integers\7f83393
-Node: Symbolic data types\7f86397
-Node: Strings\7f86660
-Node: Symbols\7f87725
-Node: Univariate polynomials\7f88627
-Node: Univariate polynomial rings\7f88885
-Node: Functions on univariate polynomials\7f93801
-Node: Special polynomials\7f97576
-Node: Internals\7f98283
-Node: Why C++ ?\7f98497
-Node: Memory efficiency\7f99997
-Node: Speed efficiency\7f100695
-Node: Garbage collection\7f101779
-Node: Using the library\7f102606
-Node: Compiler options\7f103178
-Node: Compatibility to old CLN versions\7f104116
-Node: Include files\7f105537
-Node: An Example\7f109252
-Node: Debugging support\7f112518
-Node: Customizing\7f114869
-Node: Error handling\7f115097
-Node: Floating-point underflow\7f115672
-Node: Customizing I/O\7f116311
-Node: Customizing the memory allocator\7f116601
-Node: Index\7f117585
-\1f
-End Tag Table
+++ /dev/null
-\input texinfo @c -*-texinfo-*-
-@c %**start of header
-@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 %**end of header
-
-
-@c My own index.
-@defindex my
-@c Don't need the other types of indices.
-@synindex cp my
-@synindex fn my
-@synindex vr my
-@synindex ky my
-@synindex pg my
-@synindex tp my
-
-
-@c For `info' only.
-@ifinfo
-This file documents @sc{cln}, a Class Library for Numbers.
-
-Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
-Richard Kreckel, @code{<kreckel@@ginac.de>}.
-
-Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000.
-
-Permission is granted to make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-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.
-@end ifinfo
-
-
-@c For TeX only.
-@c prevent ugly black rectangles on overfull hbox lines:
-@finalout
-@titlepage
-@title CLN, a Class Library for Numbers
-
-@author by Bruno Haible
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000.
-
-@sp 2
-Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and
-Richard 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
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided that the entire
-resulting derived work is distributed under the terms of a permission
-notice identical to this one.
-
-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.
-
-@end titlepage
-@page
-
-
-@node Top, Introduction, (dir), (dir)
-
-@c @menu
-@c * Introduction:: Introduction
-@c @end menu
-
-@menu
-* Introduction::
-* Installation::
-* Ordinary number types::
-* Functions on numbers::
-* Input/Output::
-* Rings::
-* Modular integers::
-* Symbolic data types::
-* Univariate polynomials::
-* Internals::
-* Using the library::
-* Customizing::
-* Index::
-
-
- --- The Detailed Node Listing ---
-
-Installation
-
-* Prerequisites::
-* Building the library::
-* Installing the library::
-* Cleaning up::
-
-Prerequisites
-
-* C++ compiler::
-* Make utility::
-* Sed utility::
-
-Building the library
-
-* Using the GNU MP Library::
-
-Ordinary number types
-
-* Exact numbers::
-* Floating-point numbers::
-* Complex numbers::
-* Conversions::
-
-Functions on numbers
-
-* Constructing numbers::
-* Elementary functions::
-* Elementary rational functions::
-* Elementary complex functions::
-* Comparisons::
-* Rounding functions::
-* Roots::
-* Transcendental functions::
-* Functions on integers::
-* Functions on floating-point numbers::
-* Conversion functions::
-* Random number generators::
-* Obfuscating operators::
-
-Constructing numbers
-
-* Constructing integers::
-* Constructing rational numbers::
-* Constructing floating-point numbers::
-* Constructing complex numbers::
-
-Transcendental functions
-
-* Exponential and logarithmic functions::
-* Trigonometric functions::
-* Hyperbolic functions::
-* Euler gamma::
-* Riemann zeta::
-
-Functions on integers
-
-* Logical functions::
-* Number theoretic functions::
-* Combinatorial functions::
-
-Conversion functions
-
-* Conversion to floating-point numbers::
-* Conversion to rational numbers::
-
-Input/Output
-
-* Internal and printed representation::
-* Input functions::
-* Output functions::
-
-Modular integers
-
-* Modular integer rings::
-* Functions on modular integers::
-
-Symbolic data types
-
-* Strings::
-* Symbols::
-
-Univariate polynomials
-
-* Univariate polynomial rings::
-* Functions on univariate polynomials::
-* Special polynomials::
-
-Internals
-
-* Why C++ ?::
-* Memory efficiency::
-* Speed efficiency::
-* Garbage collection::
-
-Using the library
-
-* Compiler options::
-* Compatibility to old CLN versions::
-* Include files::
-* An Example::
-* Debugging support::
-
-Customizing
-
-* Error handling::
-* Floating-point underflow::
-* Customizing I/O::
-* Customizing the memory allocator::
-
-
-@end menu
-
-@node Introduction, Installation, Top, Top
-@comment node-name, next, previous, up
-@chapter Introduction
-
-@noindent
-CLN is a library for computations with all kinds of numbers.
-It has a rich set of number classes:
-
-@itemize @bullet
-@item
-Integers (with unlimited precision),
-
-@item
-Rational numbers,
-
-@item
-Floating-point numbers:
-
-@itemize @minus
-@item
-Short float,
-@item
-Single float,
-@item
-Double float,
-@item
-Long float (with unlimited precision),
-@end itemize
-
-@item
-Complex numbers,
-
-@item
-Modular integers (integers modulo a fixed integer),
-
-@item
-Univariate polynomials.
-@end itemize
-
-@noindent
-The subtypes of the complex numbers among these are exactly the
-types of numbers known to the Common Lisp language. Therefore
-@code{CLN} can be used for Common Lisp implementations, giving
-@samp{CLN} another meaning: it becomes an abbreviation of
-``Common Lisp Numbers''.
-
-@noindent
-The CLN package implements
-
-@itemize @bullet
-@item
-Elementary functions (@code{+}, @code{-}, @code{*}, @code{/}, @code{sqrt},
-comparisons, @dots{}),
-
-@item
-Logical functions (logical @code{and}, @code{or}, @code{not}, @dots{}),
-
-@item
-Transcendental functions (exponential, logarithmic, trigonometric, hyperbolic
-functions and their inverse functions).
-@end itemize
-
-@noindent
-CLN is a C++ library. Using C++ as an implementation language provides
-
-@itemize @bullet
-@item
-efficiency: it compiles to machine code,
-@item
-type safety: the C++ compiler knows about the number types and complains
-if, for example, you try to assign a float to an integer variable.
-@item
-algebraic syntax: You can use the @code{+}, @code{-}, @code{*}, @code{=},
-@code{==}, @dots{} operators as in C or C++.
-@end itemize
-
-@noindent
-CLN is memory efficient:
-
-@itemize @bullet
-@item
-Small integers and short floats are immediate, not heap allocated.
-@item
-Heap-allocated memory is reclaimed through an automatic, non-interruptive
-garbage collection.
-@end itemize
-
-@noindent
-CLN is speed efficient:
-
-@itemize @bullet
-@item
-The kernel of CLN has been written in assembly language for some CPUs
-(@code{i386}, @code{m68k}, @code{sparc}, @code{mips}, @code{arm}).
-@item
-@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.
-@item
-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
-@cindex Schönhage-Strassen multiplication
-@end ifinfo
-multiplication, which is an asymptotically optimal multiplication
-algorithm, for multiplication, division and radix conversion.
-@end itemize
-
-@noindent
-CLN aims at being easily integrated into larger software packages:
-
-@itemize @bullet
-@item
-The garbage collection imposes no burden on the main application.
-@item
-The library provides hooks for memory allocation and exceptions.
-@item
-@cindex namespace
-All non-macro identifiers are hidden in namespace @code{cln} in
-order to avoid name clashes.
-@end itemize
-
-
-@node Installation, Ordinary number types, Introduction, Top
-@chapter Installation
-
-This section describes how to install the CLN package on your system.
-
-
-@menu
-* Prerequisites::
-* Building the library::
-* Installing the library::
-* Cleaning up::
-@end menu
-
-@node Prerequisites, Building the library, Installation, Installation
-@section Prerequisites
-
-@menu
-* C++ compiler::
-* Make utility::
-* Sed utility::
-@end menu
-
-@node C++ compiler, Make utility, Prerequisites, Prerequisites
-@subsection C++ compiler
-
-To build CLN, you need a C++ compiler.
-Actually, you need GNU @code{g++ 2.90} or newer, the EGCS compilers will
-do.
-I recommend GNU @code{g++ 2.95} or newer.
-
-The following C++ features are used:
-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.
-
-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
-
-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
-@subsection Make utility
-@cindex @code{make}
-
-To build CLN, you also need to have GNU @code{make} installed.
-
-@node Sed utility, , Make utility, Prerequisites
-@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
-on @code{sed}, and the vendor's @code{sed} utility on these systems is too
-limited.
-
-
-@node Building the library, Installing the library, Prerequisites, Installation
-@section Building the library
-
-As with any autoconfiguring GNU software, installation is as easy as this:
-
-@example
-$ ./configure
-$ make
-$ make check
-@end example
-
-If on your system, @samp{make} is not GNU @code{make}, you have to use
-@samp{gmake} instead of @samp{make} above.
-
-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.
-
-The @code{configure} command accepts options. To get a summary of them, try
-
-@example
-$ ./configure --help
-@end example
-
-Some of the options are explained in detail in the @samp{INSTALL.generic} file.
-
-You can specify the C compiler, the C++ compiler and their options through
-the following environment variables when running @code{configure}:
-
-@table @code
-@item CC
-Specifies the C compiler.
-
-@item CFLAGS
-Flags to be given to the C compiler when compiling programs (not when linking).
-
-@item CXX
-Specifies the C++ compiler.
-
-@item CXXFLAGS
-Flags to be given to the C++ compiler when compiling programs (not when linking).
-@end table
-
-Examples:
-
-@example
-$ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
-$ CC="gcc -V egcs-2.91.60" CFLAGS="-O -g" \
- CXX="g++ -V egcs-2.91.60" CXXFLAGS="-O -g" ./configure
-$ CC="gcc -V 2.95.2" CFLAGS="-O2 -fno-exceptions" \
- CXX="g++ -V 2.95.2" CFLAGS="-O2 -fno-exceptions" ./configure
-@end example
-@ignore
-@comment cl_modules.h requires g++
-You should not mix GNU and non-GNU compilers. So, if @code{CXX} is a non-GNU
-compiler, @code{CC} should be set to a non-GNU compiler as well. Examples:
-
-@example
-$ CC="cc" CFLAGS="-O" CXX="CC" CXXFLAGS="-O" ./configure
-$ CC="gcc -V 2.7.0" CFLAGS="-g" CXX="g++ -V 2.7.0" CXXFLAGS="-g" ./configure
-@end example
-
-On SGI Irix 5, if you wish not to use @code{g++}:
-
-@example
-$ CC="cc" CFLAGS="-O" CXX="CC" CXXFLAGS="-O -Olimit 16000" ./configure
-@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
-commands, you have to @code{export} the environment variables before
-calling @code{configure}. In a @code{csh} shell, you have to use the
-@samp{setenv} command for setting each of the environment variables.
-
-Currently CLN works only with the GNU @code{g++} compiler, and only in
-optimizing mode. So you should specify at least @code{-O} in the CXXFLAGS,
-or no CXXFLAGS at all. (If CXXFLAGS is not set, CLN will use @code{-O}.)
-
-If you use @code{g++} 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++} version egcs-2.91.x (egcs-1.1) or gcc-2.95.x on Sparc,
-add either @samp{-O}, @samp{-O1} or @samp{-O2 -fno-schedule-insns} to the
-CXXFLAGS. With full @samp{-O2}, @code{g++} miscompiles the division routines.
-Also, if you have @code{g++} version egcs-1.1.1 or older on Sparc, you must
-specify @samp{--disable-shared} because @code{g++} would miscompile parts of
-the library.
-
-By default, both a shared and a static library are built. You can build
-CLN as a static (or shared) library only, by calling @code{configure} with
-the option @samp{--disable-shared} (or @samp{--disable-static}). While
-shared libraries are usually more convenient to use, they may not work
-on all architectures. Try disabling them if you run into linker
-problems. Also, they are generally somewhat slower than static
-libraries so runtime-critical applications should be linked statically.
-
-
-@menu
-* Using the GNU MP Library::
-@end menu
-
-@node Using the GNU MP Library, , Building the library, Building the library
-@subsection Using the GNU MP Library
-@cindex GMP
-
-Starting with version 1.1, CLN may be configured to make use of a
-preinstalled @code{gmp} library. Please make sure that you have at
-least @code{gmp} version 3.0 installed since earlier versions are
-unsupported and likely not to work. Enabling this feature by calling
-@code{configure} with the option @samp{--with-gmp} is known to be quite
-a boost for CLN's performance.
-
-If you have installed the @code{gmp} library and its header file in
-some place where your compiler cannot find it by default, you must help
-@code{configure} by setting @code{CPPFLAGS} and @code{LDFLAGS}. Here is
-an example:
-
-@example
-$ CC="gcc" CFLAGS="-O2" CXX="g++" CXXFLAGS="-O2 -fno-exceptions" \
- CPPFLAGS="-I/opt/gmp/include" LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
-@end example
-
-
-@node Installing the library, Cleaning up, Building the library, Installation
-@section Installing the library
-@cindex installation
-
-As with any autoconfiguring GNU software, installation is as easy as this:
-
-@example
-$ make install
-@end example
-
-The @samp{make install} command installs the library and the include files
-into public places (@file{/usr/local/lib/} and @file{/usr/local/include/},
-if you haven't specified a @code{--prefix} option to @code{configure}).
-This step may require superuser privileges.
-
-If you have already built the library and wish to install it, but didn't
-specify @code{--prefix=@dots{}} at configure time, just re-run
-@code{configure}, giving it the same options as the first time, plus
-the @code{--prefix=@dots{}} option.
-
-
-@node Cleaning up, , Installing the library, Installation
-@section Cleaning up
-
-You can remove system-dependent files generated by @code{make} through
-
-@example
-$ make clean
-@end example
-
-You can remove all files generated by @code{make}, thus reverting to a
-virgin distribution of CLN, through
-
-@example
-$ make distclean
-@end example
-
-
-@node Ordinary number types, Functions on numbers, Installation, Top
-@chapter Ordinary number types
-
-CLN implements the following class hierarchy:
-
-@example
- Number
- cl_number
- <cln/number.h>
- |
- |
- Real or complex number
- cl_N
- <cln/complex.h>
- |
- |
- Real number
- cl_R
- <cln/real.h>
- |
- +-------------------+-------------------+
- | |
-Rational number Floating-point number
- cl_RA cl_F
-<cln/rational.h> <cln/float.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.
-
-
-@menu
-* Exact numbers::
-* Floating-point numbers::
-* Complex numbers::
-* Conversions::
-@end menu
-
-@node Exact numbers, Floating-point numbers, Ordinary number types, Ordinary number types
-@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
-representation. On exact numbers, the elementary operations (@code{+},
-@code{-}, @code{*}, @code{/}, comparisons, @dots{}) compute the completely
-correct result.
-
-In CLN, the exact numbers are:
-
-@itemize @bullet
-@item
-rational numbers (including integers),
-@item
-complex numbers whose real and imaginary parts are both rational numbers.
-@end itemize
-
-Rational numbers are always normalized to the form
-@code{@var{numerator}/@var{denominator}} where the numerator and denominator
-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},
-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
-@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
-a computer, even if one assumes that it has unlimited storage. But there
-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
-@samp{0.7}. Rounding errors like this one are inevitable when computing
-with floating-point numbers.
-
-Nevertheless, CLN rounds the floating-point results of the operations @code{+},
-@code{-}, @code{*}, @code{/}, @code{sqrt} according to the ``round-to-even''
-rule: It first computes the exact mathematical result and then returns the
-floating-point number which is nearest to this. If two floating-point numbers
-are equally distant from the ideal result, the one with a @code{0} in its least
-significant mantissa bit is chosen.
-
-Similarly, testing floating point numbers for equality @samp{x == y}
-is gambling with random errors. Better check for @samp{abs(x - y) < epsilon}
-for some well-chosen @code{epsilon}.
-
-Floating point numbers come in four flavors:
-
-@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).
-In CLN, they are represented as IEEE single-precision floating point numbers.
-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).
-In CLN, they are represented as IEEE double-precision floating point numbers.
-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.
-The precision of a long float is unlimited, but once created, a long float
-has a fixed precision. (No ``lazy recomputation''.)
-@end itemize
-
-Of course, computations with long floats are more expensive than those
-with smaller floating-point formats.
-
-CLN does not implement features like NaNs, denormalized numbers and
-gradual underflow. If the exponent range of some floating-point type
-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
-when you change the precision of some computation (say, from @code{cl_DF}
-to @code{cl_LF}), you don't have to change the code, only the precision
-of the initial values. Also, many transcendental functions have been
-declared as returning a @code{cl_F} when the argument is a @code{cl_F},
-but such declarations are missing for the types @code{cl_SF}, @code{cl_FF},
-@code{cl_DF}, @code{cl_LF}. (Such declarations would be wrong if
-the floating point contagion rule happened to change in the future.)
-
-
-@node Complex numbers, Conversions, Floating-point numbers, Ordinary number types
-@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
-imaginary part is the exact number @code{0} is automatically converted
-to a real number.
-
-Complex numbers can arise from real numbers alone, for example
-through application of @code{sqrt} or transcendental functions.
-
-
-@node Conversions, , Complex numbers, Ordinary number types
-@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{long} and @samp{unsigned long}
-are provided for the classes @code{cl_I}, @code{cl_RA}, @code{cl_R},
-@code{cl_N} and @code{cl_number}.
-
-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:
-
-@itemize @minus
-@item
-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.
-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}.
-
-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}.
-
-Conversions from the C built-in type @samp{double} are provided for the classes
-@code{cl_DF}, @code{cl_F}, @code{cl_R}, @code{cl_N} and @code{cl_number}.
-
-Conversions from @samp{const char *} are provided for the classes
-@code{cl_I}, @code{cl_RA},
-@code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}, @code{cl_F},
-@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
-Note that this conversion is done at runtime, not at compile-time.
-
-Conversions from @code{cl_I} to the C built-in types @samp{int},
-@samp{unsigned int}, @samp{long}, @samp{unsigned long} are provided through
-the functions
-
-@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
-
-Conversions from the classes @code{cl_I}, @code{cl_RA},
-@code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}, @code{cl_F} and
-@code{cl_R}
-to the C built-in types @samp{float} and @samp{double} are provided through
-the functions
-
-@table @code
-@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.
-@end table
-
-Conversions from any class to any of its subclasses (``derived classes'' in
-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 @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.
-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.
- // In general, it would be a rational number.
-@end group
-@end example
-
-
-@node Functions on numbers, Input/Output, Ordinary number types, Top
-@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 <cln/integer.h>}.
-
-
-@menu
-* Constructing numbers::
-* Elementary functions::
-* Elementary rational functions::
-* Elementary complex functions::
-* Comparisons::
-* Rounding functions::
-* Roots::
-* Transcendental functions::
-* Functions on integers::
-* Functions on floating-point numbers::
-* Conversion functions::
-* Random number generators::
-* Obfuscating operators::
-@end menu
-
-@node Constructing numbers, Elementary functions, Functions on numbers, Functions on numbers
-@section Constructing numbers
-
-Here is how to create number objects ``from nothing''.
-
-
-@menu
-* Constructing integers::
-* Constructing rational numbers::
-* Constructing floating-point numbers::
-* Constructing complex numbers::
-@end menu
-
-@node Constructing integers, Constructing rational numbers, Constructing numbers, Constructing numbers
-@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
-@subsection Constructing rational numbers
-
-@code{cl_RA} objects can be constructed from strings. The syntax
-for rational numbers is described in @ref{Internal and printed representation}.
-Another standard way to produce a rational number is through application
-of @samp{operator /} or @samp{recip} on integers.
-
-
-@node Constructing floating-point numbers, Constructing complex numbers, Constructing rational numbers, Constructing numbers
-@subsection Constructing floating-point numbers
-
-@code{cl_F} objects with low precision are most easily constructed from
-C @samp{float} and @samp{double}. See @ref{Conversions}.
-
-To construct a @code{cl_F} with high precision, you can use the conversion
-from @samp{const char *}, but you have to specify the desired precision
-within the string. (See @ref{Internal and printed representation}.)
-Example:
-@example
- cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
-@end example
-will set @samp{e} to the given value, with a precision of 40 decimal digits.
-
-The programmatic way to construct a @code{cl_F} with high precision is
-through the @code{cl_float} conversion function, see
-@ref{Conversion to floating-point numbers}. For example, to compute
-@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);
- cl_F e = exp(cl_float(1,precision));
-@end example
-
-
-@node Constructing complex numbers, , Constructing floating-point numbers, Constructing numbers
-@subsection Constructing complex numbers
-
-Non-real @code{cl_N} objects are normally constructed through the function
-@example
- cl_N complex (const cl_R& realpart, const cl_R& imagpart)
-@end example
-See @ref{Elementary complex functions}.
-
-
-@node Elementary functions, Elementary rational functions, Constructing numbers, Functions on numbers
-@section Elementary functions
-
-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 the following operations:
-
-@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
-
-Each of 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}
-defines the following operations:
-
-@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}.)
-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
-
-The following exponentiation functions are defined:
-
-@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}.
-@end table
-
-Each of the classes @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 the following operation:
-
-@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
-
-The class @code{cl_N} implements this as follows:
-
-@table @code
-@item cl_R abs (const cl_N x)
-Returns the absolute value of @code{x}.
-@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 the following operation:
-
-@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
-0 or 1 or -1.
-@end table
-
-
-@node Elementary rational functions, Elementary complex functions, Elementary functions, Functions on numbers
-@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
-
-The numerator and denominator of a rational number are normalized in such
-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
-@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
-
-Each of the classes @code{cl_N}, @code{cl_R} defines the following operations:
-
-@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
-@item
-@code{x = complex(realpart(x), imagpart(x))}
-@item
-@code{conjugate(x) = complex(realpart(x), -imagpart(x))}
-@end itemize
-
-
-@node Comparisons, Rounding functions, Elementary complex functions, Functions on numbers
-@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}
-defines the following operations:
-
-@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 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)
-@cindex @code{zerop ()}
-Compare against zero: @code{x == 0}
-@end table
-
-Each of the classes @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 the following operations:
-
-@table @code
-@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)
-@cindex @code{minusp ()}
-Compare against zero: @code{x < 0}
-
-@item cl_boolean 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
-
-When a floating point number and a rational number are compared, the float
-is first converted to a rational number using the function @code{rational}.
-Since a floating point number actually represents an interval of real numbers,
-the result might be surprising.
-For example, @code{(cl_F)(cl_R)"1/3" == (cl_R)"1/3"} returns false because
-there is no floating point number whose value is exactly @code{1/3}.
-
-
-@node Rounding functions, Roots, Comparisons, Functions on numbers
-@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 Common Lisp and ISO Lisp standards offer four rounding functions:
-
-@table @code
-@item floor(x)
-This is the largest integer <=@code{x}.
-
-@item ceiling(x)
-This is the smallest integer >=@code{x}.
-
-@item truncate(x)
-Among the integers between 0 and @code{x} (inclusive) the one nearest to @code{x}.
-
-@item round(x)
-The integer nearest to @code{x}. If @code{x} is exactly halfway between two
-integers, choose the even one.
-@end table
-
-These functions have different advantages:
-
-@code{floor} and @code{ceiling} are translation invariant:
-@code{floor(x+n) = floor(x) + n} and @code{ceiling(x+n) = ceiling(x) + n}
-for every @code{x} and every integer @code{n}.
-
-On the other hand, @code{truncate} and @code{round} are symmetric:
-@code{truncate(-x) = -truncate(x)} and @code{round(-x) = -round(x)},
-and furthermore @code{round} is unbiased: on the ``average'', it rounds
-down exactly as often as it rounds up.
-
-The functions are related like this:
-
-@itemize @asis
-@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
-@item
-@code{truncate(x) = sign(x) * floor(abs(x))}
-@end itemize
-
-Each of the classes @code{cl_R}, @code{cl_RA},
-@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
-defines the following operations:
-
-@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
-
-Each of the classes @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 the following operations:
-
-@table @code
-@item cl_I floor1 (const @var{type}& x, const @var{type}& y)
-Returns @code{floor(x/y)}.
-@item cl_I ceiling1 (const @var{type}& x, const @var{type}& y)
-Returns @code{ceiling(x/y)}.
-@item cl_I truncate1 (const @var{type}& x, const @var{type}& y)
-Returns @code{truncate(x/y)}.
-@item cl_I round1 (const @var{type}& x, const @var{type}& y)
-Returns @code{round(x/y)}.
-@end table
-
-These functions are called @samp{floor1}, @dots{} here instead of
-@samp{floor}, @dots{}, because on some systems, system dependent include
-files define @samp{floor} and @samp{ceiling} as macros.
-
-In many cases, one needs both the quotient and the remainder of a division.
-It is more efficient to compute both at the same time than to perform
-two divisions, one for quotient and the next one for the remainder.
-The following functions therefore return a structure containing both
-the quotient and the remainder. The suffix @samp{2} indicates the number
-of ``return values''. The remainder is defined as follows:
-
-@itemize @bullet
-@item
-for the computation of @code{quotient = floor(x)},
-@code{remainder = x - quotient},
-@item
-for the computation of @code{quotient = floor(x,y)},
-@code{remainder = x - quotient*y},
-@end itemize
-
-and similarly for the other three operations.
-
-Each of the classes @code{cl_R}, @code{cl_RA},
-@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
-defines the following operations:
-
-@table @code
-@item struct @var{type}_div_t @{ cl_I quotient; @var{type} remainder; @};
-@itemx @var{type}_div_t floor2 (const @var{type}& x)
-@itemx @var{type}_div_t ceiling2 (const @var{type}& x)
-@itemx @var{type}_div_t truncate2 (const @var{type}& x)
-@itemx @var{type}_div_t round2 (const @var{type}& x)
-@end table
-
-Each of the classes @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 the following operations:
-
-@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
-same format as the argument, if the argument is a float) instead of as
-an integer. The prefix @samp{f} indicates this.
-
-Each of the classes
-@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
-defines the following operations:
-
-@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}.
-
-The class @code{cl_R} defines the following operations:
-
-@table @code
-@item cl_F ffloor (const @var{type}& x, const @var{type}& y)
-@itemx cl_F fceiling (const @var{type}& x, const @var{type}& y)
-@itemx cl_F ftruncate (const @var{type}& x, const @var{type}& y)
-@itemx cl_F fround (const @var{type}& x, const @var{type}& y)
-@end table
-
-These functions also exist in versions which return both the quotient
-and the remainder. The suffix @samp{2} indicates this.
-
-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 struct @var{type}_fdiv_t @{ cl_F quotient; cl_R remainder; @};
-@itemx @var{type}_fdiv_t ffloor2 (const @var{type}& x, const @var{type}& y)
-@itemx @var{type}_fdiv_t fceiling2 (const @var{type}& x, const @var{type}& y)
-@itemx @var{type}_fdiv_t ftruncate2 (const @var{type}& x, const @var{type}& y)
-@itemx @var{type}_fdiv_t fround2 (const @var{type}& x, const @var{type}& y)
-@end table
-
-Other applications need only the remainder of a division.
-The remainder of @samp{floor} and @samp{ffloor} is called @samp{mod}
-(abbreviation of ``modulo''). The remainder @samp{truncate} and
-@samp{ftruncate} is called @samp{rem} (abbreviation of ``remainder'').
-
-@itemize @bullet
-@item
-@code{mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y}
-@item
-@code{rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y}
-@end itemize
-
-If @code{x} and @code{y} are both >= 0, @code{mod(x,y) = rem(x,y) >= 0}.
-In general, @code{mod(x,y)} has the sign of @code{y} or is zero,
-and @code{rem(x,y)} has the sign of @code{x} or is zero.
-
-The classes @code{cl_R}, @code{cl_I} define 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
-@section Roots
-
-Each of the classes @code{cl_R},
-@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
-defines the following operation:
-
-@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
-floating-point approximation.
-@end table
-
-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)
-@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)
-@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)}.
-@end table
-
-For @code{n}th roots, the classes @code{cl_RA}, @code{cl_I}
-define the following operation:
-
-@table @code
-@item cl_boolean 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
-false.
-@end table
-
-The only square root function which accepts negative numbers is the one
-for class @code{cl_N}:
-
-@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
-right half plane @code{realpart(sqrt(z)) >= 0}
-including the positive imaginary axis and 0, but excluding
-the negative imaginary axis.
-The result is an exact number only if @code{z} is an exact number.
-@end table
-
-
-@node Transcendental functions, Functions on integers, Roots, Functions on numbers
-@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
-inexact numbers even if the argument is exact.
-For example, @code{cos(0) = 1} returns the rational number @code{1}.
-
-
-@menu
-* Exponential and logarithmic functions::
-* Trigonometric functions::
-* Hyperbolic functions::
-* Euler gamma::
-* Riemann zeta::
-@end menu
-
-@node Exponential and logarithmic functions, Trigonometric functions, Transcendental functions, Transcendental 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)}.
-The range of the result is the interval @code{-pi < phase(x) <= pi}.
-The result will be an exact number only if @code{zerop(x)} or
-if @code{x} is real and positive.
-
-@item cl_R log (const cl_R& a, const cl_R& b)
-@code{a} and @code{b} must be > 0. Returns the logarithm of @code{a} with
-respect to base @code{b}. @code{log(a,b) = ln(a)/ln(b)}.
-The result can be exact only if @code{a = 1} or if @code{a} and @code{b}
-are both rational.
-
-@item cl_N log (const cl_N& a, const cl_N& b)
-Returns the logarithm of @code{a} with respect to base @code{b}.
-@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 exp1 (cl_float_format_t f)
-@cindex @code{exp1 ()}
-Returns e as a float of format @code{f}.
-
-@item cl_F exp1 (const cl_F& y)
-Returns e in the float format of @code{y}.
-
-@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
-@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}.
-
-@item cl_N sin (const cl_N& z)
-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 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
-@code{arcsin(-z) = -arcsin(z)}.
-The range of the result is the strip in the complex domain
-@code{-pi/2 <= realpart(arcsin(z)) <= pi/2}, excluding the numbers
-with @code{realpart = -pi/2} and @code{imagpart < 0} and the numbers
-with @code{realpart = pi/2} and @code{imagpart > 0}.
-@ignore
-Proof: This follows from arcsin(z) = arsinh(iz)/i and the corresponding
-results for arsinh.
-@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
- Kahan's formula:
- @code{arccos(z) = 2*log(sqrt((1+z)/2)+i*sqrt((1-z)/2))/i}
-@end ignore
-and satisfies @code{arccos(-z) = pi - arccos(z)}.
-The range of the result is the strip in the complex domain
-@code{0 <= realpart(arcsin(z)) <= pi}, excluding the numbers
-with @code{realpart = 0} and @code{imagpart < 0} and the numbers
-with @code{realpart = pi} and @code{imagpart > 0}.
-@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
-the result is the interval @code{-pi < atan(x,y) <= pi}. The result will
-be an exact number only if @code{x > 0} and @code{y} is the exact @code{0}.
-WARNING: In Common Lisp, this function is called as @code{(atan y x)},
-with reversed order of arguments.
-
-@item cl_R atan (const cl_R& x)
-Returns @code{arctan(x)}. This is the same as @code{atan(1,x)}. The range
-of the result is the interval @code{-pi/2 < atan(x) < pi/2}. The result
-will be an exact number only if @code{x} is the exact @code{0}.
-
-@item cl_N atan (const cl_N& z)
-Returns @code{arctan(z)}. This is defined as
-@code{arctan(z) = (log(1+iz)-log(1-iz)) / 2i} and satisfies
-@code{arctan(-z) = -arctan(z)}. The range of the result is
-the strip in the complex domain
-@code{-pi/2 <= realpart(arctan(z)) <= pi/2}, excluding the numbers
-with @code{realpart = -pi/2} and @code{imagpart >= 0} and the numbers
-with @code{realpart = pi/2} and @code{imagpart <= 0}.
-@ignore
-Proof: arctan(z) = artanh(iz)/i, we know the range of the artanh function.
-@end ignore
-
-@end table
-
-@cindex pi
-@cindex Archimedes' constant
-Archimedes' constant pi = 3.14@dots{} is returned by the following functions:
-
-@table @code
-@item cl_F pi (cl_float_format_t f)
-@cindex @code{pi ()}
-Returns pi as a float of format @code{f}.
-
-@item cl_F pi (const cl_F& y)
-Returns pi in the float format of @code{y}.
-
-@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
-@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 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)}.
-@ignore
-Proof: Knowing the range of log, we know -pi < imagpart(arsinh(z)) <= pi.
-Actually, z+sqrt(1+z^2) can never be real and <0, so
--pi < imagpart(arsinh(z)) < pi.
-We have (z+sqrt(1+z^2))*(-z+sqrt(1+(-z)^2)) = (1+z^2)-z^2 = 1, hence the
-logs of both factors sum up to 0 mod 2*pi*i, hence to 0.
-@end ignore
-The range of the result is the strip in the complex domain
-@code{-pi/2 <= imagpart(arsinh(z)) <= pi/2}, excluding the numbers
-with @code{imagpart = -pi/2} and @code{realpart > 0} and the numbers
-with @code{imagpart = pi/2} and @code{realpart < 0}.
-@ignore
-Proof: Write z = x+iy. Because of arsinh(-z) = -arsinh(z), we may assume
-that z is in Range(sqrt), that is, x>=0 and, if x=0, then y>=0.
-If x > 0, then Re(z+sqrt(1+z^2)) = x + Re(sqrt(1+z^2)) >= x > 0,
-so -pi/2 < imagpart(log(z+sqrt(1+z^2))) < pi/2.
-If x = 0 and y >= 0, arsinh(z) = log(i*y+sqrt(1-y^2)).
- If y <= 1, the realpart is 0 and the imagpart is >= 0 and <= pi/2.
- If y >= 1, the imagpart is pi/2 and the realpart is
- log(y+sqrt(y^2-1)) >= log(y) >= 0.
-@end ignore
-@ignore
-Moreover, if z is in Range(sqrt),
-log(sqrt(1+z^2)+z) = 2 artanh(z/(1+sqrt(1+z^2)))
-(for a proof, see file src/cl_C_asinh.cc).
-@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
-@code{-pi < imagpart(arcosh(z)) <= pi, realpart(arcosh(z)) >= 0},
-excluding the numbers with @code{realpart = 0} and @code{-pi < imagpart < 0}.
-@ignore
-Proof: sqrt((z+1)/2) and sqrt((z-1)/2)) lie in Range(sqrt), hence does
-their sum, hence its log has an imagpart <= pi/2 and > -pi/2.
-If z is in Range(sqrt), we have
- sqrt(z+1)*sqrt(z-1) = sqrt(z^2-1)
- ==> (sqrt((z+1)/2)+sqrt((z-1)/2))^2 = (z+1)/2 + sqrt(z^2-1) + (z-1)/2
- = z + sqrt(z^2-1)
- ==> arcosh(z) = log(z+sqrt(z^2-1)) mod 2*pi*i
- and since the imagpart of both expressions is > -pi, <= pi
- ==> arcosh(z) = log(z+sqrt(z^2-1))
- To prove that the realpart of this is >= 0, write z = x+iy with x>=0,
- z^2-1 = u+iv with u = x^2-y^2-1, v = 2xy,
- sqrt(z^2-1) = p+iq with p = sqrt((sqrt(u^2+v^2)+u)/2) >= 0,
- q = sqrt((sqrt(u^2+v^2)-u)/2) * sign(v),
- then |z+sqrt(z^2-1)|^2 = |x+iy + p+iq|^2
- = (x+p)^2 + (y+q)^2
- = x^2 + 2xp + p^2 + y^2 + 2yq + q^2
- >= x^2 + p^2 + y^2 + q^2 (since x>=0, p>=0, yq>=0)
- = x^2 + y^2 + sqrt(u^2+v^2)
- >= x^2 + y^2 + |u|
- >= x^2 + y^2 - u
- = 1 + 2*y^2
- >= 1
- hence realpart(log(z+sqrt(z^2-1))) = log(|z+sqrt(z^2-1)|) >= 0.
- Equality holds only if y = 0 and u <= 0, i.e. 0 <= x < 1.
- In this case arcosh(z) = log(x+i*sqrt(1-x^2)) has imagpart >=0.
-Otherwise, -z is in Range(sqrt).
- If y != 0, sqrt((z+1)/2) = i^sign(y) * sqrt((-z-1)/2),
- sqrt((z-1)/2) = i^sign(y) * sqrt((-z+1)/2),
- hence arcosh(z) = sign(y)*pi/2*i + arcosh(-z),
- and this has realpart > 0.
- If y = 0 and -1<=x<=0, we still have sqrt(z+1)*sqrt(z-1) = sqrt(z^2-1),
- ==> arcosh(z) = log(z+sqrt(z^2-1)) = log(x+i*sqrt(1-x^2))
- has realpart = 0 and imagpart > 0.
- If y = 0 and x<=-1, however, sqrt(z+1)*sqrt(z-1) = - sqrt(z^2-1),
- ==> arcosh(z) = log(z-sqrt(z^2-1)) = pi*i + arcosh(-z).
- This has realpart >= 0 and imagpart = pi.
-@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
-the strip in the complex domain
-@code{-pi/2 <= imagpart(artanh(z)) <= pi/2}, excluding the numbers
-with @code{imagpart = -pi/2} and @code{realpart <= 0} and the numbers
-with @code{imagpart = pi/2} and @code{realpart >= 0}.
-@ignore
-Proof: Write z = x+iy. Examine
- imagpart(artanh(z)) = (atan(1+x,y) - atan(1-x,-y))/2.
- Case 1: y = 0.
- x > 1 ==> imagpart = -pi/2, realpart = 1/2 log((x+1)/(x-1)) > 0,
- x < -1 ==> imagpart = pi/2, realpart = 1/2 log((-x-1)/(-x+1)) < 0,
- |x| < 1 ==> imagpart = 0
- Case 2: y > 0.
- imagpart(artanh(z))
- = (atan(1+x,y) - atan(1-x,-y))/2
- = ((pi/2 - atan((1+x)/y)) - (-pi/2 - atan((1-x)/-y)))/2
- = (pi - atan((1+x)/y) - atan((1-x)/y))/2
- > (pi - pi/2 - pi/2 )/2 = 0
- and (1+x)/y > (1-x)/y
- ==> atan((1+x)/y) > atan((-1+x)/y) = - atan((1-x)/y)
- ==> imagpart < pi/2.
- Hence 0 < imagpart < pi/2.
- Case 3: y < 0.
- By artanh(z) = -artanh(-z) and case 2, -pi/2 < imagpart < 0.
-@end ignore
-@end table
-
-
-@node Euler gamma, Riemann zeta, Hyperbolic functions, Transcendental functions
-@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 eulerconst (cl_float_format_t f)
-@cindex @code{eulerconst ()}
-Returns Euler's constant as a float of format @code{f}.
-
-@item cl_F eulerconst (const cl_F& y)
-Returns Euler's constant in the float format of @code{y}.
-
-@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 catalanconst (cl_float_format_t f)
-@cindex @code{catalanconst ()}
-Returns Catalan's constant as a float of format @code{f}.
-
-@item cl_F catalanconst (const cl_F& y)
-Returns Catalan's constant in the float format of @code{y}.
-
-@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
-@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 zeta (int s, cl_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 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 zeta (int s)
-Returns Riemann's zeta function at @code{s} as a float of format
-@code{default_float_format}.
-@end table
-
-
-@node Functions on integers, Functions on floating-point numbers, Transcendental functions, Functions on numbers
-@section Functions on integers
-
-@menu
-* Logical functions::
-* Number theoretic functions::
-* Combinatorial functions::
-@end menu
-
-@node Logical functions, Number theoretic functions, Functions on integers, Functions on integers
-@subsection Logical functions
-
-Integers, when viewed as in two's complement notation, can be thought as
-infinite bit strings where the bits' values eventually are constant.
-For example,
-@example
- 17 = ......00010001
- -6 = ......11111010
-@end example
-
-The logical operations view integers as such bit strings and operate
-on each of the bit positions in parallel.
-
-@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_1}, @code{boole_2}, @code{boole_c1}, @code{boole_c2},
-@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)
-@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)
-@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)
-@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; @};
-@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)
-@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.
-@end table
-
-The functions @code{ldb} and @code{dpb} implicitly shift. The following
-functions are their counterparts without shifting:
-
-@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
-@item
-@code{ldb (n, b) = mask_field(n, b) >> b.position},
-@item
-@code{dpb (newbyte, n, b) = deposit_field (newbyte << b.position, n, b)},
-@item
-@code{deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^ mask_field(new_byte,b)}.
-@end itemize
-
-The following operations on integers as bit strings are efficient shortcuts
-for common arithmetic operations:
-
-@table @code
-@item cl_boolean 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)
-@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)
-@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)
-@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)
-@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
-@subsection Number theoretic functions
-
-@table @code
-@item uint32 gcd (uint32 a, uint32 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{u} and @code{v} with @code{u*a+v*b = g}, @code{g} >= 0.
-@code{u} and @code{v} will be normalized to be of smallest possible absolute
-value, in the following sense: If @code{a} and @code{b} are non-zero, and
-@code{abs(a) != abs(b)}, @code{u} and @code{v} will satisfy the inequalities
-@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)
-@cindex @code{logp ()}
-@itemx cl_boolean 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.
-@end table
-
-
-@node Combinatorial functions, , Number theoretic functions, Functions on integers
-@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)!}$
-@end tex
-@ifinfo
-(@code{n} choose @code{k}) = @code{n}! / @code{k}! @code{(n-k)}!
-@end ifinfo
-for 0 <= k <= n, 0 else.
-@end table
-
-
-@node Functions on floating-point numbers, Conversion functions, Functions on integers, Functions on numbers
-@section Functions on floating-point numbers
-
-Recall that a floating-point number consists of a sign @code{s}, an
-exponent @code{e} and a mantissa @code{m}. The value of the number is
-@code{(-1)^s * 2^e * m}.
-
-Each of the classes
-@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}
-defines the following operations.
-
-@table @code
-@item @var{type} scale_float (const @var{type}& x, sintL 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.
-@end table
-
-The following functions provide an abstract interface to the underlying
-representation of floating-point numbers.
-
-@table @code
-@item sintL 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)
-@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)
-@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
-0 if @code{x} = 0.
-@end table
-
-The complete internal representation of a float is encoded in the type
-@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 decoded_@var{type}float @{
- @var{type} mantissa; cl_I exponent; @var{type} sign;
-@};
-@end example
-
-and returned by the function
-
-@table @code
-@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.
-@code{e} is the same as returned by the function @code{float_exponent}.
-@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;
-@};
-@end example
-by the following function:
-
-@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.
-WARNING: The exponent @code{e} is not the same as the one returned by
-the functions @code{decode_float} and @code{float_exponent}.
-@end table
-
-Some other function, implemented only for class @code{cl_F}:
-
-@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
-@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
-@subsection Conversion to floating-point numbers
-
-The type @code{cl_float_format_t} describes a floating-point format.
-@cindex @code{cl_float_format_t}
-
-@table @code
-@item cl_float_format_t cl_float_format (uintL n)
-@cindex @code{cl_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)
-Returns the floating point format of @code{x}.
-
-@item cl_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
-
-To convert a real number to a float, each of the types
-@code{cl_R}, @code{cl_F}, @code{cl_I}, @code{cl_RA},
-@code{int}, @code{unsigned int}, @code{float}, @code{double}
-defines the following operations:
-
-@table @code
-@item cl_F cl_float (const @var{type}&x, cl_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{default_float_format} if
-it is an exact number, or @code{x} itself if it is already a float.
-@end table
-
-Of course, converting a number to a float can lose precision.
-
-Every floating-point format has some characteristic numbers:
-
-@table @code
-@item cl_F most_positive_float (cl_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)
-@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)
-@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)
-@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)
-@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)
-@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
-@subsection Conversion to rational numbers
-
-Each of the classes @code{cl_R}, @code{cl_RA}, @code{cl_F}
-defines the following operation:
-
-@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.
-@end table
-
-In order to convert back, say, @code{(cl_F)(cl_R)"1/3"} to @code{1/3}, there is
-the function
-
-@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)
-which lies in this interval.
-If @code{x} is already an exact number, this function returns @code{x}.
-@end table
-
-If @code{x} is any float, one has
-
-@itemize @asis
-@item
-@code{cl_float(rational(x),x) = x}
-@item
-@code{cl_float(rationalize(x),x) = x}
-@end itemize
-
-
-@node Random number generators, Obfuscating operators, Conversion functions, Functions on numbers
-@section Random number generators
-
-
-A random generator is a machine which produces (pseudo-)random numbers.
-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.
-
-The following functions return (pseudo-)random numbers in different formats.
-Calling one of these modifies the state of the random number generator in
-a complicated but deterministic way.
-
-The global variable
-@cindex @code{random_state}
-@cindex @code{default_random_state}
-@example
-random_state default_random_state
-@end example
-contains a default random number generator. It is used when the functions
-below are called without @code{random_state} argument.
-
-@table @code
-@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 (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 (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 (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
-@cindex modifying operators
-
-The modifying C/C++ operators @code{+=}, @code{-=}, @code{*=}, @code{/=},
-@code{&=}, @code{|=}, @code{^=}, @code{<<=}, @code{>>=}
-are not available by default because their
-use tends to make programs unreadable. It is trivial to get away without
-them. However, if you feel that you absolutely need these operators
-to get happy, then add
-@example
-#define WANT_OBFUSCATING_OPERATORS
-@end example
-@cindex @code{WANT_OBFUSCATING_OPERATORS}
-to the beginning of your source files, before the inclusion of any CLN
-include files. This flag will enable the following operators:
-
-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}:
-
-@table @code
-@item @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}&)
-@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},
-@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}:
-
-@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:
-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
-@chapter Input/Output
-@cindex Input/Output
-
-@menu
-* Internal and printed representation::
-* Input functions::
-* Output functions::
-@end menu
-
-@node Internal and printed representation, Input functions, Input/Output, Input/Output
-@section Internal and printed representation
-@cindex representation
-
-All computations deal with the internal representations of the numbers.
-
-Every number has an external representation as a sequence of ASCII characters.
-Several external representations may denote the same number, for example,
-"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''.
-@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''.
-
-Different types of numbers have different external representations (case
-is insignificant):
-
-@table @asis
-@item Integers
-External representation: @var{sign}@{@var{digit}@}+. The reader also accepts the
-Common Lisp syntaxes @var{sign}@{@var{digit}@}+@code{.} with a trailing dot
-for decimal integers
-and the @code{#@var{n}R}, @code{#b}, @code{#o}, @code{#x} prefixes.
-
-@item Rational numbers
-External representation: @var{sign}@{@var{digit}@}+@code{/}@{@var{digit}@}+.
-The @code{#@var{n}R}, @code{#b}, @code{#o}, @code{#x} prefixes are allowed
-here as well.
-
-@item Floating-point numbers
-External representation: @var{sign}@{@var{digit}@}*@var{exponent} or
-@var{sign}@{@var{digit}@}*@code{.}@{@var{digit}@}*@var{exponent} or
-@var{sign}@{@var{digit}@}*@code{.}@{@var{digit}@}+. A precision specifier
-of the form _@var{prec} may be appended. There must be at least
-one digit in the non-exponent part. The exponent has the syntax
-@var{expmarker} @var{expsign} @{@var{digit}@}+.
-The exponent marker is
-
-@itemize @asis
-@item
-@samp{s} for short-floats,
-@item
-@samp{f} for single-floats,
-@item
-@samp{d} for double-floats,
-@item
-@samp{L} for long-floats,
-@end itemize
-
-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}.
-
-@item Complex numbers
-External representation:
-@itemize @asis
-@item
-In algebraic notation: @code{@var{realpart}+@var{imagpart}i}. Of course,
-if @var{imagpart} is negative, its printed representation begins with
-a @samp{-}, and the @samp{+} between @var{realpart} and @var{imagpart}
-may be omitted. Note that this notation cannot be used when the @var{imagpart}
-is rational and the rational number's base is >18, because the @samp{i}
-is then read as a digit.
-@item
-In Common Lisp notation: @code{#C(@var{realpart} @var{imagpart})}.
-@end itemize
-@end table
-
-
-@node Input functions, Output functions, Internal and printed representation, Input/Output
-@section Input functions
-
-Including @code{<cln/io.h>} defines a type @code{cl_istream}, which is
-the type of the first argument to all input functions. @code{cl_istream}
-is the same as @code{std::istream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_istream stdin}
-@end itemize
-contains the standard input stream.
-
-These are the simple input functions:
-
-@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{<cln/@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{<cln/@var{type}_io.h>},
-are the following:
-
-@table @code
-@item cl_N read_complex (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_R read_real (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_F read_float (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_I read_integer (cl_istream stream, const cl_read_flags& flags)
-Reads a number from @code{stream}. The @code{flags} are parameters which
-affect the input syntax. Whitespace before the number is silently skipped.
-
-@item cl_N read_complex (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
-@itemx cl_R read_real (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
-@itemx cl_F read_float (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
-@itemx cl_RA read_rational (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
-@itemx cl_I read_integer (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)
-Reads a number from a string in memory. The @code{flags} are parameters which
-affect the input syntax. The string starts at @code{string} and ends at
-@code{string_limit} (exclusive limit). @code{string_limit} may also be
-@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}
-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.
-@end table
-
-The structure @code{cl_read_flags} contains the following fields:
-
-@table @code
-@item cl_read_syntax_t syntax
-The possible results of the read operation. Possible values are
-@code{syntax_number}, @code{syntax_real}, @code{syntax_rational},
-@code{syntax_integer}, @code{syntax_float}, @code{syntax_sfloat},
-@code{syntax_ffloat}, @code{syntax_dfloat}, @code{syntax_lfloat}.
-
-@item cl_read_lsyntax_t lsyntax
-Specifies the language-dependent syntax variant for the read operation.
-Possible values are
-
-@table @code
-@item lsyntax_standard
-accept standard algebraic notation only, no complex numbers,
-@item lsyntax_algebraic
-accept the algebraic notation @code{@var{x}+@var{y}i} for complex numbers,
-@item lsyntax_commonlisp
-accept the @code{#b}, @code{#o}, @code{#x} syntaxes for binary, octal,
-hexadecimal numbers,
-@code{#@var{base}R} for rational numbers in a given base,
-@code{#c(@var{realpart} @var{imagpart})} for complex numbers,
-@item lsyntax_all
-accept all of these extensions.
-@end table
-
-@item unsigned int rational_base
-The base in which rational numbers are read.
-
-@item cl_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
-The float format used when reading floats with exponent marker @samp{l}.
-
-@item cl_boolean 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
-@section Output functions
-
-Including @code{<cln/io.h>} defines a type @code{cl_ostream}, which is
-the type of the first argument to all output functions. @code{cl_ostream}
-is the same as @code{std::ostream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream stdout}
-@end itemize
-contains the standard output stream.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream stderr}
-@end itemize
-contains the standard error output stream.
-
-These are the simple output functions:
-
-@table @code
-@item void fprintchar (cl_ostream stream, char c)
-Prints the character @code{x} literally on the @code{stream}.
-
-@item void fprint (cl_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)
-Prints the integer @code{x} in decimal on the @code{stream}.
-
-@item void fprintbinary (cl_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)
-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)
-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{<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)
-Prints the number @code{x} on the @code{stream}. The output may depend
-on the global printer settings in the variable @code{default_print_flags}.
-The @code{ostream} flags and settings (flags, width and locale) are
-ignored.
-@end table
-
-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,
- const cl_N& z);
-void print_real (cl_ostream stream, const cl_print_flags& flags,
- const cl_R& z);
-void print_float (cl_ostream stream, const cl_print_flags& flags,
- const cl_F& z);
-void print_rational (cl_ostream stream, const cl_print_flags& flags,
- const cl_RA& z);
-void print_integer (cl_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
-parameters which affect the output.
-
-The structure type @code{cl_print_flags} contains the following fields:
-
-@table @code
-@item unsigned int rational_base
-The base in which rational numbers are printed. Default is @code{10}.
-
-@item cl_boolean 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
-If this flag is true, type specific exponent markers have precedence over 'E'.
-Default is false.
-
-@item cl_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}.
-
-@item cl_boolean 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.
-
-@item cl_string univpoly_varname
-Univariate polynomials with no explicit indeterminate name will be printed
-using this variable name. Default is @code{"x"}.
-@end table
-
-The global variable @code{default_print_flags} contains the default values,
-used by the function @code{fprint}.
-
-
-@node Rings, Modular integers, Input/Output, Top
-@chapter Rings
-
-CLN has a class of abstract rings.
-
-@example
- Ring
- cl_ring
- <cln/ring.h>
-@end example
-
-Rings can be compared for equality:
-
-@table @code
-@item bool operator== (const cl_ring&, const cl_ring&)
-@itemx bool operator!= (const cl_ring&, const cl_ring&)
-These compare two rings for equality.
-@end table
-
-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)
-@cindex @code{fprint ()}
-@itemx cl_boolean R->equal (const cl_ring_element& x, const cl_ring_element& y)
-@cindex @code{equal ()}
-@itemx cl_ring_element R->zero ()
-@cindex @code{zero ()}
-@itemx cl_boolean R->zerop (const cl_ring_element& x)
-@cindex @code{zerop ()}
-@itemx cl_ring_element R->plus (const cl_ring_element& x, const cl_ring_element& y)
-@cindex @code{plus ()}
-@itemx cl_ring_element R->minus (const cl_ring_element& x, const cl_ring_element& y)
-@cindex @code{minus ()}
-@itemx cl_ring_element R->uminus (const cl_ring_element& x)
-@cindex @code{uminus ()}
-@itemx cl_ring_element R->one ()
-@cindex @code{one ()}
-@itemx cl_ring_element R->canonhom (const cl_I& x)
-@cindex @code{canonhom ()}
-@itemx cl_ring_element R->mul (const cl_ring_element& x, const cl_ring_element& y)
-@cindex @code{mul ()}
-@itemx cl_ring_element R->square (const cl_ring_element& x)
-@cindex @code{square ()}
-@itemx cl_ring_element R->expt_pos (const cl_ring_element& x, const cl_I& y)
-@cindex @code{expt_pos ()}
-@end table
-
-The following rings are built-in.
-
-@table @code
-@item cl_null_ring cl_0_ring
-The null ring, containing only zero.
-
-@item cl_complex_ring cl_C_ring
-The ring of complex numbers. This corresponds to the type @code{cl_N}.
-
-@item cl_real_ring cl_R_ring
-The ring of real numbers. This corresponds to the type @code{cl_R}.
-
-@item cl_rational_ring cl_RA_ring
-The ring of rational numbers. This corresponds to the type @code{cl_RA}.
-
-@item cl_integer_ring cl_I_ring
-The ring of integers. This corresponds to the type @code{cl_I}.
-@end table
-
-Type tests can be performed for any of @code{cl_C_ring}, @code{cl_R_ring},
-@code{cl_RA_ring}, @code{cl_I_ring}:
-
-@table @code
-@item cl_boolean instanceof (const cl_number& x, const cl_number_ring& R)
-@cindex @code{instanceof ()}
-Tests whether the given number is an element of the number ring R.
-@end table
-
-
-@node Modular integers, Symbolic data types, Rings, Top
-@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
-@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
-allow you to (accidentally) mix elements of different modular rings,
-e.g. @code{(3 mod 4) + (2 mod 5)} will result in a runtime error.
-(Ideally one would imagine a generic data type @code{cl_MI(N)}, but C++
-doesn't have generic types. So one has to live with runtime checks.)
-
-The class of modular integer rings is
-
-@example
- Ring
- cl_ring
- <cln/ring.h>
- |
- |
- Modular integer ring
- cl_modint_ring
- <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
- <cln/modinteger.h>
-@end example
-
-Modular integer rings are constructed using the function
-
-@table @code
-@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
-to a minimum.
-@end table
-
-Modular integer rings can be compared for equality:
-
-@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{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
-@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(random_state& randomstate)
-@itemx cl_MI R->random()
-@cindex @code{random ()}
-This returns a random integer modulo @code{N}.
-@end table
-
-The following operations are defined on modular integers.
-
-@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&)
-@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&)
-@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&)
-@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)
-@cindex @code{zerop ()}
-Returns true if @code{x} is @code{0 mod N}.
-@end table
-
-The following output functions are defined (see also the chapter on
-input/output).
-
-@table @code
-@item void fprint (cl_ostream stream, const cl_MI& x)
-@cindex @code{fprint ()}
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_MI& x)
-@cindex @code{operator << ()}
-Prints the modular integer @code{x} on the @code{stream}. The output may depend
-on the global printer settings in the variable @code{default_print_flags}.
-@end table
-
-
-@node Symbolic data types, Univariate polynomials, Modular integers, Top
-@chapter Symbolic data types
-@cindex symbolic type
-
-CLN implements two symbolic (non-numeric) data types: strings and symbols.
-
-@menu
-* Strings::
-* Symbols::
-@end menu
-
-@node Strings, Symbols, Symbolic data types, Symbolic data types
-@section Strings
-@cindex string
-@cindex @code{cl_string}
-
-The class
-
-@example
- String
- cl_string
- <cln/string.h>
-@end example
-
-implements immutable strings.
-
-Strings are constructed through the following constructors:
-
-@table @code
-@item cl_string (const char * s)
-Returns an immutable copy of the (zero-terminated) C string @code{s}.
-
-@item cl_string (const char * ptr, unsigned long len)
-Returns an immutable copy of the @code{len} characters at
-@code{ptr[0]}, @dots{}, @code{ptr[len-1]}. NUL characters are allowed.
-@end table
-
-The following functions are available on strings:
-
-@table @code
-@item operator =
-Assignment from @code{cl_string} and @code{const char *}.
-
-@item s.length()
-@cindex @code{length ()}
-@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()}.
-
-@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
-@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
-comparison), whereas comparison of two strings must in the worst case walk
-both strings until their end.
-Symbols are used, for example, as tags for properties, as names of variables
-in polynomial rings, etc.
-
-Symbols are constructed through the following constructor:
-
-@table @code
-@item cl_symbol (const cl_string& s)
-Looks up or creates a new symbol with a given name.
-@end table
-
-The following operations are available on symbols:
-
-@table @code
-@item cl_string (const cl_symbol& sym)
-Conversion to @code{cl_string}: Returns the string which names the symbol
-@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
-@chapter Univariate polynomials
-@cindex polynomial
-@cindex univariate polynomial
-
-@menu
-* Univariate polynomial rings::
-* Functions on univariate polynomials::
-* Special polynomials::
-@end menu
-
-@node Univariate polynomial rings, Functions on univariate polynomials, Univariate polynomials, Univariate polynomials
-@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{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.
-@code{(a^2+1) * (b^3-1)} will result in a runtime error. (Ideally this should
-return a multivariate polynomial, but they are not yet implemented in CLN.)
-
-The classes of univariate polynomial rings are
-
-@example
- Ring
- cl_ring
- <cln/ring.h>
- |
- |
- Univariate polynomial ring
- cl_univpoly_ring
- <cln/univpoly.h>
- |
- +----------------+-------------------+
- | | |
- Complex polynomial ring | Modular integer polynomial ring
- cl_univpoly_complex_ring | cl_univpoly_modint_ring
- <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
- |
- +----------------+
- | |
- Real polynomial ring |
- cl_univpoly_real_ring |
- <cln/univpoly_real.h> |
- |
- +----------------+
- | |
- Rational polynomial ring |
- cl_univpoly_rational_ring |
- <cln/univpoly_rational.h> |
- |
- +----------------+
- |
- Integer polynomial ring
- cl_univpoly_integer_ring
- <cln/univpoly_integer.h>
-@end example
-
-and the corresponding classes of univariate polynomials are
-
-@example
- Univariate polynomial
- cl_UP
- <cln/univpoly.h>
- |
- +----------------+-------------------+
- | | |
- Complex polynomial | Modular integer polynomial
- cl_UP_N | cl_UP_MI
- <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
- |
- +----------------+
- | |
- Real polynomial |
- cl_UP_R |
- <cln/univpoly_real.h> |
- |
- +----------------+
- | |
- Rational polynomial |
- cl_UP_RA |
- <cln/univpoly_rational.h> |
- |
- +----------------+
- |
- Integer polynomial
- cl_UP_I
- <cln/univpoly_integer.h>
-@end example
-
-Univariate polynomial rings are constructed using the functions
-
-@table @code
-@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,
-real numbers, rational numbers, integers, or modular integer rings.
-There is a cache table of rings, indexed by @code{R} and @code{varname}.
-This ensures that two calls of this function with the same arguments will
-return the same polynomial ring.
-
-@itemx cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R)
-@cindex @code{find_univpoly_ring ()}
-@itemx cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R)
-@itemx cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R)
-@itemx cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R)
-@itemx cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)
-@itemx cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R)
-@itemx cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname)
-These functions are equivalent to the general @code{find_univpoly_ring},
-only the return type is more specific, according to the base ring's type.
-@end table
-
-@node Functions on univariate polynomials, Special polynomials, Univariate polynomial rings, 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()
-@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()
-@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}
-member function.
-@end table
-
-The following are the only destructive operations on univariate polynomials.
-
-@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
-produce wrong results or crash the program.
-@end table
-
-The following operations are defined on univariate polynomials.
-
-@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)
-@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 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
-
-The following output functions are defined (see also the chapter on
-input/output).
-
-@table @code
-@item void fprint (cl_ostream stream, const cl_UP& x)
-@cindex @code{fprint ()}
-@itemx cl_ostream operator<< (cl_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{default_print_flags}.
-@end table
-
-@node Special polynomials, , Functions on univariate polynomials, Univariate polynomials
-@section Special polynomials
-
-The following functions return special polynomials.
-
-@table @code
-@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 hermite (sintL n)
-@cindex @code{hermite ()}
-@cindex Hermite polynomial
-Returns the n-th Hermite polynomial (n >= 0).
-
-@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 laguerre (sintL n)
-@cindex @code{laguerre ()}
-@cindex Laguerre polynomial
-Returns the n-th Laguerre polynomial (n >= 0).
-@end table
-
-Information how to derive the differential equation satisfied by each
-of these polynomials from their definition can be found in the
-@code{doc/polynomial/} directory.
-
-
-@node Internals, Using the library, Univariate polynomials, Top
-@chapter Internals
-
-@menu
-* Why C++ ?::
-* Memory efficiency::
-* Speed efficiency::
-* Garbage collection::
-@end menu
-
-@node Why C++ ?, Memory efficiency, Internals, Internals
-@section Why C++ ?
-@cindex advocacy
-
-Using C++ as an implementation language provides
-
-@itemize @bullet
-@item
-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.
-
-@item
-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{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.
-
-@item
-Algebraic syntax: The elementary operations @code{+}, @code{-}, @code{*},
-@code{=}, @code{==}, ... can be used in infix notation, which is more
-convenient than Lisp notation @samp{(+ x y)} or C notation @samp{add(x,y,&z)}.
-@end itemize
-
-With these language features, there is no need for two separate languages,
-one for the implementation of the library and one in which the library's users
-can program. This means that a prototype implementation of an algorithm
-can be integrated into the library immediately after it has been tested and
-debugged. No need to rewrite it in a low-level language after having prototyped
-in a high-level language.
-
-
-@node Memory efficiency, Speed efficiency, Why C++ ?, Internals
-@section Memory efficiency
-
-In order to save memory allocations, CLN implements:
-
-@itemize @bullet
-@item
-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
-Small integers are represented as immediate values instead of pointers
-to heap allocated storage. This means that integers @code{> -2^29},
-@code{< 2^29} don't consume heap memory, unless they were explicitly allocated
-on the heap.
-@end itemize
-
-
-@node Speed efficiency, Garbage collection, Memory efficiency, Internals
-@section Speed efficiency
-
-Speed efficiency is obtained by the combination of the following tricks
-and algorithms:
-
-@itemize @bullet
-@item
-Small integers, being represented as immediate values, don't require
-memory access, just a couple of instructions for each elementary operation.
-@item
-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 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
-@iftex
-@tex
-$O(N^{1.6})$
-@end tex
-@end iftex
-@ifinfo
-@code{O(N^1.6)}
-@end ifinfo
-algorithm.
-@item
-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
-@cindex Schönhage-Strassen multiplication
-@end ifinfo
-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
-@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
-number objects, only the objects' reference count are manipulated.
-
-Memory occupied by number objects are automatically reclaimed as soon as
-their reference count drops to zero.
-
-For number rings, another strategy is implemented: There is a cache of,
-for example, the modular integer rings. A modular integer ring is destroyed
-only if its reference count dropped to zero and the cache is about to be
-resized. The effect of this strategy is that recently used rings remain
-cached, whereas undue memory consumption through cached rings is avoided.
-
-
-@node Using the library, Customizing, Internals, Top
-@chapter Using the library
-
-For the following discussion, we will assume that you have installed
-the CLN source in @code{$CLN_DIR} and built it in @code{$CLN_TARGETDIR}.
-For example, for me it's @code{CLN_DIR="$HOME/cln"} and
-@code{CLN_TARGETDIR="$HOME/cln/linuxelf"}. You might define these as
-environment variables, or directly substitute the appropriate values.
-
-
-@menu
-* Compiler options::
-* Compatibility to old CLN versions::
-* Include files::
-* An Example::
-* Debugging support::
-@end menu
-
-@node Compiler options, Compatibility to old CLN versions, Using the library, Using the library
-@section Compiler options
-@cindex compiler options
-
-Until you have installed CLN in a public place, the following options are
-needed:
-
-When you compile CLN application code, add the flags
-@example
- -I$CLN_DIR/include -I$CLN_TARGETDIR/include
-@end example
-to the C++ compiler's command line (@code{make} variable CFLAGS or CXXFLAGS).
-When you link CLN application code to form an executable, add the flags
-@example
- $CLN_TARGETDIR/src/libcln.a
-@end example
-to the C/C++ compiler's command line (@code{make} variable LIBS).
-
-If you did a @code{make install}, the include files are installed in a
-public directory (normally @code{/usr/local/include}), hence you don't
-need special flags for compiling. The library has been installed to a
-public directory as well (normally @code{/usr/local/lib}), hence when
-linking a CLN application it is sufficient to give the flag @code{-lcln}.
-
-
-@node Compatibility to old CLN versions, Include files, Compiler options, Using the library
-@section Compatibility to old CLN versions
-@cindex namespace
-@cindex compatibility
-
-As of CLN version 1.1 all non-macro identifiers were hidden in namespace
-@code{cln} in order to avoid potential name clashes with other C++
-libraries. If you have an old application, you will have to manually
-port it to the new scheme. The following principles will help during
-the transition:
-@itemize @bullet
-@item
-All headers are now in a separate subdirectory. Instead of including
-@code{cl_}@var{something}@code{.h}, include
-@code{cln/}@var{something}@code{.h} now.
-@item
-All public identifiers (typenames and functions) have lost their
-@code{cl_} prefix. Exceptions are all the typenames of number types,
-(cl_N, cl_I, cl_MI, @dots{}), rings, symbolic types (cl_string,
-cl_symbol) and polynomials (cl_UP_@var{type}). (This is because their
-names would not be mnemonic enough once the namespace @code{cln} is
-imported. Even in a namespace we favor @code{cl_N} over @code{N}.)
-@item
-All public @emph{functions} that had by a @code{cl_} in their name still
-carry that @code{cl_} if it is intrinsic part of a typename (as in
-@code{cl_I_to_int ()}).
-@end itemize
-When developing other libraries, please keep in mind not to import the
-namespace @code{cln} in one of your public header files by saying
-@code{using namespace cln;}. This would propagate to other applications
-and can cause name clashes there.
-
-
-@node Include files, An Example, Compatibility to old CLN versions, Using the library
-@section Include files
-@cindex include files
-@cindex header files
-
-Here is a summary of the include files and their contents.
-
-@table @code
-@item <cln/object.h>
-General definitions, reference counting, garbage collection.
-@item <cln/number.h>
-The class cl_number.
-@item <cln/complex.h>
-Functions for class cl_N, the complex numbers.
-@item <cln/real.h>
-Functions for class cl_R, the real numbers.
-@item <cln/float.h>
-Functions for class cl_F, the floats.
-@item <cln/sfloat.h>
-Functions for class cl_SF, the short-floats.
-@item <cln/ffloat.h>
-Functions for class cl_FF, the single-floats.
-@item <cln/dfloat.h>
-Functions for class cl_DF, the double-floats.
-@item <cln/lfloat.h>
-Functions for class cl_LF, the long-floats.
-@item <cln/rational.h>
-Functions for class cl_RA, the rational numbers.
-@item <cln/integer.h>
-Functions for class cl_I, the integers.
-@item <cln/io.h>
-Input/Output.
-@item <cln/complex_io.h>
-Input/Output for class cl_N, the complex numbers.
-@item <cln/real_io.h>
-Input/Output for class cl_R, the real numbers.
-@item <cln/float_io.h>
-Input/Output for class cl_F, the floats.
-@item <cln/sfloat_io.h>
-Input/Output for class cl_SF, the short-floats.
-@item <cln/ffloat_io.h>
-Input/Output for class cl_FF, the single-floats.
-@item <cln/dfloat_io.h>
-Input/Output for class cl_DF, the double-floats.
-@item <cln/lfloat_io.h>
-Input/Output for class cl_LF, the long-floats.
-@item <cln/rational_io.h>
-Input/Output for class cl_RA, the rational numbers.
-@item <cln/integer_io.h>
-Input/Output for class cl_I, the integers.
-@item <cln/input.h>
-Flags for customizing input operations.
-@item <cln/output.h>
-Flags for customizing output operations.
-@item <cln/malloc.h>
-@code{malloc_hook}, @code{free_hook}.
-@item <cln/abort.h>
-@code{cl_abort}.
-@item <cln/condition.h>
-Conditions/exceptions.
-@item <cln/string.h>
-Strings.
-@item <cln/symbol.h>
-Symbols.
-@item <cln/proplist.h>
-Property lists.
-@item <cln/ring.h>
-General rings.
-@item <cln/null_ring.h>
-The null ring.
-@item <cln/complex_ring.h>
-The ring of complex numbers.
-@item <cln/real_ring.h>
-The ring of real numbers.
-@item <cln/rational_ring.h>
-The ring of rational numbers.
-@item <cln/integer_ring.h>
-The ring of integers.
-@item <cln/numtheory.h>
-Number threory functions.
-@item <cln/modinteger.h>
-Modular integers.
-@item <cln/V.h>
-Vectors.
-@item <cln/GV.h>
-General vectors.
-@item <cln/GV_number.h>
-General vectors over cl_number.
-@item <cln/GV_complex.h>
-General vectors over cl_N.
-@item <cln/GV_real.h>
-General vectors over cl_R.
-@item <cln/GV_rational.h>
-General vectors over cl_RA.
-@item <cln/GV_integer.h>
-General vectors over cl_I.
-@item <cln/GV_modinteger.h>
-General vectors of modular integers.
-@item <cln/SV.h>
-Simple vectors.
-@item <cln/SV_number.h>
-Simple vectors over cl_number.
-@item <cln/SV_complex.h>
-Simple vectors over cl_N.
-@item <cln/SV_real.h>
-Simple vectors over cl_R.
-@item <cln/SV_rational.h>
-Simple vectors over cl_RA.
-@item <cln/SV_integer.h>
-Simple vectors over cl_I.
-@item <cln/SV_ringelt.h>
-Simple vectors of general ring elements.
-@item <cln/univpoly.h>
-Univariate polynomials.
-@item <cln/univpoly_integer.h>
-Univariate polynomials over the integers.
-@item <cln/univpoly_rational.h>
-Univariate polynomials over the rational numbers.
-@item <cln/univpoly_real.h>
-Univariate polynomials over the real numbers.
-@item <cln/univpoly_complex.h>
-Univariate polynomials over the complex numbers.
-@item <cln/univpoly_modint.h>
-Univariate polynomials over modular integer rings.
-@item <cln/timing.h>
-Timing facilities.
-@item <cln/cln.h>
-Includes all of the above.
-@end table
-
-
-@node An Example, Debugging support, Include files, Using the library
-@section An Example
-
-A function which computes the nth Fibonacci number can be written as follows.
-@cindex Fibonacci number
-
-@example
-#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));
- cl_R sqrt5 = sqrt(cl_float(5,prec));
- cl_R phi = (1+sqrt5)/2;
- return round1( expt(phi,n)/sqrt5 );
-@}
-@end example
-
-Let's explain what is going on in detail.
-
-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. In order not to write out
-@code{cln::}@var{foo} 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
-simply @samp{cl_I}, because that allows the compiler to detect typos like
-@samp{fibonacci(n) = 100}. It would be possible to declare the return
-type as @code{const cl_R} (real number) or even @code{const cl_N} (complex
-number). We use the most specialized possible return type because functions
-which call @samp{fibonacci} will be able to profit from the compiler's type
-analysis: Adding two integers is slightly more efficient than adding the
-same objects declared as complex numbers, because it needs less type
-dispatch. Also, when linking to CLN as a non-shared library, this minimizes
-the size of the resulting executable program.
-
-The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
-integer. In order to get a correct result, the absolute error should be less
-than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
-To this end, the first line computes a floating point precision for sqrt(5)
-and phi.
-
-Then sqrt(5) is computed by first converting the integer 5 to a floating point
-number and than taking the square root. The converse, first taking the square
-root of 5, and then converting to the desired precision, would not work in
-CLN: The square root would be computed to a default precision (normally
-single-float precision), and the following conversion could not help about
-the lacking accuracy. This is because CLN is not a symbolic computer algebra
-system and does not represent sqrt(5) in a non-numeric way.
-
-The type @code{cl_R} for sqrt5 and, in the following line, phi is the only
-possible choice. You cannot write @code{cl_F} because the C++ compiler can
-only infer that @code{cl_float(5,prec)} is a real number. You cannot write
-@code{cl_N} because a @samp{round1} does not exist for general complex
-numbers.
-
-When the function returns, all the local variables in the function are
-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
-@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:
-@example
-(gdb) break cl_abort
-@end example
-When this breakpoint is hit, look at the stack's backtrace:
-@example
-(gdb) where
-@end example
-
-@item The debugger's normal @code{print} command doesn't know about
-CLN's types and therefore prints mostly useless hexadecimal addresses.
-CLN offers a function @code{cl_print}, callable from the debugger,
-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 <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:
-@example
-(gdb) print s
-$7 = @{<cl_gcpointer> = @{ = @{pointer = 0x8055b60, heappointer = 0x8055b60,
- word = 134568800@}@}, @}
-(gdb) call cl_print(s)
-(cl_string) ""
-$8 = 134568800
-@end example
-Note that the output of @code{cl_print} goes to the program's error output,
-not to gdb's standard output.
-
-Note, however, that the above facility does not work with all CLN types,
-only with number objects and similar. Therefore CLN offers a member function
-@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,
- word = 134568800@}@}, @}
-(gdb) call s.debug_print()
-(cl_string) ""
-(gdb) define cprint
->call ($1).debug_print()
->end
-(gdb) cprint s
-(cl_string) ""
-@end example
-Unfortunately, this feature does not seem to work under all circumstances.
-@end itemize
-
-
-@node Customizing, Index, Using the library, Top
-@chapter Customizing
-@cindex customizing
-
-@menu
-* Error handling::
-* Floating-point underflow::
-* Customizing I/O::
-* Customizing the memory allocator::
-@end menu
-
-@node Error handling, Floating-point underflow, Customizing, Customizing
-@section 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
-@example
-#include <cln/abort.h>
-void cl_abort (void);
-@end example
-@cindex @code{cl_abort ()}
-This function must not return control to its caller.
-
-
-@node Floating-point underflow, Customizing I/O, Error handling, Customizing
-@section Floating-point underflow
-@cindex underflow
-
-Floating point underflow denotes the situation when a floating-point number
-is to be created which is so close to @code{0} that its exponent is too
-low to be represented internally. By default, this causes a fatal error.
-If you set the global variable
-@example
-cl_boolean 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}.
-
-
-@node Customizing I/O, Customizing the memory allocator, Floating-point underflow, Customizing
-@section Customizing I/O
-
-The output of the function @code{fprint} may be customized by changing the
-value of the global variable @code{default_print_flags}.
-@cindex @code{default_print_flags}
-
-
-@node Customizing the memory allocator, , Customizing I/O, Customizing
-@section Customizing the memory allocator
-
-Every memory allocation of CLN is done through the function pointer
-@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{malloc_hook} and @code{free_hook} yourself,
-like this:
-@example
-#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
-it is already called at program startup by the constructors of some
-global variables.
-
-
-
-
-@c Indices
-
-@node Index, , Customizing, Top
-@unnumbered Index
-
-@printindex my
-
-
-@c Table of contents
-@contents
-
-
-@bye
// Basic definitions of numbers
+
#ifndef _CL_NUMBER_H
#define _CL_NUMBER_H
+
#include "cln/object.h"
#include "cln/malloc.h"
-namespace cln {
-
// Type hierachy:
// Number (N) =
// Real (R) =
#endif
-// Conversions to subtypes:
-// As(cl_I)(x) returns x as a cl_I. It first checks that x is a cl_I
-// and then returns it without change of representation.
-#if 0 // no debug information
- #define As(type) as_##type
- #define CL_DEFINE_AS_CONVERSION(_class_) \
- extern const _class_& as_##_class_ (const cl_number& x); \
- inline const _class_& as_##_class_ (const _class_& x) { return x; }
-#else // Line number information for ease of debugging.
- #define As(type) as_##type cl_as_aux
- #define cl_as_aux(expr) (expr,__FILE__,__LINE__)
- #define CL_DEFINE_AS_CONVERSION(_class_) \
- extern const _class_& as_##_class_ (const cl_number& x, const char * filename, int line); \
- inline const _class_& as_##_class_ (const _class_& x, const char * filename, int line) { (void)filename; (void)line; return x; }
-#endif
-
+namespace cln {
// Constructors and assignment operators from C numeric types.
// from `float':
+union ffloatjanus;
extern cl_private_thing cl_float_to_FF_pointer (const union ffloatjanus& val);
#define CL_DEFINE_FLOAT_CONSTRUCTOR(_class_) \
}
// from `double':
+union dfloatjanus;
extern struct cl_heap_dfloat * cl_double_to_DF_pointer (const union dfloatjanus& val);
#define CL_DEFINE_DOUBLE_CONSTRUCTOR(_class_) \
// cl_number (const char *);
// Private pointer manipulations.
cl_number (cl_private_thing);
- cl_private_thing _as_cl_private_thing () const;
};
// Private constructors.
// Hack section.
-// Conversions to subtypes without checking:
-// the<cl_I>(x) converts x to a cl_I, without change of representation!
+// Conversions to subtypes without checking, template version:
+// the<cl_I>(x) converts x to a cl_I, without change of representation.
template<class type>
inline const type& the(const cl_number& x)
{
typedef int assertion1 [1 - 2 * (sizeof(type) != sizeof(cl_number))];
return *(const type *) &x;
}
-
-// Conversions to subtypes without checking:
-// The(cl_I)(x) converts x to a cl_I, without change of representation!
+// Conversions to subtypes without checking, macro version:
+// The(cl_I)(x) converts x to a cl_I, without change of representation.
#define The(type) *(const type *) & cl_identity
// This inline function is for type checking purposes only.
inline const cl_number& cl_identity (const cl_number& x) { return x; }
+} // namespace cln
+
+
+// Conversions to subtypes:
+// As(cl_I)(x) returns x as a cl_I. It first checks that x is a cl_I
+// and then returns it without change of representation.
+#if 0 // no debug information
+ #define As(type) as_##type
+ #define CL_DEFINE_AS_CONVERSION(_class_) \
+ extern const _class_& as_##_class_ (const cl_number& x); \
+ inline const _class_& as_##_class_ (const _class_& x) { return x; }
+#else // Line number information for ease of debugging.
+ #define As(type) as_##type cl_as_aux
+ #define cl_as_aux(expr) (expr,__FILE__,__LINE__)
+ #define CL_DEFINE_AS_CONVERSION(_class_) \
+ extern const _class_& as_##_class_ (const cl_number& x, const char * filename, int line); \
+ inline const _class_& as_##_class_ (const _class_& x, const char * filename, int line) { (void)filename; (void)line; return x; }
+#endif
+
// Mutable(type,x);
// x should be a variable `const type x' or `const type& x'.
// This macro introduces a new variable `type& x' whose value can be
const type& __tmp_##x = *(const type*) &x; \
const type& x = __tmp_##x;
-} // namespace cln
-
#endif /* _CL_NUMBER_H */
projects / cln.git / commitdiff