1 This is cln.info, produced by makeinfo version 4.0 from cln.texi.
3 This file documents CLN, a Class Library for Numbers.
5 Published by Bruno Haible, `<haible@clisp.cons.org>' and Richard
6 Kreckel, `<kreckel@ginac.de>'.
8 Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000.
10 Permission is granted to make and distribute verbatim copies of this
11 manual provided the copyright notice and this permission notice are
12 preserved on all copies.
14 Permission is granted to copy and distribute modified versions of this
15 manual under the conditions for verbatim copying, provided that the
16 entire resulting derived work is distributed under the terms of a
17 permission notice identical to this one.
19 Permission is granted to copy and distribute translations of this manual
20 into another language, under the above conditions for modified versions,
21 except that this permission notice may be stated in a translation
22 approved by the author.
25 File: cln.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)
31 * Ordinary number types::
32 * Functions on numbers::
36 * Symbolic data types::
37 * Univariate polynomials::
44 --- The Detailed Node Listing ---
49 * Building the library::
50 * Installing the library::
61 * Using the GNU MP Library::
66 * Floating-point numbers::
72 * Constructing numbers::
73 * Elementary functions::
74 * Elementary rational functions::
75 * Elementary complex functions::
77 * Rounding functions::
79 * Transcendental functions::
80 * Functions on integers::
81 * Functions on floating-point numbers::
82 * Conversion functions::
83 * Random number generators::
84 * Obfuscating operators::
88 * Constructing integers::
89 * Constructing rational numbers::
90 * Constructing floating-point numbers::
91 * Constructing complex numbers::
93 Transcendental functions
95 * Exponential and logarithmic functions::
96 * Trigonometric functions::
97 * Hyperbolic functions::
101 Functions on integers
103 * Logical functions::
104 * Number theoretic functions::
105 * Combinatorial functions::
109 * Conversion to floating-point numbers::
110 * Conversion to rational numbers::
114 * Internal and printed representation::
120 * Modular integer rings::
121 * Functions on modular integers::
128 Univariate polynomials
130 * Univariate polynomial rings::
131 * Functions on univariate polynomials::
132 * Special polynomials::
137 * Memory efficiency::
139 * Garbage collection::
144 * Compatibility to old CLN versions::
147 * Debugging support::
152 * Floating-point underflow::
154 * Customizing the memory allocator::
157 File: cln.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
162 CLN is a library for computations with all kinds of numbers. It has a
163 rich set of number classes:
165 * Integers (with unlimited precision),
169 * Floating-point numbers:
177 - Long float (with unlimited precision),
181 * Modular integers (integers modulo a fixed integer),
183 * Univariate polynomials.
185 The subtypes of the complex numbers among these are exactly the types
186 of numbers known to the Common Lisp language. Therefore `CLN' can be
187 used for Common Lisp implementations, giving `CLN' another meaning: it
188 becomes an abbreviation of "Common Lisp Numbers".
190 The CLN package implements
192 * Elementary functions (`+', `-', `*', `/', `sqrt', comparisons,
195 * Logical functions (logical `and', `or', `not', ...),
197 * Transcendental functions (exponential, logarithmic, trigonometric,
198 hyperbolic functions and their inverse functions).
200 CLN is a C++ library. Using C++ as an implementation language provides
202 * efficiency: it compiles to machine code,
204 * type safety: the C++ compiler knows about the number types and
205 complains if, for example, you try to assign a float to an integer
208 * algebraic syntax: You can use the `+', `-', `*', `=', `==', ...
209 operators as in C or C++.
211 CLN is memory efficient:
213 * Small integers and short floats are immediate, not heap allocated.
215 * Heap-allocated memory is reclaimed through an automatic,
216 non-interruptive garbage collection.
218 CLN is speed efficient:
220 * The kernel of CLN has been written in assembly language for some
221 CPUs (`i386', `m68k', `sparc', `mips', `arm').
223 * On all CPUs, CLN may be configured to use the superefficient
224 low-level routines from GNU GMP version 3.
226 * It uses Karatsuba multiplication, which is significantly faster
227 for large numbers than the standard multiplication algorithm.
229 * For very large numbers (more than 12000 decimal digits), it uses
230 Schönhage-Strassen multiplication, which is an asymptotically
231 optimal multiplication algorithm, for multiplication, division and
234 CLN aims at being easily integrated into larger software packages:
236 * The garbage collection imposes no burden on the main application.
238 * The library provides hooks for memory allocation and exceptions.
240 * All non-macro identifiers are hidden in namespace `cln' in order
241 to avoid name clashes.
244 File: cln.info, Node: Installation, Next: Ordinary number types, Prev: Introduction, Up: Top
249 This section describes how to install the CLN package on your system.
254 * Building the library::
255 * Installing the library::
259 File: cln.info, Node: Prerequisites, Next: Building the library, Prev: Installation, Up: Installation
271 File: cln.info, Node: C++ compiler, Next: Make utility, Prev: Prerequisites, Up: Prerequisites
276 To build CLN, you need a C++ compiler. Actually, you need GNU `g++
277 2.90' or newer, the EGCS compilers will do. I recommend GNU `g++ 2.95'
280 The following C++ features are used: classes, member functions,
281 overloading of functions and operators, constructors and destructors,
282 inline, const, multiple inheritance, templates and namespaces.
284 The following C++ features are not used: `new', `delete', virtual
285 inheritance, exceptions.
287 CLN relies on semi-automatic ordering of initializations of static and
288 global variables, a feature which I could implement for GNU g++ only.
291 File: cln.info, Node: Make utility, Next: Sed utility, Prev: C++ compiler, Up: Prerequisites
296 To build CLN, you also need to have GNU `make' installed.
299 File: cln.info, Node: Sed utility, Prev: Make utility, Up: Prerequisites
304 To build CLN on HP-UX, you also need to have GNU `sed' installed. This
305 is because the libtool script, which creates the CLN library, relies on
306 `sed', and the vendor's `sed' utility on these systems is too limited.
309 File: cln.info, Node: Building the library, Next: Installing the library, Prev: Prerequisites, Up: Installation
314 As with any autoconfiguring GNU software, installation is as easy as
321 If on your system, `make' is not GNU `make', you have to use `gmake'
322 instead of `make' above.
324 The `configure' command checks out some features of your system and C++
325 compiler and builds the `Makefile's. The `make' command builds the
326 library. This step may take 4 hours on an average workstation. The
327 `make check' runs some test to check that no important subroutine has
330 The `configure' command accepts options. To get a summary of them, try
334 Some of the options are explained in detail in the `INSTALL.generic'
337 You can specify the C compiler, the C++ compiler and their options
338 through the following environment variables when running `configure':
341 Specifies the C compiler.
344 Flags to be given to the C compiler when compiling programs (not
348 Specifies the C++ compiler.
351 Flags to be given to the C++ compiler when compiling programs (not
356 $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
357 $ CC="gcc -V egcs-2.91.60" CFLAGS="-O -g" \
358 CXX="g++ -V egcs-2.91.60" CXXFLAGS="-O -g" ./configure
359 $ CC="gcc -V 2.95.2" CFLAGS="-O2 -fno-exceptions" \
360 CXX="g++ -V 2.95.2" CFLAGS="-O2 -fno-exceptions" ./configure
362 Note that for these environment variables to take effect, you have to
363 set them (assuming a Bourne-compatible shell) on the same line as the
364 `configure' command. If you made the settings in earlier shell
365 commands, you have to `export' the environment variables before calling
366 `configure'. In a `csh' shell, you have to use the `setenv' command for
367 setting each of the environment variables.
369 Currently CLN works only with the GNU `g++' compiler, and only in
370 optimizing mode. So you should specify at least `-O' in the CXXFLAGS,
371 or no CXXFLAGS at all. (If CXXFLAGS is not set, CLN will use `-O'.)
373 If you use `g++' version 2.8.x or egcs-2.91.x (a.k.a. egcs-1.1) or
374 gcc-2.95.x, I recommend adding `-fno-exceptions' to the CXXFLAGS. This
375 will likely generate better code.
377 If you use `g++' version egcs-2.91.x (egcs-1.1) or gcc-2.95.x on Sparc,
378 add either `-O', `-O1' or `-O2 -fno-schedule-insns' to the CXXFLAGS.
379 With full `-O2', `g++' miscompiles the division routines. Also, if you
380 have `g++' version egcs-1.1.1 or older on Sparc, you must specify
381 `--disable-shared' because `g++' would miscompile parts of the library.
383 By default, both a shared and a static library are built. You can build
384 CLN as a static (or shared) library only, by calling `configure' with
385 the option `--disable-shared' (or `--disable-static'). While shared
386 libraries are usually more convenient to use, they may not work on all
387 architectures. Try disabling them if you run into linker problems.
388 Also, they are generally somewhat slower than static libraries so
389 runtime-critical applications should be linked statically.
393 * Using the GNU MP Library::
396 File: cln.info, Node: Using the GNU MP Library, Prev: Building the library, Up: Building the library
398 Using the GNU MP Library
399 ------------------------
401 Starting with version 1.1, CLN may be configured to make use of a
402 preinstalled `gmp' library. Please make sure that you have at least
403 `gmp' version 3.0 installed since earlier versions are unsupported and
404 likely not to work. Enabling this feature by calling `configure' with
405 the option `--with-gmp' is known to be quite a boost for CLN's
408 If you have installed the `gmp' library and its header file in some
409 place where your compiler cannot find it by default, you must help
410 `configure' by setting `CPPFLAGS' and `LDFLAGS'. Here is an example:
412 $ CC="gcc" CFLAGS="-O2" CXX="g++" CXXFLAGS="-O2 -fno-exceptions" \
413 CPPFLAGS="-I/opt/gmp/include" LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
416 File: cln.info, Node: Installing the library, Next: Cleaning up, Prev: Building the library, Up: Installation
418 Installing the library
419 ======================
421 As with any autoconfiguring GNU software, installation is as easy as
426 The `make install' command installs the library and the include files
427 into public places (`/usr/local/lib/' and `/usr/local/include/', if you
428 haven't specified a `--prefix' option to `configure'). This step may
429 require superuser privileges.
431 If you have already built the library and wish to install it, but didn't
432 specify `--prefix=...' at configure time, just re-run `configure',
433 giving it the same options as the first time, plus the `--prefix=...'
437 File: cln.info, Node: Cleaning up, Prev: Installing the library, Up: Installation
442 You can remove system-dependent files generated by `make' through
446 You can remove all files generated by `make', thus reverting to a
447 virgin distribution of CLN, through
452 File: cln.info, Node: Ordinary number types, Next: Functions on numbers, Prev: Installation, Up: Top
454 Ordinary number types
455 *********************
457 CLN implements the following class hierarchy:
464 Real or complex number
473 +-------------------+-------------------+
475 Rational number Floating-point number
477 <cln/rational.h> <cln/float.h>
479 | +--------------+--------------+--------------+
481 cl_I Short-Float Single-Float Double-Float Long-Float
482 <cln/integer.h> cl_SF cl_FF cl_DF cl_LF
483 <cln/sfloat.h> <cln/ffloat.h> <cln/dfloat.h> <cln/lfloat.h>
485 The base class `cl_number' is an abstract base class. It is not useful
486 to declare a variable of this type except if you want to completely
487 disable compile-time type checking and use run-time type checking
490 The class `cl_N' comprises real and complex numbers. There is no
491 special class for complex numbers since complex numbers with imaginary
492 part `0' are automatically converted to real numbers.
494 The class `cl_R' comprises real numbers of different kinds. It is an
497 The class `cl_RA' comprises exact real numbers: rational numbers,
498 including integers. There is no special class for non-integral rational
499 numbers since rational numbers with denominator `1' are automatically
500 converted to integers.
502 The class `cl_F' implements floating-point approximations to real
503 numbers. It is an abstract class.
508 * Floating-point numbers::
513 File: cln.info, Node: Exact numbers, Next: Floating-point numbers, Prev: Ordinary number types, Up: Ordinary number types
518 Some numbers are represented as exact numbers: there is no loss of
519 information when such a number is converted from its mathematical value
520 to its internal representation. On exact numbers, the elementary
521 operations (`+', `-', `*', `/', comparisons, ...) compute the completely
524 In CLN, the exact numbers are:
526 * rational numbers (including integers),
528 * complex numbers whose real and imaginary parts are both rational
531 Rational numbers are always normalized to the form
532 `NUMERATOR/DENOMINATOR' where the numerator and denominator are coprime
533 integers and the denominator is positive. If the resulting denominator
534 is `1', the rational number is converted to an integer.
536 Small integers (typically in the range `-2^30'...`2^30-1', for 32-bit
537 machines) are especially efficient, because they consume no heap
538 allocation. Otherwise the distinction between these immediate integers
539 (called "fixnums") and heap allocated integers (called "bignums") is
540 completely transparent.
543 File: cln.info, Node: Floating-point numbers, Next: Complex numbers, Prev: Exact numbers, Up: Ordinary number types
545 Floating-point numbers
546 ======================
548 Not all real numbers can be represented exactly. (There is an easy
549 mathematical proof for this: Only a countable set of numbers can be
550 stored exactly in a computer, even if one assumes that it has unlimited
551 storage. But there are uncountably many real numbers.) So some
552 approximation is needed. CLN implements ordinary floating-point
553 numbers, with mantissa and exponent.
555 The elementary operations (`+', `-', `*', `/', ...) only return
556 approximate results. For example, the value of the expression `(cl_F)
557 0.3 + (cl_F) 0.4' prints as `0.70000005', not as `0.7'. Rounding errors
558 like this one are inevitable when computing with floating-point numbers.
560 Nevertheless, CLN rounds the floating-point results of the operations
561 `+', `-', `*', `/', `sqrt' according to the "round-to-even" rule: It
562 first computes the exact mathematical result and then returns the
563 floating-point number which is nearest to this. If two floating-point
564 numbers are equally distant from the ideal result, the one with a `0'
565 in its least significant mantissa bit is chosen.
567 Similarly, testing floating point numbers for equality `x == y' is
568 gambling with random errors. Better check for `abs(x - y) < epsilon'
569 for some well-chosen `epsilon'.
571 Floating point numbers come in four flavors:
573 * Short floats, type `cl_SF'. They have 1 sign bit, 8 exponent bits
574 (including the exponent's sign), and 17 mantissa bits (including
575 the "hidden" bit). They don't consume heap allocation.
577 * Single floats, type `cl_FF'. They have 1 sign bit, 8 exponent
578 bits (including the exponent's sign), and 24 mantissa bits
579 (including the "hidden" bit). In CLN, they are represented as
580 IEEE single-precision floating point numbers. This corresponds
581 closely to the C/C++ type `float'.
583 * Double floats, type `cl_DF'. They have 1 sign bit, 11 exponent
584 bits (including the exponent's sign), and 53 mantissa bits
585 (including the "hidden" bit). In CLN, they are represented as
586 IEEE double-precision floating point numbers. This corresponds
587 closely to the C/C++ type `double'.
589 * Long floats, type `cl_LF'. They have 1 sign bit, 32 exponent bits
590 (including the exponent's sign), and n mantissa bits (including
591 the "hidden" bit), where n >= 64. The precision of a long float
592 is unlimited, but once created, a long float has a fixed
593 precision. (No "lazy recomputation".)
595 Of course, computations with long floats are more expensive than those
596 with smaller floating-point formats.
598 CLN does not implement features like NaNs, denormalized numbers and
599 gradual underflow. If the exponent range of some floating-point type is
600 too limited for your application, choose another floating-point type
601 with larger exponent range.
603 As a user of CLN, you can forget about the differences between the four
604 floating-point types and just declare all your floating-point variables
605 as being of type `cl_F'. This has the advantage that when you change
606 the precision of some computation (say, from `cl_DF' to `cl_LF'), you
607 don't have to change the code, only the precision of the initial
608 values. Also, many transcendental functions have been declared as
609 returning a `cl_F' when the argument is a `cl_F', but such declarations
610 are missing for the types `cl_SF', `cl_FF', `cl_DF', `cl_LF'. (Such
611 declarations would be wrong if the floating point contagion rule
612 happened to change in the future.)
615 File: cln.info, Node: Complex numbers, Next: Conversions, Prev: Floating-point numbers, Up: Ordinary number types
620 Complex numbers, as implemented by the class `cl_N', have a real part
621 and an imaginary part, both real numbers. A complex number whose
622 imaginary part is the exact number `0' is automatically converted to a
625 Complex numbers can arise from real numbers alone, for example through
626 application of `sqrt' or transcendental functions.
629 File: cln.info, Node: Conversions, Prev: Complex numbers, Up: Ordinary number types
634 Conversions from any class to any its superclasses ("base classes" in
635 C++ terminology) is done automatically.
637 Conversions from the C built-in types `long' and `unsigned long' are
638 provided for the classes `cl_I', `cl_RA', `cl_R', `cl_N' and
641 Conversions from the C built-in types `int' and `unsigned int' are
642 provided for the classes `cl_I', `cl_RA', `cl_R', `cl_N' and
643 `cl_number'. However, these conversions emphasize efficiency. Their
644 range is therefore limited:
646 - The conversion from `int' works only if the argument is < 2^29 and
649 - The conversion from `unsigned int' works only if the argument is <
652 In a declaration like `cl_I x = 10;' the C++ compiler is able to do the
653 conversion of `10' from `int' to `cl_I' at compile time already. On the
654 other hand, code like `cl_I x = 1000000000;' is in error. So, if you
655 want to be sure that an `int' whose magnitude is not guaranteed to be <
656 2^29 is correctly converted to a `cl_I', first convert it to a `long'.
657 Similarly, if a large `unsigned int' is to be converted to a `cl_I',
658 first convert it to an `unsigned long'.
660 Conversions from the C built-in type `float' are provided for the
661 classes `cl_FF', `cl_F', `cl_R', `cl_N' and `cl_number'.
663 Conversions from the C built-in type `double' are provided for the
664 classes `cl_DF', `cl_F', `cl_R', `cl_N' and `cl_number'.
666 Conversions from `const char *' are provided for the classes `cl_I',
667 `cl_RA', `cl_SF', `cl_FF', `cl_DF', `cl_LF', `cl_F', `cl_R', `cl_N'.
668 The easiest way to specify a value which is outside of the range of the
669 C++ built-in types is therefore to specify it as a string, like this:
670 cl_I order_of_rubiks_cube_group = "43252003274489856000";
671 Note that this conversion is done at runtime, not at compile-time.
673 Conversions from `cl_I' to the C built-in types `int', `unsigned int',
674 `long', `unsigned long' are provided through the functions
676 `int cl_I_to_int (const cl_I& x)'
677 `unsigned int cl_I_to_uint (const cl_I& x)'
678 `long cl_I_to_long (const cl_I& x)'
679 `unsigned long cl_I_to_ulong (const cl_I& x)'
680 Returns `x' as element of the C type CTYPE. If `x' is not
681 representable in the range of CTYPE, a runtime error occurs.
683 Conversions from the classes `cl_I', `cl_RA', `cl_SF', `cl_FF',
684 `cl_DF', `cl_LF', `cl_F' and `cl_R' to the C built-in types `float' and
685 `double' are provided through the functions
687 `float float_approx (const TYPE& x)'
688 `double double_approx (const TYPE& x)'
689 Returns an approximation of `x' of C type CTYPE. If `abs(x)' is
690 too close to 0 (underflow), 0 is returned. If `abs(x)' is too
691 large (overflow), an IEEE infinity is returned.
693 Conversions from any class to any of its subclasses ("derived classes"
694 in C++ terminology) are not provided. Instead, you can assert and check
695 that a value belongs to a certain subclass, and return it as element of
696 that class, using the `As' and `The' macros. `As(TYPE)(VALUE)' checks
697 that VALUE belongs to TYPE and returns it as such. `The(TYPE)(VALUE)'
698 assumes that VALUE belongs to TYPE and returns it as such. It is your
699 responsibility to ensure that this assumption is valid. Example:
702 if (!(x >= 0)) abort();
703 cl_I ten_x = The(cl_I)(expt(10,x)); // If x >= 0, 10^x is an integer.
704 // In general, it would be a rational number.
707 File: cln.info, Node: Functions on numbers, Next: Input/Output, Prev: Ordinary number types, Up: Top
712 Each of the number classes declares its mathematical operations in the
713 corresponding include file. For example, if your code operates with
714 objects of type `cl_I', it should `#include <cln/integer.h>'.
718 * Constructing numbers::
719 * Elementary functions::
720 * Elementary rational functions::
721 * Elementary complex functions::
723 * Rounding functions::
725 * Transcendental functions::
726 * Functions on integers::
727 * Functions on floating-point numbers::
728 * Conversion functions::
729 * Random number generators::
730 * Obfuscating operators::
733 File: cln.info, Node: Constructing numbers, Next: Elementary functions, Prev: Functions on numbers, Up: Functions on numbers
738 Here is how to create number objects "from nothing".
742 * Constructing integers::
743 * Constructing rational numbers::
744 * Constructing floating-point numbers::
745 * Constructing complex numbers::
748 File: cln.info, Node: Constructing integers, Next: Constructing rational numbers, Prev: Constructing numbers, Up: Constructing numbers
750 Constructing integers
751 ---------------------
753 `cl_I' objects are most easily constructed from C integers and from
754 strings. See *Note Conversions::.
757 File: cln.info, Node: Constructing rational numbers, Next: Constructing floating-point numbers, Prev: Constructing integers, Up: Constructing numbers
759 Constructing rational numbers
760 -----------------------------
762 `cl_RA' objects can be constructed from strings. The syntax for
763 rational numbers is described in *Note Internal and printed
764 representation::. Another standard way to produce a rational number is
765 through application of `operator /' or `recip' on integers.
768 File: cln.info, Node: Constructing floating-point numbers, Next: Constructing complex numbers, Prev: Constructing rational numbers, Up: Constructing numbers
770 Constructing floating-point numbers
771 -----------------------------------
773 `cl_F' objects with low precision are most easily constructed from C
774 `float' and `double'. See *Note Conversions::.
776 To construct a `cl_F' with high precision, you can use the conversion
777 from `const char *', but you have to specify the desired precision
778 within the string. (See *Note Internal and printed representation::.)
780 cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
781 will set `e' to the given value, with a precision of 40 decimal digits.
783 The programmatic way to construct a `cl_F' with high precision is
784 through the `cl_float' conversion function, see *Note Conversion to
785 floating-point numbers::. For example, to compute `e' to 40 decimal
786 places, first construct 1.0 to 40 decimal places and then apply the
787 exponential function:
788 cl_float_format_t precision = cl_float_format(40);
789 cl_F e = exp(cl_float(1,precision));
792 File: cln.info, Node: Constructing complex numbers, Prev: Constructing floating-point numbers, Up: Constructing numbers
794 Constructing complex numbers
795 ----------------------------
797 Non-real `cl_N' objects are normally constructed through the function
798 cl_N complex (const cl_R& realpart, const cl_R& imagpart)
799 See *Note Elementary complex functions::.
802 File: cln.info, Node: Elementary functions, Next: Elementary rational functions, Prev: Constructing numbers, Up: Functions on numbers
807 Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
808 `cl_FF', `cl_DF', `cl_LF' defines the following operations:
810 `TYPE operator + (const TYPE&, const TYPE&)'
813 `TYPE operator - (const TYPE&, const TYPE&)'
816 `TYPE operator - (const TYPE&)'
817 Returns the negative of the argument.
819 `TYPE plus1 (const TYPE& x)'
822 `TYPE minus1 (const TYPE& x)'
825 `TYPE operator * (const TYPE&, const TYPE&)'
828 `TYPE square (const TYPE& x)'
831 Each of the classes `cl_N', `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF',
832 `cl_DF', `cl_LF' defines the following operations:
834 `TYPE operator / (const TYPE&, const TYPE&)'
837 `TYPE recip (const TYPE&)'
838 Returns the reciprocal of the argument.
840 The class `cl_I' doesn't define a `/' operation because in the C/C++
841 language this operator, applied to integral types, denotes the `floor'
842 or `truncate' operation (which one of these, is implementation
843 dependent). (*Note Rounding functions::.) Instead, `cl_I' defines an
844 "exact quotient" function:
846 `cl_I exquo (const cl_I& x, const cl_I& y)'
847 Checks that `y' divides `x', and returns the quotient `x'/`y'.
849 The following exponentiation functions are defined:
851 `cl_I expt_pos (const cl_I& x, const cl_I& y)'
852 `cl_RA expt_pos (const cl_RA& x, const cl_I& y)'
853 `y' must be > 0. Returns `x^y'.
855 `cl_RA expt (const cl_RA& x, const cl_I& y)'
856 `cl_R expt (const cl_R& x, const cl_I& y)'
857 `cl_N expt (const cl_N& x, const cl_I& y)'
860 Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
861 `cl_DF', `cl_LF' defines the following operation:
863 `TYPE abs (const TYPE& x)'
864 Returns the absolute value of `x'. This is `x' if `x >= 0', and
867 The class `cl_N' implements this as follows:
869 `cl_R abs (const cl_N x)'
870 Returns the absolute value of `x'.
872 Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
873 `cl_FF', `cl_DF', `cl_LF' defines the following operation:
875 `TYPE signum (const TYPE& x)'
876 Returns the sign of `x', in the same number format as `x'. This
877 is defined as `x / abs(x)' if `x' is non-zero, and `x' if `x' is
878 zero. If `x' is real, the value is either 0 or 1 or -1.
881 File: cln.info, Node: Elementary rational functions, Next: Elementary complex functions, Prev: Elementary functions, Up: Functions on numbers
883 Elementary rational functions
884 =============================
886 Each of the classes `cl_RA', `cl_I' defines the following operations:
888 `cl_I numerator (const TYPE& x)'
889 Returns the numerator of `x'.
891 `cl_I denominator (const TYPE& x)'
892 Returns the denominator of `x'.
894 The numerator and denominator of a rational number are normalized in
895 such a way that they have no factor in common and the denominator is
899 File: cln.info, Node: Elementary complex functions, Next: Comparisons, Prev: Elementary rational functions, Up: Functions on numbers
901 Elementary complex functions
902 ============================
904 The class `cl_N' defines the following operation:
906 `cl_N complex (const cl_R& a, const cl_R& b)'
907 Returns the complex number `a+bi', that is, the complex number with
908 real part `a' and imaginary part `b'.
910 Each of the classes `cl_N', `cl_R' defines the following operations:
912 `cl_R realpart (const TYPE& x)'
913 Returns the real part of `x'.
915 `cl_R imagpart (const TYPE& x)'
916 Returns the imaginary part of `x'.
918 `TYPE conjugate (const TYPE& x)'
919 Returns the complex conjugate of `x'.
921 We have the relations
923 `x = complex(realpart(x), imagpart(x))'
925 `conjugate(x) = complex(realpart(x), -imagpart(x))'
928 File: cln.info, Node: Comparisons, Next: Rounding functions, Prev: Elementary complex functions, Up: Functions on numbers
933 Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
934 `cl_FF', `cl_DF', `cl_LF' defines the following operations:
936 `bool operator == (const TYPE&, const TYPE&)'
937 `bool operator != (const TYPE&, const TYPE&)'
938 Comparison, as in C and C++.
940 `uint32 equal_hashcode (const TYPE&)'
941 Returns a 32-bit hash code that is the same for any two numbers
942 which are the same according to `=='. This hash code depends on
943 the number's value, not its type or precision.
945 `cl_boolean zerop (const TYPE& x)'
946 Compare against zero: `x == 0'
948 Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
949 `cl_DF', `cl_LF' defines the following operations:
951 `cl_signean compare (const TYPE& x, const TYPE& y)'
952 Compares `x' and `y'. Returns +1 if `x'>`y', -1 if `x'<`y', 0 if
955 `bool operator <= (const TYPE&, const TYPE&)'
956 `bool operator < (const TYPE&, const TYPE&)'
957 `bool operator >= (const TYPE&, const TYPE&)'
958 `bool operator > (const TYPE&, const TYPE&)'
959 Comparison, as in C and C++.
961 `cl_boolean minusp (const TYPE& x)'
962 Compare against zero: `x < 0'
964 `cl_boolean plusp (const TYPE& x)'
965 Compare against zero: `x > 0'
967 `TYPE max (const TYPE& x, const TYPE& y)'
968 Return the maximum of `x' and `y'.
970 `TYPE min (const TYPE& x, const TYPE& y)'
971 Return the minimum of `x' and `y'.
973 When a floating point number and a rational number are compared, the
974 float is first converted to a rational number using the function
975 `rational'. Since a floating point number actually represents an
976 interval of real numbers, the result might be surprising. For example,
977 `(cl_F)(cl_R)"1/3" == (cl_R)"1/3"' returns false because there is no
978 floating point number whose value is exactly `1/3'.
981 File: cln.info, Node: Rounding functions, Next: Roots, Prev: Comparisons, Up: Functions on numbers
986 When a real number is to be converted to an integer, there is no "best"
987 rounding. The desired rounding function depends on the application.
988 The Common Lisp and ISO Lisp standards offer four rounding functions:
991 This is the largest integer <=`x'.
994 This is the smallest integer >=`x'.
997 Among the integers between 0 and `x' (inclusive) the one nearest
1001 The integer nearest to `x'. If `x' is exactly halfway between two
1002 integers, choose the even one.
1004 These functions have different advantages:
1006 `floor' and `ceiling' are translation invariant: `floor(x+n) = floor(x)
1007 + n' and `ceiling(x+n) = ceiling(x) + n' for every `x' and every
1010 On the other hand, `truncate' and `round' are symmetric: `truncate(-x)
1011 = -truncate(x)' and `round(-x) = -round(x)', and furthermore `round' is
1012 unbiased: on the "average", it rounds down exactly as often as it
1015 The functions are related like this:
1017 `ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1' for rational
1018 numbers `m/n' (`m', `n' integers, `n'>0), and
1020 `truncate(x) = sign(x) * floor(abs(x))'
1022 Each of the classes `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF', `cl_DF',
1023 `cl_LF' defines the following operations:
1025 `cl_I floor1 (const TYPE& x)'
1028 `cl_I ceiling1 (const TYPE& x)'
1029 Returns `ceiling(x)'.
1031 `cl_I truncate1 (const TYPE& x)'
1032 Returns `truncate(x)'.
1034 `cl_I round1 (const TYPE& x)'
1037 Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
1038 `cl_DF', `cl_LF' defines the following operations:
1040 `cl_I floor1 (const TYPE& x, const TYPE& y)'
1041 Returns `floor(x/y)'.
1043 `cl_I ceiling1 (const TYPE& x, const TYPE& y)'
1044 Returns `ceiling(x/y)'.
1046 `cl_I truncate1 (const TYPE& x, const TYPE& y)'
1047 Returns `truncate(x/y)'.
1049 `cl_I round1 (const TYPE& x, const TYPE& y)'
1050 Returns `round(x/y)'.
1052 These functions are called `floor1', ... here instead of `floor', ...,
1053 because on some systems, system dependent include files define `floor'
1054 and `ceiling' as macros.
1056 In many cases, one needs both the quotient and the remainder of a
1057 division. It is more efficient to compute both at the same time than
1058 to perform two divisions, one for quotient and the next one for the
1059 remainder. The following functions therefore return a structure
1060 containing both the quotient and the remainder. The suffix `2'
1061 indicates the number of "return values". The remainder is defined as
1064 * for the computation of `quotient = floor(x)', `remainder = x -
1067 * for the computation of `quotient = floor(x,y)', `remainder = x -
1070 and similarly for the other three operations.
1072 Each of the classes `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF', `cl_DF',
1073 `cl_LF' defines the following operations:
1075 `struct TYPE_div_t { cl_I quotient; TYPE remainder; };'
1076 `TYPE_div_t floor2 (const TYPE& x)'
1077 `TYPE_div_t ceiling2 (const TYPE& x)'
1078 `TYPE_div_t truncate2 (const TYPE& x)'
1079 `TYPE_div_t round2 (const TYPE& x)'
1080 Each of the classes `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF', `cl_FF',
1081 `cl_DF', `cl_LF' defines the following operations:
1083 `struct TYPE_div_t { cl_I quotient; TYPE remainder; };'
1084 `TYPE_div_t floor2 (const TYPE& x, const TYPE& y)'
1085 `TYPE_div_t ceiling2 (const TYPE& x, const TYPE& y)'
1086 `TYPE_div_t truncate2 (const TYPE& x, const TYPE& y)'
1087 `TYPE_div_t round2 (const TYPE& x, const TYPE& y)'
1088 Sometimes, one wants the quotient as a floating-point number (of the
1089 same format as the argument, if the argument is a float) instead of as
1090 an integer. The prefix `f' indicates this.
1092 Each of the classes `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF' defines
1093 the following operations:
1095 `TYPE ffloor (const TYPE& x)'
1096 `TYPE fceiling (const TYPE& x)'
1097 `TYPE ftruncate (const TYPE& x)'
1098 `TYPE fround (const TYPE& x)'
1099 and similarly for class `cl_R', but with return type `cl_F'.
1101 The class `cl_R' defines the following operations:
1103 `cl_F ffloor (const TYPE& x, const TYPE& y)'
1104 `cl_F fceiling (const TYPE& x, const TYPE& y)'
1105 `cl_F ftruncate (const TYPE& x, const TYPE& y)'
1106 `cl_F fround (const TYPE& x, const TYPE& y)'
1107 These functions also exist in versions which return both the quotient
1108 and the remainder. The suffix `2' indicates this.
1110 Each of the classes `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF' defines
1111 the following operations:
1113 `struct TYPE_fdiv_t { TYPE quotient; TYPE remainder; };'
1114 `TYPE_fdiv_t ffloor2 (const TYPE& x)'
1115 `TYPE_fdiv_t fceiling2 (const TYPE& x)'
1116 `TYPE_fdiv_t ftruncate2 (const TYPE& x)'
1117 `TYPE_fdiv_t fround2 (const TYPE& x)'
1118 and similarly for class `cl_R', but with quotient type `cl_F'.
1120 The class `cl_R' defines the following operations:
1122 `struct TYPE_fdiv_t { cl_F quotient; cl_R remainder; };'
1123 `TYPE_fdiv_t ffloor2 (const TYPE& x, const TYPE& y)'
1124 `TYPE_fdiv_t fceiling2 (const TYPE& x, const TYPE& y)'
1125 `TYPE_fdiv_t ftruncate2 (const TYPE& x, const TYPE& y)'
1126 `TYPE_fdiv_t fround2 (const TYPE& x, const TYPE& y)'
1127 Other applications need only the remainder of a division. The
1128 remainder of `floor' and `ffloor' is called `mod' (abbreviation of
1129 "modulo"). The remainder `truncate' and `ftruncate' is called `rem'
1130 (abbreviation of "remainder").
1132 * `mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y'
1134 * `rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y'
1136 If `x' and `y' are both >= 0, `mod(x,y) = rem(x,y) >= 0'. In general,
1137 `mod(x,y)' has the sign of `y' or is zero, and `rem(x,y)' has the sign
1140 The classes `cl_R', `cl_I' define the following operations:
1142 `TYPE mod (const TYPE& x, const TYPE& y)'
1143 `TYPE rem (const TYPE& x, const TYPE& y)'
1145 File: cln.info, Node: Roots, Next: Transcendental functions, Prev: Rounding functions, Up: Functions on numbers
1150 Each of the classes `cl_R', `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF'
1151 defines the following operation:
1153 `TYPE sqrt (const TYPE& x)'
1154 `x' must be >= 0. This function returns the square root of `x',
1155 normalized to be >= 0. If `x' is the square of a rational number,
1156 `sqrt(x)' will be a rational number, else it will return a
1157 floating-point approximation.
1159 The classes `cl_RA', `cl_I' define the following operation:
1161 `cl_boolean sqrtp (const TYPE& x, TYPE* root)'
1162 This tests whether `x' is a perfect square. If so, it returns true
1163 and the exact square root in `*root', else it returns false.
1165 Furthermore, for integers, similarly:
1167 `cl_boolean isqrt (const TYPE& x, TYPE* root)'
1168 `x' should be >= 0. This function sets `*root' to `floor(sqrt(x))'
1169 and returns the same value as `sqrtp': the boolean value
1170 `(expt(*root,2) == x)'.
1172 For `n'th roots, the classes `cl_RA', `cl_I' define the following
1175 `cl_boolean rootp (const TYPE& x, const cl_I& n, TYPE* root)'
1176 `x' must be >= 0. `n' must be > 0. This tests whether `x' is an
1177 `n'th power of a rational number. If so, it returns true and the
1178 exact root in `*root', else it returns false.
1180 The only square root function which accepts negative numbers is the one
1183 `cl_N sqrt (const cl_N& z)'
1184 Returns the square root of `z', as defined by the formula `sqrt(z)
1185 = exp(log(z)/2)'. Conversion to a floating-point type or to a
1186 complex number are done if necessary. The range of the result is
1187 the right half plane `realpart(sqrt(z)) >= 0' including the
1188 positive imaginary axis and 0, but excluding the negative
1189 imaginary axis. The result is an exact number only if `z' is an
1193 File: cln.info, Node: Transcendental functions, Next: Functions on integers, Prev: Roots, Up: Functions on numbers
1195 Transcendental functions
1196 ========================
1198 The transcendental functions return an exact result if the argument is
1199 exact and the result is exact as well. Otherwise they must return
1200 inexact numbers even if the argument is exact. For example, `cos(0) =
1201 1' returns the rational number `1'.
1205 * Exponential and logarithmic functions::
1206 * Trigonometric functions::
1207 * Hyperbolic functions::
1212 File: cln.info, Node: Exponential and logarithmic functions, Next: Trigonometric functions, Prev: Transcendental functions, Up: Transcendental functions
1214 Exponential and logarithmic functions
1215 -------------------------------------
1217 `cl_R exp (const cl_R& x)'
1218 `cl_N exp (const cl_N& x)'
1219 Returns the exponential function of `x'. This is `e^x' where `e'
1220 is the base of the natural logarithms. The range of the result is
1221 the entire complex plane excluding 0.
1223 `cl_R ln (const cl_R& x)'
1224 `x' must be > 0. Returns the (natural) logarithm of x.
1226 `cl_N log (const cl_N& x)'
1227 Returns the (natural) logarithm of x. If `x' is real and positive,
1228 this is `ln(x)'. In general, `log(x) = log(abs(x)) + i*phase(x)'.
1229 The range of the result is the strip in the complex plane `-pi <
1230 imagpart(log(x)) <= pi'.
1232 `cl_R phase (const cl_N& x)'
1233 Returns the angle part of `x' in its polar representation as a
1234 complex number. That is, `phase(x) =
1235 atan(realpart(x),imagpart(x))'. This is also the imaginary part
1236 of `log(x)'. The range of the result is the interval `-pi <
1237 phase(x) <= pi'. The result will be an exact number only if
1238 `zerop(x)' or if `x' is real and positive.
1240 `cl_R log (const cl_R& a, const cl_R& b)'
1241 `a' and `b' must be > 0. Returns the logarithm of `a' with respect
1242 to base `b'. `log(a,b) = ln(a)/ln(b)'. The result can be exact
1243 only if `a = 1' or if `a' and `b' are both rational.
1245 `cl_N log (const cl_N& a, const cl_N& b)'
1246 Returns the logarithm of `a' with respect to base `b'. `log(a,b)
1249 `cl_N expt (const cl_N& x, const cl_N& y)'
1250 Exponentiation: Returns `x^y = exp(y*log(x))'.
1252 The constant e = exp(1) = 2.71828... is returned by the following
1255 `cl_F exp1 (cl_float_format_t f)'
1256 Returns e as a float of format `f'.
1258 `cl_F exp1 (const cl_F& y)'
1259 Returns e in the float format of `y'.
1262 Returns e as a float of format `default_float_format'.
1265 File: cln.info, Node: Trigonometric functions, Next: Hyperbolic functions, Prev: Exponential and logarithmic functions, Up: Transcendental functions
1267 Trigonometric functions
1268 -----------------------
1270 `cl_R sin (const cl_R& x)'
1271 Returns `sin(x)'. The range of the result is the interval `-1 <=
1274 `cl_N sin (const cl_N& z)'
1275 Returns `sin(z)'. The range of the result is the entire complex
1278 `cl_R cos (const cl_R& x)'
1279 Returns `cos(x)'. The range of the result is the interval `-1 <=
1282 `cl_N cos (const cl_N& x)'
1283 Returns `cos(z)'. The range of the result is the entire complex
1286 `struct cos_sin_t { cl_R cos; cl_R sin; };'
1287 `cos_sin_t cos_sin (const cl_R& x)'
1288 Returns both `sin(x)' and `cos(x)'. This is more efficient than
1289 computing them separately. The relation `cos^2 + sin^2 = 1' will
1290 hold only approximately.
1292 `cl_R tan (const cl_R& x)'
1293 `cl_N tan (const cl_N& x)'
1294 Returns `tan(x) = sin(x)/cos(x)'.
1296 `cl_N cis (const cl_R& x)'
1297 `cl_N cis (const cl_N& x)'
1298 Returns `exp(i*x)'. The name `cis' means "cos + i sin", because
1299 `e^(i*x) = cos(x) + i*sin(x)'.
1301 `cl_N asin (const cl_N& z)'
1302 Returns `arcsin(z)'. This is defined as `arcsin(z) =
1303 log(iz+sqrt(1-z^2))/i' and satisfies `arcsin(-z) = -arcsin(z)'.
1304 The range of the result is the strip in the complex domain `-pi/2
1305 <= realpart(arcsin(z)) <= pi/2', excluding the numbers with
1306 `realpart = -pi/2' and `imagpart < 0' and the numbers with
1307 `realpart = pi/2' and `imagpart > 0'.
1309 `cl_N acos (const cl_N& z)'
1310 Returns `arccos(z)'. This is defined as `arccos(z) = pi/2 -
1311 arcsin(z) = log(z+i*sqrt(1-z^2))/i' and satisfies `arccos(-z) = pi
1312 - arccos(z)'. The range of the result is the strip in the complex
1313 domain `0 <= realpart(arcsin(z)) <= pi', excluding the numbers
1314 with `realpart = 0' and `imagpart < 0' and the numbers with
1315 `realpart = pi' and `imagpart > 0'.
1317 `cl_R atan (const cl_R& x, const cl_R& y)'
1318 Returns the angle of the polar representation of the complex number
1319 `x+iy'. This is `atan(y/x)' if `x>0'. The range of the result is
1320 the interval `-pi < atan(x,y) <= pi'. The result will be an exact
1321 number only if `x > 0' and `y' is the exact `0'. WARNING: In
1322 Common Lisp, this function is called as `(atan y x)', with
1323 reversed order of arguments.
1325 `cl_R atan (const cl_R& x)'
1326 Returns `arctan(x)'. This is the same as `atan(1,x)'. The range of
1327 the result is the interval `-pi/2 < atan(x) < pi/2'. The result
1328 will be an exact number only if `x' is the exact `0'.
1330 `cl_N atan (const cl_N& z)'
1331 Returns `arctan(z)'. This is defined as `arctan(z) =
1332 (log(1+iz)-log(1-iz)) / 2i' and satisfies `arctan(-z) =
1333 -arctan(z)'. The range of the result is the strip in the complex
1334 domain `-pi/2 <= realpart(arctan(z)) <= pi/2', excluding the
1335 numbers with `realpart = -pi/2' and `imagpart >= 0' and the numbers
1336 with `realpart = pi/2' and `imagpart <= 0'.
1338 Archimedes' constant pi = 3.14... is returned by the following
1341 `cl_F pi (cl_float_format_t f)'
1342 Returns pi as a float of format `f'.
1344 `cl_F pi (const cl_F& y)'
1345 Returns pi in the float format of `y'.
1348 Returns pi as a float of format `default_float_format'.
1351 File: cln.info, Node: Hyperbolic functions, Next: Euler gamma, Prev: Trigonometric functions, Up: Transcendental functions
1353 Hyperbolic functions
1354 --------------------
1356 `cl_R sinh (const cl_R& x)'
1359 `cl_N sinh (const cl_N& z)'
1360 Returns `sinh(z)'. The range of the result is the entire complex
1363 `cl_R cosh (const cl_R& x)'
1364 Returns `cosh(x)'. The range of the result is the interval
1367 `cl_N cosh (const cl_N& z)'
1368 Returns `cosh(z)'. The range of the result is the entire complex
1371 `struct cosh_sinh_t { cl_R cosh; cl_R sinh; };'
1372 `cosh_sinh_t cosh_sinh (const cl_R& x)'
1373 Returns both `sinh(x)' and `cosh(x)'. This is more efficient than
1374 computing them separately. The relation `cosh^2 - sinh^2 = 1' will
1375 hold only approximately.
1377 `cl_R tanh (const cl_R& x)'
1378 `cl_N tanh (const cl_N& x)'
1379 Returns `tanh(x) = sinh(x)/cosh(x)'.
1381 `cl_N asinh (const cl_N& z)'
1382 Returns `arsinh(z)'. This is defined as `arsinh(z) =
1383 log(z+sqrt(1+z^2))' and satisfies `arsinh(-z) = -arsinh(z)'. The
1384 range of the result is the strip in the complex domain `-pi/2 <=
1385 imagpart(arsinh(z)) <= pi/2', excluding the numbers with `imagpart
1386 = -pi/2' and `realpart > 0' and the numbers with `imagpart = pi/2'
1389 `cl_N acosh (const cl_N& z)'
1390 Returns `arcosh(z)'. This is defined as `arcosh(z) =
1391 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))'. The range of the result is
1392 the half-strip in the complex domain `-pi < imagpart(arcosh(z)) <=
1393 pi, realpart(arcosh(z)) >= 0', excluding the numbers with
1394 `realpart = 0' and `-pi < imagpart < 0'.
1396 `cl_N atanh (const cl_N& z)'
1397 Returns `artanh(z)'. This is defined as `artanh(z) =
1398 (log(1+z)-log(1-z)) / 2' and satisfies `artanh(-z) = -artanh(z)'.
1399 The range of the result is the strip in the complex domain `-pi/2
1400 <= imagpart(artanh(z)) <= pi/2', excluding the numbers with
1401 `imagpart = -pi/2' and `realpart <= 0' and the numbers with
1402 `imagpart = pi/2' and `realpart >= 0'.
1405 File: cln.info, Node: Euler gamma, Next: Riemann zeta, Prev: Hyperbolic functions, Up: Transcendental functions
1410 Euler's constant C = 0.577... is returned by the following functions:
1412 `cl_F eulerconst (cl_float_format_t f)'
1413 Returns Euler's constant as a float of format `f'.
1415 `cl_F eulerconst (const cl_F& y)'
1416 Returns Euler's constant in the float format of `y'.
1418 `cl_F eulerconst (void)'
1419 Returns Euler's constant as a float of format
1420 `default_float_format'.
1422 Catalan's constant G = 0.915... is returned by the following functions:
1424 `cl_F catalanconst (cl_float_format_t f)'
1425 Returns Catalan's constant as a float of format `f'.
1427 `cl_F catalanconst (const cl_F& y)'
1428 Returns Catalan's constant in the float format of `y'.
1430 `cl_F catalanconst (void)'
1431 Returns Catalan's constant as a float of format
1432 `default_float_format'.
1435 File: cln.info, Node: Riemann zeta, Prev: Euler gamma, Up: Transcendental functions
1440 Riemann's zeta function at an integral point `s>1' is returned by the
1441 following functions:
1443 `cl_F zeta (int s, cl_float_format_t f)'
1444 Returns Riemann's zeta function at `s' as a float of format `f'.
1446 `cl_F zeta (int s, const cl_F& y)'
1447 Returns Riemann's zeta function at `s' in the float format of `y'.
1450 Returns Riemann's zeta function at `s' as a float of format
1451 `default_float_format'.
1454 File: cln.info, Node: Functions on integers, Next: Functions on floating-point numbers, Prev: Transcendental functions, Up: Functions on numbers
1456 Functions on integers
1457 =====================
1461 * Logical functions::
1462 * Number theoretic functions::
1463 * Combinatorial functions::
1466 File: cln.info, Node: Logical functions, Next: Number theoretic functions, Prev: Functions on integers, Up: Functions on integers
1471 Integers, when viewed as in two's complement notation, can be thought as
1472 infinite bit strings where the bits' values eventually are constant.
1477 The logical operations view integers as such bit strings and operate on
1478 each of the bit positions in parallel.
1480 `cl_I lognot (const cl_I& x)'
1481 `cl_I operator ~ (const cl_I& x)'
1482 Logical not, like `~x' in C. This is the same as `-1-x'.
1484 `cl_I logand (const cl_I& x, const cl_I& y)'
1485 `cl_I operator & (const cl_I& x, const cl_I& y)'
1486 Logical and, like `x & y' in C.
1488 `cl_I logior (const cl_I& x, const cl_I& y)'
1489 `cl_I operator | (const cl_I& x, const cl_I& y)'
1490 Logical (inclusive) or, like `x | y' in C.
1492 `cl_I logxor (const cl_I& x, const cl_I& y)'
1493 `cl_I operator ^ (const cl_I& x, const cl_I& y)'
1494 Exclusive or, like `x ^ y' in C.
1496 `cl_I logeqv (const cl_I& x, const cl_I& y)'
1497 Bitwise equivalence, like `~(x ^ y)' in C.
1499 `cl_I lognand (const cl_I& x, const cl_I& y)'
1500 Bitwise not and, like `~(x & y)' in C.
1502 `cl_I lognor (const cl_I& x, const cl_I& y)'
1503 Bitwise not or, like `~(x | y)' in C.
1505 `cl_I logandc1 (const cl_I& x, const cl_I& y)'
1506 Logical and, complementing the first argument, like `~x & y' in C.
1508 `cl_I logandc2 (const cl_I& x, const cl_I& y)'
1509 Logical and, complementing the second argument, like `x & ~y' in C.
1511 `cl_I logorc1 (const cl_I& x, const cl_I& y)'
1512 Logical or, complementing the first argument, like `~x | y' in C.
1514 `cl_I logorc2 (const cl_I& x, const cl_I& y)'
1515 Logical or, complementing the second argument, like `x | ~y' in C.
1517 These operations are all available though the function
1518 `cl_I boole (cl_boole op, const cl_I& x, const cl_I& y)'
1519 where `op' must have one of the 16 values (each one stands for a
1520 function which combines two bits into one bit): `boole_clr',
1521 `boole_set', `boole_1', `boole_2', `boole_c1', `boole_c2', `boole_and',
1522 `boole_ior', `boole_xor', `boole_eqv', `boole_nand', `boole_nor',
1523 `boole_andc1', `boole_andc2', `boole_orc1', `boole_orc2'.
1525 Other functions that view integers as bit strings:
1527 `cl_boolean logtest (const cl_I& x, const cl_I& y)'
1528 Returns true if some bit is set in both `x' and `y', i.e. if
1531 `cl_boolean logbitp (const cl_I& n, const cl_I& x)'
1532 Returns true if the `n'th bit (from the right) of `x' is set. Bit
1533 0 is the least significant bit.
1535 `uintL logcount (const cl_I& x)'
1536 Returns the number of one bits in `x', if `x' >= 0, or the number
1537 of zero bits in `x', if `x' < 0.
1539 The following functions operate on intervals of bits in integers. The
1541 struct cl_byte { uintL size; uintL position; };
1542 represents the bit interval containing the bits
1543 `position'...`position+size-1' of an integer. The constructor
1544 `cl_byte(size,position)' constructs a `cl_byte'.
1546 `cl_I ldb (const cl_I& n, const cl_byte& b)'
1547 extracts the bits of `n' described by the bit interval `b' and
1548 returns them as a nonnegative integer with `b.size' bits.
1550 `cl_boolean ldb_test (const cl_I& n, const cl_byte& b)'
1551 Returns true if some bit described by the bit interval `b' is set
1554 `cl_I dpb (const cl_I& newbyte, const cl_I& n, const cl_byte& b)'
1555 Returns `n', with the bits described by the bit interval `b'
1556 replaced by `newbyte'. Only the lowest `b.size' bits of `newbyte'
1559 The functions `ldb' and `dpb' implicitly shift. The following functions
1560 are their counterparts without shifting:
1562 `cl_I mask_field (const cl_I& n, const cl_byte& b)'
1563 returns an integer with the bits described by the bit interval `b'
1564 copied from the corresponding bits in `n', the other bits zero.
1566 `cl_I deposit_field (const cl_I& newbyte, const cl_I& n, const cl_byte& b)'
1567 returns an integer where the bits described by the bit interval `b'
1568 come from `newbyte' and the other bits come from `n'.
1570 The following relations hold:
1572 `ldb (n, b) = mask_field(n, b) >> b.position',
1574 `dpb (newbyte, n, b) = deposit_field (newbyte << b.position, n,
1577 `deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^
1578 mask_field(new_byte,b)'.
1580 The following operations on integers as bit strings are efficient
1581 shortcuts for common arithmetic operations:
1583 `cl_boolean oddp (const cl_I& x)'
1584 Returns true if the least significant bit of `x' is 1. Equivalent
1587 `cl_boolean evenp (const cl_I& x)'
1588 Returns true if the least significant bit of `x' is 0. Equivalent
1591 `cl_I operator << (const cl_I& x, const cl_I& n)'
1592 Shifts `x' by `n' bits to the left. `n' should be >=0. Equivalent
1595 `cl_I operator >> (const cl_I& x, const cl_I& n)'
1596 Shifts `x' by `n' bits to the right. `n' should be >=0. Bits
1597 shifted out to the right are thrown away. Equivalent to `floor(x
1600 `cl_I ash (const cl_I& x, const cl_I& y)'
1601 Shifts `x' by `y' bits to the left (if `y'>=0) or by `-y' bits to
1602 the right (if `y'<=0). In other words, this returns `floor(x *
1605 `uintL integer_length (const cl_I& x)'
1606 Returns the number of bits (excluding the sign bit) needed to
1607 represent `x' in two's complement notation. This is the smallest n
1608 >= 0 such that -2^n <= x < 2^n. If x > 0, this is the unique n > 0
1609 such that 2^(n-1) <= x < 2^n.
1611 `uintL ord2 (const cl_I& x)'
1612 `x' must be non-zero. This function returns the number of 0 bits
1613 at the right of `x' in two's complement notation. This is the
1614 largest n >= 0 such that 2^n divides `x'.
1616 `uintL power2p (const cl_I& x)'
1617 `x' must be > 0. This function checks whether `x' is a power of 2.
1618 If `x' = 2^(n-1), it returns n. Else it returns 0. (See also the
1622 File: cln.info, Node: Number theoretic functions, Next: Combinatorial functions, Prev: Logical functions, Up: Functions on integers
1624 Number theoretic functions
1625 --------------------------
1627 `uint32 gcd (uint32 a, uint32 b)'
1628 `cl_I gcd (const cl_I& a, const cl_I& b)'
1629 This function returns the greatest common divisor of `a' and `b',
1630 normalized to be >= 0.
1632 `cl_I xgcd (const cl_I& a, const cl_I& b, cl_I* u, cl_I* v)'
1633 This function ("extended gcd") returns the greatest common divisor
1634 `g' of `a' and `b' and at the same time the representation of `g'
1635 as an integral linear combination of `a' and `b': `u' and `v' with
1636 `u*a+v*b = g', `g' >= 0. `u' and `v' will be normalized to be of
1637 smallest possible absolute value, in the following sense: If `a'
1638 and `b' are non-zero, and `abs(a) != abs(b)', `u' and `v' will
1639 satisfy the inequalities `abs(u) <= abs(b)/(2*g)', `abs(v) <=
1642 `cl_I lcm (const cl_I& a, const cl_I& b)'
1643 This function returns the least common multiple of `a' and `b',
1644 normalized to be >= 0.
1646 `cl_boolean logp (const cl_I& a, const cl_I& b, cl_RA* l)'
1647 `cl_boolean logp (const cl_RA& a, const cl_RA& b, cl_RA* l)'
1648 `a' must be > 0. `b' must be >0 and != 1. If log(a,b) is rational
1649 number, this function returns true and sets *l = log(a,b), else it
1653 File: cln.info, Node: Combinatorial functions, Prev: Number theoretic functions, Up: Functions on integers
1655 Combinatorial functions
1656 -----------------------
1658 `cl_I factorial (uintL n)'
1659 `n' must be a small integer >= 0. This function returns the
1660 factorial `n'! = `1*2*...*n'.
1662 `cl_I doublefactorial (uintL n)'
1663 `n' must be a small integer >= 0. This function returns the
1664 doublefactorial `n'!! = `1*3*...*n' or `n'!! = `2*4*...*n',
1667 `cl_I binomial (uintL n, uintL k)'
1668 `n' and `k' must be small integers >= 0. This function returns the
1669 binomial coefficient (`n' choose `k') = `n'! / `k'! `(n-k)'! for
1670 0 <= k <= n, 0 else.
1673 File: cln.info, Node: Functions on floating-point numbers, Next: Conversion functions, Prev: Functions on integers, Up: Functions on numbers
1675 Functions on floating-point numbers
1676 ===================================
1678 Recall that a floating-point number consists of a sign `s', an exponent
1679 `e' and a mantissa `m'. The value of the number is `(-1)^s * 2^e * m'.
1681 Each of the classes `cl_F', `cl_SF', `cl_FF', `cl_DF', `cl_LF' defines
1682 the following operations.
1684 `TYPE scale_float (const TYPE& x, sintL delta)'
1685 `TYPE scale_float (const TYPE& x, const cl_I& delta)'
1686 Returns `x*2^delta'. This is more efficient than an explicit
1687 multiplication because it copies `x' and modifies the exponent.
1689 The following functions provide an abstract interface to the underlying
1690 representation of floating-point numbers.
1692 `sintL float_exponent (const TYPE& x)'
1693 Returns the exponent `e' of `x'. For `x = 0.0', this is 0. For
1694 `x' non-zero, this is the unique integer with `2^(e-1) <= abs(x) <
1697 `sintL float_radix (const TYPE& x)'
1698 Returns the base of the floating-point representation. This is
1701 `TYPE float_sign (const TYPE& x)'
1702 Returns the sign `s' of `x' as a float. The value is 1 for `x' >=
1705 `uintL float_digits (const TYPE& x)'
1706 Returns the number of mantissa bits in the floating-point
1707 representation of `x', including the hidden bit. The value only
1708 depends on the type of `x', not on its value.
1710 `uintL float_precision (const TYPE& x)'
1711 Returns the number of significant mantissa bits in the
1712 floating-point representation of `x'. Since denormalized numbers
1713 are not supported, this is the same as `float_digits(x)' if `x' is
1714 non-zero, and 0 if `x' = 0.
1716 The complete internal representation of a float is encoded in the type
1717 `decoded_float' (or `decoded_sfloat', `decoded_ffloat',
1718 `decoded_dfloat', `decoded_lfloat', respectively), defined by
1719 struct decoded_TYPEfloat {
1720 TYPE mantissa; cl_I exponent; TYPE sign;
1723 and returned by the function
1725 `decoded_TYPEfloat decode_float (const TYPE& x)'
1726 For `x' non-zero, this returns `(-1)^s', `e', `m' with `x = (-1)^s
1727 * 2^e * m' and `0.5 <= m < 1.0'. For `x' = 0, it returns
1728 `(-1)^s'=1, `e'=0, `m'=0. `e' is the same as returned by the
1729 function `float_exponent'.
1731 A complete decoding in terms of integers is provided as type
1732 struct cl_idecoded_float {
1733 cl_I mantissa; cl_I exponent; cl_I sign;
1735 by the following function:
1737 `cl_idecoded_float integer_decode_float (const TYPE& x)'
1738 For `x' non-zero, this returns `(-1)^s', `e', `m' with `x = (-1)^s
1739 * 2^e * m' and `m' an integer with `float_digits(x)' bits. For `x'
1740 = 0, it returns `(-1)^s'=1, `e'=0, `m'=0. WARNING: The exponent
1741 `e' is not the same as the one returned by the functions
1742 `decode_float' and `float_exponent'.
1744 Some other function, implemented only for class `cl_F':
1746 `cl_F float_sign (const cl_F& x, const cl_F& y)'
1747 This returns a floating point number whose precision and absolute
1748 value is that of `y' and whose sign is that of `x'. If `x' is
1749 zero, it is treated as positive. Same for `y'.
1752 File: cln.info, Node: Conversion functions, Next: Random number generators, Prev: Functions on floating-point numbers, Up: Functions on numbers
1754 Conversion functions
1755 ====================
1759 * Conversion to floating-point numbers::
1760 * Conversion to rational numbers::
1763 File: cln.info, Node: Conversion to floating-point numbers, Next: Conversion to rational numbers, Prev: Conversion functions, Up: Conversion functions
1765 Conversion to floating-point numbers
1766 ------------------------------------
1768 The type `cl_float_format_t' describes a floating-point format.
1770 `cl_float_format_t cl_float_format (uintL n)'
1771 Returns the smallest float format which guarantees at least `n'
1772 decimal digits in the mantissa (after the decimal point).
1774 `cl_float_format_t cl_float_format (const cl_F& x)'
1775 Returns the floating point format of `x'.
1777 `cl_float_format_t default_float_format'
1778 Global variable: the default float format used when converting
1779 rational numbers to floats.
1781 To convert a real number to a float, each of the types `cl_R', `cl_F',
1782 `cl_I', `cl_RA', `int', `unsigned int', `float', `double' defines the
1783 following operations:
1785 `cl_F cl_float (const TYPE&x, cl_float_format_t f)'
1786 Returns `x' as a float of format `f'.
1788 `cl_F cl_float (const TYPE&x, const cl_F& y)'
1789 Returns `x' in the float format of `y'.
1791 `cl_F cl_float (const TYPE&x)'
1792 Returns `x' as a float of format `default_float_format' if it is
1793 an exact number, or `x' itself if it is already a float.
1795 Of course, converting a number to a float can lose precision.
1797 Every floating-point format has some characteristic numbers:
1799 `cl_F most_positive_float (cl_float_format_t f)'
1800 Returns the largest (most positive) floating point number in float
1803 `cl_F most_negative_float (cl_float_format_t f)'
1804 Returns the smallest (most negative) floating point number in
1807 `cl_F least_positive_float (cl_float_format_t f)'
1808 Returns the least positive floating point number (i.e. > 0 but
1809 closest to 0) in float format `f'.
1811 `cl_F least_negative_float (cl_float_format_t f)'
1812 Returns the least negative floating point number (i.e. < 0 but
1813 closest to 0) in float format `f'.
1815 `cl_F float_epsilon (cl_float_format_t f)'
1816 Returns the smallest floating point number e > 0 such that `1+e !=
1819 `cl_F float_negative_epsilon (cl_float_format_t f)'
1820 Returns the smallest floating point number e > 0 such that `1-e !=
1824 File: cln.info, Node: Conversion to rational numbers, Prev: Conversion to floating-point numbers, Up: Conversion functions
1826 Conversion to rational numbers
1827 ------------------------------
1829 Each of the classes `cl_R', `cl_RA', `cl_F' defines the following
1832 `cl_RA rational (const TYPE& x)'
1833 Returns the value of `x' as an exact number. If `x' is already an
1834 exact number, this is `x'. If `x' is a floating-point number, the
1835 value is a rational number whose denominator is a power of 2.
1837 In order to convert back, say, `(cl_F)(cl_R)"1/3"' to `1/3', there is
1840 `cl_RA rationalize (const cl_R& x)'
1841 If `x' is a floating-point number, it actually represents an
1842 interval of real numbers, and this function returns the rational
1843 number with smallest denominator (and smallest numerator, in
1844 magnitude) which lies in this interval. If `x' is already an
1845 exact number, this function returns `x'.
1847 If `x' is any float, one has
1849 `cl_float(rational(x),x) = x'
1851 `cl_float(rationalize(x),x) = x'
1854 File: cln.info, Node: Random number generators, Next: Obfuscating operators, Prev: Conversion functions, Up: Functions on numbers
1856 Random number generators
1857 ========================
1859 A random generator is a machine which produces (pseudo-)random numbers.
1860 The include file `<cln/random.h>' defines a class `random_state' which
1861 contains the state of a random generator. If you make a copy of the
1862 random number generator, the original one and the copy will produce the
1863 same sequence of random numbers.
1865 The following functions return (pseudo-)random numbers in different
1866 formats. Calling one of these modifies the state of the random number
1867 generator in a complicated but deterministic way.
1870 random_state default_random_state
1871 contains a default random number generator. It is used when the
1872 functions below are called without `random_state' argument.
1874 `uint32 random32 (random_state& randomstate)'
1875 `uint32 random32 ()'
1876 Returns a random unsigned 32-bit number. All bits are equally
1879 `cl_I random_I (random_state& randomstate, const cl_I& n)'
1880 `cl_I random_I (const cl_I& n)'
1881 `n' must be an integer > 0. This function returns a random integer
1882 `x' in the range `0 <= x < n'.
1884 `cl_F random_F (random_state& randomstate, const cl_F& n)'
1885 `cl_F random_F (const cl_F& n)'
1886 `n' must be a float > 0. This function returns a random
1887 floating-point number of the same format as `n' in the range `0 <=
1890 `cl_R random_R (random_state& randomstate, const cl_R& n)'
1891 `cl_R random_R (const cl_R& n)'
1892 Behaves like `random_I' if `n' is an integer and like `random_F'
1896 File: cln.info, Node: Obfuscating operators, Prev: Random number generators, Up: Functions on numbers
1898 Obfuscating operators
1899 =====================
1901 The modifying C/C++ operators `+=', `-=', `*=', `/=', `&=', `|=', `^=',
1902 `<<=', `>>=' are not available by default because their use tends to
1903 make programs unreadable. It is trivial to get away without them.
1904 However, if you feel that you absolutely need these operators to get
1906 #define WANT_OBFUSCATING_OPERATORS
1907 to the beginning of your source files, before the inclusion of any CLN
1908 include files. This flag will enable the following operators:
1910 For the classes `cl_N', `cl_R', `cl_RA', `cl_F', `cl_SF', `cl_FF',
1913 `TYPE& operator += (TYPE&, const TYPE&)'
1914 `TYPE& operator -= (TYPE&, const TYPE&)'
1915 `TYPE& operator *= (TYPE&, const TYPE&)'
1916 `TYPE& operator /= (TYPE&, const TYPE&)'
1917 For the class `cl_I':
1919 `TYPE& operator += (TYPE&, const TYPE&)'
1920 `TYPE& operator -= (TYPE&, const TYPE&)'
1921 `TYPE& operator *= (TYPE&, const TYPE&)'
1922 `TYPE& operator &= (TYPE&, const TYPE&)'
1923 `TYPE& operator |= (TYPE&, const TYPE&)'
1924 `TYPE& operator ^= (TYPE&, const TYPE&)'
1925 `TYPE& operator <<= (TYPE&, const TYPE&)'
1926 `TYPE& operator >>= (TYPE&, const TYPE&)'
1927 For the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
1928 `cl_FF', `cl_DF', `cl_LF':
1930 `TYPE& operator ++ (TYPE& x)'
1931 The prefix operator `++x'.
1933 `void operator ++ (TYPE& x, int)'
1934 The postfix operator `x++'.
1936 `TYPE& operator -- (TYPE& x)'
1937 The prefix operator `--x'.
1939 `void operator -- (TYPE& x, int)'
1940 The postfix operator `x--'.
1942 Note that by using these obfuscating operators, you wouldn't gain
1943 efficiency: In CLN `x += y;' is exactly the same as `x = x+y;', not
1947 File: cln.info, Node: Input/Output, Next: Rings, Prev: Functions on numbers, Up: Top
1954 * Internal and printed representation::
1956 * Output functions::
1959 File: cln.info, Node: Internal and printed representation, Next: Input functions, Prev: Input/Output, Up: Input/Output
1961 Internal and printed representation
1962 ===================================
1964 All computations deal with the internal representations of the numbers.
1966 Every number has an external representation as a sequence of ASCII
1967 characters. Several external representations may denote the same
1968 number, for example, "20.0" and "20.000".
1970 Converting an internal to an external representation is called
1971 "printing", converting an external to an internal representation is
1972 called "reading". In CLN, it is always true that conversion of an
1973 internal to an external representation and then back to an internal
1974 representation will yield the same internal representation.
1975 Symbolically: `read(print(x)) == x'. This is called "print-read
1978 Different types of numbers have different external representations (case
1982 External representation: SIGN{DIGIT}+. The reader also accepts the
1983 Common Lisp syntaxes SIGN{DIGIT}+`.' with a trailing dot for
1984 decimal integers and the `#NR', `#b', `#o', `#x' prefixes.
1987 External representation: SIGN{DIGIT}+`/'{DIGIT}+. The `#NR',
1988 `#b', `#o', `#x' prefixes are allowed here as well.
1990 Floating-point numbers
1991 External representation: SIGN{DIGIT}*EXPONENT or
1992 SIGN{DIGIT}*`.'{DIGIT}*EXPONENT or SIGN{DIGIT}*`.'{DIGIT}+. A
1993 precision specifier of the form _PREC may be appended. There must
1994 be at least one digit in the non-exponent part. The exponent has
1995 the syntax EXPMARKER EXPSIGN {DIGIT}+. The exponent marker is
1997 `s' for short-floats,
1999 `f' for single-floats,
2001 `d' for double-floats,
2003 `L' for long-floats,
2005 or `e', which denotes a default float format. The precision
2006 specifying suffix has the syntax _PREC where PREC denotes the
2007 number of valid mantissa digits (in decimal, excluding leading
2008 zeroes), cf. also function `cl_float_format'.
2011 External representation:
2012 In algebraic notation: `REALPART+IMAGPARTi'. Of course, if
2013 IMAGPART is negative, its printed representation begins with
2014 a `-', and the `+' between REALPART and IMAGPART may be
2015 omitted. Note that this notation cannot be used when the
2016 IMAGPART is rational and the rational number's base is >18,
2017 because the `i' is then read as a digit.
2019 In Common Lisp notation: `#C(REALPART IMAGPART)'.
2022 File: cln.info, Node: Input functions, Next: Output functions, Prev: Internal and printed representation, Up: Input/Output
2027 Including `<cln/io.h>' defines a type `cl_istream', which is the type
2028 of the first argument to all input functions. `cl_istream' is the same
2033 contains the standard input stream.
2035 These are the simple input functions:
2037 `int freadchar (cl_istream stream)'
2038 Reads a character from `stream'. Returns `cl_EOF' (not a `char'!)
2039 if the end of stream was encountered or an error occurred.
2041 `int funreadchar (cl_istream stream, int c)'
2042 Puts back `c' onto `stream'. `c' must be the result of the last
2043 `freadchar' operation on `stream'.
2045 Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
2046 `cl_FF', `cl_DF', `cl_LF' defines, in `<cln/TYPE_io.h>', the following
2049 `cl_istream operator>> (cl_istream stream, TYPE& result)'
2050 Reads a number from `stream' and stores it in the `result'.
2052 The most flexible input functions, defined in `<cln/TYPE_io.h>', are
2055 `cl_N read_complex (cl_istream stream, const cl_read_flags& flags)'
2056 `cl_R read_real (cl_istream stream, const cl_read_flags& flags)'
2057 `cl_F read_float (cl_istream stream, const cl_read_flags& flags)'
2058 `cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)'
2059 `cl_I read_integer (cl_istream stream, const cl_read_flags& flags)'
2060 Reads a number from `stream'. The `flags' are parameters which
2061 affect the input syntax. Whitespace before the number is silently
2064 `cl_N read_complex (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
2065 `cl_R read_real (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
2066 `cl_F read_float (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
2067 `cl_RA read_rational (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
2068 `cl_I read_integer (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)'
2069 Reads a number from a string in memory. The `flags' are parameters
2070 which affect the input syntax. The string starts at `string' and
2071 ends at `string_limit' (exclusive limit). `string_limit' may also
2072 be `NULL', denoting the entire string, i.e. equivalent to
2073 `string_limit = string + strlen(string)'. If `end_of_parse' is
2074 `NULL', the string in memory must contain exactly one number and
2075 nothing more, else a fatal error will be signalled. If
2076 `end_of_parse' is not `NULL', `*end_of_parse' will be assigned a
2077 pointer past the last parsed character (i.e. `string_limit' if
2078 nothing came after the number). Whitespace is not allowed.
2080 The structure `cl_read_flags' contains the following fields:
2082 `cl_read_syntax_t syntax'
2083 The possible results of the read operation. Possible values are
2084 `syntax_number', `syntax_real', `syntax_rational',
2085 `syntax_integer', `syntax_float', `syntax_sfloat',
2086 `syntax_ffloat', `syntax_dfloat', `syntax_lfloat'.
2088 `cl_read_lsyntax_t lsyntax'
2089 Specifies the language-dependent syntax variant for the read
2090 operation. Possible values are
2093 accept standard algebraic notation only, no complex numbers,
2096 accept the algebraic notation `X+Yi' for complex numbers,
2098 `lsyntax_commonlisp'
2099 accept the `#b', `#o', `#x' syntaxes for binary, octal,
2100 hexadecimal numbers, `#BASER' for rational numbers in a given
2101 base, `#c(REALPART IMAGPART)' for complex numbers,
2104 accept all of these extensions.
2106 `unsigned int rational_base'
2107 The base in which rational numbers are read.
2109 `cl_float_format_t float_flags.default_float_format'
2110 The float format used when reading floats with exponent marker `e'.
2112 `cl_float_format_t float_flags.default_lfloat_format'
2113 The float format used when reading floats with exponent marker `l'.
2115 `cl_boolean float_flags.mantissa_dependent_float_format'
2116 When this flag is true, floats specified with more digits than
2117 corresponding to the exponent marker they contain, but without
2118 _NNN suffix, will get a precision corresponding to their number of
2122 File: cln.info, Node: Output functions, Prev: Input functions, Up: Input/Output
2127 Including `<cln/io.h>' defines a type `cl_ostream', which is the type
2128 of the first argument to all output functions. `cl_ostream' is the same
2133 contains the standard output stream.
2137 contains the standard error output stream.
2139 These are the simple output functions:
2141 `void fprintchar (cl_ostream stream, char c)'
2142 Prints the character `x' literally on the `stream'.
2144 `void fprint (cl_ostream stream, const char * string)'
2145 Prints the `string' literally on the `stream'.
2147 `void fprintdecimal (cl_ostream stream, int x)'
2148 `void fprintdecimal (cl_ostream stream, const cl_I& x)'
2149 Prints the integer `x' in decimal on the `stream'.
2151 `void fprintbinary (cl_ostream stream, const cl_I& x)'
2152 Prints the integer `x' in binary (base 2, without prefix) on the
2155 `void fprintoctal (cl_ostream stream, const cl_I& x)'
2156 Prints the integer `x' in octal (base 8, without prefix) on the
2159 `void fprinthexadecimal (cl_ostream stream, const cl_I& x)'
2160 Prints the integer `x' in hexadecimal (base 16, without prefix) on
2163 Each of the classes `cl_N', `cl_R', `cl_RA', `cl_I', `cl_F', `cl_SF',
2164 `cl_FF', `cl_DF', `cl_LF' defines, in `<cln/TYPE_io.h>', the following
2167 `void fprint (cl_ostream stream, const TYPE& x)'
2168 `cl_ostream operator<< (cl_ostream stream, const TYPE& x)'
2169 Prints the number `x' on the `stream'. The output may depend on
2170 the global printer settings in the variable `default_print_flags'.
2171 The `ostream' flags and settings (flags, width and locale) are
2174 The most flexible output function, defined in `<cln/TYPE_io.h>', are
2176 void print_complex (cl_ostream stream, const cl_print_flags& flags,
2178 void print_real (cl_ostream stream, const cl_print_flags& flags,
2180 void print_float (cl_ostream stream, const cl_print_flags& flags,
2182 void print_rational (cl_ostream stream, const cl_print_flags& flags,
2184 void print_integer (cl_ostream stream, const cl_print_flags& flags,
2186 Prints the number `x' on the `stream'. The `flags' are parameters which
2189 The structure type `cl_print_flags' contains the following fields:
2191 `unsigned int rational_base'
2192 The base in which rational numbers are printed. Default is `10'.
2194 `cl_boolean rational_readably'
2195 If this flag is true, rational numbers are printed with radix
2196 specifiers in Common Lisp syntax (`#NR' or `#b' or `#o' or `#x'
2197 prefixes, trailing dot). Default is false.
2199 `cl_boolean float_readably'
2200 If this flag is true, type specific exponent markers have
2201 precedence over 'E'. Default is false.
2203 `cl_float_format_t default_float_format'
2204 Floating point numbers of this format will be printed using the
2205 'E' exponent marker. Default is `cl_float_format_ffloat'.
2207 `cl_boolean complex_readably'
2208 If this flag is true, complex numbers will be printed using the
2209 Common Lisp syntax `#C(REALPART IMAGPART)'. Default is false.
2211 `cl_string univpoly_varname'
2212 Univariate polynomials with no explicit indeterminate name will be
2213 printed using this variable name. Default is `"x"'.
2215 The global variable `default_print_flags' contains the default values,
2216 used by the function `fprint'.
2219 File: cln.info, Node: Rings, Next: Modular integers, Prev: Input/Output, Up: Top
2224 CLN has a class of abstract rings.
2230 Rings can be compared for equality:
2232 `bool operator== (const cl_ring&, const cl_ring&)'
2233 `bool operator!= (const cl_ring&, const cl_ring&)'
2234 These compare two rings for equality.
2236 Given a ring `R', the following members can be used.
2238 `void R->fprint (cl_ostream stream, const cl_ring_element& x)'
2239 `cl_boolean R->equal (const cl_ring_element& x, const cl_ring_element& y)'
2240 `cl_ring_element R->zero ()'
2241 `cl_boolean R->zerop (const cl_ring_element& x)'
2242 `cl_ring_element R->plus (const cl_ring_element& x, const cl_ring_element& y)'
2243 `cl_ring_element R->minus (const cl_ring_element& x, const cl_ring_element& y)'
2244 `cl_ring_element R->uminus (const cl_ring_element& x)'
2245 `cl_ring_element R->one ()'
2246 `cl_ring_element R->canonhom (const cl_I& x)'
2247 `cl_ring_element R->mul (const cl_ring_element& x, const cl_ring_element& y)'
2248 `cl_ring_element R->square (const cl_ring_element& x)'
2249 `cl_ring_element R->expt_pos (const cl_ring_element& x, const cl_I& y)'
2250 The following rings are built-in.
2252 `cl_null_ring cl_0_ring'
2253 The null ring, containing only zero.
2255 `cl_complex_ring cl_C_ring'
2256 The ring of complex numbers. This corresponds to the type `cl_N'.
2258 `cl_real_ring cl_R_ring'
2259 The ring of real numbers. This corresponds to the type `cl_R'.
2261 `cl_rational_ring cl_RA_ring'
2262 The ring of rational numbers. This corresponds to the type `cl_RA'.
2264 `cl_integer_ring cl_I_ring'
2265 The ring of integers. This corresponds to the type `cl_I'.
2267 Type tests can be performed for any of `cl_C_ring', `cl_R_ring',
2268 `cl_RA_ring', `cl_I_ring':
2270 `cl_boolean instanceof (const cl_number& x, const cl_number_ring& R)'
2271 Tests whether the given number is an element of the number ring R.
2274 File: cln.info, Node: Modular integers, Next: Symbolic data types, Prev: Rings, Up: Top
2281 * Modular integer rings::
2282 * Functions on modular integers::
2285 File: cln.info, Node: Modular integer rings, Next: Functions on modular integers, Prev: Modular integers, Up: Modular integers
2287 Modular integer rings
2288 =====================
2290 CLN implements modular integers, i.e. integers modulo a fixed integer N.
2291 The modulus is explicitly part of every modular integer. CLN doesn't
2292 allow you to (accidentally) mix elements of different modular rings,
2293 e.g. `(3 mod 4) + (2 mod 5)' will result in a runtime error. (Ideally
2294 one would imagine a generic data type `cl_MI(N)', but C++ doesn't have
2295 generic types. So one has to live with runtime checks.)
2297 The class of modular integer rings is
2304 Modular integer ring
2308 and the class of all modular integers (elements of modular integer
2315 Modular integer rings are constructed using the function
2317 `cl_modint_ring find_modint_ring (const cl_I& N)'
2318 This function returns the modular ring `Z/NZ'. It takes care of
2319 finding out about special cases of `N', like powers of two and odd
2320 numbers for which Montgomery multiplication will be a win, and
2321 precomputes any necessary auxiliary data for computing modulo `N'.
2322 There is a cache table of rings, indexed by `N' (or, more
2323 precisely, by `abs(N)'). This ensures that the precomputation
2324 costs are reduced to a minimum.
2326 Modular integer rings can be compared for equality:
2328 `bool operator== (const cl_modint_ring&, const cl_modint_ring&)'
2329 `bool operator!= (const cl_modint_ring&, const cl_modint_ring&)'
2330 These compare two modular integer rings for equality. Two
2331 different calls to `find_modint_ring' with the same argument
2332 necessarily return the same ring because it is memoized in the
2336 File: cln.info, Node: Functions on modular integers, Prev: Modular integer rings, Up: Modular integers
2338 Functions on modular integers
2339 =============================
2341 Given a modular integer ring `R', the following members can be used.
2344 This is the ring's modulus, normalized to be nonnegative: `abs(N)'.
2347 This returns `0 mod N'.
2350 This returns `1 mod N'.
2352 `cl_MI R->canonhom (const cl_I& x)'
2353 This returns `x mod N'.
2355 `cl_I R->retract (const cl_MI& x)'
2356 This is a partial inverse function to `R->canonhom'. It returns the
2357 standard representative (`>=0', `<N') of `x'.
2359 `cl_MI R->random(random_state& randomstate)'
2361 This returns a random integer modulo `N'.
2363 The following operations are defined on modular integers.
2365 `cl_modint_ring x.ring ()'
2366 Returns the ring to which the modular integer `x' belongs.
2368 `cl_MI operator+ (const cl_MI&, const cl_MI&)'
2369 Returns the sum of two modular integers. One of the arguments may
2370 also be a plain integer.
2372 `cl_MI operator- (const cl_MI&, const cl_MI&)'
2373 Returns the difference of two modular integers. One of the
2374 arguments may also be a plain integer.
2376 `cl_MI operator- (const cl_MI&)'
2377 Returns the negative of a modular integer.
2379 `cl_MI operator* (const cl_MI&, const cl_MI&)'
2380 Returns the product of two modular integers. One of the arguments
2381 may also be a plain integer.
2383 `cl_MI square (const cl_MI&)'
2384 Returns the square of a modular integer.
2386 `cl_MI recip (const cl_MI& x)'
2387 Returns the reciprocal `x^-1' of a modular integer `x'. `x' must
2388 be coprime to the modulus, otherwise an error message is issued.
2390 `cl_MI div (const cl_MI& x, const cl_MI& y)'
2391 Returns the quotient `x*y^-1' of two modular integers `x', `y'.
2392 `y' must be coprime to the modulus, otherwise an error message is
2395 `cl_MI expt_pos (const cl_MI& x, const cl_I& y)'
2396 `y' must be > 0. Returns `x^y'.
2398 `cl_MI expt (const cl_MI& x, const cl_I& y)'
2399 Returns `x^y'. If `y' is negative, `x' must be coprime to the
2400 modulus, else an error message is issued.
2402 `cl_MI operator<< (const cl_MI& x, const cl_I& y)'
2405 `cl_MI operator>> (const cl_MI& x, const cl_I& y)'
2406 Returns `x*2^-y'. When `y' is positive, the modulus must be odd,
2407 or an error message is issued.
2409 `bool operator== (const cl_MI&, const cl_MI&)'
2410 `bool operator!= (const cl_MI&, const cl_MI&)'
2411 Compares two modular integers, belonging to the same modular
2412 integer ring, for equality.
2414 `cl_boolean zerop (const cl_MI& x)'
2415 Returns true if `x' is `0 mod N'.
2417 The following output functions are defined (see also the chapter on
2420 `void fprint (cl_ostream stream, const cl_MI& x)'
2421 `cl_ostream operator<< (cl_ostream stream, const cl_MI& x)'
2422 Prints the modular integer `x' on the `stream'. The output may
2423 depend on the global printer settings in the variable
2424 `default_print_flags'.
2427 File: cln.info, Node: Symbolic data types, Next: Univariate polynomials, Prev: Modular integers, Up: Top
2432 CLN implements two symbolic (non-numeric) data types: strings and
2441 File: cln.info, Node: Strings, Next: Symbols, Prev: Symbolic data types, Up: Symbolic data types
2452 implements immutable strings.
2454 Strings are constructed through the following constructors:
2456 `cl_string (const char * s)'
2457 Returns an immutable copy of the (zero-terminated) C string `s'.
2459 `cl_string (const char * ptr, unsigned long len)'
2460 Returns an immutable copy of the `len' characters at `ptr[0]',
2461 ..., `ptr[len-1]'. NUL characters are allowed.
2463 The following functions are available on strings:
2466 Assignment from `cl_string' and `const char *'.
2470 Returns the length of the string `s'.
2473 Returns the `i'th character of the string `s'. `i' must be in the
2474 range `0 <= i < s.length()'.
2476 `bool equal (const cl_string& s1, const cl_string& s2)'
2477 Compares two strings for equality. One of the arguments may also
2478 be a plain `const char *'.
2481 File: cln.info, Node: Symbols, Prev: Strings, Up: Symbolic data types
2486 Symbols are uniquified strings: all symbols with the same name are
2487 shared. This means that comparison of two symbols is fast (effectively
2488 just a pointer comparison), whereas comparison of two strings must in
2489 the worst case walk both strings until their end. Symbols are used,
2490 for example, as tags for properties, as names of variables in
2491 polynomial rings, etc.
2493 Symbols are constructed through the following constructor:
2495 `cl_symbol (const cl_string& s)'
2496 Looks up or creates a new symbol with a given name.
2498 The following operations are available on symbols:
2500 `cl_string (const cl_symbol& sym)'
2501 Conversion to `cl_string': Returns the string which names the
2504 `bool equal (const cl_symbol& sym1, const cl_symbol& sym2)'
2505 Compares two symbols for equality. This is very fast.
2508 File: cln.info, Node: Univariate polynomials, Next: Internals, Prev: Symbolic data types, Up: Top
2510 Univariate polynomials
2511 **********************
2515 * Univariate polynomial rings::
2516 * Functions on univariate polynomials::
2517 * Special polynomials::
2520 File: cln.info, Node: Univariate polynomial rings, Next: Functions on univariate polynomials, Prev: Univariate polynomials, Up: Univariate polynomials
2522 Univariate polynomial rings
2523 ===========================
2525 CLN implements univariate polynomials (polynomials in one variable)
2526 over an arbitrary ring. The indeterminate variable may be either
2527 unnamed (and will be printed according to
2528 `default_print_flags.univpoly_varname', which defaults to `x') or carry
2529 a given name. The base ring and the indeterminate are explicitly part
2530 of every polynomial. CLN doesn't allow you to (accidentally) mix
2531 elements of different polynomial rings, e.g. `(a^2+1) * (b^3-1)' will
2532 result in a runtime error. (Ideally this should return a multivariate
2533 polynomial, but they are not yet implemented in CLN.)
2535 The classes of univariate polynomial rings are
2542 Univariate polynomial ring
2546 +----------------+-------------------+
2548 Complex polynomial ring | Modular integer polynomial ring
2549 cl_univpoly_complex_ring | cl_univpoly_modint_ring
2550 <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
2554 Real polynomial ring |
2555 cl_univpoly_real_ring |
2556 <cln/univpoly_real.h> |
2560 Rational polynomial ring |
2561 cl_univpoly_rational_ring |
2562 <cln/univpoly_rational.h> |
2566 Integer polynomial ring
2567 cl_univpoly_integer_ring
2568 <cln/univpoly_integer.h>
2570 and the corresponding classes of univariate polynomials are
2572 Univariate polynomial
2576 +----------------+-------------------+
2578 Complex polynomial | Modular integer polynomial
2580 <cln/univpoly_complex.h> | <cln/univpoly_modint.h>
2586 <cln/univpoly_real.h> |
2590 Rational polynomial |
2592 <cln/univpoly_rational.h> |
2598 <cln/univpoly_integer.h>
2600 Univariate polynomial rings are constructed using the functions
2602 `cl_univpoly_ring find_univpoly_ring (const cl_ring& R)'
2603 `cl_univpoly_ring find_univpoly_ring (const cl_ring& R, const cl_symbol& varname)'
2604 This function returns the polynomial ring `R[X]', unnamed or named.
2605 `R' may be an arbitrary ring. This function takes care of finding
2606 out about special cases of `R', such as the rings of complex
2607 numbers, real numbers, rational numbers, integers, or modular
2608 integer rings. There is a cache table of rings, indexed by `R'
2609 and `varname'. This ensures that two calls of this function with
2610 the same arguments will return the same polynomial ring.
2612 `cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R)'
2613 `cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)'
2614 `cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R)'
2615 `cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)'
2616 `cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R)'
2617 `cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)'
2618 `cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R)'
2619 `cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)'
2620 `cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R)'
2621 `cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname)'
2622 These functions are equivalent to the general `find_univpoly_ring',
2623 only the return type is more specific, according to the base
2627 File: cln.info, Node: Functions on univariate polynomials, Next: Special polynomials, Prev: Univariate polynomial rings, Up: Univariate polynomials
2629 Functions on univariate polynomials
2630 ===================================
2632 Given a univariate polynomial ring `R', the following members can be
2635 `cl_ring R->basering()'
2636 This returns the base ring, as passed to `find_univpoly_ring'.
2639 This returns `0 in R', a polynomial of degree -1.
2642 This returns `1 in R', a polynomial of degree <= 0.
2644 `cl_UP R->canonhom (const cl_I& x)'
2645 This returns `x in R', a polynomial of degree <= 0.
2647 `cl_UP R->monomial (const cl_ring_element& x, uintL e)'
2648 This returns a sparse polynomial: `x * X^e', where `X' is the
2651 `cl_UP R->create (sintL degree)'
2652 Creates a new polynomial with a given degree. The zero polynomial
2653 has degree `-1'. After creating the polynomial, you should put in
2654 the coefficients, using the `set_coeff' member function, and then
2655 call the `finalize' member function.
2657 The following are the only destructive operations on univariate
2660 `void set_coeff (cl_UP& x, uintL index, const cl_ring_element& y)'
2661 This changes the coefficient of `X^index' in `x' to be `y'. After
2662 changing a polynomial and before applying any "normal" operation
2663 on it, you should call its `finalize' member function.
2665 `void finalize (cl_UP& x)'
2666 This function marks the endpoint of destructive modifications of a
2667 polynomial. It normalizes the internal representation so that
2668 subsequent computations have less overhead. Doing normal
2669 computations on unnormalized polynomials may produce wrong results
2670 or crash the program.
2672 The following operations are defined on univariate polynomials.
2674 `cl_univpoly_ring x.ring ()'
2675 Returns the ring to which the univariate polynomial `x' belongs.
2677 `cl_UP operator+ (const cl_UP&, const cl_UP&)'
2678 Returns the sum of two univariate polynomials.
2680 `cl_UP operator- (const cl_UP&, const cl_UP&)'
2681 Returns the difference of two univariate polynomials.
2683 `cl_UP operator- (const cl_UP&)'
2684 Returns the negative of a univariate polynomial.
2686 `cl_UP operator* (const cl_UP&, const cl_UP&)'
2687 Returns the product of two univariate polynomials. One of the
2688 arguments may also be a plain integer or an element of the base
2691 `cl_UP square (const cl_UP&)'
2692 Returns the square of a univariate polynomial.
2694 `cl_UP expt_pos (const cl_UP& x, const cl_I& y)'
2695 `y' must be > 0. Returns `x^y'.
2697 `bool operator== (const cl_UP&, const cl_UP&)'
2698 `bool operator!= (const cl_UP&, const cl_UP&)'
2699 Compares two univariate polynomials, belonging to the same
2700 univariate polynomial ring, for equality.
2702 `cl_boolean zerop (const cl_UP& x)'
2703 Returns true if `x' is `0 in R'.
2705 `sintL degree (const cl_UP& x)'
2706 Returns the degree of the polynomial. The zero polynomial has
2709 `cl_ring_element coeff (const cl_UP& x, uintL index)'
2710 Returns the coefficient of `X^index' in the polynomial `x'.
2712 `cl_ring_element x (const cl_ring_element& y)'
2713 Evaluation: If `x' is a polynomial and `y' belongs to the base
2714 ring, then `x(y)' returns the value of the substitution of `y' into
2717 `cl_UP deriv (const cl_UP& x)'
2718 Returns the derivative of the polynomial `x' with respect to the
2721 The following output functions are defined (see also the chapter on
2724 `void fprint (cl_ostream stream, const cl_UP& x)'
2725 `cl_ostream operator<< (cl_ostream stream, const cl_UP& x)'
2726 Prints the univariate polynomial `x' on the `stream'. The output
2727 may depend on the global printer settings in the variable
2728 `default_print_flags'.
2731 File: cln.info, Node: Special polynomials, Prev: Functions on univariate polynomials, Up: Univariate polynomials
2736 The following functions return special polynomials.
2738 `cl_UP_I tschebychev (sintL n)'
2739 Returns the n-th Chebyshev polynomial (n >= 0).
2741 `cl_UP_I hermite (sintL n)'
2742 Returns the n-th Hermite polynomial (n >= 0).
2744 `cl_UP_RA legendre (sintL n)'
2745 Returns the n-th Legendre polynomial (n >= 0).
2747 `cl_UP_I laguerre (sintL n)'
2748 Returns the n-th Laguerre polynomial (n >= 0).
2750 Information how to derive the differential equation satisfied by each
2751 of these polynomials from their definition can be found in the
2752 `doc/polynomial/' directory.
2755 File: cln.info, Node: Internals, Next: Using the library, Prev: Univariate polynomials, Up: Top
2763 * Memory efficiency::
2764 * Speed efficiency::
2765 * Garbage collection::
2768 File: cln.info, Node: Why C++ ?, Next: Memory efficiency, Prev: Internals, Up: Internals
2773 Using C++ as an implementation language provides
2775 * Efficiency: It compiles to machine code.
2777 * Portability: It runs on all platforms supporting a C++ compiler.
2778 Because of the availability of GNU C++, this includes all
2779 currently used 32-bit and 64-bit platforms, independently of the
2780 quality of the vendor's C++ compiler.
2782 * Type safety: The C++ compilers knows about the number types and
2783 complains if, for example, you try to assign a float to an integer
2784 variable. However, a drawback is that C++ doesn't know about
2785 generic types, hence a restriction like that `operator+ (const
2786 cl_MI&, const cl_MI&)' requires that both arguments belong to the
2787 same modular ring cannot be expressed as a compile-time
2790 * Algebraic syntax: The elementary operations `+', `-', `*', `=',
2791 `==', ... can be used in infix notation, which is more convenient
2792 than Lisp notation `(+ x y)' or C notation `add(x,y,&z)'.
2794 With these language features, there is no need for two separate
2795 languages, one for the implementation of the library and one in which
2796 the library's users can program. This means that a prototype
2797 implementation of an algorithm can be integrated into the library
2798 immediately after it has been tested and debugged. No need to rewrite
2799 it in a low-level language after having prototyped in a high-level
2803 File: cln.info, Node: Memory efficiency, Next: Speed efficiency, Prev: Why C++ ?, Up: Internals
2808 In order to save memory allocations, CLN implements:
2810 * Object sharing: An operation like `x+0' returns `x' without copying
2813 * Garbage collection: A reference counting mechanism makes sure that
2814 any number object's storage is freed immediately when the last
2815 reference to the object is gone.
2817 * Small integers are represented as immediate values instead of
2818 pointers to heap allocated storage. This means that integers `>
2819 -2^29', `< 2^29' don't consume heap memory, unless they were
2820 explicitly allocated on the heap.
2823 File: cln.info, Node: Speed efficiency, Next: Garbage collection, Prev: Memory efficiency, Up: Internals
2828 Speed efficiency is obtained by the combination of the following tricks
2831 * Small integers, being represented as immediate values, don't
2832 require memory access, just a couple of instructions for each
2833 elementary operation.
2835 * The kernel of CLN has been written in assembly language for some
2836 CPUs (`i386', `m68k', `sparc', `mips', `arm').
2838 * On all CPUs, CLN may be configured to use the superefficient
2839 low-level routines from GNU GMP version 3.
2841 * For large numbers, CLN uses, instead of the standard `O(N^2)'
2842 algorithm, the Karatsuba multiplication, which is an `O(N^1.6)'
2845 * For very large numbers (more than 12000 decimal digits), CLN uses
2846 Schönhage-Strassen multiplication, which is an asymptotically
2847 optimal multiplication algorithm.
2849 * These fast multiplication algorithms also give improvements in the
2850 speed of division and radix conversion.
2853 File: cln.info, Node: Garbage collection, Prev: Speed efficiency, Up: Internals
2858 All the number classes are reference count classes: They only contain a
2859 pointer to an object in the heap. Upon construction, assignment and
2860 destruction of number objects, only the objects' reference count are
2863 Memory occupied by number objects are automatically reclaimed as soon as
2864 their reference count drops to zero.
2866 For number rings, another strategy is implemented: There is a cache of,
2867 for example, the modular integer rings. A modular integer ring is
2868 destroyed only if its reference count dropped to zero and the cache is
2869 about to be resized. The effect of this strategy is that recently used
2870 rings remain cached, whereas undue memory consumption through cached
2874 File: cln.info, Node: Using the library, Next: Customizing, Prev: Internals, Up: Top
2879 For the following discussion, we will assume that you have installed
2880 the CLN source in `$CLN_DIR' and built it in `$CLN_TARGETDIR'. For
2881 example, for me it's `CLN_DIR="$HOME/cln"' and
2882 `CLN_TARGETDIR="$HOME/cln/linuxelf"'. You might define these as
2883 environment variables, or directly substitute the appropriate values.
2887 * Compiler options::
2888 * Compatibility to old CLN versions::
2891 * Debugging support::
2894 File: cln.info, Node: Compiler options, Next: Compatibility to old CLN versions, Prev: Using the library, Up: Using the library
2899 Until you have installed CLN in a public place, the following options
2902 When you compile CLN application code, add the flags
2903 -I$CLN_DIR/include -I$CLN_TARGETDIR/include
2904 to the C++ compiler's command line (`make' variable CFLAGS or CXXFLAGS).
2905 When you link CLN application code to form an executable, add the flags
2906 $CLN_TARGETDIR/src/libcln.a
2907 to the C/C++ compiler's command line (`make' variable LIBS).
2909 If you did a `make install', the include files are installed in a
2910 public directory (normally `/usr/local/include'), hence you don't need
2911 special flags for compiling. The library has been installed to a public
2912 directory as well (normally `/usr/local/lib'), hence when linking a CLN
2913 application it is sufficient to give the flag `-lcln'.
2916 File: cln.info, Node: Compatibility to old CLN versions, Next: Include files, Prev: Compiler options, Up: Using the library
2918 Compatibility to old CLN versions
2919 =================================
2921 As of CLN version 1.1 all non-macro identifiers were hidden in namespace
2922 `cln' in order to avoid potential name clashes with other C++
2923 libraries. If you have an old application, you will have to manually
2924 port it to the new scheme. The following principles will help during
2926 * All headers are now in a separate subdirectory. Instead of
2927 including `cl_'SOMETHING`.h', include `cln/'SOMETHING`.h' now.
2929 * All public identifiers (typenames and functions) have lost their
2930 `cl_' prefix. Exceptions are all the typenames of number types,
2931 (cl_N, cl_I, cl_MI, ...), rings, symbolic types (cl_string,
2932 cl_symbol) and polynomials (cl_UP_TYPE). (This is because their
2933 names would not be mnemonic enough once the namespace `cln' is
2934 imported. Even in a namespace we favor `cl_N' over `N'.)
2936 * All public _functions_ that had by a `cl_' in their name still
2937 carry that `cl_' if it is intrinsic part of a typename (as in
2939 When developing other libraries, please keep in mind not to import the
2940 namespace `cln' in one of your public header files by saying `using
2941 namespace cln;'. This would propagate to other applications and can
2942 cause name clashes there.
2945 File: cln.info, Node: Include files, Next: An Example, Prev: Compatibility to old CLN versions, Up: Using the library
2950 Here is a summary of the include files and their contents.
2953 General definitions, reference counting, garbage collection.
2956 The class cl_number.
2959 Functions for class cl_N, the complex numbers.
2962 Functions for class cl_R, the real numbers.
2965 Functions for class cl_F, the floats.
2968 Functions for class cl_SF, the short-floats.
2971 Functions for class cl_FF, the single-floats.
2974 Functions for class cl_DF, the double-floats.
2977 Functions for class cl_LF, the long-floats.
2980 Functions for class cl_RA, the rational numbers.
2983 Functions for class cl_I, the integers.
2988 `<cln/complex_io.h>'
2989 Input/Output for class cl_N, the complex numbers.
2992 Input/Output for class cl_R, the real numbers.
2995 Input/Output for class cl_F, the floats.
2998 Input/Output for class cl_SF, the short-floats.
3001 Input/Output for class cl_FF, the single-floats.
3004 Input/Output for class cl_DF, the double-floats.
3007 Input/Output for class cl_LF, the long-floats.
3009 `<cln/rational_io.h>'
3010 Input/Output for class cl_RA, the rational numbers.
3012 `<cln/integer_io.h>'
3013 Input/Output for class cl_I, the integers.
3016 Flags for customizing input operations.
3019 Flags for customizing output operations.
3022 `malloc_hook', `free_hook'.
3028 Conditions/exceptions.
3045 `<cln/complex_ring.h>'
3046 The ring of complex numbers.
3049 The ring of real numbers.
3051 `<cln/rational_ring.h>'
3052 The ring of rational numbers.
3054 `<cln/integer_ring.h>'
3055 The ring of integers.
3058 Number threory functions.
3060 `<cln/modinteger.h>'
3070 General vectors over cl_number.
3072 `<cln/GV_complex.h>'
3073 General vectors over cl_N.
3076 General vectors over cl_R.
3078 `<cln/GV_rational.h>'
3079 General vectors over cl_RA.
3081 `<cln/GV_integer.h>'
3082 General vectors over cl_I.
3084 `<cln/GV_modinteger.h>'
3085 General vectors of modular integers.
3091 Simple vectors over cl_number.
3093 `<cln/SV_complex.h>'
3094 Simple vectors over cl_N.
3097 Simple vectors over cl_R.
3099 `<cln/SV_rational.h>'
3100 Simple vectors over cl_RA.
3102 `<cln/SV_integer.h>'
3103 Simple vectors over cl_I.
3105 `<cln/SV_ringelt.h>'
3106 Simple vectors of general ring elements.
3109 Univariate polynomials.
3111 `<cln/univpoly_integer.h>'
3112 Univariate polynomials over the integers.
3114 `<cln/univpoly_rational.h>'
3115 Univariate polynomials over the rational numbers.
3117 `<cln/univpoly_real.h>'
3118 Univariate polynomials over the real numbers.
3120 `<cln/univpoly_complex.h>'
3121 Univariate polynomials over the complex numbers.
3123 `<cln/univpoly_modint.h>'
3124 Univariate polynomials over modular integer rings.
3130 Includes all of the above.
3133 File: cln.info, Node: An Example, Next: Debugging support, Prev: Include files, Up: Using the library
3138 A function which computes the nth Fibonacci number can be written as
3141 #include <cln/integer.h>
3142 #include <cln/real.h>
3143 using namespace cln;
3145 // Returns F_n, computed as the nearest integer to
3146 // ((1+sqrt(5))/2)^n/sqrt(5). Assume n>=0.
3147 const cl_I fibonacci (int n)
3149 // Need a precision of ((1+sqrt(5))/2)^-n.
3150 cl_float_format_t prec = cl_float_format((int)(0.208987641*n+5));
3151 cl_R sqrt5 = sqrt(cl_float(5,prec));
3152 cl_R phi = (1+sqrt5)/2;
3153 return round1( expt(phi,n)/sqrt5 );
3156 Let's explain what is going on in detail.
3158 The include file `<cln/integer.h>' is necessary because the type `cl_I'
3159 is used in the function, and the include file `<cln/real.h>' is needed
3160 for the type `cl_R' and the floating point number functions. The order
3161 of the include files does not matter. In order not to write out
3162 `cln::'FOO we can safely import the whole namespace `cln'.
3164 Then comes the function declaration. The argument is an `int', the
3165 result an integer. The return type is defined as `const cl_I', not
3166 simply `cl_I', because that allows the compiler to detect typos like
3167 `fibonacci(n) = 100'. It would be possible to declare the return type
3168 as `const cl_R' (real number) or even `const cl_N' (complex number). We
3169 use the most specialized possible return type because functions which
3170 call `fibonacci' will be able to profit from the compiler's type
3171 analysis: Adding two integers is slightly more efficient than adding the
3172 same objects declared as complex numbers, because it needs less type
3173 dispatch. Also, when linking to CLN as a non-shared library, this
3174 minimizes the size of the resulting executable program.
3176 The result will be computed as expt(phi,n)/sqrt(5), rounded to the
3177 nearest integer. In order to get a correct result, the absolute error
3178 should be less than 1/2, i.e. the relative error should be less than
3179 sqrt(5)/(2*expt(phi,n)). To this end, the first line computes a
3180 floating point precision for sqrt(5) and phi.
3182 Then sqrt(5) is computed by first converting the integer 5 to a
3183 floating point number and than taking the square root. The converse,
3184 first taking the square root of 5, and then converting to the desired
3185 precision, would not work in CLN: The square root would be computed to
3186 a default precision (normally single-float precision), and the
3187 following conversion could not help about the lacking accuracy. This is
3188 because CLN is not a symbolic computer algebra system and does not
3189 represent sqrt(5) in a non-numeric way.
3191 The type `cl_R' for sqrt5 and, in the following line, phi is the only
3192 possible choice. You cannot write `cl_F' because the C++ compiler can
3193 only infer that `cl_float(5,prec)' is a real number. You cannot write
3194 `cl_N' because a `round1' does not exist for general complex numbers.
3196 When the function returns, all the local variables in the function are
3197 automatically reclaimed (garbage collected). Only the result survives
3198 and gets passed to the caller.
3200 The file `fibonacci.cc' in the subdirectory `examples' contains this
3201 implementation together with an even faster algorithm.
3204 File: cln.info, Node: Debugging support, Prev: An Example, Up: Using the library
3209 When debugging a CLN application with GNU `gdb', two facilities are
3210 available from the library:
3212 * The library does type checks, range checks, consistency checks at
3213 many places. When one of these fails, the function `cl_abort()' is
3214 called. Its default implementation is to perform an `exit(1)', so
3215 you won't have a core dump. But for debugging, it is best to set a
3216 breakpoint at this function:
3217 (gdb) break cl_abort
3218 When this breakpoint is hit, look at the stack's backtrace:
3221 * The debugger's normal `print' command doesn't know about CLN's
3222 types and therefore prints mostly useless hexadecimal addresses.
3223 CLN offers a function `cl_print', callable from the debugger, for
3224 printing number objects. In order to get this function, you have
3225 to define the macro `CL_DEBUG' and then include all the header
3226 files for which you want `cl_print' debugging support. For example:
3228 #include <cln/string.h>
3229 Now, if you have in your program a variable `cl_string s', and
3230 inspect it under `gdb', the output may look like this:
3232 $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
3233 word = 134568800}}, }
3234 (gdb) call cl_print(s)
3237 Note that the output of `cl_print' goes to the program's error
3238 output, not to gdb's standard output.
3240 Note, however, that the above facility does not work with all CLN
3241 types, only with number objects and similar. Therefore CLN offers
3242 a member function `debug_print()' on all CLN types. The same macro
3243 `CL_DEBUG' is needed for this member function to be implemented.
3244 Under `gdb', you call it like this:
3246 $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
3247 word = 134568800}}, }
3248 (gdb) call s.debug_print()
3251 >call ($1).debug_print()
3255 Unfortunately, this feature does not seem to work under all
3259 File: cln.info, Node: Customizing, Next: Index, Prev: Using the library, Up: Top
3267 * Floating-point underflow::
3269 * Customizing the memory allocator::
3272 File: cln.info, Node: Error handling, Next: Floating-point underflow, Prev: Customizing, Up: Customizing
3277 When a fatal error occurs, an error message is output to the standard
3278 error output stream, and the function `cl_abort' is called. The default
3279 version of this function (provided in the library) terminates the
3280 application. To catch such a fatal error, you need to define the
3281 function `cl_abort' yourself, with the prototype
3282 #include <cln/abort.h>
3283 void cl_abort (void);
3284 This function must not return control to its caller.
3287 File: cln.info, Node: Floating-point underflow, Next: Customizing I/O, Prev: Error handling, Up: Customizing
3289 Floating-point underflow
3290 ========================
3292 Floating point underflow denotes the situation when a floating-point
3293 number is to be created which is so close to `0' that its exponent is
3294 too low to be represented internally. By default, this causes a fatal
3295 error. If you set the global variable
3296 cl_boolean cl_inhibit_floating_point_underflow
3297 to `cl_true', the error will be inhibited, and a floating-point zero
3298 will be generated instead. The default value of
3299 `cl_inhibit_floating_point_underflow' is `cl_false'.
3302 File: cln.info, Node: Customizing I/O, Next: Customizing the memory allocator, Prev: Floating-point underflow, Up: Customizing
3307 The output of the function `fprint' may be customized by changing the
3308 value of the global variable `default_print_flags'.
3311 File: cln.info, Node: Customizing the memory allocator, Prev: Customizing I/O, Up: Customizing
3313 Customizing the memory allocator
3314 ================================
3316 Every memory allocation of CLN is done through the function pointer
3317 `malloc_hook'. Freeing of this memory is done through the function
3318 pointer `free_hook'. The default versions of these functions, provided
3319 in the library, call `malloc' and `free' and check the `malloc' result
3320 against `NULL'. If you want to provide another memory allocator, you
3321 need to define the variables `malloc_hook' and `free_hook' yourself,
3323 #include <cln/malloc.h>
3325 void* (*malloc_hook) (size_t size) = ...;
3326 void (*free_hook) (void* ptr) = ...;
3328 The `cl_malloc_hook' function must not return a `NULL' pointer.
3330 It is not possible to change the memory allocator at runtime, because
3331 it is already called at program startup by the constructors of some
3335 File: cln.info, Node: Index, Prev: Customizing, Up: Top
3342 * abs (): Elementary functions.
3343 * abstract class: Ordinary number types.
3344 * acos (): Trigonometric functions.
3345 * acosh (): Hyperbolic functions.
3346 * advocacy: Why C++ ?.
3347 * Archimedes' constant: Trigonometric functions.
3348 * As()(): Conversions.
3349 * ash (): Logical functions.
3350 * asin: Trigonometric functions.
3351 * asin (): Trigonometric functions.
3352 * asinh (): Hyperbolic functions.
3353 * atan: Trigonometric functions.
3354 * atan (): Trigonometric functions.
3355 * atanh (): Hyperbolic functions.
3356 * basering (): Functions on univariate polynomials.
3357 * binomial (): Combinatorial functions.
3358 * boole (): Logical functions.
3359 * boole_1: Logical functions.
3360 * boole_2: Logical functions.
3361 * boole_and: Logical functions.
3362 * boole_andc1: Logical functions.
3363 * boole_andc2: Logical functions.
3364 * boole_c1: Logical functions.
3365 * boole_c2: Logical functions.
3366 * boole_clr: Logical functions.
3367 * boole_eqv: Logical functions.
3368 * boole_nand: Logical functions.
3369 * boole_nor: Logical functions.
3370 * boole_orc1: Logical functions.
3371 * boole_orc2: Logical functions.
3372 * boole_set: Logical functions.
3373 * boole_xor: Logical functions.
3374 * canonhom () <1>: Functions on univariate polynomials.
3375 * canonhom () <2>: Functions on modular integers.
3376 * canonhom (): Rings.
3377 * Catalan's constant: Euler gamma.
3378 * catalanconst (): Euler gamma.
3379 * ceiling1 (): Rounding functions.
3380 * ceiling2 (): Rounding functions.
3381 * Chebyshev polynomial: Special polynomials.
3382 * cis (): Trigonometric functions.
3383 * cl_abort (): Error handling.
3384 * cl_byte: Logical functions.
3385 * CL_DEBUG: Debugging support.
3386 * cl_DF: Floating-point numbers.
3387 * cl_DF_fdiv_t: Rounding functions.
3388 * cl_F <1>: Floating-point numbers.
3389 * cl_F: Ordinary number types.
3390 * cl_F_fdiv_t: Rounding functions.
3391 * cl_FF: Floating-point numbers.
3392 * cl_FF_fdiv_t: Rounding functions.
3393 * cl_float (): Conversion to floating-point numbers.
3394 * cl_float_format (): Conversion to floating-point numbers.
3395 * cl_float_format_t: Conversion to floating-point numbers.
3396 * cl_I_to_int (): Conversions.
3397 * cl_I_to_long (): Conversions.
3398 * cl_I_to_uint (): Conversions.
3399 * cl_I_to_ulong (): Conversions.
3400 * cl_idecoded_float: Functions on floating-point numbers.
3401 * cl_LF: Floating-point numbers.
3402 * cl_LF_fdiv_t: Rounding functions.
3403 * cl_modint_ring: Modular integer rings.
3404 * cl_N: Ordinary number types.
3405 * cl_number: Ordinary number types.
3406 * cl_R: Ordinary number types.
3407 * cl_R_fdiv_t: Rounding functions.
3408 * cl_RA: Ordinary number types.
3409 * cl_SF: Floating-point numbers.
3410 * cl_SF_fdiv_t: Rounding functions.
3411 * cl_string: Strings.
3412 * cl_symbol: Symbols.
3413 * coeff (): Functions on univariate polynomials.
3414 * compare (): Comparisons.
3415 * comparison: Comparisons.
3416 * compatibility: Compatibility to old CLN versions.
3417 * compiler options: Compiler options.
3418 * complex (): Elementary complex functions.
3419 * complex number <1>: Complex numbers.
3420 * complex number: Ordinary number types.
3421 * conjugate (): Elementary complex functions.
3422 * conversion <1>: Conversion functions.
3423 * conversion: Conversions.
3424 * cos (): Trigonometric functions.
3425 * cos_sin (): Trigonometric functions.
3426 * cos_sin_t: Trigonometric functions.
3427 * cosh (): Hyperbolic functions.
3428 * cosh_sinh (): Hyperbolic functions.
3429 * cosh_sinh_t: Hyperbolic functions.
3430 * create (): Functions on univariate polynomials.
3431 * customizing: Customizing.
3432 * debug_print (): Debugging support.
3433 * debugging: Debugging support.
3434 * decode_float (): Functions on floating-point numbers.
3435 * decoded_dfloat: Functions on floating-point numbers.
3436 * decoded_ffloat: Functions on floating-point numbers.
3437 * decoded_float: Functions on floating-point numbers.
3438 * decoded_lfloat: Functions on floating-point numbers.
3439 * decoded_sfloat: Functions on floating-point numbers.
3440 * default_float_format: Conversion to floating-point numbers.
3441 * default_print_flags: Customizing I/O.
3442 * default_random_state: Random number generators.
3443 * degree (): Functions on univariate polynomials.
3444 * denominator (): Elementary rational functions.
3445 * deposit_field (): Logical functions.
3446 * deriv (): Functions on univariate polynomials.
3447 * div (): Functions on modular integers.
3448 * double_approx (): Conversions.
3449 * doublefactorial (): Combinatorial functions.
3450 * dpb (): Logical functions.
3451 * equal () <1>: Symbols.
3452 * equal () <2>: Strings.
3454 * equal_hashcode (): Comparisons.
3455 * Euler's constant: Euler gamma.
3456 * eulerconst (): Euler gamma.
3457 * evenp (): Logical functions.
3458 * exact number: Exact numbers.
3459 * exp (): Exponential and logarithmic functions.
3460 * exp1 (): Exponential and logarithmic functions.
3461 * expt () <1>: Functions on modular integers.
3462 * expt () <2>: Exponential and logarithmic functions.
3463 * expt (): Elementary functions.
3464 * expt_pos () <1>: Functions on univariate polynomials.
3465 * expt_pos () <2>: Functions on modular integers.
3466 * expt_pos () <3>: Rings.
3467 * expt_pos (): Elementary functions.
3468 * exquo (): Elementary functions.
3469 * factorial (): Combinatorial functions.
3470 * fceiling (): Rounding functions.
3471 * fceiling2 (): Rounding functions.
3472 * ffloor (): Rounding functions.
3473 * ffloor2 (): Rounding functions.
3474 * Fibonacci number: An Example.
3475 * finalize (): Functions on univariate polynomials.
3476 * find_modint_ring (): Modular integer rings.
3477 * find_univpoly_ring (): Univariate polynomial rings.
3478 * float_approx (): Conversions.
3479 * float_digits (): Functions on floating-point numbers.
3480 * float_epsilon (): Conversion to floating-point numbers.
3481 * float_exponent (): Functions on floating-point numbers.
3482 * float_negative_epsilon (): Conversion to floating-point numbers.
3483 * float_precision (): Functions on floating-point numbers.
3484 * float_radix (): Functions on floating-point numbers.
3485 * float_sign (): Functions on floating-point numbers.
3486 * floating-point number: Floating-point numbers.
3487 * floor1 (): Rounding functions.
3488 * floor2 (): Rounding functions.
3489 * fprint () <1>: Functions on univariate polynomials.
3490 * fprint () <2>: Functions on modular integers.
3492 * free_hook (): Customizing the memory allocator.
3493 * fround (): Rounding functions.
3494 * fround2 (): Rounding functions.
3495 * ftruncate (): Rounding functions.
3496 * ftruncate2 (): Rounding functions.
3497 * garbage collection <1>: Garbage collection.
3498 * garbage collection: Memory efficiency.
3499 * gcd (): Number theoretic functions.
3500 * GMP <1>: Using the GNU MP Library.
3501 * GMP: Introduction.
3502 * header files: Include files.
3503 * hermite (): Special polynomials.
3504 * Hermite polynomial: Special polynomials.
3505 * imagpart (): Elementary complex functions.
3506 * include files: Include files.
3507 * Input/Output: Input/Output.
3508 * installation: Installing the library.
3509 * instanceof (): Rings.
3510 * integer: Ordinary number types.
3511 * integer_decode_float (): Functions on floating-point numbers.
3512 * integer_length (): Logical functions.
3514 * laguerre (): Special polynomials.
3515 * Laguerre polynomial: Special polynomials.
3516 * lcm (): Number theoretic functions.
3517 * ldb (): Logical functions.
3518 * ldb_test (): Logical functions.
3519 * least_negative_float (): Conversion to floating-point numbers.
3520 * least_positive_float (): Conversion to floating-point numbers.
3521 * Legende polynomial: Special polynomials.
3522 * legendre (): Special polynomials.
3523 * length (): Strings.
3524 * ln (): Exponential and logarithmic functions.
3525 * log (): Exponential and logarithmic functions.
3526 * logand (): Logical functions.
3527 * logandc1 (): Logical functions.
3528 * logandc2 (): Logical functions.
3529 * logbitp (): Logical functions.
3530 * logcount (): Logical functions.
3531 * logeqv (): Logical functions.
3532 * logior (): Logical functions.
3533 * lognand (): Logical functions.
3534 * lognor (): Logical functions.
3535 * lognot (): Logical functions.
3536 * logorc1 (): Logical functions.
3537 * logorc2 (): Logical functions.
3538 * logp (): Number theoretic functions.
3539 * logtest (): Logical functions.
3540 * logxor (): Logical functions.
3541 * make: Make utility.
3542 * malloc_hook (): Customizing the memory allocator.
3543 * mask_field (): Logical functions.
3544 * max (): Comparisons.
3545 * min (): Comparisons.
3547 * minus1 (): Elementary functions.
3548 * minusp (): Comparisons.
3549 * mod (): Rounding functions.
3550 * modifying operators: Obfuscating operators.
3551 * modular integer: Modular integers.
3552 * modulus: Functions on modular integers.
3553 * monomial (): Functions on univariate polynomials.
3554 * Montgomery multiplication: Modular integer rings.
3555 * most_negative_float (): Conversion to floating-point numbers.
3556 * most_positive_float (): Conversion to floating-point numbers.
3558 * namespace <1>: Compatibility to old CLN versions.
3559 * namespace: Introduction.
3560 * numerator (): Elementary rational functions.
3561 * oddp (): Logical functions.
3562 * one () <1>: Functions on univariate polynomials.
3563 * one () <2>: Functions on modular integers.
3565 * operator != () <1>: Functions on univariate polynomials.
3566 * operator != () <2>: Functions on modular integers.
3567 * operator != () <3>: Modular integer rings.
3568 * operator != (): Comparisons.
3569 * operator & (): Logical functions.
3570 * operator &= (): Obfuscating operators.
3571 * operator () (): Functions on univariate polynomials.
3572 * operator * () <1>: Functions on univariate polynomials.
3573 * operator * () <2>: Functions on modular integers.
3574 * operator * (): Elementary functions.
3575 * operator *= (): Obfuscating operators.
3576 * operator + () <1>: Functions on univariate polynomials.
3577 * operator + () <2>: Functions on modular integers.
3578 * operator + (): Elementary functions.
3579 * operator ++ (): Obfuscating operators.
3580 * operator += (): Obfuscating operators.
3581 * operator - () <1>: Functions on univariate polynomials.
3582 * operator - () <2>: Functions on modular integers.
3583 * operator - (): Elementary functions.
3584 * operator -- (): Obfuscating operators.
3585 * operator -= (): Obfuscating operators.
3586 * operator / (): Elementary functions.
3587 * operator /= (): Obfuscating operators.
3588 * operator < (): Comparisons.
3589 * operator << () <1>: Functions on univariate polynomials.
3590 * operator << () <2>: Functions on modular integers.
3591 * operator << (): Logical functions.
3592 * operator <<= (): Obfuscating operators.
3593 * operator <= (): Comparisons.
3594 * operator == () <1>: Functions on univariate polynomials.
3595 * operator == () <2>: Functions on modular integers.
3596 * operator == () <3>: Modular integer rings.
3597 * operator == (): Comparisons.
3598 * operator > (): Comparisons.
3599 * operator >= (): Comparisons.
3600 * operator >> () <1>: Functions on modular integers.
3601 * operator >> (): Logical functions.
3602 * operator >>= (): Obfuscating operators.
3603 * operator [] (): Strings.
3604 * operator ^ (): Logical functions.
3605 * operator ^= (): Obfuscating operators.
3606 * operator | (): Logical functions.
3607 * operator |= (): Obfuscating operators.
3608 * operator ~ (): Logical functions.
3609 * ord2 (): Logical functions.
3610 * phase (): Exponential and logarithmic functions.
3611 * pi: Trigonometric functions.
3612 * pi (): Trigonometric functions.
3614 * plus1 (): Elementary functions.
3615 * plusp (): Comparisons.
3616 * polynomial: Univariate polynomials.
3617 * portability: Why C++ ?.
3618 * power2p (): Logical functions.
3619 * printing: Internal and printed representation.
3620 * random (): Functions on modular integers.
3621 * random32 (): Random number generators.
3622 * random_F (): Random number generators.
3623 * random_I (): Random number generators.
3624 * random_R (): Random number generators.
3625 * random_state: Random number generators.
3626 * rational (): Conversion to rational numbers.
3627 * rational number: Ordinary number types.
3628 * rationalize (): Conversion to rational numbers.
3629 * reading: Internal and printed representation.
3630 * real number: Ordinary number types.
3631 * realpart (): Elementary complex functions.
3632 * recip () <1>: Functions on modular integers.
3633 * recip (): Elementary functions.
3634 * reference counting: Memory efficiency.
3635 * rem (): Rounding functions.
3636 * representation: Internal and printed representation.
3637 * retract (): Functions on modular integers.
3638 * Riemann's zeta: Riemann zeta.
3639 * ring: Modular integer rings.
3640 * ring () <1>: Functions on univariate polynomials.
3641 * ring (): Functions on modular integers.
3643 * round1 (): Rounding functions.
3644 * round2 (): Rounding functions.
3645 * rounding: Rounding functions.
3646 * rounding error: Floating-point numbers.
3647 * Rubik's cube: Conversions.
3648 * scale_float (): Functions on floating-point numbers.
3649 * Schönhage-Strassen multiplication <1>: Speed efficiency.
3650 * Schönhage-Strassen multiplication: Introduction.
3652 * set_coeff (): Functions on univariate polynomials.
3653 * signum (): Elementary functions.
3654 * sin (): Trigonometric functions.
3655 * sinh (): Hyperbolic functions.
3658 * square () <1>: Functions on univariate polynomials.
3659 * square () <2>: Functions on modular integers.
3660 * square () <3>: Rings.
3661 * square (): Elementary functions.
3663 * strlen (): Strings.
3665 * symbolic type: Symbolic data types.
3666 * tan (): Trigonometric functions.
3667 * tanh (): Hyperbolic functions.
3668 * The()(): Conversions.
3669 * transcendental functions: Transcendental functions.
3670 * truncate1 (): Rounding functions.
3671 * truncate2 (): Rounding functions.
3672 * tschebychev (): Special polynomials.
3674 * underflow: Floating-point underflow.
3675 * univariate polynomial: Univariate polynomials.
3676 * WANT_OBFUSCATING_OPERATORS: Obfuscating operators.
3677 * xgcd (): Number theoretic functions.
3678 * zero () <1>: Functions on univariate polynomials.
3679 * zero () <2>: Functions on modular integers.
3681 * zerop () <1>: Functions on univariate polynomials.
3682 * zerop () <2>: Functions on modular integers.
3683 * zerop () <3>: Rings.
3684 * zerop (): Comparisons.
3685 * zeta (): Riemann zeta.
3691 Node: Introduction
\7f3191
3692 Node: Installation
\7f5812
3693 Node: Prerequisites
\7f6106
3694 Node: C++ compiler
\7f6304
3695 Node: Make utility
\7f7016
3696 Node: Sed utility
\7f7202
3697 Node: Building the library
\7f7522
3698 Node: Using the GNU MP Library
\7f10745
3699 Node: Installing the library
\7f11621
3700 Node: Cleaning up
\7f12344
3701 Node: Ordinary number types
\7f12669
3702 Node: Exact numbers
\7f15022
3703 Node: Floating-point numbers
\7f16187
3704 Node: Complex numbers
\7f19766
3705 Node: Conversions
\7f20263
3706 Node: Functions on numbers
\7f23723
3707 Node: Constructing numbers
\7f24427
3708 Node: Constructing integers
\7f24799
3709 Node: Constructing rational numbers
\7f25089
3710 Node: Constructing floating-point numbers
\7f25564
3711 Node: Constructing complex numbers
\7f26684
3712 Node: Elementary functions
\7f27048
3713 Node: Elementary rational functions
\7f29517
3714 Node: Elementary complex functions
\7f30089
3715 Node: Comparisons
\7f30917
3716 Node: Rounding functions
\7f32810
3718 Node: Transcendental functions
\7f40468
3719 Node: Exponential and logarithmic functions
\7f41024
3720 Node: Trigonometric functions
\7f43029
3721 Node: Hyperbolic functions
\7f46359
3722 Node: Euler gamma
\7f48423
3723 Node: Riemann zeta
\7f49315
3724 Node: Functions on integers
\7f49859
3725 Node: Logical functions
\7f50147
3726 Node: Number theoretic functions
\7f56100
3727 Node: Combinatorial functions
\7f57467
3728 Node: Functions on floating-point numbers
\7f58145
3729 Node: Conversion functions
\7f61355
3730 Node: Conversion to floating-point numbers
\7f61635
3731 Node: Conversion to rational numbers
\7f63852
3732 Node: Random number generators
\7f64906
3733 Node: Obfuscating operators
\7f66557
3734 Node: Input/Output
\7f68287
3735 Node: Internal and printed representation
\7f68497
3736 Node: Input functions
\7f71039
3737 Node: Output functions
\7f75524
3739 Node: Modular integers
\7f81108
3740 Node: Modular integer rings
\7f81308
3741 Node: Functions on modular integers
\7f83393
3742 Node: Symbolic data types
\7f86397
3743 Node: Strings
\7f86660
3744 Node: Symbols
\7f87725
3745 Node: Univariate polynomials
\7f88627
3746 Node: Univariate polynomial rings
\7f88885
3747 Node: Functions on univariate polynomials
\7f93801
3748 Node: Special polynomials
\7f97576
3749 Node: Internals
\7f98283
3750 Node: Why C++ ?
\7f98497
3751 Node: Memory efficiency
\7f99997
3752 Node: Speed efficiency
\7f100695
3753 Node: Garbage collection
\7f101779
3754 Node: Using the library
\7f102606
3755 Node: Compiler options
\7f103178
3756 Node: Compatibility to old CLN versions
\7f104116
3757 Node: Include files
\7f105537
3758 Node: An Example
\7f109252
3759 Node: Debugging support
\7f112518
3760 Node: Customizing
\7f114869
3761 Node: Error handling
\7f115097
3762 Node: Floating-point underflow
\7f115672
3763 Node: Customizing I/O
\7f116311
3764 Node: Customizing the memory allocator
\7f116601
3765 Node: Index
\7f117585
git://www.ginac.de / cln.git / blob