<html lang="en">
<head>
<title>CLN, a Class Library for Numbers</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="CLN, a Class Library for Numbers">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="top" href="#Top">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Top"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
</div>
<h2 class="unnumbered">CLN</h2>
<!-- For `info' only. -->
<p>This manual documents <span class="sc">cln</span>, a Class Library for Numbers.
<p>Published by Bruno Haible, <code><haible@clisp.cons.org></code> and
Richard B. Kreckel, <code><kreckel@ginac.de></code>.
<p>Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008.
Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009.
Copyright (C) Alexei Sheplyakov 2008.
<p>Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
<p>Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.
<p>Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the author.
<!-- For TeX only. -->
<!-- prevent ugly black rectangles on overfull hbox lines: -->
<ul class="menu">
<li><a accesskey="1" href="#Introduction">Introduction</a>
<li><a accesskey="2" href="#Installation">Installation</a>
<li><a accesskey="3" href="#Ordinary-number-types">Ordinary number types</a>
<li><a accesskey="4" href="#Functions-on-numbers">Functions on numbers</a>
<li><a accesskey="5" href="#Input_002fOutput">Input/Output</a>
<li><a accesskey="6" href="#Rings">Rings</a>
<li><a accesskey="7" href="#Modular-integers">Modular integers</a>
<li><a accesskey="8" href="#Symbolic-data-types">Symbolic data types</a>
<li><a accesskey="9" href="#Univariate-polynomials">Univariate polynomials</a>
<li><a href="#Internals">Internals</a>
<li><a href="#Using-the-library">Using the library</a>
<li><a href="#Customizing">Customizing</a>
<li><a href="#Index">Index</a>
</li></ul>
<p>--- The Detailed Node Listing ---
<p>Installation
</p>
<ul class="menu">
<li><a href="#Prerequisites">Prerequisites</a>
<li><a href="#Building-the-library">Building the library</a>
<li><a href="#Installing-the-library">Installing the library</a>
<li><a href="#Cleaning-up">Cleaning up</a>
</li></ul>
<p>Prerequisites
</p>
<ul class="menu">
<li><a href="#C_002b_002b-compiler">C++ compiler</a>
<li><a href="#Make-utility">Make utility</a>
<li><a href="#Sed-utility">Sed utility</a>
</li></ul>
<p>Building the library
</p>
<ul class="menu">
<li><a href="#Using-the-GNU-MP-Library">Using the GNU MP Library</a>
</li></ul>
<p>Ordinary number types
</p>
<ul class="menu">
<li><a href="#Exact-numbers">Exact numbers</a>
<li><a href="#Floating_002dpoint-numbers">Floating-point numbers</a>
<li><a href="#Complex-numbers">Complex numbers</a>
<li><a href="#Conversions">Conversions</a>
</li></ul>
<p>Functions on numbers
</p>
<ul class="menu">
<li><a href="#Constructing-numbers">Constructing numbers</a>
<li><a href="#Elementary-functions">Elementary functions</a>
<li><a href="#Elementary-rational-functions">Elementary rational functions</a>
<li><a href="#Elementary-complex-functions">Elementary complex functions</a>
<li><a href="#Comparisons">Comparisons</a>
<li><a href="#Rounding-functions">Rounding functions</a>
<li><a href="#Roots">Roots</a>
<li><a href="#Transcendental-functions">Transcendental functions</a>
<li><a href="#Functions-on-integers">Functions on integers</a>
<li><a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a>
<li><a href="#Conversion-functions">Conversion functions</a>
<li><a href="#Random-number-generators">Random number generators</a>
<li><a href="#Modifying-operators">Modifying operators</a>
</li></ul>
<p>Constructing numbers
</p>
<ul class="menu">
<li><a href="#Constructing-integers">Constructing integers</a>
<li><a href="#Constructing-rational-numbers">Constructing rational numbers</a>
<li><a href="#Constructing-floating_002dpoint-numbers">Constructing floating-point numbers</a>
<li><a href="#Constructing-complex-numbers">Constructing complex numbers</a>
</li></ul>
<p>Transcendental functions
</p>
<ul class="menu">
<li><a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a>
<li><a href="#Trigonometric-functions">Trigonometric functions</a>
<li><a href="#Hyperbolic-functions">Hyperbolic functions</a>
<li><a href="#Euler-gamma">Euler gamma</a>
<li><a href="#Riemann-zeta">Riemann zeta</a>
</li></ul>
<p>Functions on integers
</p>
<ul class="menu">
<li><a href="#Logical-functions">Logical functions</a>
<li><a href="#Number-theoretic-functions">Number theoretic functions</a>
<li><a href="#Combinatorial-functions">Combinatorial functions</a>
</li></ul>
<p>Conversion functions
</p>
<ul class="menu">
<li><a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a>
<li><a href="#Conversion-to-rational-numbers">Conversion to rational numbers</a>
</li></ul>
<p>Input/Output
</p>
<ul class="menu">
<li><a href="#Internal-and-printed-representation">Internal and printed representation</a>
<li><a href="#Input-functions">Input functions</a>
<li><a href="#Output-functions">Output functions</a>
</li></ul>
<p>Modular integers
</p>
<ul class="menu">
<li><a href="#Modular-integer-rings">Modular integer rings</a>
<li><a href="#Functions-on-modular-integers">Functions on modular integers</a>
</li></ul>
<p>Symbolic data types
</p>
<ul class="menu">
<li><a href="#Strings">Strings</a>
<li><a href="#Symbols">Symbols</a>
</li></ul>
<p>Univariate polynomials
</p>
<ul class="menu">
<li><a href="#Univariate-polynomial-rings">Univariate polynomial rings</a>
<li><a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a>
<li><a href="#Special-polynomials">Special polynomials</a>
</li></ul>
<p>Internals
</p>
<ul class="menu">
<li><a href="#Why-C_002b_002b-_003f">Why C++ ?</a>
<li><a href="#Memory-efficiency">Memory efficiency</a>
<li><a href="#Speed-efficiency">Speed efficiency</a>
<li><a href="#Garbage-collection">Garbage collection</a>
</li></ul>
<p>Using the library
</p>
<ul class="menu">
<li><a href="#Compiler-options">Compiler options</a>
<li><a href="#Include-files">Include files</a>
<li><a href="#An-Example">An Example</a>
<li><a href="#Debugging-support">Debugging support</a>
<li><a href="#Reporting-Problems">Reporting Problems</a>
</li></ul>
<p>Customizing
</p>
<ul class="menu">
<li><a href="#Error-handling">Error handling</a>
<li><a href="#Floating_002dpoint-underflow">Floating-point underflow</a>
<li><a href="#Customizing-I_002fO">Customizing I/O</a>
<li><a href="#Customizing-the-memory-allocator">Customizing the memory allocator</a>
</ul>
<div class="node">
<a name="Introduction"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Installation">Installation</a>,
Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">1 Introduction</h2>
<p class="noindent">CLN is a library for computations with all kinds of numbers.
It has a rich set of number classes:
<ul>
<li>Integers (with unlimited precision),
<li>Rational numbers,
<li>Floating-point numbers:
<ul>
<li>Short float,
<li>Single float,
<li>Double float,
<li>Long float (with unlimited precision),
</ul>
<li>Complex numbers,
<li>Modular integers (integers modulo a fixed integer),
<li>Univariate polynomials.
</ul>
<p class="noindent">The subtypes of the complex numbers among these are exactly the
types of numbers known to the Common Lisp language. Therefore
<code>CLN</code> can be used for Common Lisp implementations, giving
‘<samp><span class="samp">CLN</span></samp>’ another meaning: it becomes an abbreviation of
“Common Lisp Numbers”.
<p class="noindent">The CLN package implements
<ul>
<li>Elementary functions (<code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>sqrt</code>,
comparisons, <small class="dots">...</small>),
<li>Logical functions (logical <code>and</code>, <code>or</code>, <code>not</code>, <small class="dots">...</small>),
<li>Transcendental functions (exponential, logarithmic, trigonometric, hyperbolic
functions and their inverse functions).
</ul>
<p class="noindent">CLN is a C++ library. Using C++ as an implementation language provides
<ul>
<li>efficiency: it compiles to machine code,
<li>type safety: the C++ compiler knows about the number types and complains
if, for example, you try to assign a float to an integer variable.
<li>algebraic syntax: You can use the <code>+</code>, <code>-</code>, <code>*</code>, <code>=</code>,
<code>==</code>, <small class="dots">...</small> operators as in C or C++.
</ul>
<p class="noindent">CLN is memory efficient:
<ul>
<li>Small integers and short floats are immediate, not heap allocated.
<li>Heap-allocated memory is reclaimed through an automatic, non-interruptive
garbage collection.
</ul>
<p class="noindent">CLN is speed efficient:
<ul>
<li>The kernel of CLN has been written in assembly language for some CPUs
(<code>i386</code>, <code>m68k</code>, <code>sparc</code>, <code>mips</code>, <code>arm</code>).
<li><a name="index-GMP-1"></a>On all CPUs, CLN may be configured to use the superefficient low-level
routines from GNU GMP version 3.
<li>It uses Karatsuba multiplication, which is significantly faster
for large numbers than the standard multiplication algorithm.
<li>For very large numbers (more than 12000 decimal digits), it uses
multiplication, which is an asymptotically optimal multiplication
algorithm, for multiplication, division and radix conversion.
<li><a name="index-binary-splitting-2"></a>It uses binary splitting for fast evaluation of series of rational
numbers as they occur in the evaluation of elementary functions and some
constants.
</ul>
<p class="noindent">CLN aims at being easily integrated into larger software packages:
<ul>
<li>The garbage collection imposes no burden on the main application.
<li>The library provides hooks for memory allocation and throws exceptions
in case of errors.
<li><a name="index-namespace-3"></a>All non-macro identifiers are hidden in namespace <code>cln</code> in
order to avoid name clashes.
</ul>
<div class="node">
<a name="Installation"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Ordinary-number-types">Ordinary number types</a>,
Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">2 Installation</h2>
<p>This section describes how to install the CLN package on your system.
<ul class="menu">
<li><a accesskey="1" href="#Prerequisites">Prerequisites</a>
<li><a accesskey="2" href="#Building-the-library">Building the library</a>
<li><a accesskey="3" href="#Installing-the-library">Installing the library</a>
<li><a accesskey="4" href="#Cleaning-up">Cleaning up</a>
</ul>
<div class="node">
<a name="Prerequisites"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Building-the-library">Building the library</a>,
Previous: <a rel="previous" accesskey="p" href="#Installation">Installation</a>,
Up: <a rel="up" accesskey="u" href="#Installation">Installation</a>
</div>
<h3 class="section">2.1 Prerequisites</h3>
<ul class="menu">
<li><a accesskey="1" href="#C_002b_002b-compiler">C++ compiler</a>
<li><a accesskey="2" href="#Make-utility">Make utility</a>
<li><a accesskey="3" href="#Sed-utility">Sed utility</a>
</ul>
<div class="node">
<a name="C++-compiler"></a>
<a name="C_002b_002b-compiler"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Make-utility">Make utility</a>,
Up: <a rel="up" accesskey="u" href="#Prerequisites">Prerequisites</a>
</div>
<h4 class="subsection">2.1.1 C++ compiler</h4>
<p>To build CLN, you need a C++ compiler.
Actually, you need GNU <code>g++ 3.0.0</code> or newer.
<p>The following C++ features are used:
classes, member functions, overloading of functions and operators,
constructors and destructors, inline, const, multiple inheritance,
templates and namespaces.
<p>The following C++ features are not used:
<code>new</code>, <code>delete</code>, virtual inheritance.
<p>CLN relies on semi-automatic ordering of initializations of static and
global variables, a feature which I could implement for GNU g++
only. Also, it is not known whether this semi-automatic ordering works
on all platforms when a non-GNU assembler is being used.
<div class="node">
<a name="Make-utility"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Sed-utility">Sed utility</a>,
Previous: <a rel="previous" accesskey="p" href="#C_002b_002b-compiler">C++ compiler</a>,
Up: <a rel="up" accesskey="u" href="#Prerequisites">Prerequisites</a>
</div>
<h4 class="subsection">2.1.2 Make utility</h4>
<p><a name="index-g_t_0040code_007bmake_007d-4"></a>
To build CLN, you also need to have GNU <code>make</code> installed.
<p>Only GNU <code>make</code> 3.77 is unusable for CLN; other versions work fine.
<div class="node">
<a name="Sed-utility"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Make-utility">Make utility</a>,
Up: <a rel="up" accesskey="u" href="#Prerequisites">Prerequisites</a>
</div>
<h4 class="subsection">2.1.3 Sed utility</h4>
<p><a name="index-g_t_0040code_007bsed_007d-5"></a>
To build CLN on HP-UX, you also need to have GNU <code>sed</code> installed.
This is because the libtool script, which creates the CLN library, relies
on <code>sed</code>, and the vendor's <code>sed</code> utility on these systems is too
limited.
<div class="node">
<a name="Building-the-library"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Installing-the-library">Installing the library</a>,
Previous: <a rel="previous" accesskey="p" href="#Prerequisites">Prerequisites</a>,
Up: <a rel="up" accesskey="u" href="#Installation">Installation</a>
</div>
<h3 class="section">2.2 Building the library</h3>
<p>As with any autoconfiguring GNU software, installation is as easy as this:
<pre class="example"> $ ./configure
$ make
$ make check
</pre>
<p>If on your system, ‘<samp><span class="samp">make</span></samp>’ is not GNU <code>make</code>, you have to use
‘<samp><span class="samp">gmake</span></samp>’ instead of ‘<samp><span class="samp">make</span></samp>’ above.
<p>The <code>configure</code> command checks out some features of your system and
C++ compiler and builds the <code>Makefile</code>s. The <code>make</code> command
builds the library. This step may take about half an hour on an average
workstation. The <code>make check</code> runs some test to check that no
important subroutine has been miscompiled.
<p>The <code>configure</code> command accepts options. To get a summary of them, try
<pre class="example"> $ ./configure --help
</pre>
<p>Some of the options are explained in detail in the ‘<samp><span class="samp">INSTALL.generic</span></samp>’ file.
<p>You can specify the C compiler, the C++ compiler and their options through
the following environment variables when running <code>configure</code>:
<dl>
<dt><code>CC</code><dd>Specifies the C compiler.
<br><dt><code>CFLAGS</code><dd>Flags to be given to the C compiler when compiling programs (not when linking).
<br><dt><code>CXX</code><dd>Specifies the C++ compiler.
<br><dt><code>CXXFLAGS</code><dd>Flags to be given to the C++ compiler when compiling programs (not when linking).
<br><dt><code>CPPFLAGS</code><dd>Flags to be given to the C/C++ preprocessor.
<br><dt><code>LDFLAGS</code><dd>Flags to be given to the linker.
</dl>
<p>Examples:
<pre class="example"> $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
</pre>
<pre class="example"> $ CC="gcc -V 3.2.3" CFLAGS="-O2 -finline-limit=1000" \
CXX="g++ -V 3.2.3" CXXFLAGS="-O2 -finline-limit=1000" \
CPPFLAGS="-DNO_ASM" ./configure
</pre>
<pre class="example"> $ CC="gcc-4.2" CFLAGS="-O2" CXX="g++-4.2" CXXFLAGS="-O2" ./configure
</pre>
<p>Note that for these environment variables to take effect, you have to set
them (assuming a Bourne-compatible shell) on the same line as the
<code>configure</code> command. If you made the settings in earlier shell
commands, you have to <code>export</code> the environment variables before
calling <code>configure</code>. In a <code>csh</code> shell, you have to use the
‘<samp><span class="samp">setenv</span></samp>’ command for setting each of the environment variables.
<p>Currently CLN works only with the GNU <code>g++</code> compiler, and only in
optimizing mode. So you should specify at least <code>-O</code> in the
CXXFLAGS, or no CXXFLAGS at all. If CXXFLAGS is not set, CLN will be
compiled with <code>-O</code>.
<p>The assembler language kernel can be turned off by specifying
<code>-DNO_ASM</code> in the CPPFLAGS. If <code>make check</code> reports any
problems, you may try to clean up (see <a href="#Cleaning-up">Cleaning up</a>) and configure
and compile again, this time with <code>-DNO_ASM</code>.
<p>If you use <code>g++</code> 3.2.x or earlier, I recommend adding
‘<samp><span class="samp">-finline-limit=1000</span></samp>’ to the CXXFLAGS. This is essential for good
code.
<p>If you use <code>g++</code> from gcc-3.0.4 or older on Sparc, add either
‘<samp><span class="samp">-O</span></samp>’, ‘<samp><span class="samp">-O1</span></samp>’ or ‘<samp><span class="samp">-O2 -fno-schedule-insns</span></samp>’ to the
CXXFLAGS. With full ‘<samp><span class="samp">-O2</span></samp>’, <code>g++</code> miscompiles the division
routines. Also, do not use gcc-3.0 on Sparc for compiling CLN, it
won't work at all.
<p>Also, please do not compile CLN with <code>g++</code> using the <code>-O3</code>
optimization level. This leads to inferior code quality.
<p>Some newer versions of <code>g++</code> require quite an amount of memory.
You might need some swap space if your machine doesn't have 512 MB of
RAM.
<p>By default, both a shared and a static library are built. You can build
CLN as a static (or shared) library only, by calling <code>configure</code>
with the option ‘<samp><span class="samp">--disable-shared</span></samp>’ (or ‘<samp><span class="samp">--disable-static</span></samp>’).
While shared libraries are usually more convenient to use, they may not
work on all architectures. Try disabling them if you run into linker
problems. Also, they are generally slightly slower than static
libraries so runtime-critical applications should be linked statically.
<ul class="menu">
<li><a accesskey="1" href="#Using-the-GNU-MP-Library">Using the GNU MP Library</a>
</ul>
<div class="node">
<a name="Using-the-GNU-MP-Library"></a>
<p><hr>
Up: <a rel="up" accesskey="u" href="#Building-the-library">Building the library</a>
</div>
<h4 class="subsection">2.2.1 Using the GNU MP Library</h4>
<p><a name="index-GMP-6"></a>
CLN may be configured to make use of a preinstalled <code>gmp</code> library
for some low-level routines. Please make sure that you have at least
<code>gmp</code> version 3.0 installed since earlier versions are unsupported
and likely not to work. Using <code>gmp</code> is known to be quite a boost
for CLN's performance.
<p>By default, CLN will autodetect <code>gmp</code> and use it. If you do not
want CLN to make use of a preinstalled <code>gmp</code> library, then you can
explicitly specify so by calling <code>configure</code> with the option
‘<samp><span class="samp">--without-gmp</span></samp>’.
<p>If you have installed the <code>gmp</code> library and its header files in
some place where the compiler cannot find it by default, you must help
<code>configure</code> and specify the prefix that was used when <code>gmp</code>
was configured. Here is an example:
<pre class="example"> $ ./configure --with-gmp=/opt/gmp-4.2.2
</pre>
<p>This assumes that the <code>gmp</code> header files have been installed in
<samp><span class="file">/opt/gmp-4.2.2/include/</span></samp> and the library in
<samp><span class="file">/opt/gmp-4.2.2/lib/</span></samp>. More uncommon GMP installations can be
handled by setting CPPFLAGS and LDFLAGS appropriately prior to running
<code>configure</code>.
<div class="node">
<a name="Installing-the-library"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Cleaning-up">Cleaning up</a>,
Previous: <a rel="previous" accesskey="p" href="#Building-the-library">Building the library</a>,
Up: <a rel="up" accesskey="u" href="#Installation">Installation</a>
</div>
<h3 class="section">2.3 Installing the library</h3>
<p><a name="index-installation-7"></a>
As with any autoconfiguring GNU software, installation is as easy as this:
<pre class="example"> $ make install
</pre>
<p>The ‘<samp><span class="samp">make install</span></samp>’ command installs the library and the include files
into public places (<samp><span class="file">/usr/local/lib/</span></samp> and <samp><span class="file">/usr/local/include/</span></samp>,
if you haven't specified a <code>--prefix</code> option to <code>configure</code>).
This step may require superuser privileges.
<p>If you have already built the library and wish to install it, but didn't
specify <code>--prefix=...</code> at configure time, just re-run
<code>configure</code>, giving it the same options as the first time, plus
the <code>--prefix=...</code> option.
<div class="node">
<a name="Cleaning-up"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Installing-the-library">Installing the library</a>,
Up: <a rel="up" accesskey="u" href="#Installation">Installation</a>
</div>
<h3 class="section">2.4 Cleaning up</h3>
<p>You can remove system-dependent files generated by <code>make</code> through
<pre class="example"> $ make clean
</pre>
<p>You can remove all files generated by <code>make</code>, thus reverting to a
virgin distribution of CLN, through
<pre class="example"> $ make distclean
</pre>
<div class="node">
<a name="Ordinary-number-types"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Functions-on-numbers">Functions on numbers</a>,
Previous: <a rel="previous" accesskey="p" href="#Installation">Installation</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">3 Ordinary number types</h2>
<p>CLN implements the following class hierarchy:
<pre class="example"> Number
cl_number
<cln/number.h>
|
|
Real or complex number
cl_N
<cln/complex.h>
|
|
Real number
cl_R
<cln/real.h>
|
+-------------------+-------------------+
| |
Rational number Floating-point number
cl_RA cl_F
<cln/rational.h> <cln/float.h>
| |
| +--------------+--------------+--------------+
Integer | | | |
cl_I Short-Float Single-Float Double-Float Long-Float
<cln/integer.h> cl_SF cl_FF cl_DF cl_LF
<cln/sfloat.h> <cln/ffloat.h> <cln/dfloat.h> <cln/lfloat.h>
</pre>
<p><a name="index-g_t_0040code_007bcl_005fnumber_007d-8"></a><a name="index-abstract-class-9"></a>The base class <code>cl_number</code> is an abstract base class.
It is not useful to declare a variable of this type except if you want
to completely disable compile-time type checking and use run-time type
checking instead.
<p><a name="index-g_t_0040code_007bcl_005fN_007d-10"></a><a name="index-real-number-11"></a><a name="index-complex-number-12"></a>The class <code>cl_N</code> comprises real and complex numbers. There is
no special class for complex numbers since complex numbers with imaginary
part <code>0</code> are automatically converted to real numbers.
<p><a name="index-g_t_0040code_007bcl_005fR_007d-13"></a>The class <code>cl_R</code> comprises real numbers of different kinds. It is an
abstract class.
<p><a name="index-g_t_0040code_007bcl_005fRA_007d-14"></a><a name="index-rational-number-15"></a><a name="index-integer-16"></a>The class <code>cl_RA</code> comprises exact real numbers: rational numbers, including
integers. There is no special class for non-integral rational numbers
since rational numbers with denominator <code>1</code> are automatically converted
to integers.
<p><a name="index-g_t_0040code_007bcl_005fF_007d-17"></a>The class <code>cl_F</code> implements floating-point approximations to real numbers.
It is an abstract class.
<ul class="menu">
<li><a accesskey="1" href="#Exact-numbers">Exact numbers</a>
<li><a accesskey="2" href="#Floating_002dpoint-numbers">Floating-point numbers</a>
<li><a accesskey="3" href="#Complex-numbers">Complex numbers</a>
<li><a accesskey="4" href="#Conversions">Conversions</a>
</ul>
<div class="node">
<a name="Exact-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Floating_002dpoint-numbers">Floating-point numbers</a>,
Up: <a rel="up" accesskey="u" href="#Ordinary-number-types">Ordinary number types</a>
</div>
<h3 class="section">3.1 Exact numbers</h3>
<p><a name="index-exact-number-18"></a>
Some numbers are represented as exact numbers: there is no loss of information
when such a number is converted from its mathematical value to its internal
representation. On exact numbers, the elementary operations (<code>+</code>,
<code>-</code>, <code>*</code>, <code>/</code>, comparisons, <small class="dots">...</small>) compute the completely
correct result.
<p>In CLN, the exact numbers are:
<ul>
<li>rational numbers (including integers),
<li>complex numbers whose real and imaginary parts are both rational numbers.
</ul>
<p>Rational numbers are always normalized to the form
<var>numerator</var><code>/</code><var>denominator</var> where the numerator and denominator
are coprime integers and the denominator is positive. If the resulting
denominator is <code>1</code>, the rational number is converted to an integer.
<p><a name="index-immediate-numbers-19"></a>Small integers (typically in the range <code>-2^29</code><small class="dots">...</small><code>2^29-1</code>,
for 32-bit machines) are especially efficient, because they consume no heap
allocation. Otherwise the distinction between these immediate integers
(called “fixnums”) and heap allocated integers (called “bignums”)
is completely transparent.
<div class="node">
<a name="Floating-point-numbers"></a>
<a name="Floating_002dpoint-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Complex-numbers">Complex numbers</a>,
Previous: <a rel="previous" accesskey="p" href="#Exact-numbers">Exact numbers</a>,
Up: <a rel="up" accesskey="u" href="#Ordinary-number-types">Ordinary number types</a>
</div>
<h3 class="section">3.2 Floating-point numbers</h3>
<p><a name="index-floating_002dpoint-number-20"></a>
Not all real numbers can be represented exactly. (There is an easy mathematical
proof for this: Only a countable set of numbers can be stored exactly in
a computer, even if one assumes that it has unlimited storage. But there
are uncountably many real numbers.) So some approximation is needed.
CLN implements ordinary floating-point numbers, with mantissa and exponent.
<p><a name="index-rounding-error-21"></a>The elementary operations (<code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <small class="dots">...</small>)
only return approximate results. For example, the value of the expression
<code>(cl_F) 0.3 + (cl_F) 0.4</code> prints as ‘<samp><span class="samp">0.70000005</span></samp>’, not as
‘<samp><span class="samp">0.7</span></samp>’. Rounding errors like this one are inevitable when computing
with floating-point numbers.
<p>Nevertheless, CLN rounds the floating-point results of the operations <code>+</code>,
<code>-</code>, <code>*</code>, <code>/</code>, <code>sqrt</code> according to the “round-to-even”
rule: It first computes the exact mathematical result and then returns the
floating-point number which is nearest to this. If two floating-point numbers
are equally distant from the ideal result, the one with a <code>0</code> in its least
significant mantissa bit is chosen.
<p>Similarly, testing floating point numbers for equality ‘<samp><span class="samp">x == y</span></samp>’
is gambling with random errors. Better check for ‘<samp><span class="samp">abs(x - y) < epsilon</span></samp>’
for some well-chosen <code>epsilon</code>.
<p>Floating point numbers come in four flavors:
<ul>
<li><a name="index-g_t_0040code_007bcl_005fSF_007d-22"></a>Short floats, type <code>cl_SF</code>.
They have 1 sign bit, 8 exponent bits (including the exponent's sign),
and 17 mantissa bits (including the “hidden” bit).
They don't consume heap allocation.
<li><a name="index-g_t_0040code_007bcl_005fFF_007d-23"></a>Single floats, type <code>cl_FF</code>.
They have 1 sign bit, 8 exponent bits (including the exponent's sign),
and 24 mantissa bits (including the “hidden” bit).
In CLN, they are represented as IEEE single-precision floating point numbers.
This corresponds closely to the C/C++ type ‘<samp><span class="samp">float</span></samp>’.
<li><a name="index-g_t_0040code_007bcl_005fDF_007d-24"></a>Double floats, type <code>cl_DF</code>.
They have 1 sign bit, 11 exponent bits (including the exponent's sign),
and 53 mantissa bits (including the “hidden” bit).
In CLN, they are represented as IEEE double-precision floating point numbers.
This corresponds closely to the C/C++ type ‘<samp><span class="samp">double</span></samp>’.
<li><a name="index-g_t_0040code_007bcl_005fLF_007d-25"></a>Long floats, type <code>cl_LF</code>.
They have 1 sign bit, 32 exponent bits (including the exponent's sign),
and n mantissa bits (including the “hidden” bit), where n >= 64.
The precision of a long float is unlimited, but once created, a long float
has a fixed precision. (No “lazy recomputation”.)
</ul>
<p>Of course, computations with long floats are more expensive than those
with smaller floating-point formats.
<p>CLN does not implement features like NaNs, denormalized numbers and
gradual underflow. If the exponent range of some floating-point type
is too limited for your application, choose another floating-point type
with larger exponent range.
<p><a name="index-g_t_0040code_007bcl_005fF_007d-26"></a>As a user of CLN, you can forget about the differences between the
four floating-point types and just declare all your floating-point
variables as being of type <code>cl_F</code>. This has the advantage that
when you change the precision of some computation (say, from <code>cl_DF</code>
to <code>cl_LF</code>), you don't have to change the code, only the precision
of the initial values. Also, many transcendental functions have been
declared as returning a <code>cl_F</code> when the argument is a <code>cl_F</code>,
but such declarations are missing for the types <code>cl_SF</code>, <code>cl_FF</code>,
<code>cl_DF</code>, <code>cl_LF</code>. (Such declarations would be wrong if
the floating point contagion rule happened to change in the future.)
<div class="node">
<a name="Complex-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Conversions">Conversions</a>,
Previous: <a rel="previous" accesskey="p" href="#Floating_002dpoint-numbers">Floating-point numbers</a>,
Up: <a rel="up" accesskey="u" href="#Ordinary-number-types">Ordinary number types</a>
</div>
<h3 class="section">3.3 Complex numbers</h3>
<p><a name="index-complex-number-27"></a>
Complex numbers, as implemented by the class <code>cl_N</code>, have a real
part and an imaginary part, both real numbers. A complex number whose
imaginary part is the exact number <code>0</code> is automatically converted
to a real number.
<p>Complex numbers can arise from real numbers alone, for example
through application of <code>sqrt</code> or transcendental functions.
<div class="node">
<a name="Conversions"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Complex-numbers">Complex numbers</a>,
Up: <a rel="up" accesskey="u" href="#Ordinary-number-types">Ordinary number types</a>
</div>
<h3 class="section">3.4 Conversions</h3>
<p><a name="index-conversion-28"></a>
Conversions from any class to any its superclasses (“base classes” in
C++ terminology) is done automatically.
<p>Conversions from the C built-in types ‘<samp><span class="samp">long</span></samp>’ and ‘<samp><span class="samp">unsigned long</span></samp>’
are provided for the classes <code>cl_I</code>, <code>cl_RA</code>, <code>cl_R</code>,
<code>cl_N</code> and <code>cl_number</code>.
<p>Conversions from the C built-in types ‘<samp><span class="samp">int</span></samp>’ and ‘<samp><span class="samp">unsigned int</span></samp>’
are provided for the classes <code>cl_I</code>, <code>cl_RA</code>, <code>cl_R</code>,
<code>cl_N</code> and <code>cl_number</code>. However, these conversions emphasize
efficiency. On 32-bit systems, their range is therefore limited:
<ul>
<li>The conversion from ‘<samp><span class="samp">int</span></samp>’ works only if the argument is < 2^29 and >= -2^29.
<li>The conversion from ‘<samp><span class="samp">unsigned int</span></samp>’ works only if the argument is < 2^29.
</ul>
<p>In a declaration like ‘<samp><span class="samp">cl_I x = 10;</span></samp>’ the C++ compiler is able to
do the conversion of <code>10</code> from ‘<samp><span class="samp">int</span></samp>’ to ‘<samp><span class="samp">cl_I</span></samp>’ at compile time
already. On the other hand, code like ‘<samp><span class="samp">cl_I x = 1000000000;</span></samp>’ is
in error on 32-bit machines.
So, if you want to be sure that an ‘<samp><span class="samp">int</span></samp>’ whose magnitude is not guaranteed
to be < 2^29 is correctly converted to a ‘<samp><span class="samp">cl_I</span></samp>’, first convert it to a
‘<samp><span class="samp">long</span></samp>’. Similarly, if a large ‘<samp><span class="samp">unsigned int</span></samp>’ is to be converted to a
‘<samp><span class="samp">cl_I</span></samp>’, first convert it to an ‘<samp><span class="samp">unsigned long</span></samp>’. On 64-bit machines
there is no such restriction. There, conversions from arbitrary 32-bit ‘<samp><span class="samp">int</span></samp>’
values always works correctly.
<p>Conversions from the C built-in type ‘<samp><span class="samp">float</span></samp>’ are provided for the classes
<code>cl_FF</code>, <code>cl_F</code>, <code>cl_R</code>, <code>cl_N</code> and <code>cl_number</code>.
<p>Conversions from the C built-in type ‘<samp><span class="samp">double</span></samp>’ are provided for the classes
<code>cl_DF</code>, <code>cl_F</code>, <code>cl_R</code>, <code>cl_N</code> and <code>cl_number</code>.
<p>Conversions from ‘<samp><span class="samp">const char *</span></samp>’ are provided for the classes
<code>cl_I</code>, <code>cl_RA</code>,
<code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>, <code>cl_F</code>,
<code>cl_R</code>, <code>cl_N</code>.
The easiest way to specify a value which is outside of the range of the
C++ built-in types is therefore to specify it as a string, like this:
<a name="index-Rubik_0027s-cube-29"></a>
<pre class="example"> cl_I order_of_rubiks_cube_group = "43252003274489856000";
</pre>
<p>Note that this conversion is done at runtime, not at compile-time.
<p>Conversions from <code>cl_I</code> to the C built-in types ‘<samp><span class="samp">int</span></samp>’,
‘<samp><span class="samp">unsigned int</span></samp>’, ‘<samp><span class="samp">long</span></samp>’, ‘<samp><span class="samp">unsigned long</span></samp>’ are provided through
the functions
<dl>
<dt><code>int cl_I_to_int (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcl_005fI_005fto_005fint-_0028_0029_007d-30"></a><dt><code>unsigned int cl_I_to_uint (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcl_005fI_005fto_005fuint-_0028_0029_007d-31"></a><dt><code>long cl_I_to_long (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcl_005fI_005fto_005flong-_0028_0029_007d-32"></a><dt><code>unsigned long cl_I_to_ulong (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcl_005fI_005fto_005fulong-_0028_0029_007d-33"></a>Returns <code>x</code> as element of the C type <var>ctype</var>. If <code>x</code> is not
representable in the range of <var>ctype</var>, a runtime error occurs.
</dl>
<p>Conversions from the classes <code>cl_I</code>, <code>cl_RA</code>,
<code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>, <code>cl_F</code> and
<code>cl_R</code>
to the C built-in types ‘<samp><span class="samp">float</span></samp>’ and ‘<samp><span class="samp">double</span></samp>’ are provided through
the functions
<dl>
<dt><code>float float_approx (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloat_005fapprox-_0028_0029_007d-34"></a><dt><code>double double_approx (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bdouble_005fapprox-_0028_0029_007d-35"></a>Returns an approximation of <code>x</code> of C type <var>ctype</var>.
If <code>abs(x)</code> is too close to 0 (underflow), 0 is returned.
If <code>abs(x)</code> is too large (overflow), an IEEE infinity is returned.
</dl>
<p>Conversions from any class to any of its subclasses (“derived classes” in
C++ terminology) are not provided. Instead, you can assert and check
that a value belongs to a certain subclass, and return it as element of that
class, using the ‘<samp><span class="samp">As</span></samp>’ and ‘<samp><span class="samp">The</span></samp>’ macros.
<a name="index-cast-36"></a><a name="index-g_t_0040code_007bAs_0028_0029_0028_0029_007d-37"></a><code>As(</code><var>type</var><code>)(</code><var>value</var><code>)</code> checks that <var>value</var> belongs to
<var>type</var> and returns it as such.
<a name="index-g_t_0040code_007bThe_0028_0029_0028_0029_007d-38"></a><code>The(</code><var>type</var><code>)(</code><var>value</var><code>)</code> assumes that <var>value</var> belongs to
<var>type</var> and returns it as such. It is your responsibility to ensure
that this assumption is valid. Since macros and namespaces don't go
together well, there is an equivalent to ‘<samp><span class="samp">The</span></samp>’: the template
‘<samp><span class="samp">the</span></samp>’.
<p>Example:
<pre class="example"> cl_I x = ...;
if (!(x >= 0)) abort();
cl_I ten_x_a = The(cl_I)(expt(10,x)); // If x >= 0, 10^x is an integer.
// In general, it would be a rational number.
cl_I ten_x_b = the<cl_I>(expt(10,x)); // The same as above.
</pre>
<div class="node">
<a name="Functions-on-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Input_002fOutput">Input/Output</a>,
Previous: <a rel="previous" accesskey="p" href="#Ordinary-number-types">Ordinary number types</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">4 Functions on numbers</h2>
<p>Each of the number classes declares its mathematical operations in the
corresponding include file. For example, if your code operates with
objects of type <code>cl_I</code>, it should <code>#include <cln/integer.h></code>.
<ul class="menu">
<li><a accesskey="1" href="#Constructing-numbers">Constructing numbers</a>
<li><a accesskey="2" href="#Elementary-functions">Elementary functions</a>
<li><a accesskey="3" href="#Elementary-rational-functions">Elementary rational functions</a>
<li><a accesskey="4" href="#Elementary-complex-functions">Elementary complex functions</a>
<li><a accesskey="5" href="#Comparisons">Comparisons</a>
<li><a accesskey="6" href="#Rounding-functions">Rounding functions</a>
<li><a accesskey="7" href="#Roots">Roots</a>
<li><a accesskey="8" href="#Transcendental-functions">Transcendental functions</a>
<li><a accesskey="9" href="#Functions-on-integers">Functions on integers</a>
<li><a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a>
<li><a href="#Conversion-functions">Conversion functions</a>
<li><a href="#Random-number-generators">Random number generators</a>
<li><a href="#Modifying-operators">Modifying operators</a>
</ul>
<div class="node">
<a name="Constructing-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Elementary-functions">Elementary functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.1 Constructing numbers</h3>
<p>Here is how to create number objects “from nothing”.
<ul class="menu">
<li><a accesskey="1" href="#Constructing-integers">Constructing integers</a>
<li><a accesskey="2" href="#Constructing-rational-numbers">Constructing rational numbers</a>
<li><a accesskey="3" href="#Constructing-floating_002dpoint-numbers">Constructing floating-point numbers</a>
<li><a accesskey="4" href="#Constructing-complex-numbers">Constructing complex numbers</a>
</ul>
<div class="node">
<a name="Constructing-integers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Constructing-rational-numbers">Constructing rational numbers</a>,
Up: <a rel="up" accesskey="u" href="#Constructing-numbers">Constructing numbers</a>
</div>
<h4 class="subsection">4.1.1 Constructing integers</h4>
<p><code>cl_I</code> objects are most easily constructed from C integers and from
strings. See <a href="#Conversions">Conversions</a>.
<div class="node">
<a name="Constructing-rational-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Constructing-floating_002dpoint-numbers">Constructing floating-point numbers</a>,
Previous: <a rel="previous" accesskey="p" href="#Constructing-integers">Constructing integers</a>,
Up: <a rel="up" accesskey="u" href="#Constructing-numbers">Constructing numbers</a>
</div>
<h4 class="subsection">4.1.2 Constructing rational numbers</h4>
<p><code>cl_RA</code> objects can be constructed from strings. The syntax
for rational numbers is described in <a href="#Internal-and-printed-representation">Internal and printed representation</a>.
Another standard way to produce a rational number is through application
of ‘<samp><span class="samp">operator /</span></samp>’ or ‘<samp><span class="samp">recip</span></samp>’ on integers.
<div class="node">
<a name="Constructing-floating-point-numbers"></a>
<a name="Constructing-floating_002dpoint-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Constructing-complex-numbers">Constructing complex numbers</a>,
Previous: <a rel="previous" accesskey="p" href="#Constructing-rational-numbers">Constructing rational numbers</a>,
Up: <a rel="up" accesskey="u" href="#Constructing-numbers">Constructing numbers</a>
</div>
<h4 class="subsection">4.1.3 Constructing floating-point numbers</h4>
<p><code>cl_F</code> objects with low precision are most easily constructed from
C ‘<samp><span class="samp">float</span></samp>’ and ‘<samp><span class="samp">double</span></samp>’. See <a href="#Conversions">Conversions</a>.
<p>To construct a <code>cl_F</code> with high precision, you can use the conversion
from ‘<samp><span class="samp">const char *</span></samp>’, but you have to specify the desired precision
within the string. (See <a href="#Internal-and-printed-representation">Internal and printed representation</a>.)
Example:
<pre class="example"> cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
</pre>
<p>will set ‘<samp><span class="samp">e</span></samp>’ to the given value, with a precision of 40 decimal digits.
<p>The programmatic way to construct a <code>cl_F</code> with high precision is
through the <code>cl_float</code> conversion function, see
<a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a>. For example, to compute
<code>e</code> to 40 decimal places, first construct 1.0 to 40 decimal places
and then apply the exponential function:
<pre class="example"> float_format_t precision = float_format(40);
cl_F e = exp(cl_float(1,precision));
</pre>
<div class="node">
<a name="Constructing-complex-numbers"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Constructing-floating_002dpoint-numbers">Constructing floating-point numbers</a>,
Up: <a rel="up" accesskey="u" href="#Constructing-numbers">Constructing numbers</a>
</div>
<h4 class="subsection">4.1.4 Constructing complex numbers</h4>
<p>Non-real <code>cl_N</code> objects are normally constructed through the function
<pre class="example"> cl_N complex (const cl_R& realpart, const cl_R& imagpart)
</pre>
<p>See <a href="#Elementary-complex-functions">Elementary complex functions</a>.
<div class="node">
<a name="Elementary-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Elementary-rational-functions">Elementary rational functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Constructing-numbers">Constructing numbers</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.2 Elementary functions</h3>
<p>Each of the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><var>type</var><code> operator + (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002b-_0028_0029_007d-39"></a>Addition.
<br><dt><var>type</var><code> operator - (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002d-_0028_0029_007d-40"></a>Subtraction.
<br><dt><var>type</var><code> operator - (const </code><var>type</var><code>&)</code><dd>Returns the negative of the argument.
<br><dt><var>type</var><code> plus1 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bplus1-_0028_0029_007d-41"></a>Returns <code>x + 1</code>.
<br><dt><var>type</var><code> minus1 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bminus1-_0028_0029_007d-42"></a>Returns <code>x - 1</code>.
<br><dt><var>type</var><code> operator * (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002a-_0028_0029_007d-43"></a>Multiplication.
<br><dt><var>type</var><code> square (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bsquare-_0028_0029_007d-44"></a>Returns <code>x * x</code>.
</dl>
<p>Each of the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><var>type</var><code> operator / (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002f-_0028_0029_007d-45"></a>Division.
<br><dt><var>type</var><code> recip (const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007brecip-_0028_0029_007d-46"></a>Returns the reciprocal of the argument.
</dl>
<p>The class <code>cl_I</code> doesn't define a ‘<samp><span class="samp">/</span></samp>’ operation because
in the C/C++ language this operator, applied to integral types,
denotes the ‘<samp><span class="samp">floor</span></samp>’ or ‘<samp><span class="samp">truncate</span></samp>’ operation (which one of these,
is implementation dependent). (See <a href="#Rounding-functions">Rounding functions</a>.)
Instead, <code>cl_I</code> defines an “exact quotient” function:
<dl>
<dt><code>cl_I exquo (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexquo-_0028_0029_007d-47"></a>Checks that <code>y</code> divides <code>x</code>, and returns the quotient <code>x</code>/<code>y</code>.
</dl>
<p>The following exponentiation functions are defined:
<dl>
<dt><code>cl_I expt_pos (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-48"></a><dt><code>cl_RA expt_pos (const cl_RA& x, const cl_I& y)</code><dd><code>y</code> must be > 0. Returns <code>x^y</code>.
<br><dt><code>cl_RA expt (const cl_RA& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexpt-_0028_0029_007d-49"></a><dt><code>cl_R expt (const cl_R& x, const cl_I& y)</code><dt><code>cl_N expt (const cl_N& x, const cl_I& y)</code><dd>Returns <code>x^y</code>.
</dl>
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operation:
<dl>
<dt><var>type</var><code> abs (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007babs-_0028_0029_007d-50"></a>Returns the absolute value of <code>x</code>.
This is <code>x</code> if <code>x >= 0</code>, and <code>-x</code> if <code>x <= 0</code>.
</dl>
<p>The class <code>cl_N</code> implements this as follows:
<dl>
<dt><code>cl_R abs (const cl_N x)</code><dd>Returns the absolute value of <code>x</code>.
</dl>
<p>Each of the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operation:
<dl>
<dt><var>type</var><code> signum (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bsignum-_0028_0029_007d-51"></a>Returns the sign of <code>x</code>, in the same number format as <code>x</code>.
This is defined as <code>x / abs(x)</code> if <code>x</code> is non-zero, and
<code>x</code> if <code>x</code> is zero. If <code>x</code> is real, the value is either
0 or 1 or -1.
</dl>
<div class="node">
<a name="Elementary-rational-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Elementary-complex-functions">Elementary complex functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Elementary-functions">Elementary functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.3 Elementary rational functions</h3>
<p>Each of the classes <code>cl_RA</code>, <code>cl_I</code> defines the following operations:
<dl>
<dt><code>cl_I numerator (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bnumerator-_0028_0029_007d-52"></a>Returns the numerator of <code>x</code>.
<br><dt><code>cl_I denominator (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bdenominator-_0028_0029_007d-53"></a>Returns the denominator of <code>x</code>.
</dl>
<p>The numerator and denominator of a rational number are normalized in such
a way that they have no factor in common and the denominator is positive.
<div class="node">
<a name="Elementary-complex-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Comparisons">Comparisons</a>,
Previous: <a rel="previous" accesskey="p" href="#Elementary-rational-functions">Elementary rational functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.4 Elementary complex functions</h3>
<p>The class <code>cl_N</code> defines the following operation:
<dl>
<dt><code>cl_N complex (const cl_R& a, const cl_R& b)</code><dd><a name="index-g_t_0040code_007bcomplex-_0028_0029_007d-54"></a>Returns the complex number <code>a+bi</code>, that is, the complex number with
real part <code>a</code> and imaginary part <code>b</code>.
</dl>
<p>Each of the classes <code>cl_N</code>, <code>cl_R</code> defines the following operations:
<dl>
<dt><code>cl_R realpart (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007brealpart-_0028_0029_007d-55"></a>Returns the real part of <code>x</code>.
<br><dt><code>cl_R imagpart (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bimagpart-_0028_0029_007d-56"></a>Returns the imaginary part of <code>x</code>.
<br><dt><var>type</var><code> conjugate (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bconjugate-_0028_0029_007d-57"></a>Returns the complex conjugate of <code>x</code>.
</dl>
<p>We have the relations
<ul>
<li><code>x = complex(realpart(x), imagpart(x))</code>
<li><code>conjugate(x) = complex(realpart(x), -imagpart(x))</code>
</ul>
<div class="node">
<a name="Comparisons"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Rounding-functions">Rounding functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Elementary-complex-functions">Elementary complex functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.5 Comparisons</h3>
<p><a name="index-comparison-58"></a>
Each of the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><code>bool operator == (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-59"></a><dt><code>bool operator != (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-60"></a>Comparison, as in C and C++.
<br><dt><code>uint32 equal_hashcode (const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007bequal_005fhashcode-_0028_0029_007d-61"></a>Returns a 32-bit hash code that is the same for any two numbers which are
the same according to <code>==</code>. This hash code depends on the number's value,
not its type or precision.
<br><dt><code>bool zerop (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bzerop-_0028_0029_007d-62"></a>Compare against zero: <code>x == 0</code>
</dl>
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><code>cl_signean compare (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bcompare-_0028_0029_007d-63"></a>Compares <code>x</code> and <code>y</code>. Returns +1 if <code>x</code>><code>y</code>,
-1 if <code>x</code><<code>y</code>, 0 if <code>x</code>=<code>y</code>.
<br><dt><code>bool operator <= (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003c_003d-_0028_0029_007d-64"></a><dt><code>bool operator < (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003c-_0028_0029_007d-65"></a><dt><code>bool operator >= (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003e_003d-_0028_0029_007d-66"></a><dt><code>bool operator > (const </code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003e-_0028_0029_007d-67"></a>Comparison, as in C and C++.
<br><dt><code>bool minusp (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bminusp-_0028_0029_007d-68"></a>Compare against zero: <code>x < 0</code>
<br><dt><code>bool plusp (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bplusp-_0028_0029_007d-69"></a>Compare against zero: <code>x > 0</code>
<br><dt><var>type</var><code> max (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bmax-_0028_0029_007d-70"></a>Return the maximum of <code>x</code> and <code>y</code>.
<br><dt><var>type</var><code> min (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bmin-_0028_0029_007d-71"></a>Return the minimum of <code>x</code> and <code>y</code>.
</dl>
<p>When a floating point number and a rational number are compared, the float
is first converted to a rational number using the function <code>rational</code>.
Since a floating point number actually represents an interval of real numbers,
the result might be surprising.
For example, <code>(cl_F)(cl_R)"1/3" == (cl_R)"1/3"</code> returns false because
there is no floating point number whose value is exactly <code>1/3</code>.
<div class="node">
<a name="Rounding-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Roots">Roots</a>,
Previous: <a rel="previous" accesskey="p" href="#Comparisons">Comparisons</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.6 Rounding functions</h3>
<p><a name="index-rounding-72"></a>
When a real number is to be converted to an integer, there is no “best”
rounding. The desired rounding function depends on the application.
The Common Lisp and ISO Lisp standards offer four rounding functions:
<dl>
<dt><code>floor(x)</code><dd>This is the largest integer <=<code>x</code>.
<br><dt><code>ceiling(x)</code><dd>This is the smallest integer >=<code>x</code>.
<br><dt><code>truncate(x)</code><dd>Among the integers between 0 and <code>x</code> (inclusive) the one nearest to <code>x</code>.
<br><dt><code>round(x)</code><dd>The integer nearest to <code>x</code>. If <code>x</code> is exactly halfway between two
integers, choose the even one.
</dl>
<p>These functions have different advantages:
<p><code>floor</code> and <code>ceiling</code> are translation invariant:
<code>floor(x+n) = floor(x) + n</code> and <code>ceiling(x+n) = ceiling(x) + n</code>
for every <code>x</code> and every integer <code>n</code>.
<p>On the other hand, <code>truncate</code> and <code>round</code> are symmetric:
<code>truncate(-x) = -truncate(x)</code> and <code>round(-x) = -round(x)</code>,
and furthermore <code>round</code> is unbiased: on the “average”, it rounds
down exactly as often as it rounds up.
<p>The functions are related like this:
<ul>
<li><code>ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1</code>
for rational numbers <code>m/n</code> (<code>m</code>, <code>n</code> integers, <code>n</code>>0), and
<li><code>truncate(x) = sign(x) * floor(abs(x))</code>
</ul>
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><code>cl_I floor1 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloor1-_0028_0029_007d-73"></a>Returns <code>floor(x)</code>.
<br><dt><code>cl_I ceiling1 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bceiling1-_0028_0029_007d-74"></a>Returns <code>ceiling(x)</code>.
<br><dt><code>cl_I truncate1 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007btruncate1-_0028_0029_007d-75"></a>Returns <code>truncate(x)</code>.
<br><dt><code>cl_I round1 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bround1-_0028_0029_007d-76"></a>Returns <code>round(x)</code>.
</dl>
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><code>cl_I floor1 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd>Returns <code>floor(x/y)</code>.
<br><dt><code>cl_I ceiling1 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd>Returns <code>ceiling(x/y)</code>.
<br><dt><code>cl_I truncate1 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd>Returns <code>truncate(x/y)</code>.
<br><dt><code>cl_I round1 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd>Returns <code>round(x/y)</code>.
</dl>
<p>These functions are called ‘<samp><span class="samp">floor1</span></samp>’, <small class="dots">...</small> here instead of
‘<samp><span class="samp">floor</span></samp>’, <small class="dots">...</small>, because on some systems, system dependent include
files define ‘<samp><span class="samp">floor</span></samp>’ and ‘<samp><span class="samp">ceiling</span></samp>’ as macros.
<p>In many cases, one needs both the quotient and the remainder of a division.
It is more efficient to compute both at the same time than to perform
two divisions, one for quotient and the next one for the remainder.
The following functions therefore return a structure containing both
the quotient and the remainder. The suffix ‘<samp><span class="samp">2</span></samp>’ indicates the number
of “return values”. The remainder is defined as follows:
<ul>
<li>for the computation of <code>quotient = floor(x)</code>,
<code>remainder = x - quotient</code>,
<li>for the computation of <code>quotient = floor(x,y)</code>,
<code>remainder = x - quotient*y</code>,
</ul>
<p>and similarly for the other three operations.
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><code>struct </code><var>type</var><code>_div_t { cl_I quotient; </code><var>type</var><code> remainder; };</code><dt><var>type</var><code>_div_t floor2 (const </code><var>type</var><code>& x)</code><dt><var>type</var><code>_div_t ceiling2 (const </code><var>type</var><code>& x)</code><dt><var>type</var><code>_div_t truncate2 (const </code><var>type</var><code>& x)</code><dt><var>type</var><code>_div_t round2 (const </code><var>type</var><code>& x)</code><dd></dl>
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><code>struct </code><var>type</var><code>_div_t { cl_I quotient; </code><var>type</var><code> remainder; };</code><dt><var>type</var><code>_div_t floor2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bfloor2-_0028_0029_007d-77"></a><dt><var>type</var><code>_div_t ceiling2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bceiling2-_0028_0029_007d-78"></a><dt><var>type</var><code>_div_t truncate2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007btruncate2-_0028_0029_007d-79"></a><dt><var>type</var><code>_div_t round2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bround2-_0028_0029_007d-80"></a></dl>
<p>Sometimes, one wants the quotient as a floating-point number (of the
same format as the argument, if the argument is a float) instead of as
an integer. The prefix ‘<samp><span class="samp">f</span></samp>’ indicates this.
<p>Each of the classes
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<dl>
<dt><var>type</var><code> ffloor (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bffloor-_0028_0029_007d-81"></a><dt><var>type</var><code> fceiling (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfceiling-_0028_0029_007d-82"></a><dt><var>type</var><code> ftruncate (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bftruncate-_0028_0029_007d-83"></a><dt><var>type</var><code> fround (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfround-_0028_0029_007d-84"></a></dl>
<p>and similarly for class <code>cl_R</code>, but with return type <code>cl_F</code>.
<p>The class <code>cl_R</code> defines the following operations:
<dl>
<dt><code>cl_F ffloor (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dt><code>cl_F fceiling (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dt><code>cl_F ftruncate (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dt><code>cl_F fround (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd></dl>
<p>These functions also exist in versions which return both the quotient
and the remainder. The suffix ‘<samp><span class="samp">2</span></samp>’ indicates this.
<p>Each of the classes
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations:
<a name="index-g_t_0040code_007bcl_005fF_005ffdiv_005ft_007d-85"></a><a name="index-g_t_0040code_007bcl_005fSF_005ffdiv_005ft_007d-86"></a><a name="index-g_t_0040code_007bcl_005fFF_005ffdiv_005ft_007d-87"></a><a name="index-g_t_0040code_007bcl_005fDF_005ffdiv_005ft_007d-88"></a><a name="index-g_t_0040code_007bcl_005fLF_005ffdiv_005ft_007d-89"></a>
<dl>
<dt><code>struct </code><var>type</var><code>_fdiv_t { </code><var>type</var><code> quotient; </code><var>type</var><code> remainder; };</code><dt><var>type</var><code>_fdiv_t ffloor2 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bffloor2-_0028_0029_007d-90"></a><dt><var>type</var><code>_fdiv_t fceiling2 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfceiling2-_0028_0029_007d-91"></a><dt><var>type</var><code>_fdiv_t ftruncate2 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bftruncate2-_0028_0029_007d-92"></a><dt><var>type</var><code>_fdiv_t fround2 (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfround2-_0028_0029_007d-93"></a></dl>
and similarly for class <code>cl_R</code>, but with quotient type <code>cl_F</code>.
<a name="index-g_t_0040code_007bcl_005fR_005ffdiv_005ft_007d-94"></a>
The class <code>cl_R</code> defines the following operations:
<dl>
<dt><code>struct </code><var>type</var><code>_fdiv_t { cl_F quotient; cl_R remainder; };</code><dt><var>type</var><code>_fdiv_t ffloor2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dt><var>type</var><code>_fdiv_t fceiling2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dt><var>type</var><code>_fdiv_t ftruncate2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dt><var>type</var><code>_fdiv_t fround2 (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd></dl>
<p>Other applications need only the remainder of a division.
The remainder of ‘<samp><span class="samp">floor</span></samp>’ and ‘<samp><span class="samp">ffloor</span></samp>’ is called ‘<samp><span class="samp">mod</span></samp>’
(abbreviation of “modulo”). The remainder ‘<samp><span class="samp">truncate</span></samp>’ and
‘<samp><span class="samp">ftruncate</span></samp>’ is called ‘<samp><span class="samp">rem</span></samp>’ (abbreviation of “remainder”).
<ul>
<li><code>mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y</code>
<li><code>rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y</code>
</ul>
<p>If <code>x</code> and <code>y</code> are both >= 0, <code>mod(x,y) = rem(x,y) >= 0</code>.
In general, <code>mod(x,y)</code> has the sign of <code>y</code> or is zero,
and <code>rem(x,y)</code> has the sign of <code>x</code> or is zero.
<p>The classes <code>cl_R</code>, <code>cl_I</code> define the following operations:
<dl>
<dt><var>type</var><code> mod (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007bmod-_0028_0029_007d-95"></a><dt><var>type</var><code> rem (const </code><var>type</var><code>& x, const </code><var>type</var><code>& y)</code><dd><a name="index-g_t_0040code_007brem-_0028_0029_007d-96"></a></dl>
<div class="node">
<a name="Roots"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Transcendental-functions">Transcendental functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Rounding-functions">Rounding functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.7 Roots</h3>
<p>Each of the classes <code>cl_R</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operation:
<dl>
<dt><var>type</var><code> sqrt (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bsqrt-_0028_0029_007d-97"></a><code>x</code> must be >= 0. This function returns the square root of <code>x</code>,
normalized to be >= 0. If <code>x</code> is the square of a rational number,
<code>sqrt(x)</code> will be a rational number, else it will return a
floating-point approximation.
</dl>
<p>The classes <code>cl_RA</code>, <code>cl_I</code> define the following operation:
<dl>
<dt><code>bool sqrtp (const </code><var>type</var><code>& x, </code><var>type</var><code>* root)</code><dd><a name="index-g_t_0040code_007bsqrtp-_0028_0029_007d-98"></a>This tests whether <code>x</code> is a perfect square. If so, it returns true
and the exact square root in <code>*root</code>, else it returns false.
</dl>
<p>Furthermore, for integers, similarly:
<dl>
<dt><code>bool isqrt (const </code><var>type</var><code>& x, </code><var>type</var><code>* root)</code><dd><a name="index-g_t_0040code_007bisqrt-_0028_0029_007d-99"></a><code>x</code> should be >= 0. This function sets <code>*root</code> to
<code>floor(sqrt(x))</code> and returns the same value as <code>sqrtp</code>:
the boolean value <code>(expt(*root,2) == x)</code>.
</dl>
<p>For <code>n</code>th roots, the classes <code>cl_RA</code>, <code>cl_I</code>
define the following operation:
<dl>
<dt><code>bool rootp (const </code><var>type</var><code>& x, const cl_I& n, </code><var>type</var><code>* root)</code><dd><a name="index-g_t_0040code_007brootp-_0028_0029_007d-100"></a><code>x</code> must be >= 0. <code>n</code> must be > 0.
This tests whether <code>x</code> is an <code>n</code>th power of a rational number.
If so, it returns true and the exact root in <code>*root</code>, else it returns
false.
</dl>
<p>The only square root function which accepts negative numbers is the one
for class <code>cl_N</code>:
<dl>
<dt><code>cl_N sqrt (const cl_N& z)</code><dd><a name="index-g_t_0040code_007bsqrt-_0028_0029_007d-101"></a>Returns the square root of <code>z</code>, as defined by the formula
<code>sqrt(z) = exp(log(z)/2)</code>. Conversion to a floating-point type
or to a complex number are done if necessary. The range of the result is the
right half plane <code>realpart(sqrt(z)) >= 0</code>
including the positive imaginary axis and 0, but excluding
the negative imaginary axis.
The result is an exact number only if <code>z</code> is an exact number.
</dl>
<div class="node">
<a name="Transcendental-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Functions-on-integers">Functions on integers</a>,
Previous: <a rel="previous" accesskey="p" href="#Roots">Roots</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.8 Transcendental functions</h3>
<p><a name="index-transcendental-functions-102"></a>
The transcendental functions return an exact result if the argument
is exact and the result is exact as well. Otherwise they must return
inexact numbers even if the argument is exact.
For example, <code>cos(0) = 1</code> returns the rational number <code>1</code>.
<ul class="menu">
<li><a accesskey="1" href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a>
<li><a accesskey="2" href="#Trigonometric-functions">Trigonometric functions</a>
<li><a accesskey="3" href="#Hyperbolic-functions">Hyperbolic functions</a>
<li><a accesskey="4" href="#Euler-gamma">Euler gamma</a>
<li><a accesskey="5" href="#Riemann-zeta">Riemann zeta</a>
</ul>
<div class="node">
<a name="Exponential-and-logarithmic-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Trigonometric-functions">Trigonometric functions</a>,
Up: <a rel="up" accesskey="u" href="#Transcendental-functions">Transcendental functions</a>
</div>
<h4 class="subsection">4.8.1 Exponential and logarithmic functions</h4>
<dl>
<dt><code>cl_R exp (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bexp-_0028_0029_007d-103"></a><dt><code>cl_N exp (const cl_N& x)</code><dd>Returns the exponential function of <code>x</code>. This is <code>e^x</code> where
<code>e</code> is the base of the natural logarithms. The range of the result
is the entire complex plane excluding 0.
<br><dt><code>cl_R ln (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bln-_0028_0029_007d-104"></a><code>x</code> must be > 0. Returns the (natural) logarithm of x.
<br><dt><code>cl_N log (const cl_N& x)</code><dd><a name="index-g_t_0040code_007blog-_0028_0029_007d-105"></a>Returns the (natural) logarithm of x. If <code>x</code> is real and positive,
this is <code>ln(x)</code>. In general, <code>log(x) = log(abs(x)) + i*phase(x)</code>.
The range of the result is the strip in the complex plane
<code>-pi < imagpart(log(x)) <= pi</code>.
<br><dt><code>cl_R phase (const cl_N& x)</code><dd><a name="index-g_t_0040code_007bphase-_0028_0029_007d-106"></a>Returns the angle part of <code>x</code> in its polar representation as a
complex number. That is, <code>phase(x) = atan(realpart(x),imagpart(x))</code>.
This is also the imaginary part of <code>log(x)</code>.
The range of the result is the interval <code>-pi < phase(x) <= pi</code>.
The result will be an exact number only if <code>zerop(x)</code> or
if <code>x</code> is real and positive.
<br><dt><code>cl_R log (const cl_R& a, const cl_R& b)</code><dd><code>a</code> and <code>b</code> must be > 0. Returns the logarithm of <code>a</code> with
respect to base <code>b</code>. <code>log(a,b) = ln(a)/ln(b)</code>.
The result can be exact only if <code>a = 1</code> or if <code>a</code> and <code>b</code>
are both rational.
<br><dt><code>cl_N log (const cl_N& a, const cl_N& b)</code><dd>Returns the logarithm of <code>a</code> with respect to base <code>b</code>.
<code>log(a,b) = log(a)/log(b)</code>.
<br><dt><code>cl_N expt (const cl_N& x, const cl_N& y)</code><dd><a name="index-g_t_0040code_007bexpt-_0028_0029_007d-107"></a>Exponentiation: Returns <code>x^y = exp(y*log(x))</code>.
</dl>
<p>The constant e = exp(1) = 2.71828<small class="dots">...</small> is returned by the following functions:
<dl>
<dt><code>cl_F exp1 (float_format_t f)</code><dd><a name="index-g_t_0040code_007bexp1-_0028_0029_007d-108"></a>Returns e as a float of format <code>f</code>.
<br><dt><code>cl_F exp1 (const cl_F& y)</code><dd>Returns e in the float format of <code>y</code>.
<br><dt><code>cl_F exp1 (void)</code><dd>Returns e as a float of format <code>default_float_format</code>.
</dl>
<div class="node">
<a name="Trigonometric-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Hyperbolic-functions">Hyperbolic functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a>,
Up: <a rel="up" accesskey="u" href="#Transcendental-functions">Transcendental functions</a>
</div>
<h4 class="subsection">4.8.2 Trigonometric functions</h4>
<dl>
<dt><code>cl_R sin (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bsin-_0028_0029_007d-109"></a>Returns <code>sin(x)</code>. The range of the result is the interval
<code>-1 <= sin(x) <= 1</code>.
<br><dt><code>cl_N sin (const cl_N& z)</code><dd>Returns <code>sin(z)</code>. The range of the result is the entire complex plane.
<br><dt><code>cl_R cos (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bcos-_0028_0029_007d-110"></a>Returns <code>cos(x)</code>. The range of the result is the interval
<code>-1 <= cos(x) <= 1</code>.
<br><dt><code>cl_N cos (const cl_N& x)</code><dd>Returns <code>cos(z)</code>. The range of the result is the entire complex plane.
<br><dt><code>struct cos_sin_t { cl_R cos; cl_R sin; };</code><dd><a name="index-g_t_0040code_007bcos_005fsin_005ft_007d-111"></a><dt><code>cos_sin_t cos_sin (const cl_R& x)</code><dd>Returns both <code>sin(x)</code> and <code>cos(x)</code>. This is more efficient than
<a name="index-g_t_0040code_007bcos_005fsin-_0028_0029_007d-112"></a>computing them separately. The relation <code>cos^2 + sin^2 = 1</code> will
hold only approximately.
<br><dt><code>cl_R tan (const cl_R& x)</code><dd><a name="index-g_t_0040code_007btan-_0028_0029_007d-113"></a><dt><code>cl_N tan (const cl_N& x)</code><dd>Returns <code>tan(x) = sin(x)/cos(x)</code>.
<br><dt><code>cl_N cis (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bcis-_0028_0029_007d-114"></a><dt><code>cl_N cis (const cl_N& x)</code><dd>Returns <code>exp(i*x)</code>. The name ‘<samp><span class="samp">cis</span></samp>’ means “cos + i sin”, because
<code>e^(i*x) = cos(x) + i*sin(x)</code>.
<p><a name="index-g_t_0040code_007basin_007d-115"></a><a name="index-g_t_0040code_007basin-_0028_0029_007d-116"></a><br><dt><code>cl_N asin (const cl_N& z)</code><dd>Returns <code>arcsin(z)</code>. This is defined as
<code>arcsin(z) = log(iz+sqrt(1-z^2))/i</code> and satisfies
<code>arcsin(-z) = -arcsin(z)</code>.
The range of the result is the strip in the complex domain
<code>-pi/2 <= realpart(arcsin(z)) <= pi/2</code>, excluding the numbers
with <code>realpart = -pi/2</code> and <code>imagpart < 0</code> and the numbers
with <code>realpart = pi/2</code> and <code>imagpart > 0</code>.
<br><dt><code>cl_N acos (const cl_N& z)</code><dd><a name="index-g_t_0040code_007bacos-_0028_0029_007d-117"></a>Returns <code>arccos(z)</code>. This is defined as
<code>arccos(z) = pi/2 - arcsin(z) = log(z+i*sqrt(1-z^2))/i</code>
and satisfies <code>arccos(-z) = pi - arccos(z)</code>.
The range of the result is the strip in the complex domain
<code>0 <= realpart(arcsin(z)) <= pi</code>, excluding the numbers
with <code>realpart = 0</code> and <code>imagpart < 0</code> and the numbers
with <code>realpart = pi</code> and <code>imagpart > 0</code>.
<p><a name="index-g_t_0040code_007batan_007d-118"></a><a name="index-g_t_0040code_007batan-_0028_0029_007d-119"></a><br><dt><code>cl_R atan (const cl_R& x, const cl_R& y)</code><dd>Returns the angle of the polar representation of the complex number
<code>x+iy</code>. This is <code>atan(y/x)</code> if <code>x>0</code>. The range of
the result is the interval <code>-pi < atan(x,y) <= pi</code>. The result will
be an exact number only if <code>x > 0</code> and <code>y</code> is the exact <code>0</code>.
WARNING: In Common Lisp, this function is called as <code>(atan y x)</code>,
with reversed order of arguments.
<br><dt><code>cl_R atan (const cl_R& x)</code><dd>Returns <code>arctan(x)</code>. This is the same as <code>atan(1,x)</code>. The range
of the result is the interval <code>-pi/2 < atan(x) < pi/2</code>. The result
will be an exact number only if <code>x</code> is the exact <code>0</code>.
<br><dt><code>cl_N atan (const cl_N& z)</code><dd>Returns <code>arctan(z)</code>. This is defined as
<code>arctan(z) = (log(1+iz)-log(1-iz)) / 2i</code> and satisfies
<code>arctan(-z) = -arctan(z)</code>. The range of the result is
the strip in the complex domain
<code>-pi/2 <= realpart(arctan(z)) <= pi/2</code>, excluding the numbers
with <code>realpart = -pi/2</code> and <code>imagpart >= 0</code> and the numbers
with <code>realpart = pi/2</code> and <code>imagpart <= 0</code>.
</dl>
<p><a name="index-pi-120"></a><a name="index-Archimedes_0027-constant-121"></a>Archimedes' constant pi = 3.14<small class="dots">...</small> is returned by the following functions:
<dl>
<dt><code>cl_F pi (float_format_t f)</code><dd><a name="index-g_t_0040code_007bpi-_0028_0029_007d-122"></a>Returns pi as a float of format <code>f</code>.
<br><dt><code>cl_F pi (const cl_F& y)</code><dd>Returns pi in the float format of <code>y</code>.
<br><dt><code>cl_F pi (void)</code><dd>Returns pi as a float of format <code>default_float_format</code>.
</dl>
<div class="node">
<a name="Hyperbolic-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Euler-gamma">Euler gamma</a>,
Previous: <a rel="previous" accesskey="p" href="#Trigonometric-functions">Trigonometric functions</a>,
Up: <a rel="up" accesskey="u" href="#Transcendental-functions">Transcendental functions</a>
</div>
<h4 class="subsection">4.8.3 Hyperbolic functions</h4>
<dl>
<dt><code>cl_R sinh (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bsinh-_0028_0029_007d-123"></a>Returns <code>sinh(x)</code>.
<br><dt><code>cl_N sinh (const cl_N& z)</code><dd>Returns <code>sinh(z)</code>. The range of the result is the entire complex plane.
<br><dt><code>cl_R cosh (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bcosh-_0028_0029_007d-124"></a>Returns <code>cosh(x)</code>. The range of the result is the interval
<code>cosh(x) >= 1</code>.
<br><dt><code>cl_N cosh (const cl_N& z)</code><dd>Returns <code>cosh(z)</code>. The range of the result is the entire complex plane.
<br><dt><code>struct cosh_sinh_t { cl_R cosh; cl_R sinh; };</code><dd><a name="index-g_t_0040code_007bcosh_005fsinh_005ft_007d-125"></a><dt><code>cosh_sinh_t cosh_sinh (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bcosh_005fsinh-_0028_0029_007d-126"></a>Returns both <code>sinh(x)</code> and <code>cosh(x)</code>. This is more efficient than
computing them separately. The relation <code>cosh^2 - sinh^2 = 1</code> will
hold only approximately.
<br><dt><code>cl_R tanh (const cl_R& x)</code><dd><a name="index-g_t_0040code_007btanh-_0028_0029_007d-127"></a><dt><code>cl_N tanh (const cl_N& x)</code><dd>Returns <code>tanh(x) = sinh(x)/cosh(x)</code>.
<br><dt><code>cl_N asinh (const cl_N& z)</code><dd><a name="index-g_t_0040code_007basinh-_0028_0029_007d-128"></a>Returns <code>arsinh(z)</code>. This is defined as
<code>arsinh(z) = log(z+sqrt(1+z^2))</code> and satisfies
<code>arsinh(-z) = -arsinh(z)</code>.
The range of the result is the strip in the complex domain
<code>-pi/2 <= imagpart(arsinh(z)) <= pi/2</code>, excluding the numbers
with <code>imagpart = -pi/2</code> and <code>realpart > 0</code> and the numbers
with <code>imagpart = pi/2</code> and <code>realpart < 0</code>.
<br><dt><code>cl_N acosh (const cl_N& z)</code><dd><a name="index-g_t_0040code_007bacosh-_0028_0029_007d-129"></a>Returns <code>arcosh(z)</code>. This is defined as
<code>arcosh(z) = 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))</code>.
The range of the result is the half-strip in the complex domain
<code>-pi < imagpart(arcosh(z)) <= pi, realpart(arcosh(z)) >= 0</code>,
excluding the numbers with <code>realpart = 0</code> and <code>-pi < imagpart < 0</code>.
<br><dt><code>cl_N atanh (const cl_N& z)</code><dd><a name="index-g_t_0040code_007batanh-_0028_0029_007d-130"></a>Returns <code>artanh(z)</code>. This is defined as
<code>artanh(z) = (log(1+z)-log(1-z)) / 2</code> and satisfies
<code>artanh(-z) = -artanh(z)</code>. The range of the result is
the strip in the complex domain
<code>-pi/2 <= imagpart(artanh(z)) <= pi/2</code>, excluding the numbers
with <code>imagpart = -pi/2</code> and <code>realpart <= 0</code> and the numbers
with <code>imagpart = pi/2</code> and <code>realpart >= 0</code>.
</dl>
<div class="node">
<a name="Euler-gamma"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Riemann-zeta">Riemann zeta</a>,
Previous: <a rel="previous" accesskey="p" href="#Hyperbolic-functions">Hyperbolic functions</a>,
Up: <a rel="up" accesskey="u" href="#Transcendental-functions">Transcendental functions</a>
</div>
<h4 class="subsection">4.8.4 Euler gamma</h4>
<p><a name="index-Euler_0027s-constant-131"></a>
Euler's constant C = 0.577<small class="dots">...</small> is returned by the following functions:
<dl>
<dt><code>cl_F eulerconst (float_format_t f)</code><dd><a name="index-g_t_0040code_007beulerconst-_0028_0029_007d-132"></a>Returns Euler's constant as a float of format <code>f</code>.
<br><dt><code>cl_F eulerconst (const cl_F& y)</code><dd>Returns Euler's constant in the float format of <code>y</code>.
<br><dt><code>cl_F eulerconst (void)</code><dd>Returns Euler's constant as a float of format <code>default_float_format</code>.
</dl>
<p>Catalan's constant G = 0.915<small class="dots">...</small> is returned by the following functions:
<a name="index-Catalan_0027s-constant-133"></a>
<dl>
<dt><code>cl_F catalanconst (float_format_t f)</code><dd><a name="index-g_t_0040code_007bcatalanconst-_0028_0029_007d-134"></a>Returns Catalan's constant as a float of format <code>f</code>.
<br><dt><code>cl_F catalanconst (const cl_F& y)</code><dd>Returns Catalan's constant in the float format of <code>y</code>.
<br><dt><code>cl_F catalanconst (void)</code><dd>Returns Catalan's constant as a float of format <code>default_float_format</code>.
</dl>
<div class="node">
<a name="Riemann-zeta"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Euler-gamma">Euler gamma</a>,
Up: <a rel="up" accesskey="u" href="#Transcendental-functions">Transcendental functions</a>
</div>
<h4 class="subsection">4.8.5 Riemann zeta</h4>
<p><a name="index-Riemann_0027s-zeta-135"></a>
Riemann's zeta function at an integral point <code>s>1</code> is returned by the
following functions:
<dl>
<dt><code>cl_F zeta (int s, float_format_t f)</code><dd><a name="index-g_t_0040code_007bzeta-_0028_0029_007d-136"></a>Returns Riemann's zeta function at <code>s</code> as a float of format <code>f</code>.
<br><dt><code>cl_F zeta (int s, const cl_F& y)</code><dd>Returns Riemann's zeta function at <code>s</code> in the float format of <code>y</code>.
<br><dt><code>cl_F zeta (int s)</code><dd>Returns Riemann's zeta function at <code>s</code> as a float of format
<code>default_float_format</code>.
</dl>
<div class="node">
<a name="Functions-on-integers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a>,
Previous: <a rel="previous" accesskey="p" href="#Transcendental-functions">Transcendental functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.9 Functions on integers</h3>
<ul class="menu">
<li><a accesskey="1" href="#Logical-functions">Logical functions</a>
<li><a accesskey="2" href="#Number-theoretic-functions">Number theoretic functions</a>
<li><a accesskey="3" href="#Combinatorial-functions">Combinatorial functions</a>
</ul>
<div class="node">
<a name="Logical-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Number-theoretic-functions">Number theoretic functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-integers">Functions on integers</a>
</div>
<h4 class="subsection">4.9.1 Logical functions</h4>
<p>Integers, when viewed as in two's complement notation, can be thought as
infinite bit strings where the bits' values eventually are constant.
For example,
<pre class="example"> 17 = ......00010001
-6 = ......11111010
</pre>
<p>The logical operations view integers as such bit strings and operate
on each of the bit positions in parallel.
<dl>
<dt><code>cl_I lognot (const cl_I& x)</code><dd><a name="index-g_t_0040code_007blognot-_0028_0029_007d-137"></a><dt><code>cl_I operator ~ (const cl_I& x)</code><dd><a name="index-g_t_0040code_007boperator-_007e-_0028_0029_007d-138"></a>Logical not, like <code>~x</code> in C. This is the same as <code>-1-x</code>.
<br><dt><code>cl_I logand (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogand-_0028_0029_007d-139"></a><dt><code>cl_I operator & (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007boperator-_0026-_0028_0029_007d-140"></a>Logical and, like <code>x & y</code> in C.
<br><dt><code>cl_I logior (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogior-_0028_0029_007d-141"></a><dt><code>cl_I operator | (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007boperator-_007c-_0028_0029_007d-142"></a>Logical (inclusive) or, like <code>x | y</code> in C.
<br><dt><code>cl_I logxor (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogxor-_0028_0029_007d-143"></a><dt><code>cl_I operator ^ (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007boperator-_005e-_0028_0029_007d-144"></a>Exclusive or, like <code>x ^ y</code> in C.
<br><dt><code>cl_I logeqv (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogeqv-_0028_0029_007d-145"></a>Bitwise equivalence, like <code>~(x ^ y)</code> in C.
<br><dt><code>cl_I lognand (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blognand-_0028_0029_007d-146"></a>Bitwise not and, like <code>~(x & y)</code> in C.
<br><dt><code>cl_I lognor (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blognor-_0028_0029_007d-147"></a>Bitwise not or, like <code>~(x | y)</code> in C.
<br><dt><code>cl_I logandc1 (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogandc1-_0028_0029_007d-148"></a>Logical and, complementing the first argument, like <code>~x & y</code> in C.
<br><dt><code>cl_I logandc2 (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogandc2-_0028_0029_007d-149"></a>Logical and, complementing the second argument, like <code>x & ~y</code> in C.
<br><dt><code>cl_I logorc1 (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogorc1-_0028_0029_007d-150"></a>Logical or, complementing the first argument, like <code>~x | y</code> in C.
<br><dt><code>cl_I logorc2 (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogorc2-_0028_0029_007d-151"></a>Logical or, complementing the second argument, like <code>x | ~y</code> in C.
</dl>
<p>These operations are all available though the function
<dl>
<dt><code>cl_I boole (cl_boole op, const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bboole-_0028_0029_007d-152"></a></dl>
where <code>op</code> must have one of the 16 values (each one stands for a function
which combines two bits into one bit): <code>boole_clr</code>, <code>boole_set</code>,
<code>boole_1</code>, <code>boole_2</code>, <code>boole_c1</code>, <code>boole_c2</code>,
<code>boole_and</code>, <code>boole_ior</code>, <code>boole_xor</code>, <code>boole_eqv</code>,
<code>boole_nand</code>, <code>boole_nor</code>, <code>boole_andc1</code>, <code>boole_andc2</code>,
<code>boole_orc1</code>, <code>boole_orc2</code>.
<a name="index-g_t_0040code_007bboole_005fclr_007d-153"></a><a name="index-g_t_0040code_007bboole_005fset_007d-154"></a><a name="index-g_t_0040code_007bboole_005f1_007d-155"></a><a name="index-g_t_0040code_007bboole_005f2_007d-156"></a><a name="index-g_t_0040code_007bboole_005fc1_007d-157"></a><a name="index-g_t_0040code_007bboole_005fc2_007d-158"></a><a name="index-g_t_0040code_007bboole_005fand_007d-159"></a><a name="index-g_t_0040code_007bboole_005fxor_007d-160"></a><a name="index-g_t_0040code_007bboole_005feqv_007d-161"></a><a name="index-g_t_0040code_007bboole_005fnand_007d-162"></a><a name="index-g_t_0040code_007bboole_005fnor_007d-163"></a><a name="index-g_t_0040code_007bboole_005fandc1_007d-164"></a><a name="index-g_t_0040code_007bboole_005fandc2_007d-165"></a><a name="index-g_t_0040code_007bboole_005forc1_007d-166"></a><a name="index-g_t_0040code_007bboole_005forc2_007d-167"></a>
<p>Other functions that view integers as bit strings:
<dl>
<dt><code>bool logtest (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007blogtest-_0028_0029_007d-168"></a>Returns true if some bit is set in both <code>x</code> and <code>y</code>, i.e. if
<code>logand(x,y) != 0</code>.
<br><dt><code>bool logbitp (const cl_I& n, const cl_I& x)</code><dd><a name="index-g_t_0040code_007blogbitp-_0028_0029_007d-169"></a>Returns true if the <code>n</code>th bit (from the right) of <code>x</code> is set.
Bit 0 is the least significant bit.
<br><dt><code>uintC logcount (const cl_I& x)</code><dd><a name="index-g_t_0040code_007blogcount-_0028_0029_007d-170"></a>Returns the number of one bits in <code>x</code>, if <code>x</code> >= 0, or
the number of zero bits in <code>x</code>, if <code>x</code> < 0.
</dl>
<p>The following functions operate on intervals of bits in integers.
The type
<pre class="example"> struct cl_byte { uintC size; uintC position; };
</pre>
<p><a name="index-g_t_0040code_007bcl_005fbyte_007d-171"></a>represents the bit interval containing the bits
<code>position</code><small class="dots">...</small><code>position+size-1</code> of an integer.
The constructor <code>cl_byte(size,position)</code> constructs a <code>cl_byte</code>.
<dl>
<dt><code>cl_I ldb (const cl_I& n, const cl_byte& b)</code><dd><a name="index-g_t_0040code_007bldb-_0028_0029_007d-172"></a>extracts the bits of <code>n</code> described by the bit interval <code>b</code>
and returns them as a nonnegative integer with <code>b.size</code> bits.
<br><dt><code>bool ldb_test (const cl_I& n, const cl_byte& b)</code><dd><a name="index-g_t_0040code_007bldb_005ftest-_0028_0029_007d-173"></a>Returns true if some bit described by the bit interval <code>b</code> is set in
<code>n</code>.
<br><dt><code>cl_I dpb (const cl_I& newbyte, const cl_I& n, const cl_byte& b)</code><dd><a name="index-g_t_0040code_007bdpb-_0028_0029_007d-174"></a>Returns <code>n</code>, with the bits described by the bit interval <code>b</code>
replaced by <code>newbyte</code>. Only the lowest <code>b.size</code> bits of
<code>newbyte</code> are relevant.
</dl>
<p>The functions <code>ldb</code> and <code>dpb</code> implicitly shift. The following
functions are their counterparts without shifting:
<dl>
<dt><code>cl_I mask_field (const cl_I& n, const cl_byte& b)</code><dd><a name="index-g_t_0040code_007bmask_005ffield-_0028_0029_007d-175"></a>returns an integer with the bits described by the bit interval <code>b</code>
copied from the corresponding bits in <code>n</code>, the other bits zero.
<br><dt><code>cl_I deposit_field (const cl_I& newbyte, const cl_I& n, const cl_byte& b)</code><dd><a name="index-g_t_0040code_007bdeposit_005ffield-_0028_0029_007d-176"></a>returns an integer where the bits described by the bit interval <code>b</code>
come from <code>newbyte</code> and the other bits come from <code>n</code>.
</dl>
<p>The following relations hold:
<ul>
<li><code>ldb (n, b) = mask_field(n, b) >> b.position</code>,
<li><code>dpb (newbyte, n, b) = deposit_field (newbyte << b.position, n, b)</code>,
<li><code>deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^ mask_field(new_byte,b)</code>.
</ul>
<p>The following operations on integers as bit strings are efficient shortcuts
for common arithmetic operations:
<dl>
<dt><code>bool oddp (const cl_I& x)</code><dd><a name="index-g_t_0040code_007boddp-_0028_0029_007d-177"></a>Returns true if the least significant bit of <code>x</code> is 1. Equivalent to
<code>mod(x,2) != 0</code>.
<br><dt><code>bool evenp (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bevenp-_0028_0029_007d-178"></a>Returns true if the least significant bit of <code>x</code> is 0. Equivalent to
<code>mod(x,2) == 0</code>.
<br><dt><code>cl_I operator << (const cl_I& x, const cl_I& n)</code><dd><a name="index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-179"></a>Shifts <code>x</code> by <code>n</code> bits to the left. <code>n</code> should be >=0.
Equivalent to <code>x * expt(2,n)</code>.
<br><dt><code>cl_I operator >> (const cl_I& x, const cl_I& n)</code><dd><a name="index-g_t_0040code_007boperator-_003e_003e-_0028_0029_007d-180"></a>Shifts <code>x</code> by <code>n</code> bits to the right. <code>n</code> should be >=0.
Bits shifted out to the right are thrown away.
Equivalent to <code>floor(x / expt(2,n))</code>.
<br><dt><code>cl_I ash (const cl_I& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bash-_0028_0029_007d-181"></a>Shifts <code>x</code> by <code>y</code> bits to the left (if <code>y</code>>=0) or
by <code>-y</code> bits to the right (if <code>y</code><=0). In other words, this
returns <code>floor(x * expt(2,y))</code>.
<br><dt><code>uintC integer_length (const cl_I& x)</code><dd><a name="index-g_t_0040code_007binteger_005flength-_0028_0029_007d-182"></a>Returns the number of bits (excluding the sign bit) needed to represent <code>x</code>
in two's complement notation. This is the smallest n >= 0 such that
-2^n <= x < 2^n. If x > 0, this is the unique n > 0 such that
2^(n-1) <= x < 2^n.
<br><dt><code>uintC ord2 (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bord2-_0028_0029_007d-183"></a><code>x</code> must be non-zero. This function returns the number of 0 bits at the
right of <code>x</code> in two's complement notation. This is the largest n >= 0
such that 2^n divides <code>x</code>.
<br><dt><code>uintC power2p (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bpower2p-_0028_0029_007d-184"></a><code>x</code> must be > 0. This function checks whether <code>x</code> is a power of 2.
If <code>x</code> = 2^(n-1), it returns n. Else it returns 0.
(See also the function <code>logp</code>.)
</dl>
<div class="node">
<a name="Number-theoretic-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Combinatorial-functions">Combinatorial functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Logical-functions">Logical functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-integers">Functions on integers</a>
</div>
<h4 class="subsection">4.9.2 Number theoretic functions</h4>
<dl>
<dt><code>uint32 gcd (unsigned long a, unsigned long b)</code><dd><a name="index-g_t_0040code_007bgcd-_0028_0029_007d-185"></a><dt><code>cl_I gcd (const cl_I& a, const cl_I& b)</code><dd>This function returns the greatest common divisor of <code>a</code> and <code>b</code>,
normalized to be >= 0.
<br><dt><code>cl_I xgcd (const cl_I& a, const cl_I& b, cl_I* u, cl_I* v)</code><dd><a name="index-g_t_0040code_007bxgcd-_0028_0029_007d-186"></a>This function (“extended gcd”) returns the greatest common divisor <code>g</code> of
<code>a</code> and <code>b</code> and at the same time the representation of <code>g</code>
as an integral linear combination of <code>a</code> and <code>b</code>:
<code>u</code> and <code>v</code> with <code>u*a+v*b = g</code>, <code>g</code> >= 0.
<code>u</code> and <code>v</code> will be normalized to be of smallest possible absolute
value, in the following sense: If <code>a</code> and <code>b</code> are non-zero, and
<code>abs(a) != abs(b)</code>, <code>u</code> and <code>v</code> will satisfy the inequalities
<code>abs(u) <= abs(b)/(2*g)</code>, <code>abs(v) <= abs(a)/(2*g)</code>.
<br><dt><code>cl_I lcm (const cl_I& a, const cl_I& b)</code><dd><a name="index-g_t_0040code_007blcm-_0028_0029_007d-187"></a>This function returns the least common multiple of <code>a</code> and <code>b</code>,
normalized to be >= 0.
<br><dt><code>bool logp (const cl_I& a, const cl_I& b, cl_RA* l)</code><dd><a name="index-g_t_0040code_007blogp-_0028_0029_007d-188"></a><dt><code>bool logp (const cl_RA& a, const cl_RA& b, cl_RA* l)</code><dd><code>a</code> must be > 0. <code>b</code> must be >0 and != 1. If log(a,b) is
rational number, this function returns true and sets *l = log(a,b), else
it returns false.
<br><dt><code>int jacobi (signed long a, signed long b)</code><dd><a name="index-g_t_0040code_007bjacobi_0028_0029_007d-189"></a><dt><code>int jacobi (const cl_I& a, const cl_I& b)</code><dd>Returns the Jacobi symbol
(a/b),
<code>a,b</code> must be integers, <code>b>0</code> and odd. The result is 0
iff gcd(a,b)>1.
<br><dt><code>bool isprobprime (const cl_I& n)</code><dd><a name="index-prime-190"></a><a name="index-g_t_0040code_007bisprobprime_0028_0029_007d-191"></a>Returns true if <code>n</code> is a small prime or passes the Miller-Rabin
primality test. The probability of a false positive is 1:10^30.
<br><dt><code>cl_I nextprobprime (const cl_R& x)</code><dd><a name="index-g_t_0040code_007bnextprobprime_0028_0029_007d-192"></a>Returns the smallest probable prime >=<code>x</code>.
</dl>
<div class="node">
<a name="Combinatorial-functions"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Number-theoretic-functions">Number theoretic functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-integers">Functions on integers</a>
</div>
<h4 class="subsection">4.9.3 Combinatorial functions</h4>
<dl>
<dt><code>cl_I factorial (uintL n)</code><dd><a name="index-g_t_0040code_007bfactorial-_0028_0029_007d-193"></a><code>n</code> must be a small integer >= 0. This function returns the factorial
<code>n</code>! = <code>1*2*...*n</code>.
<br><dt><code>cl_I doublefactorial (uintL n)</code><dd><a name="index-g_t_0040code_007bdoublefactorial-_0028_0029_007d-194"></a><code>n</code> must be a small integer >= 0. This function returns the
doublefactorial <code>n</code>!! = <code>1*3*...*n</code> or
<code>n</code>!! = <code>2*4*...*n</code>, respectively.
<br><dt><code>cl_I binomial (uintL n, uintL k)</code><dd><a name="index-g_t_0040code_007bbinomial-_0028_0029_007d-195"></a><code>n</code> and <code>k</code> must be small integers >= 0. This function returns the
binomial coefficient
for 0 <= k <= n, 0 else.
</dl>
<div class="node">
<a name="Functions-on-floating-point-numbers"></a>
<a name="Functions-on-floating_002dpoint-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Conversion-functions">Conversion functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Functions-on-integers">Functions on integers</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.10 Functions on floating-point numbers</h3>
<p>Recall that a floating-point number consists of a sign <code>s</code>, an
exponent <code>e</code> and a mantissa <code>m</code>. The value of the number is
<code>(-1)^s * 2^e * m</code>.
<p>Each of the classes
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines the following operations.
<dl>
<dt><var>type</var><code> scale_float (const </code><var>type</var><code>& x, sintC delta)</code><dd><a name="index-g_t_0040code_007bscale_005ffloat-_0028_0029_007d-196"></a><dt><var>type</var><code> scale_float (const </code><var>type</var><code>& x, const cl_I& delta)</code><dd>Returns <code>x*2^delta</code>. This is more efficient than an explicit multiplication
because it copies <code>x</code> and modifies the exponent.
</dl>
<p>The following functions provide an abstract interface to the underlying
representation of floating-point numbers.
<dl>
<dt><code>sintE float_exponent (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloat_005fexponent-_0028_0029_007d-197"></a>Returns the exponent <code>e</code> of <code>x</code>.
For <code>x = 0.0</code>, this is 0. For <code>x</code> non-zero, this is the unique
integer with <code>2^(e-1) <= abs(x) < 2^e</code>.
<br><dt><code>sintL float_radix (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloat_005fradix-_0028_0029_007d-198"></a>Returns the base of the floating-point representation. This is always <code>2</code>.
<br><dt><var>type</var><code> float_sign (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloat_005fsign-_0028_0029_007d-199"></a>Returns the sign <code>s</code> of <code>x</code> as a float. The value is 1 for
<code>x</code> >= 0, -1 for <code>x</code> < 0.
<br><dt><code>uintC float_digits (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloat_005fdigits-_0028_0029_007d-200"></a>Returns the number of mantissa bits in the floating-point representation
of <code>x</code>, including the hidden bit. The value only depends on the type
of <code>x</code>, not on its value.
<br><dt><code>uintC float_precision (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bfloat_005fprecision-_0028_0029_007d-201"></a>Returns the number of significant mantissa bits in the floating-point
representation of <code>x</code>. Since denormalized numbers are not supported,
this is the same as <code>float_digits(x)</code> if <code>x</code> is non-zero, and
0 if <code>x</code> = 0.
</dl>
<p>The complete internal representation of a float is encoded in the type
<a name="index-g_t_0040code_007bdecoded_005ffloat_007d-202"></a><a name="index-g_t_0040code_007bdecoded_005fsfloat_007d-203"></a><a name="index-g_t_0040code_007bdecoded_005fffloat_007d-204"></a><a name="index-g_t_0040code_007bdecoded_005fdfloat_007d-205"></a><a name="index-g_t_0040code_007bdecoded_005flfloat_007d-206"></a><code>decoded_float</code> (or <code>decoded_sfloat</code>, <code>decoded_ffloat</code>,
<code>decoded_dfloat</code>, <code>decoded_lfloat</code>, respectively), defined by
<pre class="example"> struct decoded_<var>type</var>float {
<var>type</var> mantissa; cl_I exponent; <var>type</var> sign;
};
</pre>
<p>and returned by the function
<dl>
<dt><code>decoded_</code><var>type</var><code>float decode_float (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007bdecode_005ffloat-_0028_0029_007d-207"></a>For <code>x</code> non-zero, this returns <code>(-1)^s</code>, <code>e</code>, <code>m</code> with
<code>x = (-1)^s * 2^e * m</code> and <code>0.5 <= m < 1.0</code>. For <code>x</code> = 0,
it returns <code>(-1)^s</code>=1, <code>e</code>=0, <code>m</code>=0.
<code>e</code> is the same as returned by the function <code>float_exponent</code>.
</dl>
<p>A complete decoding in terms of integers is provided as type
<a name="index-g_t_0040code_007bcl_005fidecoded_005ffloat_007d-208"></a>
<pre class="example"> struct cl_idecoded_float {
cl_I mantissa; cl_I exponent; cl_I sign;
};
</pre>
<p>by the following function:
<dl>
<dt><code>cl_idecoded_float integer_decode_float (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007binteger_005fdecode_005ffloat-_0028_0029_007d-209"></a>For <code>x</code> non-zero, this returns <code>(-1)^s</code>, <code>e</code>, <code>m</code> with
<code>x = (-1)^s * 2^e * m</code> and <code>m</code> an integer with <code>float_digits(x)</code>
bits. For <code>x</code> = 0, it returns <code>(-1)^s</code>=1, <code>e</code>=0, <code>m</code>=0.
WARNING: The exponent <code>e</code> is not the same as the one returned by
the functions <code>decode_float</code> and <code>float_exponent</code>.
</dl>
<p>Some other function, implemented only for class <code>cl_F</code>:
<dl>
<dt><code>cl_F float_sign (const cl_F& x, const cl_F& y)</code><dd><a name="index-g_t_0040code_007bfloat_005fsign-_0028_0029_007d-210"></a>This returns a floating point number whose precision and absolute value
is that of <code>y</code> and whose sign is that of <code>x</code>. If <code>x</code> is
zero, it is treated as positive. Same for <code>y</code>.
</dl>
<div class="node">
<a name="Conversion-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Random-number-generators">Random number generators</a>,
Previous: <a rel="previous" accesskey="p" href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.11 Conversion functions</h3>
<p><a name="index-conversion-211"></a>
<ul class="menu">
<li><a accesskey="1" href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a>
<li><a accesskey="2" href="#Conversion-to-rational-numbers">Conversion to rational numbers</a>
</ul>
<div class="node">
<a name="Conversion-to-floating-point-numbers"></a>
<a name="Conversion-to-floating_002dpoint-numbers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Conversion-to-rational-numbers">Conversion to rational numbers</a>,
Up: <a rel="up" accesskey="u" href="#Conversion-functions">Conversion functions</a>
</div>
<h4 class="subsection">4.11.1 Conversion to floating-point numbers</h4>
<p>The type <code>float_format_t</code> describes a floating-point format.
<a name="index-g_t_0040code_007bfloat_005fformat_005ft_007d-212"></a>
<dl>
<dt><code>float_format_t float_format (uintE n)</code><dd><a name="index-g_t_0040code_007bfloat_005fformat-_0028_0029_007d-213"></a>Returns the smallest float format which guarantees at least <code>n</code>
decimal digits in the mantissa (after the decimal point).
<br><dt><code>float_format_t float_format (const cl_F& x)</code><dd>Returns the floating point format of <code>x</code>.
<br><dt><code>float_format_t default_float_format</code><dd><a name="index-g_t_0040code_007bdefault_005ffloat_005fformat_007d-214"></a>Global variable: the default float format used when converting rational numbers
to floats.
</dl>
<p>To convert a real number to a float, each of the types
<code>cl_R</code>, <code>cl_F</code>, <code>cl_I</code>, <code>cl_RA</code>,
<code>int</code>, <code>unsigned int</code>, <code>float</code>, <code>double</code>
defines the following operations:
<dl>
<dt><code>cl_F cl_float (const </code><var>type</var><code>&x, float_format_t f)</code><dd><a name="index-g_t_0040code_007bcl_005ffloat-_0028_0029_007d-215"></a>Returns <code>x</code> as a float of format <code>f</code>.
<br><dt><code>cl_F cl_float (const </code><var>type</var><code>&x, const cl_F& y)</code><dd>Returns <code>x</code> in the float format of <code>y</code>.
<br><dt><code>cl_F cl_float (const </code><var>type</var><code>&x)</code><dd>Returns <code>x</code> as a float of format <code>default_float_format</code> if
it is an exact number, or <code>x</code> itself if it is already a float.
</dl>
<p>Of course, converting a number to a float can lose precision.
<p>Every floating-point format has some characteristic numbers:
<dl>
<dt><code>cl_F most_positive_float (float_format_t f)</code><dd><a name="index-g_t_0040code_007bmost_005fpositive_005ffloat-_0028_0029_007d-216"></a>Returns the largest (most positive) floating point number in float format <code>f</code>.
<br><dt><code>cl_F most_negative_float (float_format_t f)</code><dd><a name="index-g_t_0040code_007bmost_005fnegative_005ffloat-_0028_0029_007d-217"></a>Returns the smallest (most negative) floating point number in float format <code>f</code>.
<br><dt><code>cl_F least_positive_float (float_format_t f)</code><dd><a name="index-g_t_0040code_007bleast_005fpositive_005ffloat-_0028_0029_007d-218"></a>Returns the least positive floating point number (i.e. > 0 but closest to 0)
in float format <code>f</code>.
<br><dt><code>cl_F least_negative_float (float_format_t f)</code><dd><a name="index-g_t_0040code_007bleast_005fnegative_005ffloat-_0028_0029_007d-219"></a>Returns the least negative floating point number (i.e. < 0 but closest to 0)
in float format <code>f</code>.
<br><dt><code>cl_F float_epsilon (float_format_t f)</code><dd><a name="index-g_t_0040code_007bfloat_005fepsilon-_0028_0029_007d-220"></a>Returns the smallest floating point number e > 0 such that <code>1+e != 1</code>.
<br><dt><code>cl_F float_negative_epsilon (float_format_t f)</code><dd><a name="index-g_t_0040code_007bfloat_005fnegative_005fepsilon-_0028_0029_007d-221"></a>Returns the smallest floating point number e > 0 such that <code>1-e != 1</code>.
</dl>
<div class="node">
<a name="Conversion-to-rational-numbers"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a>,
Up: <a rel="up" accesskey="u" href="#Conversion-functions">Conversion functions</a>
</div>
<h4 class="subsection">4.11.2 Conversion to rational numbers</h4>
<p>Each of the classes <code>cl_R</code>, <code>cl_RA</code>, <code>cl_F</code>
defines the following operation:
<dl>
<dt><code>cl_RA rational (const </code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007brational-_0028_0029_007d-222"></a>Returns the value of <code>x</code> as an exact number. If <code>x</code> is already
an exact number, this is <code>x</code>. If <code>x</code> is a floating-point number,
the value is a rational number whose denominator is a power of 2.
</dl>
<p>In order to convert back, say, <code>(cl_F)(cl_R)"1/3"</code> to <code>1/3</code>, there is
the function
<dl>
<dt><code>cl_RA rationalize (const cl_R& x)</code><dd><a name="index-g_t_0040code_007brationalize-_0028_0029_007d-223"></a>If <code>x</code> is a floating-point number, it actually represents an interval
of real numbers, and this function returns the rational number with
smallest denominator (and smallest numerator, in magnitude)
which lies in this interval.
If <code>x</code> is already an exact number, this function returns <code>x</code>.
</dl>
<p>If <code>x</code> is any float, one has
<ul>
<li><code>cl_float(rational(x),x) = x</code>
<li><code>cl_float(rationalize(x),x) = x</code>
</ul>
<div class="node">
<a name="Random-number-generators"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Modifying-operators">Modifying operators</a>,
Previous: <a rel="previous" accesskey="p" href="#Conversion-functions">Conversion functions</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.12 Random number generators</h3>
<p>A random generator is a machine which produces (pseudo-)random numbers.
The include file <code><cln/random.h></code> defines a class <code>random_state</code>
which contains the state of a random generator. If you make a copy
of the random number generator, the original one and the copy will produce
the same sequence of random numbers.
<p>The following functions return (pseudo-)random numbers in different formats.
Calling one of these modifies the state of the random number generator in
a complicated but deterministic way.
<p>The global variable
<a name="index-g_t_0040code_007brandom_005fstate_007d-224"></a><a name="index-g_t_0040code_007bdefault_005frandom_005fstate_007d-225"></a>
<pre class="example"> random_state default_random_state
</pre>
<p>contains a default random number generator. It is used when the functions
below are called without <code>random_state</code> argument.
<dl>
<dt><code>uint32 random32 (random_state& randomstate)</code><dt><code>uint32 random32 ()</code><dd><a name="index-g_t_0040code_007brandom32-_0028_0029_007d-226"></a>Returns a random unsigned 32-bit number. All bits are equally random.
<br><dt><code>cl_I random_I (random_state& randomstate, const cl_I& n)</code><dt><code>cl_I random_I (const cl_I& n)</code><dd><a name="index-g_t_0040code_007brandom_005fI-_0028_0029_007d-227"></a><code>n</code> must be an integer > 0. This function returns a random integer <code>x</code>
in the range <code>0 <= x < n</code>.
<br><dt><code>cl_F random_F (random_state& randomstate, const cl_F& n)</code><dt><code>cl_F random_F (const cl_F& n)</code><dd><a name="index-g_t_0040code_007brandom_005fF-_0028_0029_007d-228"></a><code>n</code> must be a float > 0. This function returns a random floating-point
number of the same format as <code>n</code> in the range <code>0 <= x < n</code>.
<br><dt><code>cl_R random_R (random_state& randomstate, const cl_R& n)</code><dt><code>cl_R random_R (const cl_R& n)</code><dd><a name="index-g_t_0040code_007brandom_005fR-_0028_0029_007d-229"></a>Behaves like <code>random_I</code> if <code>n</code> is an integer and like <code>random_F</code>
if <code>n</code> is a float.
</dl>
<div class="node">
<a name="Modifying-operators"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Random-number-generators">Random number generators</a>,
Up: <a rel="up" accesskey="u" href="#Functions-on-numbers">Functions on numbers</a>
</div>
<h3 class="section">4.13 Modifying operators</h3>
<p><a name="index-modifying-operators-230"></a>
The modifying C/C++ operators <code>+=</code>, <code>-=</code>, <code>*=</code>, <code>/=</code>,
<code>&=</code>, <code>|=</code>, <code>^=</code>, <code><<=</code>, <code>>>=</code>
are all available.
<p>For the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>:
<dl>
<dt><var>type</var><code>& operator += (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002b_003d-_0028_0029_007d-231"></a><dt><var>type</var><code>& operator -= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002d_003d-_0028_0029_007d-232"></a><dt><var>type</var><code>& operator *= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002a_003d-_0028_0029_007d-233"></a><dt><var>type</var><code>& operator /= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_002f_003d-_0028_0029_007d-234"></a></dl>
<p>For the class <code>cl_I</code>:
<dl>
<dt><var>type</var><code>& operator += (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dt><var>type</var><code>& operator -= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dt><var>type</var><code>& operator *= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dt><var>type</var><code>& operator &= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_0026_003d-_0028_0029_007d-235"></a><dt><var>type</var><code>& operator |= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_007c_003d-_0028_0029_007d-236"></a><dt><var>type</var><code>& operator ^= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_005e_003d-_0028_0029_007d-237"></a><dt><var>type</var><code>& operator <<= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003c_003c_003d-_0028_0029_007d-238"></a><dt><var>type</var><code>& operator >>= (</code><var>type</var><code>&, const </code><var>type</var><code>&)</code><dd><a name="index-g_t_0040code_007boperator-_003e_003e_003d-_0028_0029_007d-239"></a></dl>
<p>For the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>:
<dl>
<dt><var>type</var><code>& operator ++ (</code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007boperator-_002b_002b-_0028_0029_007d-240"></a>The prefix operator <code>++x</code>.
<br><dt><code>void operator ++ (</code><var>type</var><code>& x, int)</code><dd>The postfix operator <code>x++</code>.
<br><dt><var>type</var><code>& operator -- (</code><var>type</var><code>& x)</code><dd><a name="index-g_t_0040code_007boperator-_002d_002d-_0028_0029_007d-241"></a>The prefix operator <code>--x</code>.
<br><dt><code>void operator -- (</code><var>type</var><code>& x, int)</code><dd>The postfix operator <code>x--</code>.
</dl>
<p>Note that by using these modifying operators, you don't gain efficiency:
In CLN ‘<samp><span class="samp">x += y;</span></samp>’ is exactly the same as ‘<samp><span class="samp">x = x+y;</span></samp>’, not more
efficient.
<div class="node">
<a name="Input%2fOutput"></a>
<a name="Input_002fOutput"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Rings">Rings</a>,
Previous: <a rel="previous" accesskey="p" href="#Functions-on-numbers">Functions on numbers</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">5 Input/Output</h2>
<p><a name="index-Input_002fOutput-242"></a>
<ul class="menu">
<li><a accesskey="1" href="#Internal-and-printed-representation">Internal and printed representation</a>
<li><a accesskey="2" href="#Input-functions">Input functions</a>
<li><a accesskey="3" href="#Output-functions">Output functions</a>
</ul>
<div class="node">
<a name="Internal-and-printed-representation"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Input-functions">Input functions</a>,
Up: <a rel="up" accesskey="u" href="#Input_002fOutput">Input/Output</a>
</div>
<h3 class="section">5.1 Internal and printed representation</h3>
<p><a name="index-representation-243"></a>
All computations deal with the internal representations of the numbers.
<p>Every number has an external representation as a sequence of ASCII characters.
Several external representations may denote the same number, for example,
"20.0" and "20.000".
<p>Converting an internal to an external representation is called “printing”,
<a name="index-printing-244"></a>converting an external to an internal representation is called “reading”.
<a name="index-reading-245"></a>In CLN, it is always true that conversion of an internal to an external
representation and then back to an internal representation will yield the
same internal representation. Symbolically: <code>read(print(x)) == x</code>.
This is called “print-read consistency”.
<p>Different types of numbers have different external representations (case
is insignificant):
<dl>
<dt>Integers<dd>External representation: <var>sign</var>{<var>digit</var>}+. The reader also accepts the
Common Lisp syntaxes <var>sign</var>{<var>digit</var>}+<code>.</code> with a trailing dot
for decimal integers
and the <code>#</code><var>n</var><code>R</code>, <code>#b</code>, <code>#o</code>, <code>#x</code> prefixes.
<br><dt>Rational numbers<dd>External representation: <var>sign</var>{<var>digit</var>}+<code>/</code>{<var>digit</var>}+.
The <code>#</code><var>n</var><code>R</code>, <code>#b</code>, <code>#o</code>, <code>#x</code> prefixes are allowed
here as well.
<br><dt>Floating-point numbers<dd>External representation: <var>sign</var>{<var>digit</var>}*<var>exponent</var> or
<var>sign</var>{<var>digit</var>}*<code>.</code>{<var>digit</var>}*<var>exponent</var> or
<var>sign</var>{<var>digit</var>}*<code>.</code>{<var>digit</var>}+. A precision specifier
of the form _<var>prec</var> may be appended. There must be at least
one digit in the non-exponent part. The exponent has the syntax
<var>expmarker</var> <var>expsign</var> {<var>digit</var>}+.
The exponent marker is
<ul>
<li>‘<samp><span class="samp">s</span></samp>’ for short-floats,
<li>‘<samp><span class="samp">f</span></samp>’ for single-floats,
<li>‘<samp><span class="samp">d</span></samp>’ for double-floats,
<li>‘<samp><span class="samp">L</span></samp>’ for long-floats,
</ul>
<p>or ‘<samp><span class="samp">e</span></samp>’, which denotes a default float format. The precision specifying
suffix has the syntax _<var>prec</var> where <var>prec</var> denotes the number of
valid mantissa digits (in decimal, excluding leading zeroes), cf. also
function ‘<samp><span class="samp">float_format</span></samp>’.
<br><dt>Complex numbers<dd>External representation:
<ul>
<li>In algebraic notation: <var>realpart</var><code>+</code><var>imagpart</var><code>i</code>. Of course,
if <var>imagpart</var> is negative, its printed representation begins with
a ‘<samp><span class="samp">-</span></samp>’, and the ‘<samp><span class="samp">+</span></samp>’ between <var>realpart</var> and <var>imagpart</var>
may be omitted. Note that this notation cannot be used when the <var>imagpart</var>
is rational and the rational number's base is >18, because the ‘<samp><span class="samp">i</span></samp>’
is then read as a digit.
<li>In Common Lisp notation: <code>#C(</code><var>realpart</var> <var>imagpart</var><code>)</code>.
</ul>
</dl>
<div class="node">
<a name="Input-functions"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Output-functions">Output functions</a>,
Previous: <a rel="previous" accesskey="p" href="#Internal-and-printed-representation">Internal and printed representation</a>,
Up: <a rel="up" accesskey="u" href="#Input_002fOutput">Input/Output</a>
</div>
<h3 class="section">5.2 Input functions</h3>
<p>Including <code><cln/io.h></code> defines flexible input functions:
<dl>
<dt><code>cl_N read_complex (std::istream& stream, const cl_read_flags& flags)</code><dt><code>cl_R read_real (std::istream& stream, const cl_read_flags& flags)</code><dt><code>cl_F read_float (std::istream& stream, const cl_read_flags& flags)</code><dt><code>cl_RA read_rational (std::istream& stream, const cl_read_flags& flags)</code><dt><code>cl_I read_integer (std::istream& stream, const cl_read_flags& flags)</code><dd>Reads a number from <code>stream</code>. The <code>flags</code> are parameters which
affect the input syntax. Whitespace before the number is silently skipped.
<br><dt><code>cl_N read_complex (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)</code><dt><code>cl_R read_real (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)</code><dt><code>cl_F read_float (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)</code><dt><code>cl_RA read_rational (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)</code><dt><code>cl_I read_integer (const cl_read_flags& flags, const char * string, const char * string_limit, const char * * end_of_parse)</code><dd>Reads a number from a string in memory. The <code>flags</code> are parameters which
affect the input syntax. The string starts at <code>string</code> and ends at
<code>string_limit</code> (exclusive limit). <code>string_limit</code> may also be
<code>NULL</code>, denoting the entire string, i.e. equivalent to
<code>string_limit = string + strlen(string)</code>. If <code>end_of_parse</code> is
<code>NULL</code>, the string in memory must contain exactly one number and nothing
more, else an exception will be thrown. If <code>end_of_parse</code>
is not <code>NULL</code>, <code>*end_of_parse</code> will be assigned a pointer past
the last parsed character (i.e. <code>string_limit</code> if nothing came after
the number). Whitespace is not allowed.
</dl>
<p>The structure <code>cl_read_flags</code> contains the following fields:
<dl>
<dt><code>cl_read_syntax_t syntax</code><dd>The possible results of the read operation. Possible values are
<code>syntax_number</code>, <code>syntax_real</code>, <code>syntax_rational</code>,
<code>syntax_integer</code>, <code>syntax_float</code>, <code>syntax_sfloat</code>,
<code>syntax_ffloat</code>, <code>syntax_dfloat</code>, <code>syntax_lfloat</code>.
<br><dt><code>cl_read_lsyntax_t lsyntax</code><dd>Specifies the language-dependent syntax variant for the read operation.
Possible values are
<dl>
<dt><code>lsyntax_standard</code><dd>accept standard algebraic notation only, no complex numbers,
<br><dt><code>lsyntax_algebraic</code><dd>accept the algebraic notation <var>x</var><code>+</code><var>y</var><code>i</code> for complex numbers,
<br><dt><code>lsyntax_commonlisp</code><dd>accept the <code>#b</code>, <code>#o</code>, <code>#x</code> syntaxes for binary, octal,
hexadecimal numbers,
<code>#</code><var>base</var><code>R</code> for rational numbers in a given base,
<code>#c(</code><var>realpart</var> <var>imagpart</var><code>)</code> for complex numbers,
<br><dt><code>lsyntax_all</code><dd>accept all of these extensions.
</dl>
<br><dt><code>unsigned int rational_base</code><dd>The base in which rational numbers are read.
<br><dt><code>float_format_t float_flags.default_float_format</code><dd>The float format used when reading floats with exponent marker ‘<samp><span class="samp">e</span></samp>’.
<br><dt><code>float_format_t float_flags.default_lfloat_format</code><dd>The float format used when reading floats with exponent marker ‘<samp><span class="samp">l</span></samp>’.
<br><dt><code>bool float_flags.mantissa_dependent_float_format</code><dd>When this flag is true, floats specified with more digits than corresponding
to the exponent marker they contain, but without <var>_nnn</var> suffix, will get a
precision corresponding to their number of significant digits.
</dl>
<div class="node">
<a name="Output-functions"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Input-functions">Input functions</a>,
Up: <a rel="up" accesskey="u" href="#Input_002fOutput">Input/Output</a>
</div>
<h3 class="section">5.3 Output functions</h3>
<p>Including <code><cln/io.h></code> defines a number of simple output functions
that write to <code>std::ostream&</code>:
<dl>
<dt><code>void fprintchar (std::ostream& stream, char c)</code><dd>Prints the character <code>x</code> literally on the <code>stream</code>.
<br><dt><code>void fprint (std::ostream& stream, const char * string)</code><dd>Prints the <code>string</code> literally on the <code>stream</code>.
<br><dt><code>void fprintdecimal (std::ostream& stream, int x)</code><dt><code>void fprintdecimal (std::ostream& stream, const cl_I& x)</code><dd>Prints the integer <code>x</code> in decimal on the <code>stream</code>.
<br><dt><code>void fprintbinary (std::ostream& stream, const cl_I& x)</code><dd>Prints the integer <code>x</code> in binary (base 2, without prefix)
on the <code>stream</code>.
<br><dt><code>void fprintoctal (std::ostream& stream, const cl_I& x)</code><dd>Prints the integer <code>x</code> in octal (base 8, without prefix)
on the <code>stream</code>.
<br><dt><code>void fprinthexadecimal (std::ostream& stream, const cl_I& x)</code><dd>Prints the integer <code>x</code> in hexadecimal (base 16, without prefix)
on the <code>stream</code>.
</dl>
<p>Each of the classes <code>cl_N</code>, <code>cl_R</code>, <code>cl_RA</code>, <code>cl_I</code>,
<code>cl_F</code>, <code>cl_SF</code>, <code>cl_FF</code>, <code>cl_DF</code>, <code>cl_LF</code>
defines, in <code><cln/</code><var>type</var><code>_io.h></code>, the following output functions:
<dl>
<dt><code>void fprint (std::ostream& stream, const </code><var>type</var><code>& x)</code><dt><code>std::ostream& operator<< (std::ostream& stream, const </code><var>type</var><code>& x)</code><dd>Prints the number <code>x</code> on the <code>stream</code>. The output may depend
on the global printer settings in the variable <code>default_print_flags</code>.
The <code>ostream</code> flags and settings (flags, width and locale) are
ignored.
</dl>
<p>The most flexible output function, defined in <code><cln/</code><var>type</var><code>_io.h></code>,
are the following:
<pre class="example"> void print_complex (std::ostream& stream, const cl_print_flags& flags,
const cl_N& z);
void print_real (std::ostream& stream, const cl_print_flags& flags,
const cl_R& z);
void print_float (std::ostream& stream, const cl_print_flags& flags,
const cl_F& z);
void print_rational (std::ostream& stream, const cl_print_flags& flags,
const cl_RA& z);
void print_integer (std::ostream& stream, const cl_print_flags& flags,
const cl_I& z);
</pre>
<p>Prints the number <code>x</code> on the <code>stream</code>. The <code>flags</code> are
parameters which affect the output.
<p>The structure type <code>cl_print_flags</code> contains the following fields:
<dl>
<dt><code>unsigned int rational_base</code><dd>The base in which rational numbers are printed. Default is <code>10</code>.
<br><dt><code>bool rational_readably</code><dd>If this flag is true, rational numbers are printed with radix specifiers in
Common Lisp syntax (<code>#</code><var>n</var><code>R</code> or <code>#b</code> or <code>#o</code> or <code>#x</code>
prefixes, trailing dot). Default is false.
<br><dt><code>bool float_readably</code><dd>If this flag is true, type specific exponent markers have precedence over 'E'.
Default is false.
<br><dt><code>float_format_t default_float_format</code><dd>Floating point numbers of this format will be printed using the 'E' exponent
marker. Default is <code>float_format_ffloat</code>.
<br><dt><code>bool complex_readably</code><dd>If this flag is true, complex numbers will be printed using the Common Lisp
syntax <code>#C(</code><var>realpart</var> <var>imagpart</var><code>)</code>. Default is false.
<br><dt><code>cl_string univpoly_varname</code><dd>Univariate polynomials with no explicit indeterminate name will be printed
using this variable name. Default is <code>"x"</code>.
</dl>
<p>The global variable <code>default_print_flags</code> contains the default values,
used by the function <code>fprint</code>.
<div class="node">
<a name="Rings"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Modular-integers">Modular integers</a>,
Previous: <a rel="previous" accesskey="p" href="#Input_002fOutput">Input/Output</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">6 Rings</h2>
<p>CLN has a class of abstract rings.
<pre class="example"> Ring
cl_ring
<cln/ring.h>
</pre>
<p>Rings can be compared for equality:
<dl>
<dt><code>bool operator== (const cl_ring&, const cl_ring&)</code><dt><code>bool operator!= (const cl_ring&, const cl_ring&)</code><dd>These compare two rings for equality.
</dl>
<p>Given a ring <code>R</code>, the following members can be used.
<dl>
<dt><code>void R->fprint (std::ostream& stream, const cl_ring_element& x)</code><dd><a name="index-g_t_0040code_007bfprint-_0028_0029_007d-246"></a><dt><code>bool R->equal (const cl_ring_element& x, const cl_ring_element& y)</code><dd><a name="index-g_t_0040code_007bequal-_0028_0029_007d-247"></a><dt><code>cl_ring_element R->zero ()</code><dd><a name="index-g_t_0040code_007bzero-_0028_0029_007d-248"></a><dt><code>bool R->zerop (const cl_ring_element& x)</code><dd><a name="index-g_t_0040code_007bzerop-_0028_0029_007d-249"></a><dt><code>cl_ring_element R->plus (const cl_ring_element& x, const cl_ring_element& y)</code><dd><a name="index-g_t_0040code_007bplus-_0028_0029_007d-250"></a><dt><code>cl_ring_element R->minus (const cl_ring_element& x, const cl_ring_element& y)</code><dd><a name="index-g_t_0040code_007bminus-_0028_0029_007d-251"></a><dt><code>cl_ring_element R->uminus (const cl_ring_element& x)</code><dd><a name="index-g_t_0040code_007buminus-_0028_0029_007d-252"></a><dt><code>cl_ring_element R->one ()</code><dd><a name="index-g_t_0040code_007bone-_0028_0029_007d-253"></a><dt><code>cl_ring_element R->canonhom (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcanonhom-_0028_0029_007d-254"></a><dt><code>cl_ring_element R->mul (const cl_ring_element& x, const cl_ring_element& y)</code><dd><a name="index-g_t_0040code_007bmul-_0028_0029_007d-255"></a><dt><code>cl_ring_element R->square (const cl_ring_element& x)</code><dd><a name="index-g_t_0040code_007bsquare-_0028_0029_007d-256"></a><dt><code>cl_ring_element R->expt_pos (const cl_ring_element& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-257"></a></dl>
<p>The following rings are built-in.
<dl>
<dt><code>cl_null_ring cl_0_ring</code><dd>The null ring, containing only zero.
<br><dt><code>cl_complex_ring cl_C_ring</code><dd>The ring of complex numbers. This corresponds to the type <code>cl_N</code>.
<br><dt><code>cl_real_ring cl_R_ring</code><dd>The ring of real numbers. This corresponds to the type <code>cl_R</code>.
<br><dt><code>cl_rational_ring cl_RA_ring</code><dd>The ring of rational numbers. This corresponds to the type <code>cl_RA</code>.
<br><dt><code>cl_integer_ring cl_I_ring</code><dd>The ring of integers. This corresponds to the type <code>cl_I</code>.
</dl>
<p>Type tests can be performed for any of <code>cl_C_ring</code>, <code>cl_R_ring</code>,
<code>cl_RA_ring</code>, <code>cl_I_ring</code>:
<dl>
<dt><code>bool instanceof (const cl_number& x, const cl_number_ring& R)</code><dd><a name="index-g_t_0040code_007binstanceof-_0028_0029_007d-258"></a>Tests whether the given number is an element of the number ring R.
</dl>
<div class="node">
<a name="Modular-integers"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Symbolic-data-types">Symbolic data types</a>,
Previous: <a rel="previous" accesskey="p" href="#Rings">Rings</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">7 Modular integers</h2>
<p><a name="index-modular-integer-259"></a>
<ul class="menu">
<li><a accesskey="1" href="#Modular-integer-rings">Modular integer rings</a>
<li><a accesskey="2" href="#Functions-on-modular-integers">Functions on modular integers</a>
</ul>
<div class="node">
<a name="Modular-integer-rings"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Functions-on-modular-integers">Functions on modular integers</a>,
Up: <a rel="up" accesskey="u" href="#Modular-integers">Modular integers</a>
</div>
<h3 class="section">7.1 Modular integer rings</h3>
<p><a name="index-ring-260"></a>
CLN implements modular integers, i.e. integers modulo a fixed integer N.
The modulus is explicitly part of every modular integer. CLN doesn't
allow you to (accidentally) mix elements of different modular rings,
e.g. <code>(3 mod 4) + (2 mod 5)</code> will result in a runtime error.
(Ideally one would imagine a generic data type <code>cl_MI(N)</code>, but C++
doesn't have generic types. So one has to live with runtime checks.)
<p>The class of modular integer rings is
<pre class="example"> Ring
cl_ring
<cln/ring.h>
|
|
Modular integer ring
cl_modint_ring
<cln/modinteger.h>
</pre>
<p><a name="index-g_t_0040code_007bcl_005fmodint_005fring_007d-261"></a>
and the class of all modular integers (elements of modular integer rings) is
<pre class="example"> Modular integer
cl_MI
<cln/modinteger.h>
</pre>
<p>Modular integer rings are constructed using the function
<dl>
<dt><code>cl_modint_ring find_modint_ring (const cl_I& N)</code><dd><a name="index-g_t_0040code_007bfind_005fmodint_005fring-_0028_0029_007d-262"></a>This function returns the modular ring ‘<samp><span class="samp">Z/NZ</span></samp>’. It takes care
of finding out about special cases of <code>N</code>, like powers of two
and odd numbers for which Montgomery multiplication will be a win,
<a name="index-Montgomery-multiplication-263"></a>and precomputes any necessary auxiliary data for computing modulo <code>N</code>.
There is a cache table of rings, indexed by <code>N</code> (or, more precisely,
by <code>abs(N)</code>). This ensures that the precomputation costs are reduced
to a minimum.
</dl>
<p>Modular integer rings can be compared for equality:
<dl>
<dt><code>bool operator== (const cl_modint_ring&, const cl_modint_ring&)</code><dd><a name="index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-264"></a><dt><code>bool operator!= (const cl_modint_ring&, const cl_modint_ring&)</code><dd><a name="index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-265"></a>These compare two modular integer rings for equality. Two different calls
to <code>find_modint_ring</code> with the same argument necessarily return the
same ring because it is memoized in the cache table.
</dl>
<div class="node">
<a name="Functions-on-modular-integers"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Modular-integer-rings">Modular integer rings</a>,
Up: <a rel="up" accesskey="u" href="#Modular-integers">Modular integers</a>
</div>
<h3 class="section">7.2 Functions on modular integers</h3>
<p>Given a modular integer ring <code>R</code>, the following members can be used.
<dl>
<dt><code>cl_I R->modulus</code><dd><a name="index-g_t_0040code_007bmodulus_007d-266"></a>This is the ring's modulus, normalized to be nonnegative: <code>abs(N)</code>.
<br><dt><code>cl_MI R->zero()</code><dd><a name="index-g_t_0040code_007bzero-_0028_0029_007d-267"></a>This returns <code>0 mod N</code>.
<br><dt><code>cl_MI R->one()</code><dd><a name="index-g_t_0040code_007bone-_0028_0029_007d-268"></a>This returns <code>1 mod N</code>.
<br><dt><code>cl_MI R->canonhom (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcanonhom-_0028_0029_007d-269"></a>This returns <code>x mod N</code>.
<br><dt><code>cl_I R->retract (const cl_MI& x)</code><dd><a name="index-g_t_0040code_007bretract-_0028_0029_007d-270"></a>This is a partial inverse function to <code>R->canonhom</code>. It returns the
standard representative (<code>>=0</code>, <code><N</code>) of <code>x</code>.
<br><dt><code>cl_MI R->random(random_state& randomstate)</code><dt><code>cl_MI R->random()</code><dd><a name="index-g_t_0040code_007brandom-_0028_0029_007d-271"></a>This returns a random integer modulo <code>N</code>.
</dl>
<p>The following operations are defined on modular integers.
<dl>
<dt><code>cl_modint_ring x.ring ()</code><dd><a name="index-g_t_0040code_007bring-_0028_0029_007d-272"></a>Returns the ring to which the modular integer <code>x</code> belongs.
<br><dt><code>cl_MI operator+ (const cl_MI&, const cl_MI&)</code><dd><a name="index-g_t_0040code_007boperator-_002b-_0028_0029_007d-273"></a>Returns the sum of two modular integers. One of the arguments may also
be a plain integer.
<br><dt><code>cl_MI operator- (const cl_MI&, const cl_MI&)</code><dd><a name="index-g_t_0040code_007boperator-_002d-_0028_0029_007d-274"></a>Returns the difference of two modular integers. One of the arguments may also
be a plain integer.
<br><dt><code>cl_MI operator- (const cl_MI&)</code><dd>Returns the negative of a modular integer.
<br><dt><code>cl_MI operator* (const cl_MI&, const cl_MI&)</code><dd><a name="index-g_t_0040code_007boperator-_002a-_0028_0029_007d-275"></a>Returns the product of two modular integers. One of the arguments may also
be a plain integer.
<br><dt><code>cl_MI square (const cl_MI&)</code><dd><a name="index-g_t_0040code_007bsquare-_0028_0029_007d-276"></a>Returns the square of a modular integer.
<br><dt><code>cl_MI recip (const cl_MI& x)</code><dd><a name="index-g_t_0040code_007brecip-_0028_0029_007d-277"></a>Returns the reciprocal <code>x^-1</code> of a modular integer <code>x</code>. <code>x</code>
must be coprime to the modulus, otherwise an error message is issued.
<br><dt><code>cl_MI div (const cl_MI& x, const cl_MI& y)</code><dd><a name="index-g_t_0040code_007bdiv-_0028_0029_007d-278"></a>Returns the quotient <code>x*y^-1</code> of two modular integers <code>x</code>, <code>y</code>.
<code>y</code> must be coprime to the modulus, otherwise an error message is issued.
<br><dt><code>cl_MI expt_pos (const cl_MI& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-279"></a><code>y</code> must be > 0. Returns <code>x^y</code>.
<br><dt><code>cl_MI expt (const cl_MI& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexpt-_0028_0029_007d-280"></a>Returns <code>x^y</code>. If <code>y</code> is negative, <code>x</code> must be coprime to the
modulus, else an error message is issued.
<br><dt><code>cl_MI operator<< (const cl_MI& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-281"></a>Returns <code>x*2^y</code>.
<br><dt><code>cl_MI operator>> (const cl_MI& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007boperator-_003e_003e-_0028_0029_007d-282"></a>Returns <code>x*2^-y</code>. When <code>y</code> is positive, the modulus must be odd,
or an error message is issued.
<br><dt><code>bool operator== (const cl_MI&, const cl_MI&)</code><dd><a name="index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-283"></a><dt><code>bool operator!= (const cl_MI&, const cl_MI&)</code><dd><a name="index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-284"></a>Compares two modular integers, belonging to the same modular integer ring,
for equality.
<br><dt><code>bool zerop (const cl_MI& x)</code><dd><a name="index-g_t_0040code_007bzerop-_0028_0029_007d-285"></a>Returns true if <code>x</code> is <code>0 mod N</code>.
</dl>
<p>The following output functions are defined (see also the chapter on
input/output).
<dl>
<dt><code>void fprint (std::ostream& stream, const cl_MI& x)</code><dd><a name="index-g_t_0040code_007bfprint-_0028_0029_007d-286"></a><dt><code>std::ostream& operator<< (std::ostream& stream, const cl_MI& x)</code><dd><a name="index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-287"></a>Prints the modular integer <code>x</code> on the <code>stream</code>. The output may depend
on the global printer settings in the variable <code>default_print_flags</code>.
</dl>
<div class="node">
<a name="Symbolic-data-types"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Univariate-polynomials">Univariate polynomials</a>,
Previous: <a rel="previous" accesskey="p" href="#Modular-integers">Modular integers</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">8 Symbolic data types</h2>
<p><a name="index-symbolic-type-288"></a>
CLN implements two symbolic (non-numeric) data types: strings and symbols.
<ul class="menu">
<li><a accesskey="1" href="#Strings">Strings</a>
<li><a accesskey="2" href="#Symbols">Symbols</a>
</ul>
<div class="node">
<a name="Strings"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Symbols">Symbols</a>,
Up: <a rel="up" accesskey="u" href="#Symbolic-data-types">Symbolic data types</a>
</div>
<h3 class="section">8.1 Strings</h3>
<p><a name="index-string-289"></a><a name="index-g_t_0040code_007bcl_005fstring_007d-290"></a>
The class
<pre class="example"> String
cl_string
<cln/string.h>
</pre>
<p>implements immutable strings.
<p>Strings are constructed through the following constructors:
<dl>
<dt><code>cl_string (const char * s)</code><dd>Returns an immutable copy of the (zero-terminated) C string <code>s</code>.
<br><dt><code>cl_string (const char * ptr, unsigned long len)</code><dd>Returns an immutable copy of the <code>len</code> characters at
<code>ptr[0]</code>, <small class="dots">...</small>, <code>ptr[len-1]</code>. NUL characters are allowed.
</dl>
<p>The following functions are available on strings:
<dl>
<dt><code>operator =</code><dd>Assignment from <code>cl_string</code> and <code>const char *</code>.
<br><dt><code>s.size()</code><dd><a name="index-g_t_0040code_007bsize_0028_0029_007d-291"></a><dt><code>strlen(s)</code><dd><a name="index-g_t_0040code_007bstrlen-_0028_0029_007d-292"></a>Returns the length of the string <code>s</code>.
<br><dt><code>s[i]</code><dd><a name="index-g_t_0040code_007boperator-_005b_005d-_0028_0029_007d-293"></a>Returns the <code>i</code>th character of the string <code>s</code>.
<code>i</code> must be in the range <code>0 <= i < s.size()</code>.
<br><dt><code>bool equal (const cl_string& s1, const cl_string& s2)</code><dd><a name="index-g_t_0040code_007bequal-_0028_0029_007d-294"></a>Compares two strings for equality. One of the arguments may also be a
plain <code>const char *</code>.
</dl>
<div class="node">
<a name="Symbols"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Strings">Strings</a>,
Up: <a rel="up" accesskey="u" href="#Symbolic-data-types">Symbolic data types</a>
</div>
<h3 class="section">8.2 Symbols</h3>
<p><a name="index-symbol-295"></a><a name="index-g_t_0040code_007bcl_005fsymbol_007d-296"></a>
Symbols are uniquified strings: all symbols with the same name are shared.
This means that comparison of two symbols is fast (effectively just a pointer
comparison), whereas comparison of two strings must in the worst case walk
both strings until their end.
Symbols are used, for example, as tags for properties, as names of variables
in polynomial rings, etc.
<p>Symbols are constructed through the following constructor:
<dl>
<dt><code>cl_symbol (const cl_string& s)</code><dd>Looks up or creates a new symbol with a given name.
</dl>
<p>The following operations are available on symbols:
<dl>
<dt><code>cl_string (const cl_symbol& sym)</code><dd>Conversion to <code>cl_string</code>: Returns the string which names the symbol
<code>sym</code>.
<br><dt><code>bool equal (const cl_symbol& sym1, const cl_symbol& sym2)</code><dd><a name="index-g_t_0040code_007bequal-_0028_0029_007d-297"></a>Compares two symbols for equality. This is very fast.
</dl>
<div class="node">
<a name="Univariate-polynomials"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Internals">Internals</a>,
Previous: <a rel="previous" accesskey="p" href="#Symbolic-data-types">Symbolic data types</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">9 Univariate polynomials</h2>
<p><a name="index-polynomial-298"></a><a name="index-univariate-polynomial-299"></a>
<ul class="menu">
<li><a accesskey="1" href="#Univariate-polynomial-rings">Univariate polynomial rings</a>
<li><a accesskey="2" href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a>
<li><a accesskey="3" href="#Special-polynomials">Special polynomials</a>
</ul>
<div class="node">
<a name="Univariate-polynomial-rings"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a>,
Up: <a rel="up" accesskey="u" href="#Univariate-polynomials">Univariate polynomials</a>
</div>
<h3 class="section">9.1 Univariate polynomial rings</h3>
<p>CLN implements univariate polynomials (polynomials in one variable) over an
arbitrary ring. The indeterminate variable may be either unnamed (and will be
printed according to <code>default_print_flags.univpoly_varname</code>, which
defaults to ‘<samp><span class="samp">x</span></samp>’) or carry a given name. The base ring and the
indeterminate are explicitly part of every polynomial. CLN doesn't allow you to
(accidentally) mix elements of different polynomial rings, e.g.
<code>(a^2+1) * (b^3-1)</code> will result in a runtime error. (Ideally this should
return a multivariate polynomial, but they are not yet implemented in CLN.)
<p>The classes of univariate polynomial rings are
<pre class="example"> Ring
cl_ring
<cln/ring.h>
|
|
Univariate polynomial ring
cl_univpoly_ring
<cln/univpoly.h>
|
+----------------+-------------------+
| | |
Complex polynomial ring | Modular integer polynomial ring
cl_univpoly_complex_ring | cl_univpoly_modint_ring
<cln/univpoly_complex.h> | <cln/univpoly_modint.h>
|
+----------------+
| |
Real polynomial ring |
cl_univpoly_real_ring |
<cln/univpoly_real.h> |
|
+----------------+
| |
Rational polynomial ring |
cl_univpoly_rational_ring |
<cln/univpoly_rational.h> |
|
+----------------+
|
Integer polynomial ring
cl_univpoly_integer_ring
<cln/univpoly_integer.h>
</pre>
<p>and the corresponding classes of univariate polynomials are
<pre class="example"> Univariate polynomial
cl_UP
<cln/univpoly.h>
|
+----------------+-------------------+
| | |
Complex polynomial | Modular integer polynomial
cl_UP_N | cl_UP_MI
<cln/univpoly_complex.h> | <cln/univpoly_modint.h>
|
+----------------+
| |
Real polynomial |
cl_UP_R |
<cln/univpoly_real.h> |
|
+----------------+
| |
Rational polynomial |
cl_UP_RA |
<cln/univpoly_rational.h> |
|
+----------------+
|
Integer polynomial
cl_UP_I
<cln/univpoly_integer.h>
</pre>
<p>Univariate polynomial rings are constructed using the functions
<dl>
<dt><code>cl_univpoly_ring find_univpoly_ring (const cl_ring& R)</code><dt><code>cl_univpoly_ring find_univpoly_ring (const cl_ring& R, const cl_symbol& varname)</code><dd>This function returns the polynomial ring ‘<samp><span class="samp">R[X]</span></samp>’, unnamed or named.
<code>R</code> may be an arbitrary ring. This function takes care of finding out
about special cases of <code>R</code>, such as the rings of complex numbers,
real numbers, rational numbers, integers, or modular integer rings.
There is a cache table of rings, indexed by <code>R</code> and <code>varname</code>.
This ensures that two calls of this function with the same arguments will
return the same polynomial ring.
<dt><code>cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R)</code><dd><a name="index-g_t_0040code_007bfind_005funivpoly_005fring-_0028_0029_007d-300"></a><dt><code>cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname)</code><dt><code>cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R)</code><dt><code>cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname)</code><dt><code>cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R)</code><dt><code>cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname)</code><dt><code>cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R)</code><dt><code>cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname)</code><dt><code>cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R)</code><dt><code>cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname)</code><dd>These functions are equivalent to the general <code>find_univpoly_ring</code>,
only the return type is more specific, according to the base ring's type.
</dl>
<div class="node">
<a name="Functions-on-univariate-polynomials"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Special-polynomials">Special polynomials</a>,
Previous: <a rel="previous" accesskey="p" href="#Univariate-polynomial-rings">Univariate polynomial rings</a>,
Up: <a rel="up" accesskey="u" href="#Univariate-polynomials">Univariate polynomials</a>
</div>
<h3 class="section">9.2 Functions on univariate polynomials</h3>
<p>Given a univariate polynomial ring <code>R</code>, the following members can be used.
<dl>
<dt><code>cl_ring R->basering()</code><dd><a name="index-g_t_0040code_007bbasering-_0028_0029_007d-301"></a>This returns the base ring, as passed to ‘<samp><span class="samp">find_univpoly_ring</span></samp>’.
<br><dt><code>cl_UP R->zero()</code><dd><a name="index-g_t_0040code_007bzero-_0028_0029_007d-302"></a>This returns <code>0 in R</code>, a polynomial of degree -1.
<br><dt><code>cl_UP R->one()</code><dd><a name="index-g_t_0040code_007bone-_0028_0029_007d-303"></a>This returns <code>1 in R</code>, a polynomial of degree == 0.
<br><dt><code>cl_UP R->canonhom (const cl_I& x)</code><dd><a name="index-g_t_0040code_007bcanonhom-_0028_0029_007d-304"></a>This returns <code>x in R</code>, a polynomial of degree <= 0.
<br><dt><code>cl_UP R->monomial (const cl_ring_element& x, uintL e)</code><dd><a name="index-g_t_0040code_007bmonomial-_0028_0029_007d-305"></a>This returns a sparse polynomial: <code>x * X^e</code>, where <code>X</code> is the
indeterminate.
<br><dt><code>cl_UP R->create (sintL degree)</code><dd><a name="index-g_t_0040code_007bcreate-_0028_0029_007d-306"></a>Creates a new polynomial with a given degree. The zero polynomial has degree
<code>-1</code>. After creating the polynomial, you should put in the coefficients,
using the <code>set_coeff</code> member function, and then call the <code>finalize</code>
member function.
</dl>
<p>The following are the only destructive operations on univariate polynomials.
<dl>
<dt><code>void set_coeff (cl_UP& x, uintL index, const cl_ring_element& y)</code><dd><a name="index-g_t_0040code_007bset_005fcoeff-_0028_0029_007d-307"></a>This changes the coefficient of <code>X^index</code> in <code>x</code> to be <code>y</code>.
After changing a polynomial and before applying any "normal" operation on it,
you should call its <code>finalize</code> member function.
<br><dt><code>void finalize (cl_UP& x)</code><dd><a name="index-g_t_0040code_007bfinalize-_0028_0029_007d-308"></a>This function marks the endpoint of destructive modifications of a polynomial.
It normalizes the internal representation so that subsequent computations have
less overhead. Doing normal computations on unnormalized polynomials may
produce wrong results or crash the program.
</dl>
<p>The following operations are defined on univariate polynomials.
<dl>
<dt><code>cl_univpoly_ring x.ring ()</code><dd><a name="index-g_t_0040code_007bring-_0028_0029_007d-309"></a>Returns the ring to which the univariate polynomial <code>x</code> belongs.
<br><dt><code>cl_UP operator+ (const cl_UP&, const cl_UP&)</code><dd><a name="index-g_t_0040code_007boperator-_002b-_0028_0029_007d-310"></a>Returns the sum of two univariate polynomials.
<br><dt><code>cl_UP operator- (const cl_UP&, const cl_UP&)</code><dd><a name="index-g_t_0040code_007boperator-_002d-_0028_0029_007d-311"></a>Returns the difference of two univariate polynomials.
<br><dt><code>cl_UP operator- (const cl_UP&)</code><dd>Returns the negative of a univariate polynomial.
<br><dt><code>cl_UP operator* (const cl_UP&, const cl_UP&)</code><dd><a name="index-g_t_0040code_007boperator-_002a-_0028_0029_007d-312"></a>Returns the product of two univariate polynomials. One of the arguments may
also be a plain integer or an element of the base ring.
<br><dt><code>cl_UP square (const cl_UP&)</code><dd><a name="index-g_t_0040code_007bsquare-_0028_0029_007d-313"></a>Returns the square of a univariate polynomial.
<br><dt><code>cl_UP expt_pos (const cl_UP& x, const cl_I& y)</code><dd><a name="index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-314"></a><code>y</code> must be > 0. Returns <code>x^y</code>.
<br><dt><code>bool operator== (const cl_UP&, const cl_UP&)</code><dd><a name="index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-315"></a><dt><code>bool operator!= (const cl_UP&, const cl_UP&)</code><dd><a name="index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-316"></a>Compares two univariate polynomials, belonging to the same univariate
polynomial ring, for equality.
<br><dt><code>bool zerop (const cl_UP& x)</code><dd><a name="index-g_t_0040code_007bzerop-_0028_0029_007d-317"></a>Returns true if <code>x</code> is <code>0 in R</code>.
<br><dt><code>sintL degree (const cl_UP& x)</code><dd><a name="index-g_t_0040code_007bdegree-_0028_0029_007d-318"></a>Returns the degree of the polynomial. The zero polynomial has degree <code>-1</code>.
<br><dt><code>sintL ldegree (const cl_UP& x)</code><dd><a name="index-g_t_0040code_007bdegree-_0028_0029_007d-319"></a>Returns the low degree of the polynomial. This is the degree of the first
non-vanishing polynomial coefficient. The zero polynomial has ldegree <code>-1</code>.
<br><dt><code>cl_ring_element coeff (const cl_UP& x, uintL index)</code><dd><a name="index-g_t_0040code_007bcoeff-_0028_0029_007d-320"></a>Returns the coefficient of <code>X^index</code> in the polynomial <code>x</code>.
<br><dt><code>cl_ring_element x (const cl_ring_element& y)</code><dd><a name="index-g_t_0040code_007boperator-_0028_0029-_0028_0029_007d-321"></a>Evaluation: If <code>x</code> is a polynomial and <code>y</code> belongs to the base ring,
then ‘<samp><span class="samp">x(y)</span></samp>’ returns the value of the substitution of <code>y</code> into
<code>x</code>.
<br><dt><code>cl_UP deriv (const cl_UP& x)</code><dd><a name="index-g_t_0040code_007bderiv-_0028_0029_007d-322"></a>Returns the derivative of the polynomial <code>x</code> with respect to the
indeterminate <code>X</code>.
</dl>
<p>The following output functions are defined (see also the chapter on
input/output).
<dl>
<dt><code>void fprint (std::ostream& stream, const cl_UP& x)</code><dd><a name="index-g_t_0040code_007bfprint-_0028_0029_007d-323"></a><dt><code>std::ostream& operator<< (std::ostream& stream, const cl_UP& x)</code><dd><a name="index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-324"></a>Prints the univariate polynomial <code>x</code> on the <code>stream</code>. The output may
depend on the global printer settings in the variable
<code>default_print_flags</code>.
</dl>
<div class="node">
<a name="Special-polynomials"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a>,
Up: <a rel="up" accesskey="u" href="#Univariate-polynomials">Univariate polynomials</a>
</div>
<h3 class="section">9.3 Special polynomials</h3>
<p>The following functions return special polynomials.
<dl>
<dt><code>cl_UP_I tschebychev (sintL n)</code><dd><a name="index-g_t_0040code_007btschebychev-_0028_0029_007d-325"></a><a name="index-Chebyshev-polynomial-326"></a>Returns the n-th Chebyshev polynomial (n >= 0).
<br><dt><code>cl_UP_I hermite (sintL n)</code><dd><a name="index-g_t_0040code_007bhermite-_0028_0029_007d-327"></a><a name="index-Hermite-polynomial-328"></a>Returns the n-th Hermite polynomial (n >= 0).
<br><dt><code>cl_UP_RA legendre (sintL n)</code><dd><a name="index-g_t_0040code_007blegendre-_0028_0029_007d-329"></a><a name="index-Legende-polynomial-330"></a>Returns the n-th Legendre polynomial (n >= 0).
<br><dt><code>cl_UP_I laguerre (sintL n)</code><dd><a name="index-g_t_0040code_007blaguerre-_0028_0029_007d-331"></a><a name="index-Laguerre-polynomial-332"></a>Returns the n-th Laguerre polynomial (n >= 0).
</dl>
<p>Information how to derive the differential equation satisfied by each
of these polynomials from their definition can be found in the
<code>doc/polynomial/</code> directory.
<div class="node">
<a name="Internals"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Using-the-library">Using the library</a>,
Previous: <a rel="previous" accesskey="p" href="#Univariate-polynomials">Univariate polynomials</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">10 Internals</h2>
<ul class="menu">
<li><a accesskey="1" href="#Why-C_002b_002b-_003f">Why C++ ?</a>
<li><a accesskey="2" href="#Memory-efficiency">Memory efficiency</a>
<li><a accesskey="3" href="#Speed-efficiency">Speed efficiency</a>
<li><a accesskey="4" href="#Garbage-collection">Garbage collection</a>
</ul>
<div class="node">
<a name="Why-C++-%3f"></a>
<a name="Why-C_002b_002b-_003f"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Memory-efficiency">Memory efficiency</a>,
Up: <a rel="up" accesskey="u" href="#Internals">Internals</a>
</div>
<h3 class="section">10.1 Why C++ ?</h3>
<p><a name="index-advocacy-333"></a>
Using C++ as an implementation language provides
<ul>
<li>Efficiency: It compiles to machine code.
<li><a name="index-portability-334"></a>Portability: It runs on all platforms supporting a C++ compiler. Because
of the availability of GNU C++, this includes all currently used 32-bit and
64-bit platforms, independently of the quality of the vendor's C++ compiler.
<li>Type safety: The C++ compilers knows about the number types and complains if,
for example, you try to assign a float to an integer variable. However,
a drawback is that C++ doesn't know about generic types, hence a restriction
like that <code>operator+ (const cl_MI&, const cl_MI&)</code> requires that both
arguments belong to the same modular ring cannot be expressed as a compile-time
information.
<li>Algebraic syntax: The elementary operations <code>+</code>, <code>-</code>, <code>*</code>,
<code>=</code>, <code>==</code>, ... can be used in infix notation, which is more
convenient than Lisp notation ‘<samp><span class="samp">(+ x y)</span></samp>’ or C notation ‘<samp><span class="samp">add(x,y,&z)</span></samp>’.
</ul>
<p>With these language features, there is no need for two separate languages,
one for the implementation of the library and one in which the library's users
can program. This means that a prototype implementation of an algorithm
can be integrated into the library immediately after it has been tested and
debugged. No need to rewrite it in a low-level language after having prototyped
in a high-level language.
<div class="node">
<a name="Memory-efficiency"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Speed-efficiency">Speed efficiency</a>,
Previous: <a rel="previous" accesskey="p" href="#Why-C_002b_002b-_003f">Why C++ ?</a>,
Up: <a rel="up" accesskey="u" href="#Internals">Internals</a>
</div>
<h3 class="section">10.2 Memory efficiency</h3>
<p>In order to save memory allocations, CLN implements:
<ul>
<li>Object sharing: An operation like <code>x+0</code> returns <code>x</code> without copying
it.
<li><a name="index-garbage-collection-335"></a><a name="index-reference-counting-336"></a>Garbage collection: A reference counting mechanism makes sure that any
number object's storage is freed immediately when the last reference to the
object is gone.
<li><a name="index-immediate-numbers-337"></a>Small integers are represented as immediate values instead of pointers
to heap allocated storage. This means that integers <code>>= -2^29</code>,
<code>< 2^29</code> don't consume heap memory, unless they were explicitly allocated
on the heap.
</ul>
<div class="node">
<a name="Speed-efficiency"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Garbage-collection">Garbage collection</a>,
Previous: <a rel="previous" accesskey="p" href="#Memory-efficiency">Memory efficiency</a>,
Up: <a rel="up" accesskey="u" href="#Internals">Internals</a>
</div>
<h3 class="section">10.3 Speed efficiency</h3>
<p>Speed efficiency is obtained by the combination of the following tricks
and algorithms:
<ul>
<li>Small integers, being represented as immediate values, don't require
memory access, just a couple of instructions for each elementary operation.
<li>The kernel of CLN has been written in assembly language for some CPUs
(<code>i386</code>, <code>m68k</code>, <code>sparc</code>, <code>mips</code>, <code>arm</code>).
<li>On all CPUs, CLN may be configured to use the superefficient low-level
routines from GNU GMP version 3.
<li>For large numbers, CLN uses, instead of the standard <code>O(N^2)</code>
algorithm, the Karatsuba multiplication, which is an
algorithm.
<li>For very large numbers (more than 12000 decimal digits), CLN uses
multiplication, which is an asymptotically optimal multiplication
algorithm.
<li>These fast multiplication algorithms also give improvements in the speed
of division and radix conversion.
</ul>
<div class="node">
<a name="Garbage-collection"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Speed-efficiency">Speed efficiency</a>,
Up: <a rel="up" accesskey="u" href="#Internals">Internals</a>
</div>
<h3 class="section">10.4 Garbage collection</h3>
<p><a name="index-garbage-collection-338"></a>
All the number classes are reference count classes: They only contain a pointer
to an object in the heap. Upon construction, assignment and destruction of
number objects, only the objects' reference count are manipulated.
<p>Memory occupied by number objects are automatically reclaimed as soon as
their reference count drops to zero.
<p>For number rings, another strategy is implemented: There is a cache of,
for example, the modular integer rings. A modular integer ring is destroyed
only if its reference count dropped to zero and the cache is about to be
resized. The effect of this strategy is that recently used rings remain
cached, whereas undue memory consumption through cached rings is avoided.
<div class="node">
<a name="Using-the-library"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Customizing">Customizing</a>,
Previous: <a rel="previous" accesskey="p" href="#Internals">Internals</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">11 Using the library</h2>
<p>For the following discussion, we will assume that you have installed
the CLN source in <code>$CLN_DIR</code> and built it in <code>$CLN_TARGETDIR</code>.
For example, for me it's <code>CLN_DIR="$HOME/cln"</code> and
<code>CLN_TARGETDIR="$HOME/cln/linuxelf"</code>. You might define these as
environment variables, or directly substitute the appropriate values.
<ul class="menu">
<li><a accesskey="1" href="#Compiler-options">Compiler options</a>
<li><a accesskey="2" href="#Include-files">Include files</a>
<li><a accesskey="3" href="#An-Example">An Example</a>
<li><a accesskey="4" href="#Debugging-support">Debugging support</a>
<li><a accesskey="5" href="#Reporting-Problems">Reporting Problems</a>
</ul>
<div class="node">
<a name="Compiler-options"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Include-files">Include files</a>,
Up: <a rel="up" accesskey="u" href="#Using-the-library">Using the library</a>
</div>
<h3 class="section">11.1 Compiler options</h3>
<p><a name="index-compiler-options-339"></a>
Until you have installed CLN in a public place, the following options are
needed:
<p>When you compile CLN application code, add the flags
<pre class="example"> -I$CLN_DIR/include -I$CLN_TARGETDIR/include
</pre>
<p>to the C++ compiler's command line (<code>make</code> variable CFLAGS or CXXFLAGS).
When you link CLN application code to form an executable, add the flags
<pre class="example"> $CLN_TARGETDIR/src/libcln.a
</pre>
<p>to the C/C++ compiler's command line (<code>make</code> variable LIBS).
<p>If you did a <code>make install</code>, the include files are installed in a
public directory (normally <code>/usr/local/include</code>), hence you don't
need special flags for compiling. The library has been installed to a
public directory as well (normally <code>/usr/local/lib</code>), hence when
linking a CLN application it is sufficient to give the flag <code>-lcln</code>.
<p><a name="index-g_t_0040code_007bpkg_002dconfig_007d-340"></a>To make the creation of software packages that use CLN easier, the
<code>pkg-config</code> utility can be used. CLN provides all the necessary
metainformation in a file called <code>cln.pc</code> (installed in
<code>/usr/local/lib/pkgconfig</code> by default). A program using CLN can
be compiled and linked using <a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>
<pre class="example"> g++ `pkg-config --libs cln` `pkg-config --cflags cln` prog.cc -o prog
</pre>
<p>Software using GNU autoconf can check for CLN with the
<code>PKG_CHECK_MODULES</code> macro supplied with <code>pkg-config</code>.
<pre class="example"> PKG_CHECK_MODULES([CLN], [cln >= <var>MIN-VERSION</var>])
</pre>
<p>This will check for CLN version at least <var>MIN-VERSION</var>. If the
required version was found, the variables <var>CLN_CFLAGS</var> and
<var>CLN_LIBS</var> are set. Otherwise the configure script aborts. If this
is not the desired behaviour, use the following code instead
<a rel="footnote" href="#fn-2" name="fnd-2"><sup>2</sup></a>
<pre class="example"> PKG_CHECK_MODULES([CLN], [cln >= <var>MIN-VERSION</var>], [],
[AC_MSG_WARNING([No suitable version of CLN can be found])])
</pre>
<div class="node">
<a name="Include-files"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#An-Example">An Example</a>,
Previous: <a rel="previous" accesskey="p" href="#Compiler-options">Compiler options</a>,
Up: <a rel="up" accesskey="u" href="#Using-the-library">Using the library</a>
</div>
<h3 class="section">11.2 Include files</h3>
<p><a name="index-include-files-341"></a><a name="index-header-files-342"></a>
Here is a summary of the include files and their contents.
<dl>
<dt><code><cln/object.h></code><dd>General definitions, reference counting, garbage collection.
<br><dt><code><cln/number.h></code><dd>The class cl_number.
<br><dt><code><cln/complex.h></code><dd>Functions for class cl_N, the complex numbers.
<br><dt><code><cln/real.h></code><dd>Functions for class cl_R, the real numbers.
<br><dt><code><cln/float.h></code><dd>Functions for class cl_F, the floats.
<br><dt><code><cln/sfloat.h></code><dd>Functions for class cl_SF, the short-floats.
<br><dt><code><cln/ffloat.h></code><dd>Functions for class cl_FF, the single-floats.
<br><dt><code><cln/dfloat.h></code><dd>Functions for class cl_DF, the double-floats.
<br><dt><code><cln/lfloat.h></code><dd>Functions for class cl_LF, the long-floats.
<br><dt><code><cln/rational.h></code><dd>Functions for class cl_RA, the rational numbers.
<br><dt><code><cln/integer.h></code><dd>Functions for class cl_I, the integers.
<br><dt><code><cln/io.h></code><dd>Input/Output.
<br><dt><code><cln/complex_io.h></code><dd>Input/Output for class cl_N, the complex numbers.
<br><dt><code><cln/real_io.h></code><dd>Input/Output for class cl_R, the real numbers.
<br><dt><code><cln/float_io.h></code><dd>Input/Output for class cl_F, the floats.
<br><dt><code><cln/sfloat_io.h></code><dd>Input/Output for class cl_SF, the short-floats.
<br><dt><code><cln/ffloat_io.h></code><dd>Input/Output for class cl_FF, the single-floats.
<br><dt><code><cln/dfloat_io.h></code><dd>Input/Output for class cl_DF, the double-floats.
<br><dt><code><cln/lfloat_io.h></code><dd>Input/Output for class cl_LF, the long-floats.
<br><dt><code><cln/rational_io.h></code><dd>Input/Output for class cl_RA, the rational numbers.
<br><dt><code><cln/integer_io.h></code><dd>Input/Output for class cl_I, the integers.
<br><dt><code><cln/input.h></code><dd>Flags for customizing input operations.
<br><dt><code><cln/output.h></code><dd>Flags for customizing output operations.
<br><dt><code><cln/malloc.h></code><dd><code>malloc_hook</code>, <code>free_hook</code>.
<br><dt><code><cln/exception.h></code><dd>Exception base class.
<br><dt><code><cln/condition.h></code><dd>Conditions.
<br><dt><code><cln/string.h></code><dd>Strings.
<br><dt><code><cln/symbol.h></code><dd>Symbols.
<br><dt><code><cln/proplist.h></code><dd>Property lists.
<br><dt><code><cln/ring.h></code><dd>General rings.
<br><dt><code><cln/null_ring.h></code><dd>The null ring.
<br><dt><code><cln/complex_ring.h></code><dd>The ring of complex numbers.
<br><dt><code><cln/real_ring.h></code><dd>The ring of real numbers.
<br><dt><code><cln/rational_ring.h></code><dd>The ring of rational numbers.
<br><dt><code><cln/integer_ring.h></code><dd>The ring of integers.
<br><dt><code><cln/numtheory.h></code><dd>Number threory functions.
<br><dt><code><cln/modinteger.h></code><dd>Modular integers.
<br><dt><code><cln/V.h></code><dd>Vectors.
<br><dt><code><cln/GV.h></code><dd>General vectors.
<br><dt><code><cln/GV_number.h></code><dd>General vectors over cl_number.
<br><dt><code><cln/GV_complex.h></code><dd>General vectors over cl_N.
<br><dt><code><cln/GV_real.h></code><dd>General vectors over cl_R.
<br><dt><code><cln/GV_rational.h></code><dd>General vectors over cl_RA.
<br><dt><code><cln/GV_integer.h></code><dd>General vectors over cl_I.
<br><dt><code><cln/GV_modinteger.h></code><dd>General vectors of modular integers.
<br><dt><code><cln/SV.h></code><dd>Simple vectors.
<br><dt><code><cln/SV_number.h></code><dd>Simple vectors over cl_number.
<br><dt><code><cln/SV_complex.h></code><dd>Simple vectors over cl_N.
<br><dt><code><cln/SV_real.h></code><dd>Simple vectors over cl_R.
<br><dt><code><cln/SV_rational.h></code><dd>Simple vectors over cl_RA.
<br><dt><code><cln/SV_integer.h></code><dd>Simple vectors over cl_I.
<br><dt><code><cln/SV_ringelt.h></code><dd>Simple vectors of general ring elements.
<br><dt><code><cln/univpoly.h></code><dd>Univariate polynomials.
<br><dt><code><cln/univpoly_integer.h></code><dd>Univariate polynomials over the integers.
<br><dt><code><cln/univpoly_rational.h></code><dd>Univariate polynomials over the rational numbers.
<br><dt><code><cln/univpoly_real.h></code><dd>Univariate polynomials over the real numbers.
<br><dt><code><cln/univpoly_complex.h></code><dd>Univariate polynomials over the complex numbers.
<br><dt><code><cln/univpoly_modint.h></code><dd>Univariate polynomials over modular integer rings.
<br><dt><code><cln/timing.h></code><dd>Timing facilities.
<br><dt><code><cln/cln.h></code><dd>Includes all of the above.
</dl>
<div class="node">
<a name="An-Example"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Debugging-support">Debugging support</a>,
Previous: <a rel="previous" accesskey="p" href="#Include-files">Include files</a>,
Up: <a rel="up" accesskey="u" href="#Using-the-library">Using the library</a>
</div>
<h3 class="section">11.3 An Example</h3>
<p>A function which computes the nth Fibonacci number can be written as follows.
<a name="index-Fibonacci-number-343"></a>
<pre class="example"> #include <cln/integer.h>
#include <cln/real.h>
using namespace cln;
// Returns F_n, computed as the nearest integer to
// ((1+sqrt(5))/2)^n/sqrt(5). Assume n>=0.
const cl_I fibonacci (int n)
{
// Need a precision of ((1+sqrt(5))/2)^-n.
float_format_t prec = float_format((int)(0.208987641*n+5));
cl_R sqrt5 = sqrt(cl_float(5,prec));
cl_R phi = (1+sqrt5)/2;
return round1( expt(phi,n)/sqrt5 );
}
</pre>
<p>Let's explain what is going on in detail.
<p>The include file <code><cln/integer.h></code> is necessary because the type
<code>cl_I</code> is used in the function, and the include file <code><cln/real.h></code>
is needed for the type <code>cl_R</code> and the floating point number functions.
The order of the include files does not matter. In order not to write
out <code>cln::</code><var>foo</var> in this simple example we can safely import
the whole namespace <code>cln</code>.
<p>Then comes the function declaration. The argument is an <code>int</code>, the
result an integer. The return type is defined as ‘<samp><span class="samp">const cl_I</span></samp>’, not
simply ‘<samp><span class="samp">cl_I</span></samp>’, because that allows the compiler to detect typos like
‘<samp><span class="samp">fibonacci(n) = 100</span></samp>’. It would be possible to declare the return
type as <code>const cl_R</code> (real number) or even <code>const cl_N</code> (complex
number). We use the most specialized possible return type because functions
which call ‘<samp><span class="samp">fibonacci</span></samp>’ will be able to profit from the compiler's type
analysis: Adding two integers is slightly more efficient than adding the
same objects declared as complex numbers, because it needs less type
dispatch. Also, when linking to CLN as a non-shared library, this minimizes
the size of the resulting executable program.
<p>The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
integer. In order to get a correct result, the absolute error should be less
than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
To this end, the first line computes a floating point precision for sqrt(5)
and phi.
<p>Then sqrt(5) is computed by first converting the integer 5 to a floating point
number and than taking the square root. The converse, first taking the square
root of 5, and then converting to the desired precision, would not work in
CLN: The square root would be computed to a default precision (normally
single-float precision), and the following conversion could not help about
the lacking accuracy. This is because CLN is not a symbolic computer algebra
system and does not represent sqrt(5) in a non-numeric way.
<p>The type <code>cl_R</code> for sqrt5 and, in the following line, phi is the only
possible choice. You cannot write <code>cl_F</code> because the C++ compiler can
only infer that <code>cl_float(5,prec)</code> is a real number. You cannot write
<code>cl_N</code> because a ‘<samp><span class="samp">round1</span></samp>’ does not exist for general complex
numbers.
<p>When the function returns, all the local variables in the function are
automatically reclaimed (garbage collected). Only the result survives and
gets passed to the caller.
<p>The file <code>fibonacci.cc</code> in the subdirectory <code>examples</code>
contains this implementation together with an even faster algorithm.
<div class="node">
<a name="Debugging-support"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Reporting-Problems">Reporting Problems</a>,
Previous: <a rel="previous" accesskey="p" href="#An-Example">An Example</a>,
Up: <a rel="up" accesskey="u" href="#Using-the-library">Using the library</a>
</div>
<h3 class="section">11.4 Debugging support</h3>
<p><a name="index-debugging-344"></a>
When debugging a CLN application with GNU <code>gdb</code>, two facilities are
available from the library:
<ul>
<li>The library does type checks, range checks, consistency checks at
many places. When one of these fails, an exception of a type derived from
<code>runtime_exception</code> is thrown. When an exception is cought, the stack
has already been unwound, so it is may not be possible to tell at which
point the exception was thrown. For debugging, it is best to set up a
catchpoint at the event of throwning a C++ exception:
<pre class="example"> (gdb) catch throw
</pre>
<p>When this catchpoint is hit, look at the stack's backtrace:
<pre class="example"> (gdb) where
</pre>
<p>When control over the type of exception is required, it may be possible
to set a breakpoint at the <code>g++</code> runtime library function
<code>__raise_exception</code>. Refer to the documentation of GNU <code>gdb</code>
for details.
<li>The debugger's normal <code>print</code> command doesn't know about
CLN's types and therefore prints mostly useless hexadecimal addresses.
CLN offers a function <code>cl_print</code>, callable from the debugger,
for printing number objects. In order to get this function, you have
to define the macro ‘<samp><span class="samp">CL_DEBUG</span></samp>’ and then include all the header files
for which you want <code>cl_print</code> debugging support. For example:
<a name="index-g_t_0040code_007bCL_005fDEBUG_007d-345"></a>
<pre class="example"> #define CL_DEBUG
#include <cln/string.h>
</pre>
<p>Now, if you have in your program a variable <code>cl_string s</code>, and
inspect it under <code>gdb</code>, the output may look like this:
<pre class="example"> (gdb) print s
$7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
word = 134568800}}, }
(gdb) call cl_print(s)
(cl_string) ""
$8 = 134568800
</pre>
<p>Note that the output of <code>cl_print</code> goes to the program's error output,
not to gdb's standard output.
<p>Note, however, that the above facility does not work with all CLN types,
only with number objects and similar. Therefore CLN offers a member function
<code>debug_print()</code> on all CLN types. The same macro ‘<samp><span class="samp">CL_DEBUG</span></samp>’
is needed for this member function to be implemented. Under <code>gdb</code>,
you call it like this:
<a name="index-g_t_0040code_007bdebug_005fprint-_0028_0029_007d-346"></a>
<pre class="example"> (gdb) print s
$7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
word = 134568800}}, }
(gdb) call s.debug_print()
(cl_string) ""
(gdb) define cprint
>call ($1).debug_print()
>end
(gdb) cprint s
(cl_string) ""
</pre>
<p>Unfortunately, this feature does not seem to work under all circumstances.
</ul>
<div class="node">
<a name="Reporting-Problems"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Debugging-support">Debugging support</a>,
Up: <a rel="up" accesskey="u" href="#Using-the-library">Using the library</a>
</div>
<h3 class="section">11.5 Reporting Problems</h3>
<p><a name="index-bugreports-347"></a><a name="index-mailing-list-348"></a>
If you encounter any problem, please don't hesitate to send a detailed
bugreport to the <code>cln-list@ginac.de</code> mailing list. Please think
about your bug: consider including a short description of your operating
system and compilation environment with corresponding version numbers. A
description of your configuration options may also be helpful. Also, a
short test program together with the output you get and the output you
expect will help us to reproduce it quickly. Finally, do not forget to
report the version number of CLN.
<div class="node">
<a name="Customizing"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Index">Index</a>,
Previous: <a rel="previous" accesskey="p" href="#Using-the-library">Using the library</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="chapter">12 Customizing</h2>
<p><a name="index-customizing-349"></a>
<ul class="menu">
<li><a accesskey="1" href="#Error-handling">Error handling</a>
<li><a accesskey="2" href="#Floating_002dpoint-underflow">Floating-point underflow</a>
<li><a accesskey="3" href="#Customizing-I_002fO">Customizing I/O</a>
<li><a accesskey="4" href="#Customizing-the-memory-allocator">Customizing the memory allocator</a>
</ul>
<div class="node">
<a name="Error-handling"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Floating_002dpoint-underflow">Floating-point underflow</a>,
Up: <a rel="up" accesskey="u" href="#Customizing">Customizing</a>
</div>
<h3 class="section">12.1 Error handling</h3>
<p><a name="index-exception-350"></a><a name="index-error-handling-351"></a>
<a name="index-g_t_0040code_007bruntime_005fexception_007d-352"></a>CLN signals abnormal situations by throwning exceptions. All exceptions
thrown by the library are of type <code>runtime_exception</code> or of a
derived type. Class <code>cln::runtime_exception</code> in turn is derived
from the C++ standard library class <code>std::runtime_error</code> and
inherits the <code>.what()</code> member function that can be used to query
details about the cause of error.
<p>The most important classes thrown by the library are
<p><a name="index-g_t_0040code_007bfloating_005fpoint_005fexception_007d-353"></a><a name="index-g_t_0040code_007bread_005fnumber_005fexception_007d-354"></a>
<pre class="example"> Exception base class
runtime_exception
<cln/exception.h>
|
+----------------+----------------+
| |
Malformed number input Floating-point error
read_number_exception floating_poing_exception
<cln/number_io.h> <cln/float.h>
</pre>
<p>CLN has many more exception classes that allow for more fine-grained
control but I refrain from documenting them all here. They are all
declared in the public header files and they are all subclasses of the
above exceptions, so catching those you are always on the safe side.
<div class="node">
<a name="Floating-point-underflow"></a>
<a name="Floating_002dpoint-underflow"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Customizing-I_002fO">Customizing I/O</a>,
Previous: <a rel="previous" accesskey="p" href="#Error-handling">Error handling</a>,
Up: <a rel="up" accesskey="u" href="#Customizing">Customizing</a>
</div>
<h3 class="section">12.2 Floating-point underflow</h3>
<p><a name="index-underflow-355"></a>
<a name="index-g_t_0040code_007bfloating_005fpoint_005funderflow_005fexception_007d-356"></a>Floating point underflow denotes the situation when a floating-point
number is to be created which is so close to <code>0</code> that its exponent
is too low to be represented internally. By default, this causes the
exception <code>floating_point_underflow_exception</code> (subclass of
<code>floating_point_exception</code>) to be thrown. If you set the global
variable
<pre class="example"> bool cl_inhibit_floating_point_underflow
</pre>
<p>to <code>true</code>, the exception will be inhibited, and a floating-point
zero will be generated instead. The default value of
<code>cl_inhibit_floating_point_underflow</code> is <code>false</code>.
<div class="node">
<a name="Customizing-I%2fO"></a>
<a name="Customizing-I_002fO"></a>
<p><hr>
Next: <a rel="next" accesskey="n" href="#Customizing-the-memory-allocator">Customizing the memory allocator</a>,
Previous: <a rel="previous" accesskey="p" href="#Floating_002dpoint-underflow">Floating-point underflow</a>,
Up: <a rel="up" accesskey="u" href="#Customizing">Customizing</a>
</div>
<h3 class="section">12.3 Customizing I/O</h3>
<p>The output of the function <code>fprint</code> may be customized by changing the
value of the global variable <code>default_print_flags</code>.
<a name="index-g_t_0040code_007bdefault_005fprint_005fflags_007d-357"></a>
<div class="node">
<a name="Customizing-the-memory-allocator"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Customizing-I_002fO">Customizing I/O</a>,
Up: <a rel="up" accesskey="u" href="#Customizing">Customizing</a>
</div>
<h3 class="section">12.4 Customizing the memory allocator</h3>
<p>Every memory allocation of CLN is done through the function pointer
<code>malloc_hook</code>. Freeing of this memory is done through the function
pointer <code>free_hook</code>. The default versions of these functions,
provided in the library, call <code>malloc</code> and <code>free</code> and check
the <code>malloc</code> result against <code>NULL</code>.
If you want to provide another memory allocator, you need to define
the variables <code>malloc_hook</code> and <code>free_hook</code> yourself,
like this:
<pre class="example"> #include <cln/malloc.h>
namespace cln {
void* (*malloc_hook) (size_t size) = ...;
void (*free_hook) (void* ptr) = ...;
}
</pre>
<p><a name="index-g_t_0040code_007bmalloc_005fhook-_0028_0029_007d-358"></a><a name="index-g_t_0040code_007bfree_005fhook-_0028_0029_007d-359"></a>The <code>cl_malloc_hook</code> function must not return a <code>NULL</code> pointer.
<p>It is not possible to change the memory allocator at runtime, because
it is already called at program startup by the constructors of some
global variables.
<!-- Indices -->
<div class="node">
<a name="Index"></a>
<p><hr>
Previous: <a rel="previous" accesskey="p" href="#Customizing">Customizing</a>,
Up: <a rel="up" accesskey="u" href="#Top">Top</a>
</div>
<h2 class="unnumbered">Index</h2>
<ul class="index-my" compact>
<li><a href="#index-g_t_0040code_007babs-_0028_0029_007d-50"><code>abs ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-abstract-class-9">abstract class</a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bacos-_0028_0029_007d-117"><code>acos ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bacosh-_0028_0029_007d-129"><code>acosh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-advocacy-333">advocacy</a>: <a href="#Why-C_002b_002b-_003f">Why C++ ?</a></li>
<li><a href="#index-Archimedes_0027-constant-121">Archimedes' constant</a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bAs_0028_0029_0028_0029_007d-37"><code>As()()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bash-_0028_0029_007d-181"><code>ash ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007basin_007d-115"><code>asin</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007basin-_0028_0029_007d-116"><code>asin ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007basinh-_0028_0029_007d-128"><code>asinh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007batan_007d-118"><code>atan</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007batan-_0028_0029_007d-119"><code>atan ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007batanh-_0028_0029_007d-130"><code>atanh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007bbasering-_0028_0029_007d-301"><code>basering ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-binary-splitting-2">binary splitting</a>: <a href="#Introduction">Introduction</a></li>
<li><a href="#index-g_t_0040code_007bbinomial-_0028_0029_007d-195"><code>binomial ()</code></a>: <a href="#Combinatorial-functions">Combinatorial functions</a></li>
<li><a href="#index-g_t_0040code_007bboole-_0028_0029_007d-152"><code>boole ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005f1_007d-155"><code>boole_1</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005f2_007d-156"><code>boole_2</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fand_007d-159"><code>boole_and</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fandc1_007d-164"><code>boole_andc1</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fandc2_007d-165"><code>boole_andc2</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fc1_007d-157"><code>boole_c1</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fc2_007d-158"><code>boole_c2</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fclr_007d-153"><code>boole_clr</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005feqv_007d-161"><code>boole_eqv</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fnand_007d-162"><code>boole_nand</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fnor_007d-163"><code>boole_nor</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005forc1_007d-166"><code>boole_orc1</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005forc2_007d-167"><code>boole_orc2</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fset_007d-154"><code>boole_set</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bboole_005fxor_007d-160"><code>boole_xor</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-bugreports-347">bugreports</a>: <a href="#Reporting-Problems">Reporting Problems</a></li>
<li><a href="#index-g_t_0040code_007bcanonhom-_0028_0029_007d-304"><code>canonhom ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bcanonhom-_0028_0029_007d-269"><code>canonhom ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bcanonhom-_0028_0029_007d-254"><code>canonhom ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-cast-36">cast</a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-Catalan_0027s-constant-133">Catalan's constant</a>: <a href="#Euler-gamma">Euler gamma</a></li>
<li><a href="#index-g_t_0040code_007bcatalanconst-_0028_0029_007d-134"><code>catalanconst ()</code></a>: <a href="#Euler-gamma">Euler gamma</a></li>
<li><a href="#index-g_t_0040code_007bceiling1-_0028_0029_007d-74"><code>ceiling1 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bceiling2-_0028_0029_007d-78"><code>ceiling2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-Chebyshev-polynomial-326">Chebyshev polynomial</a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-g_t_0040code_007bcis-_0028_0029_007d-114"><code>cis ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fbyte_007d-171"><code>cl_byte</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bCL_005fDEBUG_007d-345"><code>CL_DEBUG</code></a>: <a href="#Debugging-support">Debugging support</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fDF_007d-24"><code>cl_DF</code></a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fDF_005ffdiv_005ft_007d-88"><code>cl_DF_fdiv_t</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fF_007d-26"><code>cl_F</code></a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fF_007d-17"><code>cl_F</code></a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fF_005ffdiv_005ft_007d-85"><code>cl_F_fdiv_t</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fFF_007d-23"><code>cl_FF</code></a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fFF_005ffdiv_005ft_007d-87"><code>cl_FF_fdiv_t</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005ffloat-_0028_0029_007d-215"><code>cl_float ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fI_005fto_005fint-_0028_0029_007d-30"><code>cl_I_to_int ()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fI_005fto_005flong-_0028_0029_007d-32"><code>cl_I_to_long ()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fI_005fto_005fuint-_0028_0029_007d-31"><code>cl_I_to_uint ()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fI_005fto_005fulong-_0028_0029_007d-33"><code>cl_I_to_ulong ()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fidecoded_005ffloat_007d-208"><code>cl_idecoded_float</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fLF_007d-25"><code>cl_LF</code></a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fLF_005ffdiv_005ft_007d-89"><code>cl_LF_fdiv_t</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fmodint_005fring_007d-261"><code>cl_modint_ring</code></a>: <a href="#Modular-integer-rings">Modular integer rings</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fN_007d-10"><code>cl_N</code></a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fnumber_007d-8"><code>cl_number</code></a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fR_007d-13"><code>cl_R</code></a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fR_005ffdiv_005ft_007d-94"><code>cl_R_fdiv_t</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fRA_007d-14"><code>cl_RA</code></a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fSF_007d-22"><code>cl_SF</code></a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fSF_005ffdiv_005ft_007d-86"><code>cl_SF_fdiv_t</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fstring_007d-290"><code>cl_string</code></a>: <a href="#Strings">Strings</a></li>
<li><a href="#index-g_t_0040code_007bcl_005fsymbol_007d-296"><code>cl_symbol</code></a>: <a href="#Symbols">Symbols</a></li>
<li><a href="#index-g_t_0040code_007bcoeff-_0028_0029_007d-320"><code>coeff ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bcompare-_0028_0029_007d-63"><code>compare ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-comparison-58">comparison</a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-compiler-options-339">compiler options</a>: <a href="#Compiler-options">Compiler options</a></li>
<li><a href="#index-g_t_0040code_007bcomplex-_0028_0029_007d-54"><code>complex ()</code></a>: <a href="#Elementary-complex-functions">Elementary complex functions</a></li>
<li><a href="#index-complex-number-27">complex number</a>: <a href="#Complex-numbers">Complex numbers</a></li>
<li><a href="#index-complex-number-12">complex number</a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007bconjugate-_0028_0029_007d-57"><code>conjugate ()</code></a>: <a href="#Elementary-complex-functions">Elementary complex functions</a></li>
<li><a href="#index-conversion-211">conversion</a>: <a href="#Conversion-functions">Conversion functions</a></li>
<li><a href="#index-conversion-28">conversion</a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bcos-_0028_0029_007d-110"><code>cos ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bcos_005fsin-_0028_0029_007d-112"><code>cos_sin ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bcos_005fsin_005ft_007d-111"><code>cos_sin_t</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bcosh-_0028_0029_007d-124"><code>cosh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007bcosh_005fsinh-_0028_0029_007d-126"><code>cosh_sinh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007bcosh_005fsinh_005ft_007d-125"><code>cosh_sinh_t</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007bcreate-_0028_0029_007d-306"><code>create ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-customizing-349">customizing</a>: <a href="#Customizing">Customizing</a></li>
<li><a href="#index-g_t_0040code_007bdebug_005fprint-_0028_0029_007d-346"><code>debug_print ()</code></a>: <a href="#Debugging-support">Debugging support</a></li>
<li><a href="#index-debugging-344">debugging</a>: <a href="#Debugging-support">Debugging support</a></li>
<li><a href="#index-g_t_0040code_007bdecode_005ffloat-_0028_0029_007d-207"><code>decode_float ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdecoded_005fdfloat_007d-205"><code>decoded_dfloat</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdecoded_005fffloat_007d-204"><code>decoded_ffloat</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdecoded_005ffloat_007d-202"><code>decoded_float</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdecoded_005flfloat_007d-206"><code>decoded_lfloat</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdecoded_005fsfloat_007d-203"><code>decoded_sfloat</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdefault_005ffloat_005fformat_007d-214"><code>default_float_format</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bdefault_005fprint_005fflags_007d-357"><code>default_print_flags</code></a>: <a href="#Customizing-I_002fO">Customizing I/O</a></li>
<li><a href="#index-g_t_0040code_007bdefault_005frandom_005fstate_007d-225"><code>default_random_state</code></a>: <a href="#Random-number-generators">Random number generators</a></li>
<li><a href="#index-g_t_0040code_007bdegree-_0028_0029_007d-318"><code>degree ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bdenominator-_0028_0029_007d-53"><code>denominator ()</code></a>: <a href="#Elementary-rational-functions">Elementary rational functions</a></li>
<li><a href="#index-g_t_0040code_007bdeposit_005ffield-_0028_0029_007d-176"><code>deposit_field ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bderiv-_0028_0029_007d-322"><code>deriv ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bdiv-_0028_0029_007d-278"><code>div ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bdouble_005fapprox-_0028_0029_007d-35"><code>double_approx ()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bdoublefactorial-_0028_0029_007d-194"><code>doublefactorial ()</code></a>: <a href="#Combinatorial-functions">Combinatorial functions</a></li>
<li><a href="#index-g_t_0040code_007bdpb-_0028_0029_007d-174"><code>dpb ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bequal-_0028_0029_007d-297"><code>equal ()</code></a>: <a href="#Symbols">Symbols</a></li>
<li><a href="#index-g_t_0040code_007bequal-_0028_0029_007d-294"><code>equal ()</code></a>: <a href="#Strings">Strings</a></li>
<li><a href="#index-g_t_0040code_007bequal-_0028_0029_007d-247"><code>equal ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bequal_005fhashcode-_0028_0029_007d-61"><code>equal_hashcode ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-error-handling-351">error handling</a>: <a href="#Error-handling">Error handling</a></li>
<li><a href="#index-Euler_0027s-constant-131">Euler's constant</a>: <a href="#Euler-gamma">Euler gamma</a></li>
<li><a href="#index-g_t_0040code_007beulerconst-_0028_0029_007d-132"><code>eulerconst ()</code></a>: <a href="#Euler-gamma">Euler gamma</a></li>
<li><a href="#index-g_t_0040code_007bevenp-_0028_0029_007d-178"><code>evenp ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-exact-number-18">exact number</a>: <a href="#Exact-numbers">Exact numbers</a></li>
<li><a href="#index-exception-350">exception</a>: <a href="#Error-handling">Error handling</a></li>
<li><a href="#index-g_t_0040code_007bexp-_0028_0029_007d-103"><code>exp ()</code></a>: <a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a></li>
<li><a href="#index-g_t_0040code_007bexp1-_0028_0029_007d-108"><code>exp1 ()</code></a>: <a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a></li>
<li><a href="#index-g_t_0040code_007bexpt-_0028_0029_007d-280"><code>expt ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bexpt-_0028_0029_007d-107"><code>expt ()</code></a>: <a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a></li>
<li><a href="#index-g_t_0040code_007bexpt-_0028_0029_007d-49"><code>expt ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-314"><code>expt_pos ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-279"><code>expt_pos ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-257"><code>expt_pos ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bexpt_005fpos-_0028_0029_007d-48"><code>expt_pos ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007bexquo-_0028_0029_007d-47"><code>exquo ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007bfactorial-_0028_0029_007d-193"><code>factorial ()</code></a>: <a href="#Combinatorial-functions">Combinatorial functions</a></li>
<li><a href="#index-g_t_0040code_007bfceiling-_0028_0029_007d-82"><code>fceiling ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bfceiling2-_0028_0029_007d-91"><code>fceiling2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bffloor-_0028_0029_007d-81"><code>ffloor ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bffloor2-_0028_0029_007d-90"><code>ffloor2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-Fibonacci-number-343">Fibonacci number</a>: <a href="#An-Example">An Example</a></li>
<li><a href="#index-g_t_0040code_007bfinalize-_0028_0029_007d-308"><code>finalize ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bfind_005fmodint_005fring-_0028_0029_007d-262"><code>find_modint_ring ()</code></a>: <a href="#Modular-integer-rings">Modular integer rings</a></li>
<li><a href="#index-g_t_0040code_007bfind_005funivpoly_005fring-_0028_0029_007d-300"><code>find_univpoly_ring ()</code></a>: <a href="#Univariate-polynomial-rings">Univariate polynomial rings</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fapprox-_0028_0029_007d-34"><code>float_approx ()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fdigits-_0028_0029_007d-200"><code>float_digits ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fepsilon-_0028_0029_007d-220"><code>float_epsilon ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fexponent-_0028_0029_007d-197"><code>float_exponent ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fformat-_0028_0029_007d-213"><code>float_format ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fformat_005ft_007d-212"><code>float_format_t</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fnegative_005fepsilon-_0028_0029_007d-221"><code>float_negative_epsilon ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fprecision-_0028_0029_007d-201"><code>float_precision ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fradix-_0028_0029_007d-198"><code>float_radix ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloat_005fsign-_0028_0029_007d-199"><code>float_sign ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-floating_002dpoint-number-20">floating-point number</a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bfloating_005fpoint_005fexception_007d-353"><code>floating_point_exception</code></a>: <a href="#Error-handling">Error handling</a></li>
<li><a href="#index-g_t_0040code_007bfloating_005fpoint_005funderflow_005fexception_007d-356"><code>floating_point_underflow_exception</code></a>: <a href="#Floating_002dpoint-underflow">Floating-point underflow</a></li>
<li><a href="#index-g_t_0040code_007bfloor1-_0028_0029_007d-73"><code>floor1 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bfloor2-_0028_0029_007d-77"><code>floor2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bfprint-_0028_0029_007d-323"><code>fprint ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bfprint-_0028_0029_007d-286"><code>fprint ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bfprint-_0028_0029_007d-246"><code>fprint ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bfree_005fhook-_0028_0029_007d-359"><code>free_hook ()</code></a>: <a href="#Customizing-the-memory-allocator">Customizing the memory allocator</a></li>
<li><a href="#index-g_t_0040code_007bfround-_0028_0029_007d-84"><code>fround ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bfround2-_0028_0029_007d-93"><code>fround2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bftruncate-_0028_0029_007d-83"><code>ftruncate ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bftruncate2-_0028_0029_007d-92"><code>ftruncate2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-garbage-collection-338">garbage collection</a>: <a href="#Garbage-collection">Garbage collection</a></li>
<li><a href="#index-garbage-collection-335">garbage collection</a>: <a href="#Memory-efficiency">Memory efficiency</a></li>
<li><a href="#index-g_t_0040code_007bgcd-_0028_0029_007d-185"><code>gcd ()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-GMP-6">GMP</a>: <a href="#Using-the-GNU-MP-Library">Using the GNU MP Library</a></li>
<li><a href="#index-GMP-1">GMP</a>: <a href="#Introduction">Introduction</a></li>
<li><a href="#index-header-files-342">header files</a>: <a href="#Include-files">Include files</a></li>
<li><a href="#index-g_t_0040code_007bhermite-_0028_0029_007d-327"><code>hermite ()</code></a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-Hermite-polynomial-328">Hermite polynomial</a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-g_t_0040code_007bimagpart-_0028_0029_007d-56"><code>imagpart ()</code></a>: <a href="#Elementary-complex-functions">Elementary complex functions</a></li>
<li><a href="#index-immediate-numbers-337">immediate numbers</a>: <a href="#Memory-efficiency">Memory efficiency</a></li>
<li><a href="#index-immediate-numbers-19">immediate numbers</a>: <a href="#Exact-numbers">Exact numbers</a></li>
<li><a href="#index-include-files-341">include files</a>: <a href="#Include-files">Include files</a></li>
<li><a href="#index-Input_002fOutput-242">Input/Output</a>: <a href="#Input_002fOutput">Input/Output</a></li>
<li><a href="#index-installation-7">installation</a>: <a href="#Installing-the-library">Installing the library</a></li>
<li><a href="#index-g_t_0040code_007binstanceof-_0028_0029_007d-258"><code>instanceof ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-integer-16">integer</a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007binteger_005fdecode_005ffloat-_0028_0029_007d-209"><code>integer_decode_float ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007binteger_005flength-_0028_0029_007d-182"><code>integer_length ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bisprobprime_0028_0029_007d-191"><code>isprobprime()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-g_t_0040code_007bisqrt-_0028_0029_007d-99"><code>isqrt ()</code></a>: <a href="#Roots">Roots</a></li>
<li><a href="#index-g_t_0040code_007bjacobi_0028_0029_007d-189"><code>jacobi()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-g_t_0040code_007blaguerre-_0028_0029_007d-331"><code>laguerre ()</code></a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-Laguerre-polynomial-332">Laguerre polynomial</a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-g_t_0040code_007blcm-_0028_0029_007d-187"><code>lcm ()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-g_t_0040code_007bldb-_0028_0029_007d-172"><code>ldb ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bldb_005ftest-_0028_0029_007d-173"><code>ldb_test ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bleast_005fnegative_005ffloat-_0028_0029_007d-219"><code>least_negative_float ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bleast_005fpositive_005ffloat-_0028_0029_007d-218"><code>least_positive_float ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-Legende-polynomial-330">Legende polynomial</a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-g_t_0040code_007blegendre-_0028_0029_007d-329"><code>legendre ()</code></a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-g_t_0040code_007bln-_0028_0029_007d-104"><code>ln ()</code></a>: <a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a></li>
<li><a href="#index-g_t_0040code_007blog-_0028_0029_007d-105"><code>log ()</code></a>: <a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a></li>
<li><a href="#index-g_t_0040code_007blogand-_0028_0029_007d-139"><code>logand ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogandc1-_0028_0029_007d-148"><code>logandc1 ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogandc2-_0028_0029_007d-149"><code>logandc2 ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogbitp-_0028_0029_007d-169"><code>logbitp ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogcount-_0028_0029_007d-170"><code>logcount ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogeqv-_0028_0029_007d-145"><code>logeqv ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogior-_0028_0029_007d-141"><code>logior ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blognand-_0028_0029_007d-146"><code>lognand ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blognor-_0028_0029_007d-147"><code>lognor ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blognot-_0028_0029_007d-137"><code>lognot ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogorc1-_0028_0029_007d-150"><code>logorc1 ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogorc2-_0028_0029_007d-151"><code>logorc2 ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogp-_0028_0029_007d-188"><code>logp ()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-g_t_0040code_007blogtest-_0028_0029_007d-168"><code>logtest ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007blogxor-_0028_0029_007d-143"><code>logxor ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-mailing-list-348">mailing list</a>: <a href="#Reporting-Problems">Reporting Problems</a></li>
<li><a href="#index-g_t_0040code_007bmake_007d-4"><code>make</code></a>: <a href="#Make-utility">Make utility</a></li>
<li><a href="#index-g_t_0040code_007bmalloc_005fhook-_0028_0029_007d-358"><code>malloc_hook ()</code></a>: <a href="#Customizing-the-memory-allocator">Customizing the memory allocator</a></li>
<li><a href="#index-g_t_0040code_007bmask_005ffield-_0028_0029_007d-175"><code>mask_field ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bmax-_0028_0029_007d-70"><code>max ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007bmin-_0028_0029_007d-71"><code>min ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007bminus-_0028_0029_007d-251"><code>minus ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bminus1-_0028_0029_007d-42"><code>minus1 ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007bminusp-_0028_0029_007d-68"><code>minusp ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007bmod-_0028_0029_007d-95"><code>mod ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-modifying-operators-230">modifying operators</a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-modular-integer-259">modular integer</a>: <a href="#Modular-integers">Modular integers</a></li>
<li><a href="#index-g_t_0040code_007bmodulus_007d-266"><code>modulus</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bmonomial-_0028_0029_007d-305"><code>monomial ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-Montgomery-multiplication-263">Montgomery multiplication</a>: <a href="#Modular-integer-rings">Modular integer rings</a></li>
<li><a href="#index-g_t_0040code_007bmost_005fnegative_005ffloat-_0028_0029_007d-217"><code>most_negative_float ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bmost_005fpositive_005ffloat-_0028_0029_007d-216"><code>most_positive_float ()</code></a>: <a href="#Conversion-to-floating_002dpoint-numbers">Conversion to floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bmul-_0028_0029_007d-255"><code>mul ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-namespace-3">namespace</a>: <a href="#Introduction">Introduction</a></li>
<li><a href="#index-g_t_0040code_007bnextprobprime_0028_0029_007d-192"><code>nextprobprime()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-g_t_0040code_007bnumerator-_0028_0029_007d-52"><code>numerator ()</code></a>: <a href="#Elementary-rational-functions">Elementary rational functions</a></li>
<li><a href="#index-g_t_0040code_007boddp-_0028_0029_007d-177"><code>oddp ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bone-_0028_0029_007d-303"><code>one ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bone-_0028_0029_007d-268"><code>one ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bone-_0028_0029_007d-253"><code>one ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-316"><code>operator != ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-284"><code>operator != ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-265"><code>operator != ()</code></a>: <a href="#Modular-integer-rings">Modular integer rings</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0021_003d-_0028_0029_007d-60"><code>operator != ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0026-_0028_0029_007d-140"><code>operator & ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0026_003d-_0028_0029_007d-235"><code>operator &= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_0028_0029-_0028_0029_007d-321"><code>operator () ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002a-_0028_0029_007d-312"><code>operator * ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002a-_0028_0029_007d-275"><code>operator * ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002a-_0028_0029_007d-43"><code>operator * ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002a_003d-_0028_0029_007d-233"><code>operator *= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002b-_0028_0029_007d-310"><code>operator + ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002b-_0028_0029_007d-273"><code>operator + ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002b-_0028_0029_007d-39"><code>operator + ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002b_002b-_0028_0029_007d-240"><code>operator ++ ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002b_003d-_0028_0029_007d-231"><code>operator += ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002d-_0028_0029_007d-311"><code>operator - ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002d-_0028_0029_007d-274"><code>operator - ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002d-_0028_0029_007d-40"><code>operator - ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002d_002d-_0028_0029_007d-241"><code>operator -- ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002d_003d-_0028_0029_007d-232"><code>operator -= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002f-_0028_0029_007d-45"><code>operator / ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_002f_003d-_0028_0029_007d-234"><code>operator /= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003c-_0028_0029_007d-65"><code>operator < ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-324"><code>operator << ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-281"><code>operator << ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003c_003c-_0028_0029_007d-179"><code>operator << ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003c_003c_003d-_0028_0029_007d-238"><code>operator <<= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003c_003d-_0028_0029_007d-64"><code>operator <= ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-315"><code>operator == ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-283"><code>operator == ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-264"><code>operator == ()</code></a>: <a href="#Modular-integer-rings">Modular integer rings</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003d_003d-_0028_0029_007d-59"><code>operator == ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003e-_0028_0029_007d-67"><code>operator > ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003e_003d-_0028_0029_007d-66"><code>operator >= ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003e_003e-_0028_0029_007d-282"><code>operator >> ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003e_003e-_0028_0029_007d-180"><code>operator >> ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_003e_003e_003d-_0028_0029_007d-239"><code>operator >>= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_005b_005d-_0028_0029_007d-293"><code>operator [] ()</code></a>: <a href="#Strings">Strings</a></li>
<li><a href="#index-g_t_0040code_007boperator-_005e-_0028_0029_007d-144"><code>operator ^ ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_005e_003d-_0028_0029_007d-237"><code>operator ^= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_007c-_0028_0029_007d-142"><code>operator | ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007boperator-_007c_003d-_0028_0029_007d-236"><code>operator |= ()</code></a>: <a href="#Modifying-operators">Modifying operators</a></li>
<li><a href="#index-g_t_0040code_007boperator-_007e-_0028_0029_007d-138"><code>operator ~ ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bord2-_0028_0029_007d-183"><code>ord2 ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-g_t_0040code_007bphase-_0028_0029_007d-106"><code>phase ()</code></a>: <a href="#Exponential-and-logarithmic-functions">Exponential and logarithmic functions</a></li>
<li><a href="#index-pi-120">pi</a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bpi-_0028_0029_007d-122"><code>pi ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bpkg_002dconfig_007d-340"><code>pkg-config</code></a>: <a href="#Compiler-options">Compiler options</a></li>
<li><a href="#index-g_t_0040code_007bplus-_0028_0029_007d-250"><code>plus ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bplus1-_0028_0029_007d-41"><code>plus1 ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007bplusp-_0028_0029_007d-69"><code>plusp ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-polynomial-298">polynomial</a>: <a href="#Univariate-polynomials">Univariate polynomials</a></li>
<li><a href="#index-portability-334">portability</a>: <a href="#Why-C_002b_002b-_003f">Why C++ ?</a></li>
<li><a href="#index-g_t_0040code_007bpower2p-_0028_0029_007d-184"><code>power2p ()</code></a>: <a href="#Logical-functions">Logical functions</a></li>
<li><a href="#index-prime-190">prime</a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-printing-244">printing</a>: <a href="#Internal-and-printed-representation">Internal and printed representation</a></li>
<li><a href="#index-g_t_0040code_007brandom-_0028_0029_007d-271"><code>random ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007brandom32-_0028_0029_007d-226"><code>random32 ()</code></a>: <a href="#Random-number-generators">Random number generators</a></li>
<li><a href="#index-g_t_0040code_007brandom_005fF-_0028_0029_007d-228"><code>random_F ()</code></a>: <a href="#Random-number-generators">Random number generators</a></li>
<li><a href="#index-g_t_0040code_007brandom_005fI-_0028_0029_007d-227"><code>random_I ()</code></a>: <a href="#Random-number-generators">Random number generators</a></li>
<li><a href="#index-g_t_0040code_007brandom_005fR-_0028_0029_007d-229"><code>random_R ()</code></a>: <a href="#Random-number-generators">Random number generators</a></li>
<li><a href="#index-g_t_0040code_007brandom_005fstate_007d-224"><code>random_state</code></a>: <a href="#Random-number-generators">Random number generators</a></li>
<li><a href="#index-g_t_0040code_007brational-_0028_0029_007d-222"><code>rational ()</code></a>: <a href="#Conversion-to-rational-numbers">Conversion to rational numbers</a></li>
<li><a href="#index-rational-number-15">rational number</a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007brationalize-_0028_0029_007d-223"><code>rationalize ()</code></a>: <a href="#Conversion-to-rational-numbers">Conversion to rational numbers</a></li>
<li><a href="#index-g_t_0040code_007bread_005fnumber_005fexception_007d-354"><code>read_number_exception</code></a>: <a href="#Error-handling">Error handling</a></li>
<li><a href="#index-reading-245">reading</a>: <a href="#Internal-and-printed-representation">Internal and printed representation</a></li>
<li><a href="#index-real-number-11">real number</a>: <a href="#Ordinary-number-types">Ordinary number types</a></li>
<li><a href="#index-g_t_0040code_007brealpart-_0028_0029_007d-55"><code>realpart ()</code></a>: <a href="#Elementary-complex-functions">Elementary complex functions</a></li>
<li><a href="#index-g_t_0040code_007brecip-_0028_0029_007d-277"><code>recip ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007brecip-_0028_0029_007d-46"><code>recip ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-reference-counting-336">reference counting</a>: <a href="#Memory-efficiency">Memory efficiency</a></li>
<li><a href="#index-g_t_0040code_007brem-_0028_0029_007d-96"><code>rem ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-representation-243">representation</a>: <a href="#Internal-and-printed-representation">Internal and printed representation</a></li>
<li><a href="#index-g_t_0040code_007bretract-_0028_0029_007d-270"><code>retract ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-Riemann_0027s-zeta-135">Riemann's zeta</a>: <a href="#Riemann-zeta">Riemann zeta</a></li>
<li><a href="#index-ring-260">ring</a>: <a href="#Modular-integer-rings">Modular integer rings</a></li>
<li><a href="#index-g_t_0040code_007bring-_0028_0029_007d-309"><code>ring ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bring-_0028_0029_007d-272"><code>ring ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007brootp-_0028_0029_007d-100"><code>rootp ()</code></a>: <a href="#Roots">Roots</a></li>
<li><a href="#index-g_t_0040code_007bround1-_0028_0029_007d-76"><code>round1 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007bround2-_0028_0029_007d-80"><code>round2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-rounding-72">rounding</a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-rounding-error-21">rounding error</a>: <a href="#Floating_002dpoint-numbers">Floating-point numbers</a></li>
<li><a href="#index-Rubik_0027s-cube-29">Rubik's cube</a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-g_t_0040code_007bruntime_005fexception_007d-352"><code>runtime_exception</code></a>: <a href="#Error-handling">Error handling</a></li>
<li><a href="#index-g_t_0040code_007bscale_005ffloat-_0028_0029_007d-196"><code>scale_float ()</code></a>: <a href="#Functions-on-floating_002dpoint-numbers">Functions on floating-point numbers</a></li>
<li><a href="#index-g_t_0040code_007bsed_007d-5"><code>sed</code></a>: <a href="#Sed-utility">Sed utility</a></li>
<li><a href="#index-g_t_0040code_007bset_005fcoeff-_0028_0029_007d-307"><code>set_coeff ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bsignum-_0028_0029_007d-51"><code>signum ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-g_t_0040code_007bsin-_0028_0029_007d-109"><code>sin ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007bsinh-_0028_0029_007d-123"><code>sinh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007bsize_0028_0029_007d-291"><code>size()</code></a>: <a href="#Strings">Strings</a></li>
<li><a href="#index-g_t_0040code_007bsqrt-_0028_0029_007d-97"><code>sqrt ()</code></a>: <a href="#Roots">Roots</a></li>
<li><a href="#index-g_t_0040code_007bsqrtp-_0028_0029_007d-98"><code>sqrtp ()</code></a>: <a href="#Roots">Roots</a></li>
<li><a href="#index-g_t_0040code_007bsquare-_0028_0029_007d-313"><code>square ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bsquare-_0028_0029_007d-276"><code>square ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bsquare-_0028_0029_007d-256"><code>square ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bsquare-_0028_0029_007d-44"><code>square ()</code></a>: <a href="#Elementary-functions">Elementary functions</a></li>
<li><a href="#index-string-289">string</a>: <a href="#Strings">Strings</a></li>
<li><a href="#index-g_t_0040code_007bstrlen-_0028_0029_007d-292"><code>strlen ()</code></a>: <a href="#Strings">Strings</a></li>
<li><a href="#index-symbol-295">symbol</a>: <a href="#Symbols">Symbols</a></li>
<li><a href="#index-symbolic-type-288">symbolic type</a>: <a href="#Symbolic-data-types">Symbolic data types</a></li>
<li><a href="#index-g_t_0040code_007btan-_0028_0029_007d-113"><code>tan ()</code></a>: <a href="#Trigonometric-functions">Trigonometric functions</a></li>
<li><a href="#index-g_t_0040code_007btanh-_0028_0029_007d-127"><code>tanh ()</code></a>: <a href="#Hyperbolic-functions">Hyperbolic functions</a></li>
<li><a href="#index-g_t_0040code_007bThe_0028_0029_0028_0029_007d-38"><code>The()()</code></a>: <a href="#Conversions">Conversions</a></li>
<li><a href="#index-transcendental-functions-102">transcendental functions</a>: <a href="#Transcendental-functions">Transcendental functions</a></li>
<li><a href="#index-g_t_0040code_007btruncate1-_0028_0029_007d-75"><code>truncate1 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007btruncate2-_0028_0029_007d-79"><code>truncate2 ()</code></a>: <a href="#Rounding-functions">Rounding functions</a></li>
<li><a href="#index-g_t_0040code_007btschebychev-_0028_0029_007d-325"><code>tschebychev ()</code></a>: <a href="#Special-polynomials">Special polynomials</a></li>
<li><a href="#index-g_t_0040code_007buminus-_0028_0029_007d-252"><code>uminus ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-underflow-355">underflow</a>: <a href="#Floating_002dpoint-underflow">Floating-point underflow</a></li>
<li><a href="#index-univariate-polynomial-299">univariate polynomial</a>: <a href="#Univariate-polynomials">Univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bxgcd-_0028_0029_007d-186"><code>xgcd ()</code></a>: <a href="#Number-theoretic-functions">Number theoretic functions</a></li>
<li><a href="#index-g_t_0040code_007bzero-_0028_0029_007d-302"><code>zero ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bzero-_0028_0029_007d-267"><code>zero ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bzero-_0028_0029_007d-248"><code>zero ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bzerop-_0028_0029_007d-317"><code>zerop ()</code></a>: <a href="#Functions-on-univariate-polynomials">Functions on univariate polynomials</a></li>
<li><a href="#index-g_t_0040code_007bzerop-_0028_0029_007d-285"><code>zerop ()</code></a>: <a href="#Functions-on-modular-integers">Functions on modular integers</a></li>
<li><a href="#index-g_t_0040code_007bzerop-_0028_0029_007d-249"><code>zerop ()</code></a>: <a href="#Rings">Rings</a></li>
<li><a href="#index-g_t_0040code_007bzerop-_0028_0029_007d-62"><code>zerop ()</code></a>: <a href="#Comparisons">Comparisons</a></li>
<li><a href="#index-g_t_0040code_007bzeta-_0028_0029_007d-136"><code>zeta ()</code></a>: <a href="#Riemann-zeta">Riemann zeta</a></li>
</ul><div class="footnote">
<hr>
<a name="texinfo-footnotes-in-document"></a><h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> If you installed CLN to
non-standard location <var>prefix</var>, you need to set the
<samp><span class="env">PKG_CONFIG_PATH</span></samp> environment variable to <var>prefix</var>/lib/pkgconfig
for this to work.</p>
<p class="footnote"><small>[<a name="fn-2" href="#fnd-2">2</a>]</small> See the <code>pkg-config</code> documentation for more details.</p>
<hr></div>
</body></html>
distrib
>
Fedora
>
13
>
i386
>
media
>
os
>
by-pkgid
>
3ffa093c702067d125f27610757cdfb2
>
files
>
83
