From f6b8e7b68cb9d636d2658b56847bff69dc89936a Mon Sep 17 00:00:00 2001 From: Richard Kreckel Date: Wed, 30 Aug 2000 22:12:05 +0000 Subject: [PATCH] * 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. * Changelog: *trival* documentation changes have nix verloren. * doc/cln.info, doc/cln.texi: Removed non-sources from CVS. --- ChangeLog | 21 +- doc/cln.info | 3767 -------------------------------------- doc/cln.texi | 4076 ------------------------------------------ include/cln/number.h | 54 +- 4 files changed, 38 insertions(+), 7880 deletions(-) delete mode 100644 doc/cln.info delete mode 100644 doc/cln.texi diff --git a/ChangeLog b/ChangeLog index b1b6e31..b5501b8 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,8 +1,18 @@ +2000-08-30 Richard Kreckel + + * 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 * include/cln/number.h, the(const cl_number& x): New template function. +2000-08-29 Richard Kreckel + + * TODO: DESCRIBE NAMESPACE CHANGES HERE!!! + 2000-08-26 Bruno Haible * autoconf/acgeneral.m4 (AC_OUTPUT): Use braces in exec_prefix default @@ -31,11 +41,6 @@ * src/float/sfloat/cl_SF.h: Use cl_pointer_size instead of cl_word_size. -2000-06-05 Richard Kreckel - - * doc/*, INSTALL: Mention that both shared and static library are - are now build by default. - 2000-05-31 Bruno Haible * tests/exam_I_floor.cc (integer_floor_tests): Add one more entry. @@ -93,12 +98,6 @@ * INSTALL.generic: Clarified behaviour of --with-gmp. * autoconf/config.guess: updated from Clisp-2000-03-06 sources. -2000-05-05 Richard Kreckel - - * 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 * gmp/: removed completely. From now on we are going to link diff --git a/doc/cln.info b/doc/cln.info deleted file mode 100644 index f9fa2ba..0000000 --- a/doc/cln.info +++ /dev/null @@ -1,3767 +0,0 @@ -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, `' and Richard -Kreckel, `'. - -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. - - -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:: - - -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. - - -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:: - - -File: cln.info, Node: Prerequisites, Next: Building the library, Prev: Installation, Up: Installation - -Prerequisites -============= - -* Menu: - -* C++ compiler:: -* Make utility:: -* Sed utility:: - - -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. - - -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. - - -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. - - -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:: - - -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 - - -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. - - -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 - - -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 - - | - | - Real or complex number - cl_N - - | - | - Real number - cl_R - - | - +-------------------+-------------------+ - | | - Rational number Floating-point number - cl_RA cl_F - - | | - | +--------------+--------------+--------------+ - Integer | | | | - cl_I Short-Float Single-Float Double-Float Long-Float - cl_SF cl_FF cl_DF cl_LF - - -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:: - - -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. - - -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.) - - -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. - - -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. - - -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 '. - -* 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:: - - -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:: - - -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::. - - -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. - - -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)); - - -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::. - - -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. - - -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. - - -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))' - - -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'. - - -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)' - -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. - - -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:: - - -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'. - - -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'. - - -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'. - - -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'. - - -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'. - - -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:: - - -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'.) - - -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. - - -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. - - -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'. - - -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:: - - -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'. - - -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' - - -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 `' 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. - - -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. - - -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:: - - -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)'. - - -File: cln.info, Node: Input functions, Next: Output functions, Prev: Internal and printed representation, Up: Input/Output - -Input functions -=============== - -Including `' 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 `', 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 `', 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. - - -File: cln.info, Node: Output functions, Prev: Input functions, Up: Input/Output - -Output functions -================ - -Including `' 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 `', 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 `', 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'. - - -File: cln.info, Node: Rings, Next: Modular integers, Prev: Input/Output, Up: Top - -Rings -***** - -CLN has a class of abstract rings. - - Ring - cl_ring - - -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. - - -File: cln.info, Node: Modular integers, Next: Symbolic data types, Prev: Rings, Up: Top - -Modular integers -**************** - -* Menu: - -* Modular integer rings:: -* Functions on modular integers:: - - -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 - - | - | - Modular integer ring - cl_modint_ring - - -and the class of all modular integers (elements of modular integer -rings) is - - Modular integer - cl_MI - - -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. - - -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', `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'. - - -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:: - - -File: cln.info, Node: Strings, Next: Symbols, Prev: Symbolic data types, Up: Symbolic data types - -Strings -======= - -The class - - String - cl_string - - -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 *'. - - -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. - - -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:: - - -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 - - | - | - Univariate polynomial ring - cl_univpoly_ring - - | - +----------------+-------------------+ - | | | - Complex polynomial ring | Modular integer polynomial ring - cl_univpoly_complex_ring | cl_univpoly_modint_ring - | - | - +----------------+ - | | - Real polynomial ring | - cl_univpoly_real_ring | - | - | - +----------------+ - | | - Rational polynomial ring | - cl_univpoly_rational_ring | - | - | - +----------------+ - | - Integer polynomial ring - cl_univpoly_integer_ring - - -and the corresponding classes of univariate polynomials are - - Univariate polynomial - cl_UP - - | - +----------------+-------------------+ - | | | - Complex polynomial | Modular integer polynomial - cl_UP_N | cl_UP_MI - | - | - +----------------+ - | | - Real polynomial | - cl_UP_R | - | - | - +----------------+ - | | - Rational polynomial | - cl_UP_RA | - | - | - +----------------+ - | - Integer polynomial - cl_UP_I - - -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. - - -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'. - - -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. - - -File: cln.info, Node: Internals, Next: Using the library, Prev: Univariate polynomials, Up: Top - -Internals -********* - -* Menu: - -* Why C++ ?:: -* Memory efficiency:: -* Speed efficiency:: -* Garbage collection:: - - -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. - - -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. - - -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. - - -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. - - -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:: - - -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'. - - -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. - - -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. - -`' - General definitions, reference counting, garbage collection. - -`' - The class cl_number. - -`' - Functions for class cl_N, the complex numbers. - -`' - Functions for class cl_R, the real numbers. - -`' - Functions for class cl_F, the floats. - -`' - Functions for class cl_SF, the short-floats. - -`' - Functions for class cl_FF, the single-floats. - -`' - Functions for class cl_DF, the double-floats. - -`' - Functions for class cl_LF, the long-floats. - -`' - Functions for class cl_RA, the rational numbers. - -`' - Functions for class cl_I, the integers. - -`' - Input/Output. - -`' - Input/Output for class cl_N, the complex numbers. - -`' - Input/Output for class cl_R, the real numbers. - -`' - Input/Output for class cl_F, the floats. - -`' - Input/Output for class cl_SF, the short-floats. - -`' - Input/Output for class cl_FF, the single-floats. - -`' - Input/Output for class cl_DF, the double-floats. - -`' - Input/Output for class cl_LF, the long-floats. - -`' - Input/Output for class cl_RA, the rational numbers. - -`' - Input/Output for class cl_I, the integers. - -`' - Flags for customizing input operations. - -`' - Flags for customizing output operations. - -`' - `malloc_hook', `free_hook'. - -`' - `cl_abort'. - -`' - Conditions/exceptions. - -`' - Strings. - -`' - Symbols. - -`' - Property lists. - -`' - General rings. - -`' - The null ring. - -`' - The ring of complex numbers. - -`' - The ring of real numbers. - -`' - The ring of rational numbers. - -`' - The ring of integers. - -`' - Number threory functions. - -`' - Modular integers. - -`' - Vectors. - -`' - General vectors. - -`' - General vectors over cl_number. - -`' - General vectors over cl_N. - -`' - General vectors over cl_R. - -`' - General vectors over cl_RA. - -`' - General vectors over cl_I. - -`' - General vectors of modular integers. - -`' - Simple vectors. - -`' - Simple vectors over cl_number. - -`' - Simple vectors over cl_N. - -`' - Simple vectors over cl_R. - -`' - Simple vectors over cl_RA. - -`' - Simple vectors over cl_I. - -`' - Simple vectors of general ring elements. - -`' - Univariate polynomials. - -`' - Univariate polynomials over the integers. - -`' - Univariate polynomials over the rational numbers. - -`' - Univariate polynomials over the real numbers. - -`' - Univariate polynomials over the complex numbers. - -`' - Univariate polynomials over modular integer rings. - -`' - Timing facilities. - -`' - Includes all of the above. - - -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 - #include - 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 `' is necessary because the type `cl_I' -is used in the function, and the include file `' 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. - - -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 - 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 = { = { = {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 = { = { = {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. - - -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:: - - -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 - void cl_abort (void); -This function must not return control to its caller. - - -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'. - - -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'. - - -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 - 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. - - -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. - - - -Tag Table: -Node: Top931 -Node: Introduction3191 -Node: Installation5812 -Node: Prerequisites6106 -Node: C++ compiler6304 -Node: Make utility7016 -Node: Sed utility7202 -Node: Building the library7522 -Node: Using the GNU MP Library10745 -Node: Installing the library11621 -Node: Cleaning up12344 -Node: Ordinary number types12669 -Node: Exact numbers15022 -Node: Floating-point numbers16187 -Node: Complex numbers19766 -Node: Conversions20263 -Node: Functions on numbers23723 -Node: Constructing numbers24427 -Node: Constructing integers24799 -Node: Constructing rational numbers25089 -Node: Constructing floating-point numbers25564 -Node: Constructing complex numbers26684 -Node: Elementary functions27048 -Node: Elementary rational functions29517 -Node: Elementary complex functions30089 -Node: Comparisons30917 -Node: Rounding functions32810 -Node: Roots38587 -Node: Transcendental functions40468 -Node: Exponential and logarithmic functions41024 -Node: Trigonometric functions43029 -Node: Hyperbolic functions46359 -Node: Euler gamma48423 -Node: Riemann zeta49315 -Node: Functions on integers49859 -Node: Logical functions50147 -Node: Number theoretic functions56100 -Node: Combinatorial functions57467 -Node: Functions on floating-point numbers58145 -Node: Conversion functions61355 -Node: Conversion to floating-point numbers61635 -Node: Conversion to rational numbers63852 -Node: Random number generators64906 -Node: Obfuscating operators66557 -Node: Input/Output68287 -Node: Internal and printed representation68497 -Node: Input functions71039 -Node: Output functions75524 -Node: Rings79184 -Node: Modular integers81108 -Node: Modular integer rings81308 -Node: Functions on modular integers83393 -Node: Symbolic data types86397 -Node: Strings86660 -Node: Symbols87725 -Node: Univariate polynomials88627 -Node: Univariate polynomial rings88885 -Node: Functions on univariate polynomials93801 -Node: Special polynomials97576 -Node: Internals98283 -Node: Why C++ ?98497 -Node: Memory efficiency99997 -Node: Speed efficiency100695 -Node: Garbage collection101779 -Node: Using the library102606 -Node: Compiler options103178 -Node: Compatibility to old CLN versions104116 -Node: Include files105537 -Node: An Example109252 -Node: Debugging support112518 -Node: Customizing114869 -Node: Error handling115097 -Node: Floating-point underflow115672 -Node: Customizing I/O116311 -Node: Customizing the memory allocator116601 -Node: Index117585 - -End Tag Table diff --git a/doc/cln.texi b/doc/cln.texi deleted file mode 100644 index 8582c21..0000000 --- a/doc/cln.texi +++ /dev/null @@ -1,4076 +0,0 @@ -\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{} and -Richard Kreckel, @code{}. - -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{} and -Richard Kreckel, @code{}. - -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 - - | - | - Real or complex number - cl_N - - | - | - Real number - cl_R - - | - +-------------------+-------------------+ - | | -Rational number Floating-point number - cl_RA cl_F - - | | - | +--------------+--------------+--------------+ - Integer | | | | - cl_I Short-Float Single-Float Double-Float Long-Float - cl_SF cl_FF cl_DF cl_LF - -@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 }. - - -@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{} 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{} 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{}, 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{}, -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{} 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{}, 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{}, -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 - -@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 - - | - | - Modular integer ring - cl_modint_ring - -@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 - -@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{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 - -@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 - - | - | - Univariate polynomial ring - cl_univpoly_ring - - | - +----------------+-------------------+ - | | | - Complex polynomial ring | Modular integer polynomial ring - cl_univpoly_complex_ring | cl_univpoly_modint_ring - | - | - +----------------+ - | | - Real polynomial ring | - cl_univpoly_real_ring | - | - | - +----------------+ - | | - Rational polynomial ring | - cl_univpoly_rational_ring | - | - | - +----------------+ - | - Integer polynomial ring - cl_univpoly_integer_ring - -@end example - -and the corresponding classes of univariate polynomials are - -@example - Univariate polynomial - cl_UP - - | - +----------------+-------------------+ - | | | - Complex polynomial | Modular integer polynomial - cl_UP_N | cl_UP_MI - | - | - +----------------+ - | | - Real polynomial | - cl_UP_R | - | - | - +----------------+ - | | - Rational polynomial | - cl_UP_RA | - | - | - +----------------+ - | - Integer polynomial - cl_UP_I - -@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 -General definitions, reference counting, garbage collection. -@item -The class cl_number. -@item -Functions for class cl_N, the complex numbers. -@item -Functions for class cl_R, the real numbers. -@item -Functions for class cl_F, the floats. -@item -Functions for class cl_SF, the short-floats. -@item -Functions for class cl_FF, the single-floats. -@item -Functions for class cl_DF, the double-floats. -@item -Functions for class cl_LF, the long-floats. -@item -Functions for class cl_RA, the rational numbers. -@item -Functions for class cl_I, the integers. -@item -Input/Output. -@item -Input/Output for class cl_N, the complex numbers. -@item -Input/Output for class cl_R, the real numbers. -@item -Input/Output for class cl_F, the floats. -@item -Input/Output for class cl_SF, the short-floats. -@item -Input/Output for class cl_FF, the single-floats. -@item -Input/Output for class cl_DF, the double-floats. -@item -Input/Output for class cl_LF, the long-floats. -@item -Input/Output for class cl_RA, the rational numbers. -@item -Input/Output for class cl_I, the integers. -@item -Flags for customizing input operations. -@item -Flags for customizing output operations. -@item -@code{malloc_hook}, @code{free_hook}. -@item -@code{cl_abort}. -@item -Conditions/exceptions. -@item -Strings. -@item -Symbols. -@item -Property lists. -@item -General rings. -@item -The null ring. -@item -The ring of complex numbers. -@item -The ring of real numbers. -@item -The ring of rational numbers. -@item -The ring of integers. -@item -Number threory functions. -@item -Modular integers. -@item -Vectors. -@item -General vectors. -@item -General vectors over cl_number. -@item -General vectors over cl_N. -@item -General vectors over cl_R. -@item -General vectors over cl_RA. -@item -General vectors over cl_I. -@item -General vectors of modular integers. -@item -Simple vectors. -@item -Simple vectors over cl_number. -@item -Simple vectors over cl_N. -@item -Simple vectors over cl_R. -@item -Simple vectors over cl_RA. -@item -Simple vectors over cl_I. -@item -Simple vectors of general ring elements. -@item -Univariate polynomials. -@item -Univariate polynomials over the integers. -@item -Univariate polynomials over the rational numbers. -@item -Univariate polynomials over the real numbers. -@item -Univariate polynomials over the complex numbers. -@item -Univariate polynomials over modular integer rings. -@item -Timing facilities. -@item -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 -#include -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{} is necessary because the type -@code{cl_I} is used in the function, and the include file @code{} -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 -@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 = @{ = @{ = @{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 = @{ = @{ = @{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 -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 -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 diff --git a/include/cln/number.h b/include/cln/number.h index 3c1da17..2467d38 100644 --- a/include/cln/number.h +++ b/include/cln/number.h @@ -1,13 +1,13 @@ // 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) = @@ -110,26 +110,12 @@ inline _class_& _class_::operator= (const unsigned long wert) \ #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_) \ @@ -145,6 +131,7 @@ inline _class_& _class_::operator= (const float x) \ } // from `double': +union dfloatjanus; extern struct cl_heap_dfloat * cl_double_to_DF_pointer (const union dfloatjanus& val); #define CL_DEFINE_DOUBLE_CONSTRUCTOR(_class_) \ @@ -189,7 +176,6 @@ public: // cl_number (const char *); // Private pointer manipulations. cl_number (cl_private_thing); - cl_private_thing _as_cl_private_thing () const; }; // Private constructors. @@ -217,8 +203,8 @@ CL_DEFINE_DOUBLE_CONSTRUCTOR(cl_number) // Hack section. -// Conversions to subtypes without checking: -// the(x) converts x to a cl_I, without change of representation! +// Conversions to subtypes without checking, template version: +// the(x) converts x to a cl_I, without change of representation. template inline const type& the(const cl_number& x) { @@ -226,13 +212,31 @@ 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 @@ -252,6 +256,4 @@ inline const type& the(const cl_number& x) const type& __tmp_##x = *(const type*) &x; \ const type& x = __tmp_##x; -} // namespace cln - #endif /* _CL_NUMBER_H */