doc/cln.html

   1 <HTML>
   2 <HEAD>
   3 <!-- Created by texi2html 1.56k from cln.texi on 5 May 2000 -->
   4
   5 <TITLE>CLN, a Class Library for Numbers</TITLE>
   6 </HEAD>
   7 <BODY>
   8 <H1>CLN, a Class Library for Numbers</H1>
   9 <ADDRESS>by Bruno Haible</ADDRESS>
  10 <P>
  11 <P><HR><P>
  12 <H1>Table of Contents</H1>
  13 <UL>
  14 <LI><A NAME="TOC1" HREF="cln.html#SEC1">1. Introduction</A>
  15 <LI><A NAME="TOC2" HREF="cln.html#SEC2">2. Installation</A>
  16 <UL>
  17 <LI><A NAME="TOC3" HREF="cln.html#SEC3">2.1 Prerequisites</A>
  18 <UL>
  19 <LI><A NAME="TOC4" HREF="cln.html#SEC4">2.1.1 C++ compiler</A>
  20 <LI><A NAME="TOC5" HREF="cln.html#SEC5">2.1.2 Make utility</A>
  21 <LI><A NAME="TOC6" HREF="cln.html#SEC6">2.1.3 Sed utility</A>
  22 </UL>
  23 <LI><A NAME="TOC7" HREF="cln.html#SEC7">2.2 Building the library</A>
  24 <UL>
  25 <LI><A NAME="TOC8" HREF="cln.html#SEC8">2.2.1 Using the GNU MP Library</A>
  26 </UL>
  27 <LI><A NAME="TOC9" HREF="cln.html#SEC9">2.3 Installing the library</A>
  28 <LI><A NAME="TOC10" HREF="cln.html#SEC10">2.4 Cleaning up</A>
  29 </UL>
  30 <LI><A NAME="TOC11" HREF="cln.html#SEC11">3. Ordinary number types</A>
  31 <UL>
  32 <LI><A NAME="TOC12" HREF="cln.html#SEC12">3.1 Exact numbers</A>
  33 <LI><A NAME="TOC13" HREF="cln.html#SEC13">3.2 Floating-point numbers</A>
  34 <LI><A NAME="TOC14" HREF="cln.html#SEC14">3.3 Complex numbers</A>
  35 <LI><A NAME="TOC15" HREF="cln.html#SEC15">3.4 Conversions</A>
  36 </UL>
  37 <LI><A NAME="TOC16" HREF="cln.html#SEC16">4. Functions on numbers</A>
  38 <UL>
  39 <LI><A NAME="TOC17" HREF="cln.html#SEC17">4.1 Constructing numbers</A>
  40 <UL>
  41 <LI><A NAME="TOC18" HREF="cln.html#SEC18">4.1.1 Constructing integers</A>
  42 <LI><A NAME="TOC19" HREF="cln.html#SEC19">4.1.2 Constructing rational numbers</A>
  43 <LI><A NAME="TOC20" HREF="cln.html#SEC20">4.1.3 Constructing floating-point numbers</A>
  44 <LI><A NAME="TOC21" HREF="cln.html#SEC21">4.1.4 Constructing complex numbers</A>
  45 </UL>
  46 <LI><A NAME="TOC22" HREF="cln.html#SEC22">4.2 Elementary functions</A>
  47 <LI><A NAME="TOC23" HREF="cln.html#SEC23">4.3 Elementary rational functions</A>
  48 <LI><A NAME="TOC24" HREF="cln.html#SEC24">4.4 Elementary complex functions</A>
  49 <LI><A NAME="TOC25" HREF="cln.html#SEC25">4.5 Comparisons</A>
  50 <LI><A NAME="TOC26" HREF="cln.html#SEC26">4.6 Rounding functions</A>
  51 <LI><A NAME="TOC27" HREF="cln.html#SEC27">4.7 Roots</A>
  52 <LI><A NAME="TOC28" HREF="cln.html#SEC28">4.8 Transcendental functions</A>
  53 <UL>
  54 <LI><A NAME="TOC29" HREF="cln.html#SEC29">4.8.1 Exponential and logarithmic functions</A>
  55 <LI><A NAME="TOC30" HREF="cln.html#SEC30">4.8.2 Trigonometric functions</A>
  56 <LI><A NAME="TOC31" HREF="cln.html#SEC31">4.8.3 Hyperbolic functions</A>
  57 <LI><A NAME="TOC32" HREF="cln.html#SEC32">4.8.4 Euler gamma</A>
  58 <LI><A NAME="TOC33" HREF="cln.html#SEC33">4.8.5 Riemann zeta</A>
  59 </UL>
  60 <LI><A NAME="TOC34" HREF="cln.html#SEC34">4.9 Functions on integers</A>
  61 <UL>
  62 <LI><A NAME="TOC35" HREF="cln.html#SEC35">4.9.1 Logical functions</A>
  63 <LI><A NAME="TOC36" HREF="cln.html#SEC36">4.9.2 Number theoretic functions</A>
  64 <LI><A NAME="TOC37" HREF="cln.html#SEC37">4.9.3 Combinatorial functions</A>
  65 </UL>
  66 <LI><A NAME="TOC38" HREF="cln.html#SEC38">4.10 Functions on floating-point numbers</A>
  67 <LI><A NAME="TOC39" HREF="cln.html#SEC39">4.11 Conversion functions</A>
  68 <UL>
  69 <LI><A NAME="TOC40" HREF="cln.html#SEC40">4.11.1 Conversion to floating-point numbers</A>
  70 <LI><A NAME="TOC41" HREF="cln.html#SEC41">4.11.2 Conversion to rational numbers</A>
  71 </UL>
  72 <LI><A NAME="TOC42" HREF="cln.html#SEC42">4.12 Random number generators</A>
  73 <LI><A NAME="TOC43" HREF="cln.html#SEC43">4.13 Obfuscating operators</A>
  74 </UL>
  75 <LI><A NAME="TOC44" HREF="cln.html#SEC44">5. Input/Output</A>
  76 <UL>
  77 <LI><A NAME="TOC45" HREF="cln.html#SEC45">5.1 Internal and printed representation</A>
  78 <LI><A NAME="TOC46" HREF="cln.html#SEC46">5.2 Input functions</A>
  79 <LI><A NAME="TOC47" HREF="cln.html#SEC47">5.3 Output functions</A>
  80 </UL>
  81 <LI><A NAME="TOC48" HREF="cln.html#SEC48">6. Rings</A>
  82 <LI><A NAME="TOC49" HREF="cln.html#SEC49">7. Modular integers</A>
  83 <UL>
  84 <LI><A NAME="TOC50" HREF="cln.html#SEC50">7.1 Modular integer rings</A>
  85 <LI><A NAME="TOC51" HREF="cln.html#SEC51">7.2 Functions on modular integers</A>
  86 </UL>
  87 <LI><A NAME="TOC52" HREF="cln.html#SEC52">8. Symbolic data types</A>
  88 <UL>
  89 <LI><A NAME="TOC53" HREF="cln.html#SEC53">8.1 Strings</A>
  90 <LI><A NAME="TOC54" HREF="cln.html#SEC54">8.2 Symbols</A>
  91 </UL>
  92 <LI><A NAME="TOC55" HREF="cln.html#SEC55">9. Univariate polynomials</A>
  93 <UL>
  94 <LI><A NAME="TOC56" HREF="cln.html#SEC56">9.1 Univariate polynomial rings</A>
  95 <LI><A NAME="TOC57" HREF="cln.html#SEC57">9.2 Functions on univariate polynomials</A>
  96 <LI><A NAME="TOC58" HREF="cln.html#SEC58">9.3 Special polynomials</A>
  97 </UL>
  98 <LI><A NAME="TOC59" HREF="cln.html#SEC59">10. Internals</A>
  99 <UL>
 100 <LI><A NAME="TOC60" HREF="cln.html#SEC60">10.1 Why C++ ?</A>
 101 <LI><A NAME="TOC61" HREF="cln.html#SEC61">10.2 Memory efficiency</A>
 102 <LI><A NAME="TOC62" HREF="cln.html#SEC62">10.3 Speed efficiency</A>
 103 <LI><A NAME="TOC63" HREF="cln.html#SEC63">10.4 Garbage collection</A>
 104 </UL>
 105 <LI><A NAME="TOC64" HREF="cln.html#SEC64">11. Using the library</A>
 106 <UL>
 107 <LI><A NAME="TOC65" HREF="cln.html#SEC65">11.1 Compiler options</A>
 108 <LI><A NAME="TOC66" HREF="cln.html#SEC66">11.2 Include files</A>
 109 <LI><A NAME="TOC67" HREF="cln.html#SEC67">11.3 An Example</A>
 110 <LI><A NAME="TOC68" HREF="cln.html#SEC68">11.4 Debugging support</A>
 111 </UL>
 112 <LI><A NAME="TOC69" HREF="cln.html#SEC69">12. Customizing</A>
 113 <UL>
 114 <LI><A NAME="TOC70" HREF="cln.html#SEC70">12.1 Error handling</A>
 115 <LI><A NAME="TOC71" HREF="cln.html#SEC71">12.2 Floating-point underflow</A>
 116 <LI><A NAME="TOC72" HREF="cln.html#SEC72">12.3 Customizing I/O</A>
 117 <LI><A NAME="TOC73" HREF="cln.html#SEC73">12.4 Customizing the memory allocator</A>
 118 </UL>
 119 <LI><A NAME="TOC74" HREF="cln.html#SEC74">Index</A>
 120 </UL>
 121 <P><HR><P>
 122
 123
 124 <H1><A NAME="SEC1" HREF="cln.html#TOC1">1. Introduction</A></H1>
 125
 126 <P>
 127 CLN is a library for computations with all kinds of numbers.
 128 It has a rich set of number classes:
 129
 130
 131
 132 <UL>
 133 <LI>
 134
 135 Integers (with unlimited precision),
 136
 137 <LI>
 138
 139 Rational numbers,
 140
 141 <LI>
 142
 143 Floating-point numbers:
 144
 145
 146 <UL>
 147 <LI>
 148
 149 Short float,
 150 <LI>
 151
 152 Single float,
 153 <LI>
 154
 155 Double float,
 156 <LI>
 157
 158 Long float (with unlimited precision),
 159 </UL>
 160
 161 <LI>
 162
 163 Complex numbers,
 164
 165 <LI>
 166
 167 Modular integers (integers modulo a fixed integer),
 168
 169 <LI>
 170
 171 Univariate polynomials.
 172 </UL>
 173
 174 <P>
 175 The subtypes of the complex numbers among these are exactly the
 176 types of numbers known to the Common Lisp language. Therefore
 177 <CODE>CLN</CODE> can be used for Common Lisp implementations, giving
 178 <SAMP>`CLN'</SAMP> another meaning: it becomes an abbreviation of
 179 "Common Lisp Numbers".
 180
 181
 182 <P>
 183 The CLN package implements
 184
 185
 186
 187 <UL>
 188 <LI>
 189
 190 Elementary functions (<CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, <CODE>sqrt</CODE>,
 191 comparisons, ...),
 192
 193 <LI>
 194
 195 Logical functions (logical <CODE>and</CODE>, <CODE>or</CODE>, <CODE>not</CODE>, ...),
 196
 197 <LI>
 198
 199 Transcendental functions (exponential, logarithmic, trigonometric, hyperbolic
 200 functions and their inverse functions).
 201 </UL>
 202
 203 <P>
 204 CLN is a C++ library. Using C++ as an implementation language provides
 205
 206
 207
 208 <UL>
 209 <LI>
 210
 211 efficiency: it compiles to machine code,
 212 <LI>
 213
 214 type safety: the C++ compiler knows about the number types and complains
 215 if, for example, you try to assign a float to an integer variable.
 216 <LI>
 217
 218 algebraic syntax: You can use the <CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>=</CODE>,
 219 <CODE>==</CODE>, ... operators as in C or C++.
 220 </UL>
 221
 222 <P>
 223 CLN is memory efficient:
 224
 225
 226
 227 <UL>
 228 <LI>
 229
 230 Small integers and short floats are immediate, not heap allocated.
 231 <LI>
 232
 233 Heap-allocated memory is reclaimed through an automatic, non-interruptive
 234 garbage collection.
 235 </UL>
 236
 237 <P>
 238 CLN is speed efficient:
 239
 240
 241
 242 <UL>
 243 <LI>
 244
 245 The kernel of CLN has been written in assembly language for some CPUs
 246 (<CODE>i386</CODE>, <CODE>m68k</CODE>, <CODE>sparc</CODE>, <CODE>mips</CODE>, <CODE>arm</CODE>).
 247 <LI>
 248
 249 <A NAME="IDX1"></A>
 250 On all CPUs, CLN may be configured to use the superefficient low-level
 251 routines from GNU GMP version 3.
 252 <LI>
 253
 254 It uses Karatsuba multiplication, which is significantly faster
 255 for large numbers than the standard multiplication algorithm.
 256 <LI>
 257
 258 For very large numbers (more than 12000 decimal digits), it uses
 259 Schönhage-Strassen
 260 <A NAME="IDX2"></A>
 261 multiplication, which is an asymptotically optimal multiplication
 262 algorithm, for multiplication, division and radix conversion.
 263 </UL>
 264
 265 <P>
 266 CLN aims at being easily integrated into larger software packages:
 267
 268
 269
 270 <UL>
 271 <LI>
 272
 273 The garbage collection imposes no burden on the main application.
 274 <LI>
 275
 276 The library provides hooks for memory allocation and exceptions.
 277 </UL>
 278
 279
 280
 281 <H1><A NAME="SEC2" HREF="cln.html#TOC2">2. Installation</A></H1>
 282
 283 <P>
 284 This section describes how to install the CLN package on your system.
 285
 286
 287
 288
 289 <H2><A NAME="SEC3" HREF="cln.html#TOC3">2.1 Prerequisites</A></H2>
 290
 291
 292
 293 <H3><A NAME="SEC4" HREF="cln.html#TOC4">2.1.1 C++ compiler</A></H3>
 294
 295 <P>
 296 To build CLN, you need a C++ compiler.
 297 Actually, you need GNU <CODE>g++ 2.7.0</CODE> or newer.
 298 On HPPA, you need GNU <CODE>g++ 2.8.0</CODE> or newer.
 299 I recommend GNU <CODE>g++ 2.95</CODE> or newer.
 300
 301
 302 <P>
 303 The following C++ features are used:
 304 classes, member functions,
 305 overloading of functions and operators,
 306 constructors and destructors, inline, const,
 307 multiple inheritance, templates.
 308
 309
 310 <P>
 311 The following C++ features are not used:
 312 <CODE>new</CODE>, <CODE>delete</CODE>, virtual inheritance,
 313 exceptions.
 314
 315
 316 <P>
 317 CLN relies on semi-automatic ordering of initializations
 318 of static and global variables, a feature which I could
 319 implement for GNU g++ only.
 320
 321
 322
 323
 324 <H3><A NAME="SEC5" HREF="cln.html#TOC5">2.1.2 Make utility</A></H3>
 325 <P>
 326 <A NAME="IDX3"></A>
 327
 328
 329 <P>
 330 To build CLN, you also need to have GNU <CODE>make</CODE> installed.
 331
 332
 333
 334
 335 <H3><A NAME="SEC6" HREF="cln.html#TOC6">2.1.3 Sed utility</A></H3>
 336 <P>
 337 <A NAME="IDX4"></A>
 338
 339
 340 <P>
 341 To build CLN on HP-UX, you also need to have GNU <CODE>sed</CODE> installed.
 342 This is because the libtool script, which creates the CLN library, relies
 343 on <CODE>sed</CODE>, and the vendor's <CODE>sed</CODE> utility on these systems is too
 344 limited.
 345
 346
 347
 348
 349 <H2><A NAME="SEC7" HREF="cln.html#TOC7">2.2 Building the library</A></H2>
 350
 351 <P>
 352 As with any autoconfiguring GNU software, installation is as easy as this:
 353
 354
 355
 356 <PRE>
 357 $ ./configure
 358 $ make
 359 $ make check
 360 </PRE>
 361
 362 <P>
 363 If on your system, <SAMP>`make'</SAMP> is not GNU <CODE>make</CODE>, you have to use
 364 <SAMP>`gmake'</SAMP> instead of <SAMP>`make'</SAMP> above.
 365
 366
 367 <P>
 368 The <CODE>configure</CODE> command checks out some features of your system and
 369 C++ compiler and builds the <CODE>Makefile</CODE>s. The <CODE>make</CODE> command
 370 builds the library. This step may take 4 hours on an average workstation.
 371 The <CODE>make check</CODE> runs some test to check that no important subroutine
 372 has been miscompiled.
 373
 374
 375 <P>
 376 The <CODE>configure</CODE> command accepts options. To get a summary of them, try
 377
 378
 379
 380 <PRE>
 381 $ ./configure --help
 382 </PRE>
 383
 384 <P>
 385 Some of the options are explained in detail in the <SAMP>`INSTALL.generic'</SAMP> file.
 386
 387
 388 <P>
 389 You can specify the C compiler, the C++ compiler and their options through
 390 the following environment variables when running <CODE>configure</CODE>:
 391
 392
 393 <DL COMPACT>
 394
 395 <DT><CODE>CC</CODE>
 396 <DD>
 397 Specifies the C compiler.
 398
 399 <DT><CODE>CFLAGS</CODE>
 400 <DD>
 401 Flags to be given to the C compiler when compiling programs (not when linking).
 402
 403 <DT><CODE>CXX</CODE>
 404 <DD>
 405 Specifies the C++ compiler.
 406
 407 <DT><CODE>CXXFLAGS</CODE>
 408 <DD>
 409 Flags to be given to the C++ compiler when compiling programs (not when linking).
 410 </DL>
 411
 412 <P>
 413 Examples:
 414
 415
 416
 417 <PRE>
 418 $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
 419 $ CC="gcc -V 2.7.2" CFLAGS="-O -g" \
 420   CXX="g++ -V 2.7.2" CXXFLAGS="-O -g" ./configure
 421 $ CC="gcc -V 2.8.1" CFLAGS="-O -fno-exceptions" \
 422   CXX="g++ -V 2.8.1" CXXFLAGS="-O -fno-exceptions" ./configure
 423 $ CC="gcc -V egcs-2.91.60" CFLAGS="-O2 -fno-exceptions" \
 424   CXX="g++ -V egcs-2.91.60" CFLAGS="-O2 -fno-exceptions" ./configure
 425 </PRE>
 426
 427 <P>
 428 Note that for these environment variables to take effect, you have to set
 429 them (assuming a Bourne-compatible shell) on the same line as the
 430 <CODE>configure</CODE> command. If you made the settings in earlier shell
 431 commands, you have to <CODE>export</CODE> the environment variables before
 432 calling <CODE>configure</CODE>. In a <CODE>csh</CODE> shell, you have to use the
 433 <SAMP>`setenv'</SAMP> command for setting each of the environment variables.
 434
 435
 436 <P>
 437 On Linux, <CODE>g++</CODE> needs 15 MB to compile the tests. So you should better
 438 have 17 MB swap space and 1 MB room in $TMPDIR.
 439
 440
 441 <P>
 442 If you use <CODE>g++</CODE> version 2.7.x, don't add <SAMP>`-O2'</SAMP> to the CXXFLAGS,
 443 because <SAMP>`g++ -O'</SAMP> generates better code for CLN than <SAMP>`g++ -O2'</SAMP>.
 444
 445
 446 <P>
 447 If you use <CODE>g++</CODE> version 2.8.x or egcs-2.91.x (a.k.a. egcs-1.1) or
 448 gcc-2.95.x, I recommend adding <SAMP>`-fno-exceptions'</SAMP> to the CXXFLAGS.
 449 This will likely generate better code.
 450
 451
 452 <P>
 453 If you use <CODE>g++</CODE> version egcs-2.91.x (egcs-1.1) or gcc-2.95.x on Sparc,
 454 add either <SAMP>`-O'</SAMP> or <SAMP>`-O2 -fno-schedule-insns'</SAMP> to the CXXFLAGS.
 455 With full <SAMP>`-O2'</SAMP>, <CODE>g++</CODE> miscompiles the division routines. Also, for
 456 --enable-shared to work, you need egcs-1.1.2 or newer.
 457
 458
 459 <P>
 460 By default, only a static library is built. You can build CLN as a shared
 461 library too, by calling <CODE>configure</CODE> with the option <SAMP>`--enable-shared'</SAMP>.
 462 To get it built as a shared library only, call <CODE>configure</CODE> with the options
 463 <SAMP>`--enable-shared --disable-static'</SAMP>.
 464
 465
 466 <P>
 467 If you use <CODE>g++</CODE> version egcs-2.91.x (egcs-1.1) on Sparc, you cannot
 468 use <SAMP>`--enable-shared'</SAMP> because <CODE>g++</CODE> would miscompile parts of the
 469 library.
 470
 471
 472
 473
 474 <H3><A NAME="SEC8" HREF="cln.html#TOC8">2.2.1 Using the GNU MP Library</A></H3>
 475 <P>
 476 <A NAME="IDX5"></A>
 477
 478
 479 <P>
 480 Starting with version 1.0.4, CLN may be configured to make use of a
 481 preinstalled <CODE>gmp</CODE> library.  Please make sure that you have at
 482 least <CODE>gmp</CODE> version 3.0 installed since earlier versions are
 483 unsupported and likely not to work.  Enabling this feature by calling
 484 <CODE>configure</CODE> with the option <SAMP>`--with-gmp'</SAMP> is known to be quite
 485 a boost for CLN's performance.
 486
 487
 488 <P>
 489 If you have installed the <CODE>gmp</CODE> library and its header file in
 490 some place where your compiler cannot find it by default, you must help
 491 <CODE>configure</CODE> by setting <CODE>CPPFLAGS</CODE> and <CODE>LDFLAGS</CODE>.  Here is
 492 an example:
 493
 494
 495
 496 <PRE>
 497 $ CC="gcc" CFLAGS="-O2" CXX="g++" CXXFLAGS="-O2 -fno-exceptions" \
 498   CPPFLAGS="-I/opt/gmp/include" LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp
 499 </PRE>
 500
 501
 502
 503 <H2><A NAME="SEC9" HREF="cln.html#TOC9">2.3 Installing the library</A></H2>
 504 <P>
 505 <A NAME="IDX6"></A>
 506
 507
 508 <P>
 509 As with any autoconfiguring GNU software, installation is as easy as this:
 510
 511
 512
 513 <PRE>
 514 $ make install
 515 </PRE>
 516
 517 <P>
 518 The <SAMP>`make install'</SAMP> command installs the library and the include files
 519 into public places (<TT>`/usr/local/lib/'</TT> and <TT>`/usr/local/include/'</TT>,
 520 if you haven't specified a <CODE>--prefix</CODE> option to <CODE>configure</CODE>).
 521 This step may require superuser privileges.
 522
 523
 524 <P>
 525 If you have already built the library and wish to install it, but didn't
 526 specify <CODE>--prefix=...</CODE> at configure time, just re-run
 527 <CODE>configure</CODE>, giving it the same options as the first time, plus
 528 the <CODE>--prefix=...</CODE> option.
 529
 530
 531
 532
 533 <H2><A NAME="SEC10" HREF="cln.html#TOC10">2.4 Cleaning up</A></H2>
 534
 535 <P>
 536 You can remove system-dependent files generated by <CODE>make</CODE> through
 537
 538
 539
 540 <PRE>
 541 $ make clean
 542 </PRE>
 543
 544 <P>
 545 You can remove all files generated by <CODE>make</CODE>, thus reverting to a
 546 virgin distribution of CLN, through
 547
 548
 549
 550 <PRE>
 551 $ make distclean
 552 </PRE>
 553
 554
 555
 556 <H1><A NAME="SEC11" HREF="cln.html#TOC11">3. Ordinary number types</A></H1>
 557
 558 <P>
 559 CLN implements the following class hierarchy:
 560
 561
 562
 563 <PRE>
 564                         Number
 565                        cl_number
 566                      &#60;cl_number.h&#62;
 567                           |
 568                           |
 569                  Real or complex number
 570                         cl_N
 571                      &#60;cl_complex.h&#62;
 572                           |
 573                           |
 574                      Real number
 575                         cl_R
 576                       &#60;cl_real.h&#62;
 577                           |
 578       +-------------------+-------------------+
 579       |                                       |
 580 Rational number                     Floating-point number
 581     cl_RA                                   cl_F
 582 &#60;cl_rational.h&#62;                          &#60;cl_float.h&#62;
 583       |                                       |
 584       |                  +-------------+-------------+-------------+
 585    Integer               |             |             |             |
 586     cl_I            Short-Float   Single-Float  Double-Float   Long-Float
 587  &#60;cl_integer.h&#62;        cl_SF         cl_FF         cl_DF         cl_LF
 588                    &#60;cl_sfloat.h&#62; &#60;cl_ffloat.h&#62; &#60;cl_dfloat.h&#62; &#60;cl_lfloat.h&#62;
 589 </PRE>
 590
 591 <P>
 592 <A NAME="IDX7"></A>
 593 <A NAME="IDX8"></A>
 594 The base class <CODE>cl_number</CODE> is an abstract base class.
 595 It is not useful to declare a variable of this type except if you want
 596 to completely disable compile-time type checking and use run-time type
 597 checking instead.
 598
 599
 600 <P>
 601 <A NAME="IDX9"></A>
 602 <A NAME="IDX10"></A>
 603 <A NAME="IDX11"></A>
 604 The class <CODE>cl_N</CODE> comprises real and complex numbers. There is
 605 no special class for complex numbers since complex numbers with imaginary
 606 part <CODE>0</CODE> are automatically converted to real numbers.
 607
 608
 609 <P>
 610 <A NAME="IDX12"></A>
 611 The class <CODE>cl_R</CODE> comprises real numbers of different kinds. It is an
 612 abstract class.
 613
 614
 615 <P>
 616 <A NAME="IDX13"></A>
 617 <A NAME="IDX14"></A>
 618 <A NAME="IDX15"></A>
 619 The class <CODE>cl_RA</CODE> comprises exact real numbers: rational numbers, including
 620 integers. There is no special class for non-integral rational numbers
 621 since rational numbers with denominator <CODE>1</CODE> are automatically converted
 622 to integers.
 623
 624
 625 <P>
 626 <A NAME="IDX16"></A>
 627 The class <CODE>cl_F</CODE> implements floating-point approximations to real numbers.
 628 It is an abstract class.
 629
 630
 631
 632
 633 <H2><A NAME="SEC12" HREF="cln.html#TOC12">3.1 Exact numbers</A></H2>
 634 <P>
 635 <A NAME="IDX17"></A>
 636
 637
 638 <P>
 639 Some numbers are represented as exact numbers: there is no loss of information
 640 when such a number is converted from its mathematical value to its internal
 641 representation. On exact numbers, the elementary operations (<CODE>+</CODE>,
 642 <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, comparisons, ...) compute the completely
 643 correct result.
 644
 645
 646 <P>
 647 In CLN, the exact numbers are:
 648
 649
 650
 651 <UL>
 652 <LI>
 653
 654 rational numbers (including integers),
 655 <LI>
 656
 657 complex numbers whose real and imaginary parts are both rational numbers.
 658 </UL>
 659
 660 <P>
 661 Rational numbers are always normalized to the form
 662 <CODE><VAR>numerator</VAR>/<VAR>denominator</VAR></CODE> where the numerator and denominator
 663 are coprime integers and the denominator is positive. If the resulting
 664 denominator is <CODE>1</CODE>, the rational number is converted to an integer.
 665
 666
 667 <P>
 668 Small integers (typically in the range <CODE>-2^30</CODE>...<CODE>2^30-1</CODE>,
 669 for 32-bit machines) are especially efficient, because they consume no heap
 670 allocation. Otherwise the distinction between these immediate integers
 671 (called "fixnums") and heap allocated integers (called "bignums")
 672 is completely transparent.
 673
 674
 675
 676
 677 <H2><A NAME="SEC13" HREF="cln.html#TOC13">3.2 Floating-point numbers</A></H2>
 678 <P>
 679 <A NAME="IDX18"></A>
 680
 681
 682 <P>
 683 Not all real numbers can be represented exactly. (There is an easy mathematical
 684 proof for this: Only a countable set of numbers can be stored exactly in
 685 a computer, even if one assumes that it has unlimited storage. But there
 686 are uncountably many real numbers.) So some approximation is needed.
 687 CLN implements ordinary floating-point numbers, with mantissa and exponent.
 688
 689
 690 <P>
 691 <A NAME="IDX19"></A>
 692 The elementary operations (<CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, ...)
 693 only return approximate results. For example, the value of the expression
 694 <CODE>(cl_F) 0.3 + (cl_F) 0.4</CODE> prints as <SAMP>`0.70000005'</SAMP>, not as
 695 <SAMP>`0.7'</SAMP>. Rounding errors like this one are inevitable when computing
 696 with floating-point numbers.
 697
 698
 699 <P>
 700 Nevertheless, CLN rounds the floating-point results of the operations <CODE>+</CODE>,
 701 <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, <CODE>sqrt</CODE> according to the "round-to-even"
 702 rule: It first computes the exact mathematical result and then returns the
 703 floating-point number which is nearest to this. If two floating-point numbers
 704 are equally distant from the ideal result, the one with a <CODE>0</CODE> in its least
 705 significant mantissa bit is chosen.
 706
 707
 708 <P>
 709 Similarly, testing floating point numbers for equality <SAMP>`x == y'</SAMP>
 710 is gambling with random errors. Better check for <SAMP>`abs(x - y) &#60; epsilon'</SAMP>
 711 for some well-chosen <CODE>epsilon</CODE>.
 712
 713
 714 <P>
 715 Floating point numbers come in four flavors:
 716
 717
 718
 719 <UL>
 720 <LI>
 721
 722 <A NAME="IDX20"></A>
 723 Short floats, type <CODE>cl_SF</CODE>.
 724 They have 1 sign bit, 8 exponent bits (including the exponent's sign),
 725 and 17 mantissa bits (including the "hidden" bit).
 726 They don't consume heap allocation.
 727
 728 <LI>
 729
 730 <A NAME="IDX21"></A>
 731 Single floats, type <CODE>cl_FF</CODE>.
 732 They have 1 sign bit, 8 exponent bits (including the exponent's sign),
 733 and 24 mantissa bits (including the "hidden" bit).
 734 In CLN, they are represented as IEEE single-precision floating point numbers.
 735 This corresponds closely to the C/C++ type <SAMP>`float'</SAMP>.
 736
 737 <LI>
 738
 739 <A NAME="IDX22"></A>
 740 Double floats, type <CODE>cl_DF</CODE>.
 741 They have 1 sign bit, 11 exponent bits (including the exponent's sign),
 742 and 53 mantissa bits (including the "hidden" bit).
 743 In CLN, they are represented as IEEE double-precision floating point numbers.
 744 This corresponds closely to the C/C++ type <SAMP>`double'</SAMP>.
 745
 746 <LI>
 747
 748 <A NAME="IDX23"></A>
 749 Long floats, type <CODE>cl_LF</CODE>.
 750 They have 1 sign bit, 32 exponent bits (including the exponent's sign),
 751 and n mantissa bits (including the "hidden" bit), where n &#62;= 64.
 752 The precision of a long float is unlimited, but once created, a long float
 753 has a fixed precision. (No "lazy recomputation".)
 754 </UL>
 755
 756 <P>
 757 Of course, computations with long floats are more expensive than those
 758 with smaller floating-point formats.
 759
 760
 761 <P>
 762 CLN does not implement features like NaNs, denormalized numbers and
 763 gradual underflow. If the exponent range of some floating-point type
 764 is too limited for your application, choose another floating-point type
 765 with larger exponent range.
 766
 767
 768 <P>
 769 <A NAME="IDX24"></A>
 770 As a user of CLN, you can forget about the differences between the
 771 four floating-point types and just declare all your floating-point
 772 variables as being of type <CODE>cl_F</CODE>. This has the advantage that
 773 when you change the precision of some computation (say, from <CODE>cl_DF</CODE>
 774 to <CODE>cl_LF</CODE>), you don't have to change the code, only the precision
 775 of the initial values. Also, many transcendental functions have been
 776 declared as returning a <CODE>cl_F</CODE> when the argument is a <CODE>cl_F</CODE>,
 777 but such declarations are missing for the types <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>,
 778 <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>. (Such declarations would be wrong if
 779 the floating point contagion rule happened to change in the future.)
 780
 781
 782
 783
 784 <H2><A NAME="SEC14" HREF="cln.html#TOC14">3.3 Complex numbers</A></H2>
 785 <P>
 786 <A NAME="IDX25"></A>
 787
 788
 789 <P>
 790 Complex numbers, as implemented by the class <CODE>cl_N</CODE>, have a real
 791 part and an imaginary part, both real numbers. A complex number whose
 792 imaginary part is the exact number <CODE>0</CODE> is automatically converted
 793 to a real number.
 794
 795
 796 <P>
 797 Complex numbers can arise from real numbers alone, for example
 798 through application of <CODE>sqrt</CODE> or transcendental functions.
 799
 800
 801
 802
 803 <H2><A NAME="SEC15" HREF="cln.html#TOC15">3.4 Conversions</A></H2>
 804 <P>
 805 <A NAME="IDX26"></A>
 806
 807
 808 <P>
 809 Conversions from any class to any its superclasses ("base classes" in
 810 C++ terminology) is done automatically.
 811
 812
 813 <P>
 814 Conversions from the C built-in types <SAMP>`long'</SAMP> and <SAMP>`unsigned long'</SAMP>
 815 are provided for the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_R</CODE>,
 816 <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
 817
 818
 819 <P>
 820 Conversions from the C built-in types <SAMP>`int'</SAMP> and <SAMP>`unsigned int'</SAMP>
 821 are provided for the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_R</CODE>,
 822 <CODE>cl_N</CODE> and <CODE>cl_number</CODE>. However, these conversions emphasize
 823 efficiency. Their range is therefore limited:
 824
 825
 826
 827 <UL>
 828 <LI>
 829
 830 The conversion from <SAMP>`int'</SAMP> works only if the argument is &#60; 2^29 and &#62; -2^29.
 831 <LI>
 832
 833 The conversion from <SAMP>`unsigned int'</SAMP> works only if the argument is &#60; 2^29.
 834 </UL>
 835
 836 <P>
 837 In a declaration like <SAMP>`cl_I x = 10;'</SAMP> the C++ compiler is able to
 838 do the conversion of <CODE>10</CODE> from <SAMP>`int'</SAMP> to <SAMP>`cl_I'</SAMP> at compile time
 839 already. On the other hand, code like <SAMP>`cl_I x = 1000000000;'</SAMP> is
 840 in error.
 841 So, if you want to be sure that an <SAMP>`int'</SAMP> whose magnitude is not guaranteed
 842 to be &#60; 2^29 is correctly converted to a <SAMP>`cl_I'</SAMP>, first convert it to a
 843 <SAMP>`long'</SAMP>. Similarly, if a large <SAMP>`unsigned int'</SAMP> is to be converted to a
 844 <SAMP>`cl_I'</SAMP>, first convert it to an <SAMP>`unsigned long'</SAMP>.
 845
 846
 847 <P>
 848 Conversions from the C built-in type <SAMP>`float'</SAMP> are provided for the classes
 849 <CODE>cl_FF</CODE>, <CODE>cl_F</CODE>, <CODE>cl_R</CODE>, <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
 850
 851
 852 <P>
 853 Conversions from the C built-in type <SAMP>`double'</SAMP> are provided for the classes
 854 <CODE>cl_DF</CODE>, <CODE>cl_F</CODE>, <CODE>cl_R</CODE>, <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
 855
 856
 857 <P>
 858 Conversions from <SAMP>`const char *'</SAMP> are provided for the classes
 859 <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
 860 <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>, <CODE>cl_F</CODE>,
 861 <CODE>cl_R</CODE>, <CODE>cl_N</CODE>.
 862 The easiest way to specify a value which is outside of the range of the
 863 C++ built-in types is therefore to specify it as a string, like this:
 864 <A NAME="IDX27"></A>
 865
 866 <PRE>
 867    cl_I order_of_rubiks_cube_group = "43252003274489856000";
 868 </PRE>
 869
 870 <P>
 871 Note that this conversion is done at runtime, not at compile-time.
 872
 873
 874 <P>
 875 Conversions from <CODE>cl_I</CODE> to the C built-in types <SAMP>`int'</SAMP>,
 876 <SAMP>`unsigned int'</SAMP>, <SAMP>`long'</SAMP>, <SAMP>`unsigned long'</SAMP> are provided through
 877 the functions
 878
 879
 880 <DL COMPACT>
 881
 882 <DT><CODE>int cl_I_to_int (const cl_I&#38; x)</CODE>
 883 <DD>
 884 <A NAME="IDX28"></A>
 885 <DT><CODE>unsigned int cl_I_to_uint (const cl_I&#38; x)</CODE>
 886 <DD>
 887 <A NAME="IDX29"></A>
 888 <DT><CODE>long cl_I_to_long (const cl_I&#38; x)</CODE>
 889 <DD>
 890 <A NAME="IDX30"></A>
 891 <DT><CODE>unsigned long cl_I_to_ulong (const cl_I&#38; x)</CODE>
 892 <DD>
 893 <A NAME="IDX31"></A>
 894 Returns <CODE>x</CODE> as element of the C type <VAR>ctype</VAR>. If <CODE>x</CODE> is not
 895 representable in the range of <VAR>ctype</VAR>, a runtime error occurs.
 896 </DL>
 897
 898 <P>
 899 Conversions from the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
 900 <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>, <CODE>cl_F</CODE> and
 901 <CODE>cl_R</CODE>
 902 to the C built-in types <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP> are provided through
 903 the functions
 904
 905
 906 <DL COMPACT>
 907
 908 <DT><CODE>float cl_float_approx (const <VAR>type</VAR>&#38; x)</CODE>
 909 <DD>
 910 <A NAME="IDX32"></A>
 911 <DT><CODE>double cl_double_approx (const <VAR>type</VAR>&#38; x)</CODE>
 912 <DD>
 913 <A NAME="IDX33"></A>
 914 Returns an approximation of <CODE>x</CODE> of C type <VAR>ctype</VAR>.
 915 If <CODE>abs(x)</CODE> is too close to 0 (underflow), 0 is returned.
 916 If <CODE>abs(x)</CODE> is too large (overflow), an IEEE infinity is returned.
 917 </DL>
 918
 919 <P>
 920 Conversions from any class to any of its subclasses ("derived classes" in
 921 C++ terminology) are not provided. Instead, you can assert and check
 922 that a value belongs to a certain subclass, and return it as element of that
 923 class, using the <SAMP>`As'</SAMP> and <SAMP>`The'</SAMP> macros.
 924 <A NAME="IDX34"></A>
 925 <CODE>As(<VAR>type</VAR>)(<VAR>value</VAR>)</CODE> checks that <VAR>value</VAR> belongs to
 926 <VAR>type</VAR> and returns it as such.
 927 <A NAME="IDX35"></A>
 928 <CODE>The(<VAR>type</VAR>)(<VAR>value</VAR>)</CODE> assumes that <VAR>value</VAR> belongs to
 929 <VAR>type</VAR> and returns it as such. It is your responsibility to ensure
 930 that this assumption is valid.
 931 Example:
 932
 933
 934
 935 <PRE>
 936    cl_I x = ...;
 937    if (!(x &#62;= 0)) abort();
 938    cl_I ten_x = The(cl_I)(expt(10,x)); // If x &#62;= 0, 10^x is an integer.
 939                 // In general, it would be a rational number.
 940 </PRE>
 941
 942
 943
 944 <H1><A NAME="SEC16" HREF="cln.html#TOC16">4. Functions on numbers</A></H1>
 945
 946 <P>
 947 Each of the number classes declares its mathematical operations in the
 948 corresponding include file. For example, if your code operates with
 949 objects of type <CODE>cl_I</CODE>, it should <CODE>#include &#60;cl_integer.h&#62;</CODE>.
 950
 951
 952
 953
 954 <H2><A NAME="SEC17" HREF="cln.html#TOC17">4.1 Constructing numbers</A></H2>
 955
 956 <P>
 957 Here is how to create number objects "from nothing".
 958
 959
 960
 961
 962 <H3><A NAME="SEC18" HREF="cln.html#TOC18">4.1.1 Constructing integers</A></H3>
 963
 964 <P>
 965 <CODE>cl_I</CODE> objects are most easily constructed from C integers and from
 966 strings. See section <A HREF="cln.html#SEC15">3.4 Conversions</A>.
 967
 968
 969
 970
 971 <H3><A NAME="SEC19" HREF="cln.html#TOC19">4.1.2 Constructing rational numbers</A></H3>
 972
 973 <P>
 974 <CODE>cl_RA</CODE> objects can be constructed from strings. The syntax
 975 for rational numbers is described in section <A HREF="cln.html#SEC45">5.1 Internal and printed representation</A>.
 976 Another standard way to produce a rational number is through application
 977 of <SAMP>`operator /'</SAMP> or <SAMP>`recip'</SAMP> on integers.
 978
 979
 980
 981
 982 <H3><A NAME="SEC20" HREF="cln.html#TOC20">4.1.3 Constructing floating-point numbers</A></H3>
 983
 984 <P>
 985 <CODE>cl_F</CODE> objects with low precision are most easily constructed from
 986 C <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP>. See section <A HREF="cln.html#SEC15">3.4 Conversions</A>.
 987
 988
 989 <P>
 990 To construct a <CODE>cl_F</CODE> with high precision, you can use the conversion
 991 from <SAMP>`const char *'</SAMP>, but you have to specify the desired precision
 992 within the string. (See section <A HREF="cln.html#SEC45">5.1 Internal and printed representation</A>.)
 993 Example:
 994
 995 <PRE>
 996    cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
 997 </PRE>
 998
 999 <P>
1000 will set <SAMP>`e'</SAMP> to the given value, with a precision of 40 decimal digits.
1001
1002
1003 <P>
1004 The programmatic way to construct a <CODE>cl_F</CODE> with high precision is
1005 through the <CODE>cl_float</CODE> conversion function, see
1006 section <A HREF="cln.html#SEC40">4.11.1 Conversion to floating-point numbers</A>. For example, to compute
1007 <CODE>e</CODE> to 40 decimal places, first construct 1.0 to 40 decimal places
1008 and then apply the exponential function:
1009
1010 <PRE>
1011    cl_float_format_t precision = cl_float_format(40);
1012    cl_F e = exp(cl_float(1,precision));
1013 </PRE>
1014
1015
1016
1017 <H3><A NAME="SEC21" HREF="cln.html#TOC21">4.1.4 Constructing complex numbers</A></H3>
1018
1019 <P>
1020 Non-real <CODE>cl_N</CODE> objects are normally constructed through the function
1021
1022 <PRE>
1023    cl_N complex (const cl_R&#38; realpart, const cl_R&#38; imagpart)
1024 </PRE>
1025
1026 <P>
1027 See section <A HREF="cln.html#SEC24">4.4 Elementary complex functions</A>.
1028
1029
1030
1031
1032 <H2><A NAME="SEC22" HREF="cln.html#TOC22">4.2 Elementary functions</A></H2>
1033
1034 <P>
1035 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1036 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1037 defines the following operations:
1038
1039
1040 <DL COMPACT>
1041
1042 <DT><CODE><VAR>type</VAR> operator + (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1043 <DD>
1044 <A NAME="IDX36"></A>
1045 Addition.
1046
1047 <DT><CODE><VAR>type</VAR> operator - (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1048 <DD>
1049 <A NAME="IDX37"></A>
1050 Subtraction.
1051
1052 <DT><CODE><VAR>type</VAR> operator - (const <VAR>type</VAR>&#38;)</CODE>
1053 <DD>
1054 Returns the negative of the argument.
1055
1056 <DT><CODE><VAR>type</VAR> plus1 (const <VAR>type</VAR>&#38; x)</CODE>
1057 <DD>
1058 <A NAME="IDX38"></A>
1059 Returns <CODE>x + 1</CODE>.
1060
1061 <DT><CODE><VAR>type</VAR> minus1 (const <VAR>type</VAR>&#38; x)</CODE>
1062 <DD>
1063 <A NAME="IDX39"></A>
1064 Returns <CODE>x - 1</CODE>.
1065
1066 <DT><CODE><VAR>type</VAR> operator * (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1067 <DD>
1068 <A NAME="IDX40"></A>
1069 Multiplication.
1070
1071 <DT><CODE><VAR>type</VAR> square (const <VAR>type</VAR>&#38; x)</CODE>
1072 <DD>
1073 <A NAME="IDX41"></A>
1074 Returns <CODE>x * x</CODE>.
1075 </DL>
1076
1077 <P>
1078 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
1079 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1080 defines the following operations:
1081
1082
1083 <DL COMPACT>
1084
1085 <DT><CODE><VAR>type</VAR> operator / (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1086 <DD>
1087 <A NAME="IDX42"></A>
1088 Division.
1089
1090 <DT><CODE><VAR>type</VAR> recip (const <VAR>type</VAR>&#38;)</CODE>
1091 <DD>
1092 <A NAME="IDX43"></A>
1093 Returns the reciprocal of the argument.
1094 </DL>
1095
1096 <P>
1097 The class <CODE>cl_I</CODE> doesn't define a <SAMP>`/'</SAMP> operation because
1098 in the C/C++ language this operator, applied to integral types,
1099 denotes the <SAMP>`floor'</SAMP> or <SAMP>`truncate'</SAMP> operation (which one of these,
1100 is implementation dependent). (See section <A HREF="cln.html#SEC26">4.6 Rounding functions</A>.)
1101 Instead, <CODE>cl_I</CODE> defines an "exact quotient" function:
1102
1103
1104 <DL COMPACT>
1105
1106 <DT><CODE>cl_I exquo (const cl_I&#38; x, const cl_I&#38; y)</CODE>
1107 <DD>
1108 <A NAME="IDX44"></A>
1109 Checks that <CODE>y</CODE> divides <CODE>x</CODE>, and returns the quotient <CODE>x</CODE>/<CODE>y</CODE>.
1110 </DL>
1111
1112 <P>
1113 The following exponentiation functions are defined:
1114
1115
1116 <DL COMPACT>
1117
1118 <DT><CODE>cl_I expt_pos (const cl_I&#38; x, const cl_I&#38; y)</CODE>
1119 <DD>
1120 <A NAME="IDX45"></A>
1121 <DT><CODE>cl_RA expt_pos (const cl_RA&#38; x, const cl_I&#38; y)</CODE>
1122 <DD>
1123 <CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.
1124
1125 <DT><CODE>cl_RA expt (const cl_RA&#38; x, const cl_I&#38; y)</CODE>
1126 <DD>
1127 <A NAME="IDX46"></A>
1128 <DT><CODE>cl_R expt (const cl_R&#38; x, const cl_I&#38; y)</CODE>
1129 <DD>
1130 <DT><CODE>cl_N expt (const cl_N&#38; x, const cl_I&#38; y)</CODE>
1131 <DD>
1132 Returns <CODE>x^y</CODE>.
1133 </DL>
1134
1135 <P>
1136 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1137 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1138 defines the following operation:
1139
1140
1141 <DL COMPACT>
1142
1143 <DT><CODE><VAR>type</VAR> abs (const <VAR>type</VAR>&#38; x)</CODE>
1144 <DD>
1145 <A NAME="IDX47"></A>
1146 Returns the absolute value of <CODE>x</CODE>.
1147 This is <CODE>x</CODE> if <CODE>x &#62;= 0</CODE>, and <CODE>-x</CODE> if <CODE>x &#60;= 0</CODE>.
1148 </DL>
1149
1150 <P>
1151 The class <CODE>cl_N</CODE> implements this as follows:
1152
1153
1154 <DL COMPACT>
1155
1156 <DT><CODE>cl_R abs (const cl_N x)</CODE>
1157 <DD>
1158 Returns the absolute value of <CODE>x</CODE>.
1159 </DL>
1160
1161 <P>
1162 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1163 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1164 defines the following operation:
1165
1166
1167 <DL COMPACT>
1168
1169 <DT><CODE><VAR>type</VAR> signum (const <VAR>type</VAR>&#38; x)</CODE>
1170 <DD>
1171 <A NAME="IDX48"></A>
1172 Returns the sign of <CODE>x</CODE>, in the same number format as <CODE>x</CODE>.
1173 This is defined as <CODE>x / abs(x)</CODE> if <CODE>x</CODE> is non-zero, and
1174 <CODE>x</CODE> if <CODE>x</CODE> is zero. If <CODE>x</CODE> is real, the value is either
1175 0 or 1 or -1.
1176 </DL>
1177
1178
1179
1180 <H2><A NAME="SEC23" HREF="cln.html#TOC23">4.3 Elementary rational functions</A></H2>
1181
1182 <P>
1183 Each of the classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE> defines the following operations:
1184
1185
1186 <DL COMPACT>
1187
1188 <DT><CODE>cl_I numerator (const <VAR>type</VAR>&#38; x)</CODE>
1189 <DD>
1190 <A NAME="IDX49"></A>
1191 Returns the numerator of <CODE>x</CODE>.
1192
1193 <DT><CODE>cl_I denominator (const <VAR>type</VAR>&#38; x)</CODE>
1194 <DD>
1195 <A NAME="IDX50"></A>
1196 Returns the denominator of <CODE>x</CODE>.
1197 </DL>
1198
1199 <P>
1200 The numerator and denominator of a rational number are normalized in such
1201 a way that they have no factor in common and the denominator is positive.
1202
1203
1204
1205
1206 <H2><A NAME="SEC24" HREF="cln.html#TOC24">4.4 Elementary complex functions</A></H2>
1207
1208 <P>
1209 The class <CODE>cl_N</CODE> defines the following operation:
1210
1211
1212 <DL COMPACT>
1213
1214 <DT><CODE>cl_N complex (const cl_R&#38; a, const cl_R&#38; b)</CODE>
1215 <DD>
1216 <A NAME="IDX51"></A>
1217 Returns the complex number <CODE>a+bi</CODE>, that is, the complex number with
1218 real part <CODE>a</CODE> and imaginary part <CODE>b</CODE>.
1219 </DL>
1220
1221 <P>
1222 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE> defines the following operations:
1223
1224
1225 <DL COMPACT>
1226
1227 <DT><CODE>cl_R realpart (const <VAR>type</VAR>&#38; x)</CODE>
1228 <DD>
1229 <A NAME="IDX52"></A>
1230 Returns the real part of <CODE>x</CODE>.
1231
1232 <DT><CODE>cl_R imagpart (const <VAR>type</VAR>&#38; x)</CODE>
1233 <DD>
1234 <A NAME="IDX53"></A>
1235 Returns the imaginary part of <CODE>x</CODE>.
1236
1237 <DT><CODE><VAR>type</VAR> conjugate (const <VAR>type</VAR>&#38; x)</CODE>
1238 <DD>
1239 <A NAME="IDX54"></A>
1240 Returns the complex conjugate of <CODE>x</CODE>.
1241 </DL>
1242
1243 <P>
1244 We have the relations
1245
1246
1247
1248 <UL>
1249 <LI>
1250
1251 <CODE>x = complex(realpart(x), imagpart(x))</CODE>
1252 <LI>
1253
1254 <CODE>conjugate(x) = complex(realpart(x), -imagpart(x))</CODE>
1255 </UL>
1256
1257
1258
1259 <H2><A NAME="SEC25" HREF="cln.html#TOC25">4.5 Comparisons</A></H2>
1260 <P>
1261 <A NAME="IDX55"></A>
1262
1263
1264 <P>
1265 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1266 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1267 defines the following operations:
1268
1269
1270 <DL COMPACT>
1271
1272 <DT><CODE>bool operator == (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1273 <DD>
1274 <A NAME="IDX56"></A>
1275 <DT><CODE>bool operator != (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1276 <DD>
1277 <A NAME="IDX57"></A>
1278 Comparison, as in C and C++.
1279
1280 <DT><CODE>uint32 cl_equal_hashcode (const <VAR>type</VAR>&#38;)</CODE>
1281 <DD>
1282 <A NAME="IDX58"></A>
1283 Returns a 32-bit hash code that is the same for any two numbers which are
1284 the same according to <CODE>==</CODE>. This hash code depends on the number's value,
1285 not its type or precision.
1286
1287 <DT><CODE>cl_boolean zerop (const <VAR>type</VAR>&#38; x)</CODE>
1288 <DD>
1289 <A NAME="IDX59"></A>
1290 Compare against zero: <CODE>x == 0</CODE>
1291 </DL>
1292
1293 <P>
1294 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1295 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1296 defines the following operations:
1297
1298
1299 <DL COMPACT>
1300
1301 <DT><CODE>cl_signean cl_compare (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1302 <DD>
1303 <A NAME="IDX60"></A>
1304 Compares <CODE>x</CODE> and <CODE>y</CODE>. Returns +1 if <CODE>x</CODE>&#62;<CODE>y</CODE>,
1305 -1 if <CODE>x</CODE>&#60;<CODE>y</CODE>, 0 if <CODE>x</CODE>=<CODE>y</CODE>.
1306
1307 <DT><CODE>bool operator &#60;= (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1308 <DD>
1309 <A NAME="IDX61"></A>
1310 <DT><CODE>bool operator &#60; (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1311 <DD>
1312 <A NAME="IDX62"></A>
1313 <DT><CODE>bool operator &#62;= (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1314 <DD>
1315 <A NAME="IDX63"></A>
1316 <DT><CODE>bool operator &#62; (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
1317 <DD>
1318 <A NAME="IDX64"></A>
1319 Comparison, as in C and C++.
1320
1321 <DT><CODE>cl_boolean minusp (const <VAR>type</VAR>&#38; x)</CODE>
1322 <DD>
1323 <A NAME="IDX65"></A>
1324 Compare against zero: <CODE>x &#60; 0</CODE>
1325
1326 <DT><CODE>cl_boolean plusp (const <VAR>type</VAR>&#38; x)</CODE>
1327 <DD>
1328 <A NAME="IDX66"></A>
1329 Compare against zero: <CODE>x &#62; 0</CODE>
1330
1331 <DT><CODE><VAR>type</VAR> max (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1332 <DD>
1333 <A NAME="IDX67"></A>
1334 Return the maximum of <CODE>x</CODE> and <CODE>y</CODE>.
1335
1336 <DT><CODE><VAR>type</VAR> min (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1337 <DD>
1338 <A NAME="IDX68"></A>
1339 Return the minimum of <CODE>x</CODE> and <CODE>y</CODE>.
1340 </DL>
1341
1342 <P>
1343 When a floating point number and a rational number are compared, the float
1344 is first converted to a rational number using the function <CODE>rational</CODE>.
1345 Since a floating point number actually represents an interval of real numbers,
1346 the result might be surprising.
1347 For example, <CODE>(cl_F)(cl_R)"1/3" == (cl_R)"1/3"</CODE> returns false because
1348 there is no floating point number whose value is exactly <CODE>1/3</CODE>.
1349
1350
1351
1352
1353 <H2><A NAME="SEC26" HREF="cln.html#TOC26">4.6 Rounding functions</A></H2>
1354 <P>
1355 <A NAME="IDX69"></A>
1356
1357
1358 <P>
1359 When a real number is to be converted to an integer, there is no "best"
1360 rounding. The desired rounding function depends on the application.
1361 The Common Lisp and ISO Lisp standards offer four rounding functions:
1362
1363
1364 <DL COMPACT>
1365
1366 <DT><CODE>floor(x)</CODE>
1367 <DD>
1368 This is the largest integer &#60;=<CODE>x</CODE>.
1369
1370 <DT><CODE>ceiling(x)</CODE>
1371 <DD>
1372 This is the smallest integer &#62;=<CODE>x</CODE>.
1373
1374 <DT><CODE>truncate(x)</CODE>
1375 <DD>
1376 Among the integers between 0 and <CODE>x</CODE> (inclusive) the one nearest to <CODE>x</CODE>.
1377
1378 <DT><CODE>round(x)</CODE>
1379 <DD>
1380 The integer nearest to <CODE>x</CODE>. If <CODE>x</CODE> is exactly halfway between two
1381 integers, choose the even one.
1382 </DL>
1383
1384 <P>
1385 These functions have different advantages:
1386
1387
1388 <P>
1389 <CODE>floor</CODE> and <CODE>ceiling</CODE> are translation invariant:
1390 <CODE>floor(x+n) = floor(x) + n</CODE> and <CODE>ceiling(x+n) = ceiling(x) + n</CODE>
1391 for every <CODE>x</CODE> and every integer <CODE>n</CODE>.
1392
1393
1394 <P>
1395 On the other hand, <CODE>truncate</CODE> and <CODE>round</CODE> are symmetric:
1396 <CODE>truncate(-x) = -truncate(x)</CODE> and <CODE>round(-x) = -round(x)</CODE>,
1397 and furthermore <CODE>round</CODE> is unbiased: on the "average", it rounds
1398 down exactly as often as it rounds up.
1399
1400
1401 <P>
1402 The functions are related like this:
1403
1404
1405
1406 <UL>
1407 <LI>
1408
1409 <CODE>ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1</CODE>
1410 for rational numbers <CODE>m/n</CODE> (<CODE>m</CODE>, <CODE>n</CODE> integers, <CODE>n</CODE>&#62;0), and
1411 <LI>
1412
1413 <CODE>truncate(x) = sign(x) * floor(abs(x))</CODE>
1414 </UL>
1415
1416 <P>
1417 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
1418 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1419 defines the following operations:
1420
1421
1422 <DL COMPACT>
1423
1424 <DT><CODE>cl_I floor1 (const <VAR>type</VAR>&#38; x)</CODE>
1425 <DD>
1426 <A NAME="IDX70"></A>
1427 Returns <CODE>floor(x)</CODE>.
1428 <DT><CODE>cl_I ceiling1 (const <VAR>type</VAR>&#38; x)</CODE>
1429 <DD>
1430 <A NAME="IDX71"></A>
1431 Returns <CODE>ceiling(x)</CODE>.
1432 <DT><CODE>cl_I truncate1 (const <VAR>type</VAR>&#38; x)</CODE>
1433 <DD>
1434 <A NAME="IDX72"></A>
1435 Returns <CODE>truncate(x)</CODE>.
1436 <DT><CODE>cl_I round1 (const <VAR>type</VAR>&#38; x)</CODE>
1437 <DD>
1438 <A NAME="IDX73"></A>
1439 Returns <CODE>round(x)</CODE>.
1440 </DL>
1441
1442 <P>
1443 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1444 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1445 defines the following operations:
1446
1447
1448 <DL COMPACT>
1449
1450 <DT><CODE>cl_I floor1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1451 <DD>
1452 Returns <CODE>floor(x/y)</CODE>.
1453 <DT><CODE>cl_I ceiling1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1454 <DD>
1455 Returns <CODE>ceiling(x/y)</CODE>.
1456 <DT><CODE>cl_I truncate1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1457 <DD>
1458 Returns <CODE>truncate(x/y)</CODE>.
1459 <DT><CODE>cl_I round1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1460 <DD>
1461 Returns <CODE>round(x/y)</CODE>.
1462 </DL>
1463
1464 <P>
1465 These functions are called <SAMP>`floor1'</SAMP>, ... here instead of
1466 <SAMP>`floor'</SAMP>, ..., because on some systems, system dependent include
1467 files define <SAMP>`floor'</SAMP> and <SAMP>`ceiling'</SAMP> as macros.
1468
1469
1470 <P>
1471 In many cases, one needs both the quotient and the remainder of a division.
1472 It is more efficient to compute both at the same time than to perform
1473 two divisions, one for quotient and the next one for the remainder.
1474 The following functions therefore return a structure containing both
1475 the quotient and the remainder. The suffix <SAMP>`2'</SAMP> indicates the number
1476 of "return values". The remainder is defined as follows:
1477
1478
1479
1480 <UL>
1481 <LI>
1482
1483 for the computation of <CODE>quotient = floor(x)</CODE>,
1484 <CODE>remainder = x - quotient</CODE>,
1485 <LI>
1486
1487 for the computation of <CODE>quotient = floor(x,y)</CODE>,
1488 <CODE>remainder = x - quotient*y</CODE>,
1489 </UL>
1490
1491 <P>
1492 and similarly for the other three operations.
1493
1494
1495 <P>
1496 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
1497 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1498 defines the following operations:
1499
1500
1501 <DL COMPACT>
1502
1503 <DT><CODE>struct <VAR>type</VAR>_div_t { cl_I quotient; <VAR>type</VAR> remainder; };</CODE>
1504 <DD>
1505 <DT><CODE><VAR>type</VAR>_div_t floor2 (const <VAR>type</VAR>&#38; x)</CODE>
1506 <DD>
1507 <DT><CODE><VAR>type</VAR>_div_t ceiling2 (const <VAR>type</VAR>&#38; x)</CODE>
1508 <DD>
1509 <DT><CODE><VAR>type</VAR>_div_t truncate2 (const <VAR>type</VAR>&#38; x)</CODE>
1510 <DD>
1511 <DT><CODE><VAR>type</VAR>_div_t round2 (const <VAR>type</VAR>&#38; x)</CODE>
1512 <DD>
1513 </DL>
1514
1515 <P>
1516 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
1517 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1518 defines the following operations:
1519
1520
1521 <DL COMPACT>
1522
1523 <DT><CODE>struct <VAR>type</VAR>_div_t { cl_I quotient; <VAR>type</VAR> remainder; };</CODE>
1524 <DD>
1525 <DT><CODE><VAR>type</VAR>_div_t floor2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1526 <DD>
1527 <A NAME="IDX74"></A>
1528 <DT><CODE><VAR>type</VAR>_div_t ceiling2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1529 <DD>
1530 <A NAME="IDX75"></A>
1531 <DT><CODE><VAR>type</VAR>_div_t truncate2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1532 <DD>
1533 <A NAME="IDX76"></A>
1534 <DT><CODE><VAR>type</VAR>_div_t round2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1535 <DD>
1536 <A NAME="IDX77"></A>
1537 </DL>
1538
1539 <P>
1540 Sometimes, one wants the quotient as a floating-point number (of the
1541 same format as the argument, if the argument is a float) instead of as
1542 an integer. The prefix <SAMP>`f'</SAMP> indicates this.
1543
1544
1545 <P>
1546 Each of the classes
1547 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1548 defines the following operations:
1549
1550
1551 <DL COMPACT>
1552
1553 <DT><CODE><VAR>type</VAR> ffloor (const <VAR>type</VAR>&#38; x)</CODE>
1554 <DD>
1555 <A NAME="IDX78"></A>
1556 <DT><CODE><VAR>type</VAR> fceiling (const <VAR>type</VAR>&#38; x)</CODE>
1557 <DD>
1558 <A NAME="IDX79"></A>
1559 <DT><CODE><VAR>type</VAR> ftruncate (const <VAR>type</VAR>&#38; x)</CODE>
1560 <DD>
1561 <A NAME="IDX80"></A>
1562 <DT><CODE><VAR>type</VAR> fround (const <VAR>type</VAR>&#38; x)</CODE>
1563 <DD>
1564 <A NAME="IDX81"></A>
1565 </DL>
1566
1567 <P>
1568 and similarly for class <CODE>cl_R</CODE>, but with return type <CODE>cl_F</CODE>.
1569
1570
1571 <P>
1572 The class <CODE>cl_R</CODE> defines the following operations:
1573
1574
1575 <DL COMPACT>
1576
1577 <DT><CODE>cl_F ffloor (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1578 <DD>
1579 <DT><CODE>cl_F fceiling (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1580 <DD>
1581 <DT><CODE>cl_F ftruncate (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1582 <DD>
1583 <DT><CODE>cl_F fround (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1584 <DD>
1585 </DL>
1586
1587 <P>
1588 These functions also exist in versions which return both the quotient
1589 and the remainder. The suffix <SAMP>`2'</SAMP> indicates this.
1590
1591
1592 <P>
1593 Each of the classes
1594 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1595 defines the following operations:
1596 <A NAME="IDX82"></A>
1597 <A NAME="IDX83"></A>
1598 <A NAME="IDX84"></A>
1599 <A NAME="IDX85"></A>
1600 <A NAME="IDX86"></A>
1601
1602
1603 <DL COMPACT>
1604
1605 <DT><CODE>struct <VAR>type</VAR>_fdiv_t { <VAR>type</VAR> quotient; <VAR>type</VAR> remainder; };</CODE>
1606 <DD>
1607 <DT><CODE><VAR>type</VAR>_fdiv_t ffloor2 (const <VAR>type</VAR>&#38; x)</CODE>
1608 <DD>
1609 <A NAME="IDX87"></A>
1610 <DT><CODE><VAR>type</VAR>_fdiv_t fceiling2 (const <VAR>type</VAR>&#38; x)</CODE>
1611 <DD>
1612 <A NAME="IDX88"></A>
1613 <DT><CODE><VAR>type</VAR>_fdiv_t ftruncate2 (const <VAR>type</VAR>&#38; x)</CODE>
1614 <DD>
1615 <A NAME="IDX89"></A>
1616 <DT><CODE><VAR>type</VAR>_fdiv_t fround2 (const <VAR>type</VAR>&#38; x)</CODE>
1617 <DD>
1618 <A NAME="IDX90"></A>
1619 </DL>
1620 <P>
1621 and similarly for class <CODE>cl_R</CODE>, but with quotient type <CODE>cl_F</CODE>.
1622 <A NAME="IDX91"></A>
1623
1624
1625 <P>
1626 The class <CODE>cl_R</CODE> defines the following operations:
1627
1628
1629 <DL COMPACT>
1630
1631 <DT><CODE>struct <VAR>type</VAR>_fdiv_t { cl_F quotient; cl_R remainder; };</CODE>
1632 <DD>
1633 <DT><CODE><VAR>type</VAR>_fdiv_t ffloor2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1634 <DD>
1635 <DT><CODE><VAR>type</VAR>_fdiv_t fceiling2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1636 <DD>
1637 <DT><CODE><VAR>type</VAR>_fdiv_t ftruncate2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1638 <DD>
1639 <DT><CODE><VAR>type</VAR>_fdiv_t fround2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1640 <DD>
1641 </DL>
1642
1643 <P>
1644 Other applications need only the remainder of a division.
1645 The remainder of <SAMP>`floor'</SAMP> and <SAMP>`ffloor'</SAMP> is called <SAMP>`mod'</SAMP>
1646 (abbreviation of "modulo"). The remainder <SAMP>`truncate'</SAMP> and
1647 <SAMP>`ftruncate'</SAMP> is called <SAMP>`rem'</SAMP> (abbreviation of "remainder").
1648
1649
1650
1651 <UL>
1652 <LI>
1653
1654 <CODE>mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y</CODE>
1655 <LI>
1656
1657 <CODE>rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y</CODE>
1658 </UL>
1659
1660 <P>
1661 If <CODE>x</CODE> and <CODE>y</CODE> are both &#62;= 0, <CODE>mod(x,y) = rem(x,y) &#62;= 0</CODE>.
1662 In general, <CODE>mod(x,y)</CODE> has the sign of <CODE>y</CODE> or is zero,
1663 and <CODE>rem(x,y)</CODE> has the sign of <CODE>x</CODE> or is zero.
1664
1665
1666 <P>
1667 The classes <CODE>cl_R</CODE>, <CODE>cl_I</CODE> define the following operations:
1668
1669
1670 <DL COMPACT>
1671
1672 <DT><CODE><VAR>type</VAR> mod (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1673 <DD>
1674 <A NAME="IDX92"></A>
1675 <DT><CODE><VAR>type</VAR> rem (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
1676 <DD>
1677 <A NAME="IDX93"></A>
1678 </DL>
1679
1680
1681
1682 <H2><A NAME="SEC27" HREF="cln.html#TOC27">4.7 Roots</A></H2>
1683
1684 <P>
1685 Each of the classes <CODE>cl_R</CODE>,
1686 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
1687 defines the following operation:
1688
1689
1690 <DL COMPACT>
1691
1692 <DT><CODE><VAR>type</VAR> sqrt (const <VAR>type</VAR>&#38; x)</CODE>
1693 <DD>
1694 <A NAME="IDX94"></A>
1695 <CODE>x</CODE> must be &#62;= 0. This function returns the square root of <CODE>x</CODE>,
1696 normalized to be &#62;= 0. If <CODE>x</CODE> is the square of a rational number,
1697 <CODE>sqrt(x)</CODE> will be a rational number, else it will return a
1698 floating-point approximation.
1699 </DL>
1700
1701 <P>
1702 The classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE> define the following operation:
1703
1704
1705 <DL COMPACT>
1706
1707 <DT><CODE>cl_boolean sqrtp (const <VAR>type</VAR>&#38; x, <VAR>type</VAR>* root)</CODE>
1708 <DD>
1709 <A NAME="IDX95"></A>
1710 This tests whether <CODE>x</CODE> is a perfect square. If so, it returns true
1711 and the exact square root in <CODE>*root</CODE>, else it returns false.
1712 </DL>
1713
1714 <P>
1715 Furthermore, for integers, similarly:
1716
1717
1718 <DL COMPACT>
1719
1720 <DT><CODE>cl_boolean isqrt (const <VAR>type</VAR>&#38; x, <VAR>type</VAR>* root)</CODE>
1721 <DD>
1722 <A NAME="IDX96"></A>
1723 <CODE>x</CODE> should be &#62;= 0. This function sets <CODE>*root</CODE> to
1724 <CODE>floor(sqrt(x))</CODE> and returns the same value as <CODE>sqrtp</CODE>:
1725 the boolean value <CODE>(expt(*root,2) == x)</CODE>.
1726 </DL>
1727
1728 <P>
1729 For <CODE>n</CODE>th roots, the classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>
1730 define the following operation:
1731
1732
1733 <DL COMPACT>
1734
1735 <DT><CODE>cl_boolean rootp (const <VAR>type</VAR>&#38; x, const cl_I&#38; n, <VAR>type</VAR>* root)</CODE>
1736 <DD>
1737 <A NAME="IDX97"></A>
1738 <CODE>x</CODE> must be &#62;= 0. <CODE>n</CODE> must be &#62; 0.
1739 This tests whether <CODE>x</CODE> is an <CODE>n</CODE>th power of a rational number.
1740 If so, it returns true and the exact root in <CODE>*root</CODE>, else it returns
1741 false.
1742 </DL>
1743
1744 <P>
1745 The only square root function which accepts negative numbers is the one
1746 for class <CODE>cl_N</CODE>:
1747
1748
1749 <DL COMPACT>
1750
1751 <DT><CODE>cl_N sqrt (const cl_N&#38; z)</CODE>
1752 <DD>
1753 <A NAME="IDX98"></A>
1754 Returns the square root of <CODE>z</CODE>, as defined by the formula
1755 <CODE>sqrt(z) = exp(log(z)/2)</CODE>. Conversion to a floating-point type
1756 or to a complex number are done if necessary. The range of the result is the
1757 right half plane <CODE>realpart(sqrt(z)) &#62;= 0</CODE>
1758 including the positive imaginary axis and 0, but excluding
1759 the negative imaginary axis.
1760 The result is an exact number only if <CODE>z</CODE> is an exact number.
1761 </DL>
1762
1763
1764
1765 <H2><A NAME="SEC28" HREF="cln.html#TOC28">4.8 Transcendental functions</A></H2>
1766 <P>
1767 <A NAME="IDX99"></A>
1768
1769
1770 <P>
1771 The transcendental functions return an exact result if the argument
1772 is exact and the result is exact as well. Otherwise they must return
1773 inexact numbers even if the argument is exact.
1774 For example, <CODE>cos(0) = 1</CODE> returns the rational number <CODE>1</CODE>.
1775
1776
1777
1778
1779 <H3><A NAME="SEC29" HREF="cln.html#TOC29">4.8.1 Exponential and logarithmic functions</A></H3>
1780
1781 <DL COMPACT>
1782
1783 <DT><CODE>cl_R exp (const cl_R&#38; x)</CODE>
1784 <DD>
1785 <A NAME="IDX100"></A>
1786 <DT><CODE>cl_N exp (const cl_N&#38; x)</CODE>
1787 <DD>
1788 Returns the exponential function of <CODE>x</CODE>. This is <CODE>e^x</CODE> where
1789 <CODE>e</CODE> is the base of the natural logarithms. The range of the result
1790 is the entire complex plane excluding 0.
1791
1792 <DT><CODE>cl_R ln (const cl_R&#38; x)</CODE>
1793 <DD>
1794 <A NAME="IDX101"></A>
1795 <CODE>x</CODE> must be &#62; 0. Returns the (natural) logarithm of x.
1796
1797 <DT><CODE>cl_N log (const cl_N&#38; x)</CODE>
1798 <DD>
1799 <A NAME="IDX102"></A>
1800 Returns the (natural) logarithm of x. If <CODE>x</CODE> is real and positive,
1801 this is <CODE>ln(x)</CODE>. In general, <CODE>log(x) = log(abs(x)) + i*phase(x)</CODE>.
1802 The range of the result is the strip in the complex plane
1803 <CODE>-pi &#60; imagpart(log(x)) &#60;= pi</CODE>.
1804
1805 <DT><CODE>cl_R phase (const cl_N&#38; x)</CODE>
1806 <DD>
1807 <A NAME="IDX103"></A>
1808 Returns the angle part of <CODE>x</CODE> in its polar representation as a
1809 complex number. That is, <CODE>phase(x) = atan(realpart(x),imagpart(x))</CODE>.
1810 This is also the imaginary part of <CODE>log(x)</CODE>.
1811 The range of the result is the interval <CODE>-pi &#60; phase(x) &#60;= pi</CODE>.
1812 The result will be an exact number only if <CODE>zerop(x)</CODE> or
1813 if <CODE>x</CODE> is real and positive.
1814
1815 <DT><CODE>cl_R log (const cl_R&#38; a, const cl_R&#38; b)</CODE>
1816 <DD>
1817 <CODE>a</CODE> and <CODE>b</CODE> must be &#62; 0. Returns the logarithm of <CODE>a</CODE> with
1818 respect to base <CODE>b</CODE>. <CODE>log(a,b) = ln(a)/ln(b)</CODE>.
1819 The result can be exact only if <CODE>a = 1</CODE> or if <CODE>a</CODE> and <CODE>b</CODE>
1820 are both rational.
1821
1822 <DT><CODE>cl_N log (const cl_N&#38; a, const cl_N&#38; b)</CODE>
1823 <DD>
1824 Returns the logarithm of <CODE>a</CODE> with respect to base <CODE>b</CODE>.
1825 <CODE>log(a,b) = log(a)/log(b)</CODE>.
1826
1827 <DT><CODE>cl_N expt (const cl_N&#38; x, const cl_N&#38; y)</CODE>
1828 <DD>
1829 <A NAME="IDX104"></A>
1830 Exponentiation: Returns <CODE>x^y = exp(y*log(x))</CODE>.
1831 </DL>
1832
1833 <P>
1834 The constant e = exp(1) = 2.71828... is returned by the following functions:
1835
1836
1837 <DL COMPACT>
1838
1839 <DT><CODE>cl_F cl_exp1 (cl_float_format_t f)</CODE>
1840 <DD>
1841 <A NAME="IDX105"></A>
1842 Returns e as a float of format <CODE>f</CODE>.
1843
1844 <DT><CODE>cl_F cl_exp1 (const cl_F&#38; y)</CODE>
1845 <DD>
1846 Returns e in the float format of <CODE>y</CODE>.
1847
1848 <DT><CODE>cl_F cl_exp1 (void)</CODE>
1849 <DD>
1850 Returns e as a float of format <CODE>cl_default_float_format</CODE>.
1851 </DL>
1852
1853
1854
1855 <H3><A NAME="SEC30" HREF="cln.html#TOC30">4.8.2 Trigonometric functions</A></H3>
1856
1857 <DL COMPACT>
1858
1859 <DT><CODE>cl_R sin (const cl_R&#38; x)</CODE>
1860 <DD>
1861 <A NAME="IDX106"></A>
1862 Returns <CODE>sin(x)</CODE>. The range of the result is the interval
1863 <CODE>-1 &#60;= sin(x) &#60;= 1</CODE>.
1864
1865 <DT><CODE>cl_N sin (const cl_N&#38; z)</CODE>
1866 <DD>
1867 Returns <CODE>sin(z)</CODE>. The range of the result is the entire complex plane.
1868
1869 <DT><CODE>cl_R cos (const cl_R&#38; x)</CODE>
1870 <DD>
1871 <A NAME="IDX107"></A>
1872 Returns <CODE>cos(x)</CODE>. The range of the result is the interval
1873 <CODE>-1 &#60;= cos(x) &#60;= 1</CODE>.
1874
1875 <DT><CODE>cl_N cos (const cl_N&#38; x)</CODE>
1876 <DD>
1877 Returns <CODE>cos(z)</CODE>. The range of the result is the entire complex plane.
1878
1879 <DT><CODE>struct cl_cos_sin_t { cl_R cos; cl_R sin; };</CODE>
1880 <DD>
1881 <A NAME="IDX108"></A>
1882 <DT><CODE>cl_cos_sin_t cl_cos_sin (const cl_R&#38; x)</CODE>
1883 <DD>
1884 Returns both <CODE>sin(x)</CODE> and <CODE>cos(x)</CODE>. This is more efficient than
1885 <A NAME="IDX109"></A>
1886 computing them separately. The relation <CODE>cos^2 + sin^2 = 1</CODE> will
1887 hold only approximately.
1888
1889 <DT><CODE>cl_R tan (const cl_R&#38; x)</CODE>
1890 <DD>
1891 <A NAME="IDX110"></A>
1892 <DT><CODE>cl_N tan (const cl_N&#38; x)</CODE>
1893 <DD>
1894 Returns <CODE>tan(x) = sin(x)/cos(x)</CODE>.
1895
1896 <DT><CODE>cl_N cis (const cl_R&#38; x)</CODE>
1897 <DD>
1898 <A NAME="IDX111"></A>
1899 <DT><CODE>cl_N cis (const cl_N&#38; x)</CODE>
1900 <DD>
1901 Returns <CODE>exp(i*x)</CODE>. The name <SAMP>`cis'</SAMP> means "cos + i sin", because
1902 <CODE>e^(i*x) = cos(x) + i*sin(x)</CODE>.
1903
1904 <A NAME="IDX112"></A>
1905 <A NAME="IDX113"></A>
1906 <DT><CODE>cl_N asin (const cl_N&#38; z)</CODE>
1907 <DD>
1908 Returns <CODE>arcsin(z)</CODE>. This is defined as
1909 <CODE>arcsin(z) = log(iz+sqrt(1-z^2))/i</CODE> and satisfies
1910 <CODE>arcsin(-z) = -arcsin(z)</CODE>.
1911 The range of the result is the strip in the complex domain
1912 <CODE>-pi/2 &#60;= realpart(arcsin(z)) &#60;= pi/2</CODE>, excluding the numbers
1913 with <CODE>realpart = -pi/2</CODE> and <CODE>imagpart &#60; 0</CODE> and the numbers
1914 with <CODE>realpart = pi/2</CODE> and <CODE>imagpart &#62; 0</CODE>.
1915
1916 <DT><CODE>cl_N acos (const cl_N&#38; z)</CODE>
1917 <DD>
1918 <A NAME="IDX114"></A>
1919 Returns <CODE>arccos(z)</CODE>. This is defined as
1920 <CODE>arccos(z) = pi/2 - arcsin(z) = log(z+i*sqrt(1-z^2))/i</CODE>
1921 and satisfies <CODE>arccos(-z) = pi - arccos(z)</CODE>.
1922 The range of the result is the strip in the complex domain
1923 <CODE>0 &#60;= realpart(arcsin(z)) &#60;= pi</CODE>, excluding the numbers
1924 with <CODE>realpart = 0</CODE> and <CODE>imagpart &#60; 0</CODE> and the numbers
1925 with <CODE>realpart = pi</CODE> and <CODE>imagpart &#62; 0</CODE>.
1926
1927 <A NAME="IDX115"></A>
1928 <A NAME="IDX116"></A>
1929 <DT><CODE>cl_R atan (const cl_R&#38; x, const cl_R&#38; y)</CODE>
1930 <DD>
1931 Returns the angle of the polar representation of the complex number
1932 <CODE>x+iy</CODE>. This is <CODE>atan(y/x)</CODE> if <CODE>x&#62;0</CODE>. The range of
1933 the result is the interval <CODE>-pi &#60; atan(x,y) &#60;= pi</CODE>. The result will
1934 be an exact number only if <CODE>x &#62; 0</CODE> and <CODE>y</CODE> is the exact <CODE>0</CODE>.
1935 WARNING: In Common Lisp, this function is called as <CODE>(atan y x)</CODE>,
1936 with reversed order of arguments.
1937
1938 <DT><CODE>cl_R atan (const cl_R&#38; x)</CODE>
1939 <DD>
1940 Returns <CODE>arctan(x)</CODE>. This is the same as <CODE>atan(1,x)</CODE>. The range
1941 of the result is the interval <CODE>-pi/2 &#60; atan(x) &#60; pi/2</CODE>. The result
1942 will be an exact number only if <CODE>x</CODE> is the exact <CODE>0</CODE>.
1943
1944 <DT><CODE>cl_N atan (const cl_N&#38; z)</CODE>
1945 <DD>
1946 Returns <CODE>arctan(z)</CODE>. This is defined as
1947 <CODE>arctan(z) = (log(1+iz)-log(1-iz)) / 2i</CODE> and satisfies
1948 <CODE>arctan(-z) = -arctan(z)</CODE>. The range of the result is
1949 the strip in the complex domain
1950 <CODE>-pi/2 &#60;= realpart(arctan(z)) &#60;= pi/2</CODE>, excluding the numbers
1951 with <CODE>realpart = -pi/2</CODE> and <CODE>imagpart &#62;= 0</CODE> and the numbers
1952 with <CODE>realpart = pi/2</CODE> and <CODE>imagpart &#60;= 0</CODE>.
1953
1954 </DL>
1955
1956 <P>
1957 <A NAME="IDX117"></A>
1958 <A NAME="IDX118"></A>
1959 Archimedes' constant pi = 3.14... is returned by the following functions:
1960
1961
1962 <DL COMPACT>
1963
1964 <DT><CODE>cl_F cl_pi (cl_float_format_t f)</CODE>
1965 <DD>
1966 <A NAME="IDX119"></A>
1967 Returns pi as a float of format <CODE>f</CODE>.
1968
1969 <DT><CODE>cl_F cl_pi (const cl_F&#38; y)</CODE>
1970 <DD>
1971 Returns pi in the float format of <CODE>y</CODE>.
1972
1973 <DT><CODE>cl_F cl_pi (void)</CODE>
1974 <DD>
1975 Returns pi as a float of format <CODE>cl_default_float_format</CODE>.
1976 </DL>
1977
1978
1979
1980 <H3><A NAME="SEC31" HREF="cln.html#TOC31">4.8.3 Hyperbolic functions</A></H3>
1981
1982 <DL COMPACT>
1983
1984 <DT><CODE>cl_R sinh (const cl_R&#38; x)</CODE>
1985 <DD>
1986 <A NAME="IDX120"></A>
1987 Returns <CODE>sinh(x)</CODE>.
1988
1989 <DT><CODE>cl_N sinh (const cl_N&#38; z)</CODE>
1990 <DD>
1991 Returns <CODE>sinh(z)</CODE>. The range of the result is the entire complex plane.
1992
1993 <DT><CODE>cl_R cosh (const cl_R&#38; x)</CODE>
1994 <DD>
1995 <A NAME="IDX121"></A>
1996 Returns <CODE>cosh(x)</CODE>. The range of the result is the interval
1997 <CODE>cosh(x) &#62;= 1</CODE>.
1998
1999 <DT><CODE>cl_N cosh (const cl_N&#38; z)</CODE>
2000 <DD>
2001 Returns <CODE>cosh(z)</CODE>. The range of the result is the entire complex plane.
2002
2003 <DT><CODE>struct cl_cosh_sinh_t { cl_R cosh; cl_R sinh; };</CODE>
2004 <DD>
2005 <A NAME="IDX122"></A>
2006 <DT><CODE>cl_cosh_sinh_t cl_cosh_sinh (const cl_R&#38; x)</CODE>
2007 <DD>
2008 <A NAME="IDX123"></A>
2009 Returns both <CODE>sinh(x)</CODE> and <CODE>cosh(x)</CODE>. This is more efficient than
2010 computing them separately. The relation <CODE>cosh^2 - sinh^2 = 1</CODE> will
2011 hold only approximately.
2012
2013 <DT><CODE>cl_R tanh (const cl_R&#38; x)</CODE>
2014 <DD>
2015 <A NAME="IDX124"></A>
2016 <DT><CODE>cl_N tanh (const cl_N&#38; x)</CODE>
2017 <DD>
2018 Returns <CODE>tanh(x) = sinh(x)/cosh(x)</CODE>.
2019
2020 <DT><CODE>cl_N asinh (const cl_N&#38; z)</CODE>
2021 <DD>
2022 <A NAME="IDX125"></A>
2023 Returns <CODE>arsinh(z)</CODE>. This is defined as
2024 <CODE>arsinh(z) = log(z+sqrt(1+z^2))</CODE> and satisfies
2025 <CODE>arsinh(-z) = -arsinh(z)</CODE>.
2026 The range of the result is the strip in the complex domain
2027 <CODE>-pi/2 &#60;= imagpart(arsinh(z)) &#60;= pi/2</CODE>, excluding the numbers
2028 with <CODE>imagpart = -pi/2</CODE> and <CODE>realpart &#62; 0</CODE> and the numbers
2029 with <CODE>imagpart = pi/2</CODE> and <CODE>realpart &#60; 0</CODE>.
2030
2031 <DT><CODE>cl_N acosh (const cl_N&#38; z)</CODE>
2032 <DD>
2033 <A NAME="IDX126"></A>
2034 Returns <CODE>arcosh(z)</CODE>. This is defined as
2035 <CODE>arcosh(z) = 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))</CODE>.
2036 The range of the result is the half-strip in the complex domain
2037 <CODE>-pi &#60; imagpart(arcosh(z)) &#60;= pi, realpart(arcosh(z)) &#62;= 0</CODE>,
2038 excluding the numbers with <CODE>realpart = 0</CODE> and <CODE>-pi &#60; imagpart &#60; 0</CODE>.
2039
2040 <DT><CODE>cl_N atanh (const cl_N&#38; z)</CODE>
2041 <DD>
2042 <A NAME="IDX127"></A>
2043 Returns <CODE>artanh(z)</CODE>. This is defined as
2044 <CODE>artanh(z) = (log(1+z)-log(1-z)) / 2</CODE> and satisfies
2045 <CODE>artanh(-z) = -artanh(z)</CODE>. The range of the result is
2046 the strip in the complex domain
2047 <CODE>-pi/2 &#60;= imagpart(artanh(z)) &#60;= pi/2</CODE>, excluding the numbers
2048 with <CODE>imagpart = -pi/2</CODE> and <CODE>realpart &#60;= 0</CODE> and the numbers
2049 with <CODE>imagpart = pi/2</CODE> and <CODE>realpart &#62;= 0</CODE>.
2050 </DL>
2051
2052
2053
2054 <H3><A NAME="SEC32" HREF="cln.html#TOC32">4.8.4 Euler gamma</A></H3>
2055 <P>
2056 <A NAME="IDX128"></A>
2057
2058
2059 <P>
2060 Euler's constant C = 0.577... is returned by the following functions:
2061
2062
2063 <DL COMPACT>
2064
2065 <DT><CODE>cl_F cl_eulerconst (cl_float_format_t f)</CODE>
2066 <DD>
2067 <A NAME="IDX129"></A>
2068 Returns Euler's constant as a float of format <CODE>f</CODE>.
2069
2070 <DT><CODE>cl_F cl_eulerconst (const cl_F&#38; y)</CODE>
2071 <DD>
2072 Returns Euler's constant in the float format of <CODE>y</CODE>.
2073
2074 <DT><CODE>cl_F cl_eulerconst (void)</CODE>
2075 <DD>
2076 Returns Euler's constant as a float of format <CODE>cl_default_float_format</CODE>.
2077 </DL>
2078
2079 <P>
2080 Catalan's constant G = 0.915... is returned by the following functions:
2081 <A NAME="IDX130"></A>
2082
2083
2084 <DL COMPACT>
2085
2086 <DT><CODE>cl_F cl_catalanconst (cl_float_format_t f)</CODE>
2087 <DD>
2088 <A NAME="IDX131"></A>
2089 Returns Catalan's constant as a float of format <CODE>f</CODE>.
2090
2091 <DT><CODE>cl_F cl_catalanconst (const cl_F&#38; y)</CODE>
2092 <DD>
2093 Returns Catalan's constant in the float format of <CODE>y</CODE>.
2094
2095 <DT><CODE>cl_F cl_catalanconst (void)</CODE>
2096 <DD>
2097 Returns Catalan's constant as a float of format <CODE>cl_default_float_format</CODE>.
2098 </DL>
2099
2100
2101
2102 <H3><A NAME="SEC33" HREF="cln.html#TOC33">4.8.5 Riemann zeta</A></H3>
2103 <P>
2104 <A NAME="IDX132"></A>
2105
2106
2107 <P>
2108 Riemann's zeta function at an integral point <CODE>s&#62;1</CODE> is returned by the
2109 following functions:
2110
2111
2112 <DL COMPACT>
2113
2114 <DT><CODE>cl_F cl_zeta (int s, cl_float_format_t f)</CODE>
2115 <DD>
2116 <A NAME="IDX133"></A>
2117 Returns Riemann's zeta function at <CODE>s</CODE> as a float of format <CODE>f</CODE>.
2118
2119 <DT><CODE>cl_F cl_zeta (int s, const cl_F&#38; y)</CODE>
2120 <DD>
2121 Returns Riemann's zeta function at <CODE>s</CODE> in the float format of <CODE>y</CODE>.
2122
2123 <DT><CODE>cl_F cl_zeta (int s)</CODE>
2124 <DD>
2125 Returns Riemann's zeta function at <CODE>s</CODE> as a float of format
2126 <CODE>cl_default_float_format</CODE>.
2127 </DL>
2128
2129
2130
2131 <H2><A NAME="SEC34" HREF="cln.html#TOC34">4.9 Functions on integers</A></H2>
2132
2133
2134
2135 <H3><A NAME="SEC35" HREF="cln.html#TOC35">4.9.1 Logical functions</A></H3>
2136
2137 <P>
2138 Integers, when viewed as in two's complement notation, can be thought as
2139 infinite bit strings where the bits' values eventually are constant.
2140 For example,
2141
2142 <PRE>
2143     17 = ......00010001
2144     -6 = ......11111010
2145 </PRE>
2146
2147 <P>
2148 The logical operations view integers as such bit strings and operate
2149 on each of the bit positions in parallel.
2150
2151
2152 <DL COMPACT>
2153
2154 <DT><CODE>cl_I lognot (const cl_I&#38; x)</CODE>
2155 <DD>
2156 <A NAME="IDX134"></A>
2157 <DT><CODE>cl_I operator ~ (const cl_I&#38; x)</CODE>
2158 <DD>
2159 <A NAME="IDX135"></A>
2160 Logical not, like <CODE>~x</CODE> in C. This is the same as <CODE>-1-x</CODE>.
2161
2162 <DT><CODE>cl_I logand (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2163 <DD>
2164 <A NAME="IDX136"></A>
2165 <DT><CODE>cl_I operator &#38; (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2166 <DD>
2167 <A NAME="IDX137"></A>
2168 Logical and, like <CODE>x &#38; y</CODE> in C.
2169
2170 <DT><CODE>cl_I logior (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2171 <DD>
2172 <A NAME="IDX138"></A>
2173 <DT><CODE>cl_I operator | (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2174 <DD>
2175 <A NAME="IDX139"></A>
2176 Logical (inclusive) or, like <CODE>x | y</CODE> in C.
2177
2178 <DT><CODE>cl_I logxor (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2179 <DD>
2180 <A NAME="IDX140"></A>
2181 <DT><CODE>cl_I operator ^ (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2182 <DD>
2183 <A NAME="IDX141"></A>
2184 Exclusive or, like <CODE>x ^ y</CODE> in C.
2185
2186 <DT><CODE>cl_I logeqv (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2187 <DD>
2188 <A NAME="IDX142"></A>
2189 Bitwise equivalence, like <CODE>~(x ^ y)</CODE> in C.
2190
2191 <DT><CODE>cl_I lognand (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2192 <DD>
2193 <A NAME="IDX143"></A>
2194 Bitwise not and, like <CODE>~(x &#38; y)</CODE> in C.
2195
2196 <DT><CODE>cl_I lognor (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2197 <DD>
2198 <A NAME="IDX144"></A>
2199 Bitwise not or, like <CODE>~(x | y)</CODE> in C.
2200
2201 <DT><CODE>cl_I logandc1 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2202 <DD>
2203 <A NAME="IDX145"></A>
2204 Logical and, complementing the first argument, like <CODE>~x &#38; y</CODE> in C.
2205
2206 <DT><CODE>cl_I logandc2 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2207 <DD>
2208 <A NAME="IDX146"></A>
2209 Logical and, complementing the second argument, like <CODE>x &#38; ~y</CODE> in C.
2210
2211 <DT><CODE>cl_I logorc1 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2212 <DD>
2213 <A NAME="IDX147"></A>
2214 Logical or, complementing the first argument, like <CODE>~x | y</CODE> in C.
2215
2216 <DT><CODE>cl_I logorc2 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2217 <DD>
2218 <A NAME="IDX148"></A>
2219 Logical or, complementing the second argument, like <CODE>x | ~y</CODE> in C.
2220 </DL>
2221
2222 <P>
2223 These operations are all available though the function
2224 <DL COMPACT>
2225
2226 <DT><CODE>cl_I boole (cl_boole op, const cl_I&#38; x, const cl_I&#38; y)</CODE>
2227 <DD>
2228 <A NAME="IDX149"></A>
2229 </DL>
2230 <P>
2231 where <CODE>op</CODE> must have one of the 16 values (each one stands for a function
2232 which combines two bits into one bit): <CODE>boole_clr</CODE>, <CODE>boole_set</CODE>,
2233 <CODE>boole_1</CODE>, <CODE>boole_2</CODE>, <CODE>boole_c1</CODE>, <CODE>boole_c2</CODE>,
2234 <CODE>boole_and</CODE>, <CODE>boole_ior</CODE>, <CODE>boole_xor</CODE>, <CODE>boole_eqv</CODE>,
2235 <CODE>boole_nand</CODE>, <CODE>boole_nor</CODE>, <CODE>boole_andc1</CODE>, <CODE>boole_andc2</CODE>,
2236 <CODE>boole_orc1</CODE>, <CODE>boole_orc2</CODE>.
2237 <A NAME="IDX150"></A>
2238 <A NAME="IDX151"></A>
2239 <A NAME="IDX152"></A>
2240 <A NAME="IDX153"></A>
2241 <A NAME="IDX154"></A>
2242 <A NAME="IDX155"></A>
2243 <A NAME="IDX156"></A>
2244 <A NAME="IDX157"></A>
2245 <A NAME="IDX158"></A>
2246 <A NAME="IDX159"></A>
2247 <A NAME="IDX160"></A>
2248 <A NAME="IDX161"></A>
2249 <A NAME="IDX162"></A>
2250 <A NAME="IDX163"></A>
2251 <A NAME="IDX164"></A>
2252
2253
2254 <P>
2255 Other functions that view integers as bit strings:
2256
2257
2258 <DL COMPACT>
2259
2260 <DT><CODE>cl_boolean logtest (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2261 <DD>
2262 <A NAME="IDX165"></A>
2263 Returns true if some bit is set in both <CODE>x</CODE> and <CODE>y</CODE>, i.e. if
2264 <CODE>logand(x,y) != 0</CODE>.
2265
2266 <DT><CODE>cl_boolean logbitp (const cl_I&#38; n, const cl_I&#38; x)</CODE>
2267 <DD>
2268 <A NAME="IDX166"></A>
2269 Returns true if the <CODE>n</CODE>th bit (from the right) of <CODE>x</CODE> is set.
2270 Bit 0 is the least significant bit.
2271
2272 <DT><CODE>uintL logcount (const cl_I&#38; x)</CODE>
2273 <DD>
2274 <A NAME="IDX167"></A>
2275 Returns the number of one bits in <CODE>x</CODE>, if <CODE>x</CODE> &#62;= 0, or
2276 the number of zero bits in <CODE>x</CODE>, if <CODE>x</CODE> &#60; 0.
2277 </DL>
2278
2279 <P>
2280 The following functions operate on intervals of bits in integers.
2281 The type
2282
2283 <PRE>
2284 struct cl_byte { uintL size; uintL position; };
2285 </PRE>
2286
2287 <P>
2288 <A NAME="IDX168"></A>
2289 represents the bit interval containing the bits
2290 <CODE>position</CODE>...<CODE>position+size-1</CODE> of an integer.
2291 The constructor <CODE>cl_byte(size,position)</CODE> constructs a <CODE>cl_byte</CODE>.
2292
2293
2294 <DL COMPACT>
2295
2296 <DT><CODE>cl_I ldb (const cl_I&#38; n, const cl_byte&#38; b)</CODE>
2297 <DD>
2298 <A NAME="IDX169"></A>
2299 extracts the bits of <CODE>n</CODE> described by the bit interval <CODE>b</CODE>
2300 and returns them as a nonnegative integer with <CODE>b.size</CODE> bits.
2301
2302 <DT><CODE>cl_boolean ldb_test (const cl_I&#38; n, const cl_byte&#38; b)</CODE>
2303 <DD>
2304 <A NAME="IDX170"></A>
2305 Returns true if some bit described by the bit interval <CODE>b</CODE> is set in
2306 <CODE>n</CODE>.
2307
2308 <DT><CODE>cl_I dpb (const cl_I&#38; newbyte, const cl_I&#38; n, const cl_byte&#38; b)</CODE>
2309 <DD>
2310 <A NAME="IDX171"></A>
2311 Returns <CODE>n</CODE>, with the bits described by the bit interval <CODE>b</CODE>
2312 replaced by <CODE>newbyte</CODE>. Only the lowest <CODE>b.size</CODE> bits of
2313 <CODE>newbyte</CODE> are relevant.
2314 </DL>
2315
2316 <P>
2317 The functions <CODE>ldb</CODE> and <CODE>dpb</CODE> implicitly shift. The following
2318 functions are their counterparts without shifting:
2319
2320
2321 <DL COMPACT>
2322
2323 <DT><CODE>cl_I mask_field (const cl_I&#38; n, const cl_byte&#38; b)</CODE>
2324 <DD>
2325 <A NAME="IDX172"></A>
2326 returns an integer with the bits described by the bit interval <CODE>b</CODE>
2327 copied from the corresponding bits in <CODE>n</CODE>, the other bits zero.
2328
2329 <DT><CODE>cl_I deposit_field (const cl_I&#38; newbyte, const cl_I&#38; n, const cl_byte&#38; b)</CODE>
2330 <DD>
2331 <A NAME="IDX173"></A>
2332 returns an integer where the bits described by the bit interval <CODE>b</CODE>
2333 come from <CODE>newbyte</CODE> and the other bits come from <CODE>n</CODE>.
2334 </DL>
2335
2336 <P>
2337 The following relations hold:
2338
2339
2340
2341 <UL>
2342 <LI>
2343
2344 <CODE>ldb (n, b) = mask_field(n, b) &#62;&#62; b.position</CODE>,
2345 <LI>
2346
2347 <CODE>dpb (newbyte, n, b) = deposit_field (newbyte &#60;&#60; b.position, n, b)</CODE>,
2348 <LI>
2349
2350 <CODE>deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^ mask_field(new_byte,b)</CODE>.
2351 </UL>
2352
2353 <P>
2354 The following operations on integers as bit strings are efficient shortcuts
2355 for common arithmetic operations:
2356
2357
2358 <DL COMPACT>
2359
2360 <DT><CODE>cl_boolean oddp (const cl_I&#38; x)</CODE>
2361 <DD>
2362 <A NAME="IDX174"></A>
2363 Returns true if the least significant bit of <CODE>x</CODE> is 1. Equivalent to
2364 <CODE>mod(x,2) != 0</CODE>.
2365
2366 <DT><CODE>cl_boolean evenp (const cl_I&#38; x)</CODE>
2367 <DD>
2368 <A NAME="IDX175"></A>
2369 Returns true if the least significant bit of <CODE>x</CODE> is 0. Equivalent to
2370 <CODE>mod(x,2) == 0</CODE>.
2371
2372 <DT><CODE>cl_I operator &#60;&#60; (const cl_I&#38; x, const cl_I&#38; n)</CODE>
2373 <DD>
2374 <A NAME="IDX176"></A>
2375 Shifts <CODE>x</CODE> by <CODE>n</CODE> bits to the left. <CODE>n</CODE> should be &#62;=0.
2376 Equivalent to <CODE>x * expt(2,n)</CODE>.
2377
2378 <DT><CODE>cl_I operator &#62;&#62; (const cl_I&#38; x, const cl_I&#38; n)</CODE>
2379 <DD>
2380 <A NAME="IDX177"></A>
2381 Shifts <CODE>x</CODE> by <CODE>n</CODE> bits to the right. <CODE>n</CODE> should be &#62;=0.
2382 Bits shifted out to the right are thrown away.
2383 Equivalent to <CODE>floor(x / expt(2,n))</CODE>.
2384
2385 <DT><CODE>cl_I ash (const cl_I&#38; x, const cl_I&#38; y)</CODE>
2386 <DD>
2387 <A NAME="IDX178"></A>
2388 Shifts <CODE>x</CODE> by <CODE>y</CODE> bits to the left (if <CODE>y</CODE>&#62;=0) or
2389 by <CODE>-y</CODE> bits to the right (if <CODE>y</CODE>&#60;=0). In other words, this
2390 returns <CODE>floor(x * expt(2,y))</CODE>.
2391
2392 <DT><CODE>uintL integer_length (const cl_I&#38; x)</CODE>
2393 <DD>
2394 <A NAME="IDX179"></A>
2395 Returns the number of bits (excluding the sign bit) needed to represent <CODE>x</CODE>
2396 in two's complement notation. This is the smallest n &#62;= 0 such that
2397 -2^n &#60;= x &#60; 2^n. If x &#62; 0, this is the unique n &#62; 0 such that
2398 2^(n-1) &#60;= x &#60; 2^n.
2399
2400 <DT><CODE>uintL ord2 (const cl_I&#38; x)</CODE>
2401 <DD>
2402 <A NAME="IDX180"></A>
2403 <CODE>x</CODE> must be non-zero. This function returns the number of 0 bits at the
2404 right of <CODE>x</CODE> in two's complement notation. This is the largest n &#62;= 0
2405 such that 2^n divides <CODE>x</CODE>.
2406
2407 <DT><CODE>uintL power2p (const cl_I&#38; x)</CODE>
2408 <DD>
2409 <A NAME="IDX181"></A>
2410 <CODE>x</CODE> must be &#62; 0. This function checks whether <CODE>x</CODE> is a power of 2.
2411 If <CODE>x</CODE> = 2^(n-1), it returns n. Else it returns 0.
2412 (See also the function <CODE>logp</CODE>.)
2413 </DL>
2414
2415
2416
2417 <H3><A NAME="SEC36" HREF="cln.html#TOC36">4.9.2 Number theoretic functions</A></H3>
2418
2419 <DL COMPACT>
2420
2421 <DT><CODE>uint32 gcd (uint32 a, uint32 b)</CODE>
2422 <DD>
2423 <A NAME="IDX182"></A>
2424 <DT><CODE>cl_I gcd (const cl_I&#38; a, const cl_I&#38; b)</CODE>
2425 <DD>
2426 This function returns the greatest common divisor of <CODE>a</CODE> and <CODE>b</CODE>,
2427 normalized to be &#62;= 0.
2428
2429 <DT><CODE>cl_I xgcd (const cl_I&#38; a, const cl_I&#38; b, cl_I* u, cl_I* v)</CODE>
2430 <DD>
2431 <A NAME="IDX183"></A>
2432 This function ("extended gcd") returns the greatest common divisor <CODE>g</CODE> of
2433 <CODE>a</CODE> and <CODE>b</CODE> and at the same time the representation of <CODE>g</CODE>
2434 as an integral linear combination of <CODE>a</CODE> and <CODE>b</CODE>:
2435 <CODE>u</CODE> and <CODE>v</CODE> with <CODE>u*a+v*b = g</CODE>, <CODE>g</CODE> &#62;= 0.
2436 <CODE>u</CODE> and <CODE>v</CODE> will be normalized to be of smallest possible absolute
2437 value, in the following sense: If <CODE>a</CODE> and <CODE>b</CODE> are non-zero, and
2438 <CODE>abs(a) != abs(b)</CODE>, <CODE>u</CODE> and <CODE>v</CODE> will satisfy the inequalities
2439 <CODE>abs(u) &#60;= abs(b)/(2*g)</CODE>, <CODE>abs(v) &#60;= abs(a)/(2*g)</CODE>.
2440
2441 <DT><CODE>cl_I lcm (const cl_I&#38; a, const cl_I&#38; b)</CODE>
2442 <DD>
2443 <A NAME="IDX184"></A>
2444 This function returns the least common multiple of <CODE>a</CODE> and <CODE>b</CODE>,
2445 normalized to be &#62;= 0.
2446
2447 <DT><CODE>cl_boolean logp (const cl_I&#38; a, const cl_I&#38; b, cl_RA* l)</CODE>
2448 <DD>
2449 <A NAME="IDX185"></A>
2450 <DT><CODE>cl_boolean logp (const cl_RA&#38; a, const cl_RA&#38; b, cl_RA* l)</CODE>
2451 <DD>
2452 <CODE>a</CODE> must be &#62; 0. <CODE>b</CODE> must be &#62;0 and != 1. If log(a,b) is
2453 rational number, this function returns true and sets *l = log(a,b), else
2454 it returns false.
2455 </DL>
2456
2457
2458
2459 <H3><A NAME="SEC37" HREF="cln.html#TOC37">4.9.3 Combinatorial functions</A></H3>
2460
2461 <DL COMPACT>
2462
2463 <DT><CODE>cl_I factorial (uintL n)</CODE>
2464 <DD>
2465 <A NAME="IDX186"></A>
2466 <CODE>n</CODE> must be a small integer &#62;= 0. This function returns the factorial
2467 <CODE>n</CODE>! = <CODE>1*2*...*n</CODE>.
2468
2469 <DT><CODE>cl_I doublefactorial (uintL n)</CODE>
2470 <DD>
2471 <A NAME="IDX187"></A>
2472 <CODE>n</CODE> must be a small integer &#62;= 0. This function returns the
2473 doublefactorial <CODE>n</CODE>!! = <CODE>1*3*...*n</CODE> or
2474 <CODE>n</CODE>!! = <CODE>2*4*...*n</CODE>, respectively.
2475
2476 <DT><CODE>cl_I binomial (uintL n, uintL k)</CODE>
2477 <DD>
2478 <A NAME="IDX188"></A>
2479 <CODE>n</CODE> and <CODE>k</CODE> must be small integers &#62;= 0. This function returns the
2480 binomial coefficient
2481 (<CODE>n</CODE> choose <CODE>k</CODE>) = <CODE>n</CODE>! / <CODE>k</CODE>! <CODE>(n-k)</CODE>!
2482 for 0 &#60;= k &#60;= n, 0 else.
2483 </DL>
2484
2485
2486
2487 <H2><A NAME="SEC38" HREF="cln.html#TOC38">4.10 Functions on floating-point numbers</A></H2>
2488
2489 <P>
2490 Recall that a floating-point number consists of a sign <CODE>s</CODE>, an
2491 exponent <CODE>e</CODE> and a mantissa <CODE>m</CODE>. The value of the number is
2492 <CODE>(-1)^s * 2^e * m</CODE>.
2493
2494
2495 <P>
2496 Each of the classes
2497 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
2498 defines the following operations.
2499
2500
2501 <DL COMPACT>
2502
2503 <DT><CODE><VAR>type</VAR> scale_float (const <VAR>type</VAR>&#38; x, sintL delta)</CODE>
2504 <DD>
2505 <A NAME="IDX189"></A>
2506 <DT><CODE><VAR>type</VAR> scale_float (const <VAR>type</VAR>&#38; x, const cl_I&#38; delta)</CODE>
2507 <DD>
2508 Returns <CODE>x*2^delta</CODE>. This is more efficient than an explicit multiplication
2509 because it copies <CODE>x</CODE> and modifies the exponent.
2510 </DL>
2511
2512 <P>
2513 The following functions provide an abstract interface to the underlying
2514 representation of floating-point numbers.
2515
2516
2517 <DL COMPACT>
2518
2519 <DT><CODE>sintL float_exponent (const <VAR>type</VAR>&#38; x)</CODE>
2520 <DD>
2521 <A NAME="IDX190"></A>
2522 Returns the exponent <CODE>e</CODE> of <CODE>x</CODE>.
2523 For <CODE>x = 0.0</CODE>, this is 0. For <CODE>x</CODE> non-zero, this is the unique
2524 integer with <CODE>2^(e-1) &#60;= abs(x) &#60; 2^e</CODE>.
2525
2526 <DT><CODE>sintL float_radix (const <VAR>type</VAR>&#38; x)</CODE>
2527 <DD>
2528 <A NAME="IDX191"></A>
2529 Returns the base of the floating-point representation. This is always <CODE>2</CODE>.
2530
2531 <DT><CODE><VAR>type</VAR> float_sign (const <VAR>type</VAR>&#38; x)</CODE>
2532 <DD>
2533 <A NAME="IDX192"></A>
2534 Returns the sign <CODE>s</CODE> of <CODE>x</CODE> as a float. The value is 1 for
2535 <CODE>x</CODE> &#62;= 0, -1 for <CODE>x</CODE> &#60; 0.
2536
2537 <DT><CODE>uintL float_digits (const <VAR>type</VAR>&#38; x)</CODE>
2538 <DD>
2539 <A NAME="IDX193"></A>
2540 Returns the number of mantissa bits in the floating-point representation
2541 of <CODE>x</CODE>, including the hidden bit. The value only depends on the type
2542 of <CODE>x</CODE>, not on its value.
2543
2544 <DT><CODE>uintL float_precision (const <VAR>type</VAR>&#38; x)</CODE>
2545 <DD>
2546 <A NAME="IDX194"></A>
2547 Returns the number of significant mantissa bits in the floating-point
2548 representation of <CODE>x</CODE>. Since denormalized numbers are not supported,
2549 this is the same as <CODE>float_digits(x)</CODE> if <CODE>x</CODE> is non-zero, and
2550 0 if <CODE>x</CODE> = 0.
2551 </DL>
2552
2553 <P>
2554 The complete internal representation of a float is encoded in the type
2555 <A NAME="IDX195"></A>
2556 <A NAME="IDX196"></A>
2557 <A NAME="IDX197"></A>
2558 <A NAME="IDX198"></A>
2559 <A NAME="IDX199"></A>
2560 <CODE>cl_decoded_float</CODE> (or <CODE>cl_decoded_sfloat</CODE>, <CODE>cl_decoded_ffloat</CODE>,
2561 <CODE>cl_decoded_dfloat</CODE>, <CODE>cl_decoded_lfloat</CODE>, respectively), defined by
2562
2563 <PRE>
2564 struct cl_decoded_<VAR>type</VAR>float {
2565         <VAR>type</VAR> mantissa; cl_I exponent; <VAR>type</VAR> sign;
2566 };
2567 </PRE>
2568
2569 <P>
2570 and returned by the function
2571
2572
2573 <DL COMPACT>
2574
2575 <DT><CODE>cl_decoded_<VAR>type</VAR>float decode_float (const <VAR>type</VAR>&#38; x)</CODE>
2576 <DD>
2577 <A NAME="IDX200"></A>
2578 For <CODE>x</CODE> non-zero, this returns <CODE>(-1)^s</CODE>, <CODE>e</CODE>, <CODE>m</CODE> with
2579 <CODE>x = (-1)^s * 2^e * m</CODE> and <CODE>0.5 &#60;= m &#60; 1.0</CODE>. For <CODE>x</CODE> = 0,
2580 it returns <CODE>(-1)^s</CODE>=1, <CODE>e</CODE>=0, <CODE>m</CODE>=0.
2581 <CODE>e</CODE> is the same as returned by the function <CODE>float_exponent</CODE>.
2582 </DL>
2583
2584 <P>
2585 A complete decoding in terms of integers is provided as type
2586
2587 <PRE>
2588 <A NAME="IDX201"></A>struct cl_idecoded_float {
2589         cl_I mantissa; cl_I exponent; cl_I sign;
2590 };
2591 </PRE>
2592
2593 <P>
2594 by the following function:
2595
2596
2597 <DL COMPACT>
2598
2599 <DT><CODE>cl_idecoded_float integer_decode_float (const <VAR>type</VAR>&#38; x)</CODE>
2600 <DD>
2601 <A NAME="IDX202"></A>
2602 For <CODE>x</CODE> non-zero, this returns <CODE>(-1)^s</CODE>, <CODE>e</CODE>, <CODE>m</CODE> with
2603 <CODE>x = (-1)^s * 2^e * m</CODE> and <CODE>m</CODE> an integer with <CODE>float_digits(x)</CODE>
2604 bits. For <CODE>x</CODE> = 0, it returns <CODE>(-1)^s</CODE>=1, <CODE>e</CODE>=0, <CODE>m</CODE>=0.
2605 WARNING: The exponent <CODE>e</CODE> is not the same as the one returned by
2606 the functions <CODE>decode_float</CODE> and <CODE>float_exponent</CODE>.
2607 </DL>
2608
2609 <P>
2610 Some other function, implemented only for class <CODE>cl_F</CODE>:
2611
2612
2613 <DL COMPACT>
2614
2615 <DT><CODE>cl_F float_sign (const cl_F&#38; x, const cl_F&#38; y)</CODE>
2616 <DD>
2617 <A NAME="IDX203"></A>
2618 This returns a floating point number whose precision and absolute value
2619 is that of <CODE>y</CODE> and whose sign is that of <CODE>x</CODE>. If <CODE>x</CODE> is
2620 zero, it is treated as positive. Same for <CODE>y</CODE>.
2621 </DL>
2622
2623
2624
2625 <H2><A NAME="SEC39" HREF="cln.html#TOC39">4.11 Conversion functions</A></H2>
2626 <P>
2627 <A NAME="IDX204"></A>
2628
2629
2630
2631
2632 <H3><A NAME="SEC40" HREF="cln.html#TOC40">4.11.1 Conversion to floating-point numbers</A></H3>
2633
2634 <P>
2635 The type <CODE>cl_float_format_t</CODE> describes a floating-point format.
2636 <A NAME="IDX205"></A>
2637
2638
2639 <DL COMPACT>
2640
2641 <DT><CODE>cl_float_format_t cl_float_format (uintL n)</CODE>
2642 <DD>
2643 <A NAME="IDX206"></A>
2644 Returns the smallest float format which guarantees at least <CODE>n</CODE>
2645 decimal digits in the mantissa (after the decimal point).
2646
2647 <DT><CODE>cl_float_format_t cl_float_format (const cl_F&#38; x)</CODE>
2648 <DD>
2649 Returns the floating point format of <CODE>x</CODE>.
2650
2651 <DT><CODE>cl_float_format_t cl_default_float_format</CODE>
2652 <DD>
2653 <A NAME="IDX207"></A>
2654 Global variable: the default float format used when converting rational numbers
2655 to floats.
2656 </DL>
2657
2658 <P>
2659 To convert a real number to a float, each of the types
2660 <CODE>cl_R</CODE>, <CODE>cl_F</CODE>, <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
2661 <CODE>int</CODE>, <CODE>unsigned int</CODE>, <CODE>float</CODE>, <CODE>double</CODE>
2662 defines the following operations:
2663
2664
2665 <DL COMPACT>
2666
2667 <DT><CODE>cl_F cl_float (const <VAR>type</VAR>&#38;x, cl_float_format_t f)</CODE>
2668 <DD>
2669 <A NAME="IDX208"></A>
2670 Returns <CODE>x</CODE> as a float of format <CODE>f</CODE>.
2671 <DT><CODE>cl_F cl_float (const <VAR>type</VAR>&#38;x, const cl_F&#38; y)</CODE>
2672 <DD>
2673 Returns <CODE>x</CODE> in the float format of <CODE>y</CODE>.
2674 <DT><CODE>cl_F cl_float (const <VAR>type</VAR>&#38;x)</CODE>
2675 <DD>
2676 Returns <CODE>x</CODE> as a float of format <CODE>cl_default_float_format</CODE> if
2677 it is an exact number, or <CODE>x</CODE> itself if it is already a float.
2678 </DL>
2679
2680 <P>
2681 Of course, converting a number to a float can lose precision.
2682
2683
2684 <P>
2685 Every floating-point format has some characteristic numbers:
2686
2687
2688 <DL COMPACT>
2689
2690 <DT><CODE>cl_F most_positive_float (cl_float_format_t f)</CODE>
2691 <DD>
2692 <A NAME="IDX209"></A>
2693 Returns the largest (most positive) floating point number in float format <CODE>f</CODE>.
2694
2695 <DT><CODE>cl_F most_negative_float (cl_float_format_t f)</CODE>
2696 <DD>
2697 <A NAME="IDX210"></A>
2698 Returns the smallest (most negative) floating point number in float format <CODE>f</CODE>.
2699
2700 <DT><CODE>cl_F least_positive_float (cl_float_format_t f)</CODE>
2701 <DD>
2702 <A NAME="IDX211"></A>
2703 Returns the least positive floating point number (i.e. &#62; 0 but closest to 0)
2704 in float format <CODE>f</CODE>.
2705
2706 <DT><CODE>cl_F least_negative_float (cl_float_format_t f)</CODE>
2707 <DD>
2708 <A NAME="IDX212"></A>
2709 Returns the least negative floating point number (i.e. &#60; 0 but closest to 0)
2710 in float format <CODE>f</CODE>.
2711
2712 <DT><CODE>cl_F float_epsilon (cl_float_format_t f)</CODE>
2713 <DD>
2714 <A NAME="IDX213"></A>
2715 Returns the smallest floating point number e &#62; 0 such that <CODE>1+e != 1</CODE>.
2716
2717 <DT><CODE>cl_F float_negative_epsilon (cl_float_format_t f)</CODE>
2718 <DD>
2719 <A NAME="IDX214"></A>
2720 Returns the smallest floating point number e &#62; 0 such that <CODE>1-e != 1</CODE>.
2721 </DL>
2722
2723
2724
2725 <H3><A NAME="SEC41" HREF="cln.html#TOC41">4.11.2 Conversion to rational numbers</A></H3>
2726
2727 <P>
2728 Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_F</CODE>
2729 defines the following operation:
2730
2731
2732 <DL COMPACT>
2733
2734 <DT><CODE>cl_RA rational (const <VAR>type</VAR>&#38; x)</CODE>
2735 <DD>
2736 <A NAME="IDX215"></A>
2737 Returns the value of <CODE>x</CODE> as an exact number. If <CODE>x</CODE> is already
2738 an exact number, this is <CODE>x</CODE>. If <CODE>x</CODE> is a floating-point number,
2739 the value is a rational number whose denominator is a power of 2.
2740 </DL>
2741
2742 <P>
2743 In order to convert back, say, <CODE>(cl_F)(cl_R)"1/3"</CODE> to <CODE>1/3</CODE>, there is
2744 the function
2745
2746
2747 <DL COMPACT>
2748
2749 <DT><CODE>cl_RA rationalize (const cl_R&#38; x)</CODE>
2750 <DD>
2751 <A NAME="IDX216"></A>
2752 If <CODE>x</CODE> is a floating-point number, it actually represents an interval
2753 of real numbers, and this function returns the rational number with
2754 smallest denominator (and smallest numerator, in magnitude)
2755 which lies in this interval.
2756 If <CODE>x</CODE> is already an exact number, this function returns <CODE>x</CODE>.
2757 </DL>
2758
2759 <P>
2760 If <CODE>x</CODE> is any float, one has
2761
2762
2763
2764 <UL>
2765 <LI>
2766
2767 <CODE>cl_float(rational(x),x) = x</CODE>
2768 <LI>
2769
2770 <CODE>cl_float(rationalize(x),x) = x</CODE>
2771 </UL>
2772
2773
2774
2775 <H2><A NAME="SEC42" HREF="cln.html#TOC42">4.12 Random number generators</A></H2>
2776
2777 <P>
2778 A random generator is a machine which produces (pseudo-)random numbers.
2779 The include file <CODE>&#60;cl_random.h&#62;</CODE> defines a class <CODE>cl_random_state</CODE>
2780 which contains the state of a random generator. If you make a copy
2781 of the random number generator, the original one and the copy will produce
2782 the same sequence of random numbers.
2783
2784
2785 <P>
2786 The following functions return (pseudo-)random numbers in different formats.
2787 Calling one of these modifies the state of the random number generator in
2788 a complicated but deterministic way.
2789
2790
2791 <P>
2792 The global variable
2793 <A NAME="IDX217"></A>
2794 <A NAME="IDX218"></A>
2795
2796 <PRE>
2797 cl_random_state cl_default_random_state
2798 </PRE>
2799
2800 <P>
2801 contains a default random number generator. It is used when the functions
2802 below are called without <CODE>cl_random_state</CODE> argument.
2803
2804
2805 <DL COMPACT>
2806
2807 <DT><CODE>uint32 random32 (cl_random_state&#38; randomstate)</CODE>
2808 <DD>
2809 <DT><CODE>uint32 random32 ()</CODE>
2810 <DD>
2811 <A NAME="IDX219"></A>
2812 Returns a random unsigned 32-bit number. All bits are equally random.
2813
2814 <DT><CODE>cl_I random_I (cl_random_state&#38; randomstate, const cl_I&#38; n)</CODE>
2815 <DD>
2816 <DT><CODE>cl_I random_I (const cl_I&#38; n)</CODE>
2817 <DD>
2818 <A NAME="IDX220"></A>
2819 <CODE>n</CODE> must be an integer &#62; 0. This function returns a random integer <CODE>x</CODE>
2820 in the range <CODE>0 &#60;= x &#60; n</CODE>.
2821
2822 <DT><CODE>cl_F random_F (cl_random_state&#38; randomstate, const cl_F&#38; n)</CODE>
2823 <DD>
2824 <DT><CODE>cl_F random_F (const cl_F&#38; n)</CODE>
2825 <DD>
2826 <A NAME="IDX221"></A>
2827 <CODE>n</CODE> must be a float &#62; 0. This function returns a random floating-point
2828 number of the same format as <CODE>n</CODE> in the range <CODE>0 &#60;= x &#60; n</CODE>.
2829
2830 <DT><CODE>cl_R random_R (cl_random_state&#38; randomstate, const cl_R&#38; n)</CODE>
2831 <DD>
2832 <DT><CODE>cl_R random_R (const cl_R&#38; n)</CODE>
2833 <DD>
2834 <A NAME="IDX222"></A>
2835 Behaves like <CODE>random_I</CODE> if <CODE>n</CODE> is an integer and like <CODE>random_F</CODE>
2836 if <CODE>n</CODE> is a float.
2837 </DL>
2838
2839
2840
2841 <H2><A NAME="SEC43" HREF="cln.html#TOC43">4.13 Obfuscating operators</A></H2>
2842 <P>
2843 <A NAME="IDX223"></A>
2844
2845
2846 <P>
2847 The modifying C/C++ operators <CODE>+=</CODE>, <CODE>-=</CODE>, <CODE>*=</CODE>, <CODE>/=</CODE>,
2848 <CODE>&#38;=</CODE>, <CODE>|=</CODE>, <CODE>^=</CODE>, <CODE>&#60;&#60;=</CODE>, <CODE>&#62;&#62;=</CODE>
2849 are not available by default because their
2850 use tends to make programs unreadable. It is trivial to get away without
2851 them. However, if you feel that you absolutely need these operators
2852 to get happy, then add
2853
2854 <PRE>
2855 #define WANT_OBFUSCATING_OPERATORS
2856 </PRE>
2857
2858 <P>
2859 <A NAME="IDX224"></A>
2860 to the beginning of your source files, before the inclusion of any CLN
2861 include files. This flag will enable the following operators:
2862
2863
2864 <P>
2865 For the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
2866 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>:
2867
2868
2869 <DL COMPACT>
2870
2871 <DT><CODE><VAR>type</VAR>&#38; operator += (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2872 <DD>
2873 <A NAME="IDX225"></A>
2874 <DT><CODE><VAR>type</VAR>&#38; operator -= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2875 <DD>
2876 <A NAME="IDX226"></A>
2877 <DT><CODE><VAR>type</VAR>&#38; operator *= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2878 <DD>
2879 <A NAME="IDX227"></A>
2880 <DT><CODE><VAR>type</VAR>&#38; operator /= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2881 <DD>
2882 <A NAME="IDX228"></A>
2883 </DL>
2884
2885 <P>
2886 For the class <CODE>cl_I</CODE>:
2887
2888
2889 <DL COMPACT>
2890
2891 <DT><CODE><VAR>type</VAR>&#38; operator += (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2892 <DD>
2893 <DT><CODE><VAR>type</VAR>&#38; operator -= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2894 <DD>
2895 <DT><CODE><VAR>type</VAR>&#38; operator *= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2896 <DD>
2897 <DT><CODE><VAR>type</VAR>&#38; operator &#38;= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2898 <DD>
2899 <A NAME="IDX229"></A>
2900 <DT><CODE><VAR>type</VAR>&#38; operator |= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2901 <DD>
2902 <A NAME="IDX230"></A>
2903 <DT><CODE><VAR>type</VAR>&#38; operator ^= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2904 <DD>
2905 <A NAME="IDX231"></A>
2906 <DT><CODE><VAR>type</VAR>&#38; operator &#60;&#60;= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2907 <DD>
2908 <A NAME="IDX232"></A>
2909 <DT><CODE><VAR>type</VAR>&#38; operator &#62;&#62;= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
2910 <DD>
2911 <A NAME="IDX233"></A>
2912 </DL>
2913
2914 <P>
2915 For the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
2916 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>:
2917
2918
2919 <DL COMPACT>
2920
2921 <DT><CODE><VAR>type</VAR>&#38; operator ++ (<VAR>type</VAR>&#38; x)</CODE>
2922 <DD>
2923 <A NAME="IDX234"></A>
2924 The prefix operator <CODE>++x</CODE>.
2925
2926 <DT><CODE>void operator ++ (<VAR>type</VAR>&#38; x, int)</CODE>
2927 <DD>
2928 The postfix operator <CODE>x++</CODE>.
2929
2930 <DT><CODE><VAR>type</VAR>&#38; operator -- (<VAR>type</VAR>&#38; x)</CODE>
2931 <DD>
2932 <A NAME="IDX235"></A>
2933 The prefix operator <CODE>--x</CODE>.
2934
2935 <DT><CODE>void operator -- (<VAR>type</VAR>&#38; x, int)</CODE>
2936 <DD>
2937 The postfix operator <CODE>x--</CODE>.
2938 </DL>
2939
2940 <P>
2941 Note that by using these obfuscating operators, you wouldn't gain efficiency:
2942 In CLN <SAMP>`x += y;'</SAMP> is exactly the same as  <SAMP>`x = x+y;'</SAMP>, not more
2943 efficient.
2944
2945
2946
2947
2948 <H1><A NAME="SEC44" HREF="cln.html#TOC44">5. Input/Output</A></H1>
2949 <P>
2950 <A NAME="IDX236"></A>
2951
2952
2953
2954
2955 <H2><A NAME="SEC45" HREF="cln.html#TOC45">5.1 Internal and printed representation</A></H2>
2956 <P>
2957 <A NAME="IDX237"></A>
2958
2959
2960 <P>
2961 All computations deal with the internal representations of the numbers.
2962
2963
2964 <P>
2965 Every number has an external representation as a sequence of ASCII characters.
2966 Several external representations may denote the same number, for example,
2967 "20.0" and "20.000".
2968
2969
2970 <P>
2971 Converting an internal to an external representation is called "printing",
2972 <A NAME="IDX238"></A>
2973 converting an external to an internal representation is called "reading".
2974 <A NAME="IDX239"></A>
2975 In CLN, it is always true that conversion of an internal to an external
2976 representation and then back to an internal representation will yield the
2977 same internal representation. Symbolically: <CODE>read(print(x)) == x</CODE>.
2978 This is called "print-read consistency".
2979
2980
2981 <P>
2982 Different types of numbers have different external representations (case
2983 is insignificant):
2984
2985
2986 <DL COMPACT>
2987
2988 <DT>Integers
2989 <DD>
2990 External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+. The reader also accepts the
2991 Common Lisp syntaxes <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>.</CODE> with a trailing dot
2992 for decimal integers
2993 and the <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes.
2994
2995 <DT>Rational numbers
2996 <DD>
2997 External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>/</CODE>{<VAR>digit</VAR>}+.
2998 The <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes are allowed
2999 here as well.
3000
3001 <DT>Floating-point numbers
3002 <DD>
3003 External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
3004 <VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
3005 <VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}+. A precision specifier
3006 of the form _<VAR>prec</VAR> may be appended. There must be at least
3007 one digit in the non-exponent part. The exponent has the syntax
3008 <VAR>expmarker</VAR> <VAR>expsign</VAR> {<VAR>digit</VAR>}+.
3009 The exponent marker is
3010
3011
3012 <UL>
3013 <LI>
3014
3015 <SAMP>`s'</SAMP> for short-floats,
3016 <LI>
3017
3018 <SAMP>`f'</SAMP> for single-floats,
3019 <LI>
3020
3021 <SAMP>`d'</SAMP> for double-floats,
3022 <LI>
3023
3024 <SAMP>`L'</SAMP> for long-floats,
3025 </UL>
3026
3027 or <SAMP>`e'</SAMP>, which denotes a default float format. The precision specifying
3028 suffix has the syntax _<VAR>prec</VAR> where <VAR>prec</VAR> denotes the number of
3029 valid mantissa digits (in decimal, excluding leading zeroes), cf. also
3030 function <SAMP>`cl_float_format'</SAMP>.
3031
3032 <DT>Complex numbers
3033 <DD>
3034 External representation:
3035
3036 <UL>
3037 <LI>
3038
3039 In algebraic notation: <CODE><VAR>realpart</VAR>+<VAR>imagpart</VAR>i</CODE>. Of course,
3040 if <VAR>imagpart</VAR> is negative, its printed representation begins with
3041 a <SAMP>`-'</SAMP>, and the <SAMP>`+'</SAMP> between <VAR>realpart</VAR> and <VAR>imagpart</VAR>
3042 may be omitted. Note that this notation cannot be used when the <VAR>imagpart</VAR>
3043 is rational and the rational number's base is &#62;18, because the <SAMP>`i'</SAMP>
3044 is then read as a digit.
3045 <LI>
3046
3047 In Common Lisp notation: <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>.
3048 </UL>
3049
3050 </DL>
3051
3052
3053
3054 <H2><A NAME="SEC46" HREF="cln.html#TOC46">5.2 Input functions</A></H2>
3055
3056 <P>
3057 Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_istream</CODE>, which is
3058 the type of the first argument to all input functions. Unless you build
3059 and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_istream</CODE>
3060 is the same as <CODE>istream&#38;</CODE>.
3061
3062
3063 <P>
3064 The variable
3065
3066 <UL>
3067 <LI>
3068
3069 <CODE>cl_istream cl_stdin</CODE>
3070 </UL>
3071
3072 <P>
3073 contains the standard input stream.
3074
3075
3076 <P>
3077 These are the simple input functions:
3078
3079
3080 <DL COMPACT>
3081
3082 <DT><CODE>int freadchar (cl_istream stream)</CODE>
3083 <DD>
3084 Reads a character from <CODE>stream</CODE>. Returns <CODE>cl_EOF</CODE> (not a <SAMP>`char'</SAMP>!)
3085 if the end of stream was encountered or an error occurred.
3086
3087 <DT><CODE>int funreadchar (cl_istream stream, int c)</CODE>
3088 <DD>
3089 Puts back <CODE>c</CODE> onto <CODE>stream</CODE>. <CODE>c</CODE> must be the result of the
3090 last <CODE>freadchar</CODE> operation on <CODE>stream</CODE>.
3091 </DL>
3092
3093 <P>
3094 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
3095 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
3096 defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following input function:
3097
3098
3099 <DL COMPACT>
3100
3101 <DT><CODE>cl_istream operator&#62;&#62; (cl_istream stream, <VAR>type</VAR>&#38; result)</CODE>
3102 <DD>
3103 Reads a number from <CODE>stream</CODE> and stores it in the <CODE>result</CODE>.
3104 </DL>
3105
3106 <P>
3107 The most flexible input functions, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
3108 are the following:
3109
3110
3111 <DL COMPACT>
3112
3113 <DT><CODE>cl_N read_complex (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
3114 <DD>
3115 <DT><CODE>cl_R read_real (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
3116 <DD>
3117 <DT><CODE>cl_F read_float (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
3118 <DD>
3119 <DT><CODE>cl_RA read_rational (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
3120 <DD>
3121 <DT><CODE>cl_I read_integer (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
3122 <DD>
3123 Reads a number from <CODE>stream</CODE>. The <CODE>flags</CODE> are parameters which
3124 affect the input syntax. Whitespace before the number is silently skipped.
3125
3126 <DT><CODE>cl_N read_complex (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
3127 <DD>
3128 <DT><CODE>cl_R read_real (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
3129 <DD>
3130 <DT><CODE>cl_F read_float (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
3131 <DD>
3132 <DT><CODE>cl_RA read_rational (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
3133 <DD>
3134 <DT><CODE>cl_I read_integer (const cl_read_flags&#38; flags, const char * string, const char * string_limit, const char * * end_of_parse)</CODE>
3135 <DD>
3136 Reads a number from a string in memory. The <CODE>flags</CODE> are parameters which
3137 affect the input syntax. The string starts at <CODE>string</CODE> and ends at
3138 <CODE>string_limit</CODE> (exclusive limit). <CODE>string_limit</CODE> may also be
3139 <CODE>NULL</CODE>, denoting the entire string, i.e. equivalent to
3140 <CODE>string_limit = string + strlen(string)</CODE>. If <CODE>end_of_parse</CODE> is
3141 <CODE>NULL</CODE>, the string in memory must contain exactly one number and nothing
3142 more, else a fatal error will be signalled. If <CODE>end_of_parse</CODE>
3143 is not <CODE>NULL</CODE>, <CODE>*end_of_parse</CODE> will be assigned a pointer past
3144 the last parsed character (i.e. <CODE>string_limit</CODE> if nothing came after
3145 the number). Whitespace is not allowed.
3146 </DL>
3147
3148 <P>
3149 The structure <CODE>cl_read_flags</CODE> contains the following fields:
3150
3151
3152 <DL COMPACT>
3153
3154 <DT><CODE>cl_read_syntax_t syntax</CODE>
3155 <DD>
3156 The possible results of the read operation. Possible values are
3157 <CODE>syntax_number</CODE>, <CODE>syntax_real</CODE>, <CODE>syntax_rational</CODE>,
3158 <CODE>syntax_integer</CODE>, <CODE>syntax_float</CODE>, <CODE>syntax_sfloat</CODE>,
3159 <CODE>syntax_ffloat</CODE>, <CODE>syntax_dfloat</CODE>, <CODE>syntax_lfloat</CODE>.
3160
3161 <DT><CODE>cl_read_lsyntax_t lsyntax</CODE>
3162 <DD>
3163 Specifies the language-dependent syntax variant for the read operation.
3164 Possible values are
3165
3166 <DL COMPACT>
3167
3168 <DT><CODE>lsyntax_standard</CODE>
3169 <DD>
3170 accept standard algebraic notation only, no complex numbers,
3171 <DT><CODE>lsyntax_algebraic</CODE>
3172 <DD>
3173 accept the algebraic notation <CODE><VAR>x</VAR>+<VAR>y</VAR>i</CODE> for complex numbers,
3174 <DT><CODE>lsyntax_commonlisp</CODE>
3175 <DD>
3176 accept the <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> syntaxes for binary, octal,
3177 hexadecimal numbers,
3178 <CODE>#<VAR>base</VAR>R</CODE> for rational numbers in a given base,
3179 <CODE>#c(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE> for complex numbers,
3180 <DT><CODE>lsyntax_all</CODE>
3181 <DD>
3182 accept all of these extensions.
3183 </DL>
3184
3185 <DT><CODE>unsigned int rational_base</CODE>
3186 <DD>
3187 The base in which rational numbers are read.
3188
3189 <DT><CODE>cl_float_format_t float_flags.default_float_format</CODE>
3190 <DD>
3191 The float format used when reading floats with exponent marker <SAMP>`e'</SAMP>.
3192
3193 <DT><CODE>cl_float_format_t float_flags.default_lfloat_format</CODE>
3194 <DD>
3195 The float format used when reading floats with exponent marker <SAMP>`l'</SAMP>.
3196
3197 <DT><CODE>cl_boolean float_flags.mantissa_dependent_float_format</CODE>
3198 <DD>
3199 When this flag is true, floats specified with more digits than corresponding
3200 to the exponent marker they contain, but without <VAR>_nnn</VAR> suffix, will get a
3201 precision corresponding to their number of significant digits.
3202 </DL>
3203
3204
3205
3206 <H2><A NAME="SEC47" HREF="cln.html#TOC47">5.3 Output functions</A></H2>
3207
3208 <P>
3209 Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_ostream</CODE>, which is
3210 the type of the first argument to all output functions. Unless you build
3211 and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_ostream</CODE>
3212 is the same as <CODE>ostream&#38;</CODE>.
3213
3214
3215 <P>
3216 The variable
3217
3218 <UL>
3219 <LI>
3220
3221 <CODE>cl_ostream cl_stdout</CODE>
3222 </UL>
3223
3224 <P>
3225 contains the standard output stream.
3226
3227
3228 <P>
3229 The variable
3230
3231 <UL>
3232 <LI>
3233
3234 <CODE>cl_ostream cl_stderr</CODE>
3235 </UL>
3236
3237 <P>
3238 contains the standard error output stream.
3239
3240
3241 <P>
3242 These are the simple output functions:
3243
3244
3245 <DL COMPACT>
3246
3247 <DT><CODE>void fprintchar (cl_ostream stream, char c)</CODE>
3248 <DD>
3249 Prints the character <CODE>x</CODE> literally on the <CODE>stream</CODE>.
3250
3251 <DT><CODE>void fprint (cl_ostream stream, const char * string)</CODE>
3252 <DD>
3253 Prints the <CODE>string</CODE> literally on the <CODE>stream</CODE>.
3254
3255 <DT><CODE>void fprintdecimal (cl_ostream stream, int x)</CODE>
3256 <DD>
3257 <DT><CODE>void fprintdecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
3258 <DD>
3259 Prints the integer <CODE>x</CODE> in decimal on the <CODE>stream</CODE>.
3260
3261 <DT><CODE>void fprintbinary (cl_ostream stream, const cl_I&#38; x)</CODE>
3262 <DD>
3263 Prints the integer <CODE>x</CODE> in binary (base 2, without prefix)
3264 on the <CODE>stream</CODE>.
3265
3266 <DT><CODE>void fprintoctal (cl_ostream stream, const cl_I&#38; x)</CODE>
3267 <DD>
3268 Prints the integer <CODE>x</CODE> in octal (base 8, without prefix)
3269 on the <CODE>stream</CODE>.
3270
3271 <DT><CODE>void fprinthexadecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
3272 <DD>
3273 Prints the integer <CODE>x</CODE> in hexadecimal (base 16, without prefix)
3274 on the <CODE>stream</CODE>.
3275 </DL>
3276
3277 <P>
3278 Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
3279 <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
3280 defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following output functions:
3281
3282
3283 <DL COMPACT>
3284
3285 <DT><CODE>void fprint (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
3286 <DD>
3287 <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
3288 <DD>
3289 Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
3290 on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
3291 The <CODE>ostream</CODE> flags and settings (flags, width and locale) are
3292 ignored.
3293 </DL>
3294
3295 <P>
3296 The most flexible output function, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
3297 are the following:
3298
3299 <PRE>
3300 void print_complex  (cl_ostream stream, const cl_print_flags&#38; flags,
3301                      const cl_N&#38; z);
3302 void print_real     (cl_ostream stream, const cl_print_flags&#38; flags,
3303                      const cl_R&#38; z);
3304 void print_float    (cl_ostream stream, const cl_print_flags&#38; flags,
3305                      const cl_F&#38; z);
3306 void print_rational (cl_ostream stream, const cl_print_flags&#38; flags,
3307                      const cl_RA&#38; z);
3308 void print_integer  (cl_ostream stream, const cl_print_flags&#38; flags,
3309                      const cl_I&#38; z);
3310 </PRE>
3311
3312 <P>
3313 Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The <CODE>flags</CODE> are
3314 parameters which affect the output.
3315
3316
3317 <P>
3318 The structure type <CODE>cl_print_flags</CODE> contains the following fields:
3319
3320
3321 <DL COMPACT>
3322
3323 <DT><CODE>unsigned int rational_base</CODE>
3324 <DD>
3325 The base in which rational numbers are printed. Default is <CODE>10</CODE>.
3326
3327 <DT><CODE>cl_boolean rational_readably</CODE>
3328 <DD>
3329 If this flag is true, rational numbers are printed with radix specifiers in
3330 Common Lisp syntax (<CODE>#<VAR>n</VAR>R</CODE> or <CODE>#b</CODE> or <CODE>#o</CODE> or <CODE>#x</CODE>
3331 prefixes, trailing dot). Default is false.
3332
3333 <DT><CODE>cl_boolean float_readably</CODE>
3334 <DD>
3335 If this flag is true, type specific exponent markers have precedence over 'E'.
3336 Default is false.
3337
3338 <DT><CODE>cl_float_format_t default_float_format</CODE>
3339 <DD>
3340 Floating point numbers of this format will be printed using the 'E' exponent
3341 marker. Default is <CODE>cl_float_format_ffloat</CODE>.
3342
3343 <DT><CODE>cl_boolean complex_readably</CODE>
3344 <DD>
3345 If this flag is true, complex numbers will be printed using the Common Lisp
3346 syntax <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>. Default is false.
3347
3348 <DT><CODE>cl_string univpoly_varname</CODE>
3349 <DD>
3350 Univariate polynomials with no explicit indeterminate name will be printed
3351 using this variable name. Default is <CODE>"x"</CODE>.
3352 </DL>
3353
3354 <P>
3355 The global variable <CODE>cl_default_print_flags</CODE> contains the default values,
3356 used by the function <CODE>fprint</CODE>.
3357
3358
3359
3360
3361 <H1><A NAME="SEC48" HREF="cln.html#TOC48">6. Rings</A></H1>
3362
3363 <P>
3364 CLN has a class of abstract rings.
3365
3366
3367
3368 <PRE>
3369                          Ring
3370                        cl_ring
3371                       &#60;cl_ring.h&#62;
3372 </PRE>
3373
3374 <P>
3375 Rings can be compared for equality:
3376
3377
3378 <DL COMPACT>
3379
3380 <DT><CODE>bool operator== (const cl_ring&#38;, const cl_ring&#38;)</CODE>
3381 <DD>
3382 <DT><CODE>bool operator!= (const cl_ring&#38;, const cl_ring&#38;)</CODE>
3383 <DD>
3384 These compare two rings for equality.
3385 </DL>
3386
3387 <P>
3388 Given a ring <CODE>R</CODE>, the following members can be used.
3389
3390
3391 <DL COMPACT>
3392
3393 <DT><CODE>void R-&#62;fprint (cl_ostream stream, const cl_ring_element&#38; x)</CODE>
3394 <DD>
3395 <DT><CODE>cl_boolean R-&#62;equal (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
3396 <DD>
3397 <DT><CODE>cl_ring_element R-&#62;zero ()</CODE>
3398 <DD>
3399 <DT><CODE>cl_boolean R-&#62;zerop (const cl_ring_element&#38; x)</CODE>
3400 <DD>
3401 <DT><CODE>cl_ring_element R-&#62;plus (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
3402 <DD>
3403 <DT><CODE>cl_ring_element R-&#62;minus (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
3404 <DD>
3405 <DT><CODE>cl_ring_element R-&#62;uminus (const cl_ring_element&#38; x)</CODE>
3406 <DD>
3407 <DT><CODE>cl_ring_element R-&#62;one ()</CODE>
3408 <DD>
3409 <DT><CODE>cl_ring_element R-&#62;canonhom (const cl_I&#38; x)</CODE>
3410 <DD>
3411 <DT><CODE>cl_ring_element R-&#62;mul (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
3412 <DD>
3413 <DT><CODE>cl_ring_element R-&#62;square (const cl_ring_element&#38; x)</CODE>
3414 <DD>
3415 <DT><CODE>cl_ring_element R-&#62;expt_pos (const cl_ring_element&#38; x, const cl_I&#38; y)</CODE>
3416 <DD>
3417 </DL>
3418
3419 <P>
3420 The following rings are built-in.
3421
3422
3423 <DL COMPACT>
3424
3425 <DT><CODE>cl_null_ring cl_0_ring</CODE>
3426 <DD>
3427 The null ring, containing only zero.
3428
3429 <DT><CODE>cl_complex_ring cl_C_ring</CODE>
3430 <DD>
3431 The ring of complex numbers. This corresponds to the type <CODE>cl_N</CODE>.
3432
3433 <DT><CODE>cl_real_ring cl_R_ring</CODE>
3434 <DD>
3435 The ring of real numbers. This corresponds to the type <CODE>cl_R</CODE>.
3436
3437 <DT><CODE>cl_rational_ring cl_RA_ring</CODE>
3438 <DD>
3439 The ring of rational numbers. This corresponds to the type <CODE>cl_RA</CODE>.
3440
3441 <DT><CODE>cl_integer_ring cl_I_ring</CODE>
3442 <DD>
3443 The ring of integers. This corresponds to the type <CODE>cl_I</CODE>.
3444 </DL>
3445
3446 <P>
3447 Type tests can be performed for any of <CODE>cl_C_ring</CODE>, <CODE>cl_R_ring</CODE>,
3448 <CODE>cl_RA_ring</CODE>, <CODE>cl_I_ring</CODE>:
3449
3450
3451 <DL COMPACT>
3452
3453 <DT><CODE>cl_boolean instanceof (const cl_number&#38; x, const cl_number_ring&#38; R)</CODE>
3454 <DD>
3455 Tests whether the given number is an element of the number ring R.
3456 </DL>
3457
3458
3459
3460 <H1><A NAME="SEC49" HREF="cln.html#TOC49">7. Modular integers</A></H1>
3461 <P>
3462 <A NAME="IDX240"></A>
3463
3464
3465
3466
3467 <H2><A NAME="SEC50" HREF="cln.html#TOC50">7.1 Modular integer rings</A></H2>
3468 <P>
3469 <A NAME="IDX241"></A>
3470
3471
3472 <P>
3473 CLN implements modular integers, i.e. integers modulo a fixed integer N.
3474 The modulus is explicitly part of every modular integer. CLN doesn't
3475 allow you to (accidentally) mix elements of different modular rings,
3476 e.g. <CODE>(3 mod 4) + (2 mod 5)</CODE> will result in a runtime error.
3477 (Ideally one would imagine a generic data type <CODE>cl_MI(N)</CODE>, but C++
3478 doesn't have generic types. So one has to live with runtime checks.)
3479
3480
3481 <P>
3482 The class of modular integer rings is
3483
3484
3485
3486 <PRE>
3487                          Ring
3488                        cl_ring
3489                       &#60;cl_ring.h&#62;
3490                           |
3491                           |
3492                  Modular integer ring
3493                     cl_modint_ring
3494                    &#60;cl_modinteger.h&#62;
3495 </PRE>
3496
3497 <P>
3498 <A NAME="IDX242"></A>
3499
3500
3501 <P>
3502 and the class of all modular integers (elements of modular integer rings) is
3503
3504
3505
3506 <PRE>
3507                     Modular integer
3508                          cl_MI
3509                    &#60;cl_modinteger.h&#62;
3510 </PRE>
3511
3512 <P>
3513 Modular integer rings are constructed using the function
3514
3515
3516 <DL COMPACT>
3517
3518 <DT><CODE>cl_modint_ring cl_find_modint_ring (const cl_I&#38; N)</CODE>
3519 <DD>
3520 <A NAME="IDX243"></A>
3521 This function returns the modular ring <SAMP>`Z/NZ'</SAMP>. It takes care
3522 of finding out about special cases of <CODE>N</CODE>, like powers of two
3523 and odd numbers for which Montgomery multiplication will be a win,
3524 <A NAME="IDX244"></A>
3525 and precomputes any necessary auxiliary data for computing modulo <CODE>N</CODE>.
3526 There is a cache table of rings, indexed by <CODE>N</CODE> (or, more precisely,
3527 by <CODE>abs(N)</CODE>). This ensures that the precomputation costs are reduced
3528 to a minimum.
3529 </DL>
3530
3531 <P>
3532 Modular integer rings can be compared for equality:
3533
3534
3535 <DL COMPACT>
3536
3537 <DT><CODE>bool operator== (const cl_modint_ring&#38;, const cl_modint_ring&#38;)</CODE>
3538 <DD>
3539 <A NAME="IDX245"></A>
3540 <DT><CODE>bool operator!= (const cl_modint_ring&#38;, const cl_modint_ring&#38;)</CODE>
3541 <DD>
3542 <A NAME="IDX246"></A>
3543 These compare two modular integer rings for equality. Two different calls
3544 to <CODE>cl_find_modint_ring</CODE> with the same argument necessarily return the
3545 same ring because it is memoized in the cache table.
3546 </DL>
3547
3548
3549
3550 <H2><A NAME="SEC51" HREF="cln.html#TOC51">7.2 Functions on modular integers</A></H2>
3551
3552 <P>
3553 Given a modular integer ring <CODE>R</CODE>, the following members can be used.
3554
3555
3556 <DL COMPACT>
3557
3558 <DT><CODE>cl_I R-&#62;modulus</CODE>
3559 <DD>
3560 <A NAME="IDX247"></A>
3561 This is the ring's modulus, normalized to be nonnegative: <CODE>abs(N)</CODE>.
3562
3563 <DT><CODE>cl_MI R-&#62;zero()</CODE>
3564 <DD>
3565 <A NAME="IDX248"></A>
3566 This returns <CODE>0 mod N</CODE>.
3567
3568 <DT><CODE>cl_MI R-&#62;one()</CODE>
3569 <DD>
3570 <A NAME="IDX249"></A>
3571 This returns <CODE>1 mod N</CODE>.
3572
3573 <DT><CODE>cl_MI R-&#62;canonhom (const cl_I&#38; x)</CODE>
3574 <DD>
3575 <A NAME="IDX250"></A>
3576 This returns <CODE>x mod N</CODE>.
3577
3578 <DT><CODE>cl_I R-&#62;retract (const cl_MI&#38; x)</CODE>
3579 <DD>
3580 <A NAME="IDX251"></A>
3581 This is a partial inverse function to <CODE>R-&#62;canonhom</CODE>. It returns the
3582 standard representative (<CODE>&#62;=0</CODE>, <CODE>&#60;N</CODE>) of <CODE>x</CODE>.
3583
3584 <DT><CODE>cl_MI R-&#62;random(cl_random_state&#38; randomstate)</CODE>
3585 <DD>
3586 <DT><CODE>cl_MI R-&#62;random()</CODE>
3587 <DD>
3588 <A NAME="IDX252"></A>
3589 This returns a random integer modulo <CODE>N</CODE>.
3590 </DL>
3591
3592 <P>
3593 The following operations are defined on modular integers.
3594
3595
3596 <DL COMPACT>
3597
3598 <DT><CODE>cl_modint_ring x.ring ()</CODE>
3599 <DD>
3600 <A NAME="IDX253"></A>
3601 Returns the ring to which the modular integer <CODE>x</CODE> belongs.
3602
3603 <DT><CODE>cl_MI operator+ (const cl_MI&#38;, const cl_MI&#38;)</CODE>
3604 <DD>
3605 <A NAME="IDX254"></A>
3606 Returns the sum of two modular integers. One of the arguments may also be
3607 a plain integer.
3608
3609 <DT><CODE>cl_MI operator- (const cl_MI&#38;, const cl_MI&#38;)</CODE>
3610 <DD>
3611 <A NAME="IDX255"></A>
3612 Returns the difference of two modular integers. One of the arguments may also be
3613 a plain integer.
3614
3615 <DT><CODE>cl_MI operator- (const cl_MI&#38;)</CODE>
3616 <DD>
3617 Returns the negative of a modular integer.
3618
3619 <DT><CODE>cl_MI operator* (const cl_MI&#38;, const cl_MI&#38;)</CODE>
3620 <DD>
3621 <A NAME="IDX256"></A>
3622 Returns the product of two modular integers. One of the arguments may also be
3623 a plain integer.
3624
3625 <DT><CODE>cl_MI square (const cl_MI&#38;)</CODE>
3626 <DD>
3627 <A NAME="IDX257"></A>
3628 Returns the square of a modular integer.
3629
3630 <DT><CODE>cl_MI recip (const cl_MI&#38; x)</CODE>
3631 <DD>
3632 <A NAME="IDX258"></A>
3633 Returns the reciprocal <CODE>x^-1</CODE> of a modular integer <CODE>x</CODE>. <CODE>x</CODE>
3634 must be coprime to the modulus, otherwise an error message is issued.
3635
3636 <DT><CODE>cl_MI div (const cl_MI&#38; x, const cl_MI&#38; y)</CODE>
3637 <DD>
3638 <A NAME="IDX259"></A>
3639 Returns the quotient <CODE>x*y^-1</CODE> of two modular integers <CODE>x</CODE>, <CODE>y</CODE>.
3640 <CODE>y</CODE> must be coprime to the modulus, otherwise an error message is issued.
3641
3642 <DT><CODE>cl_MI expt_pos (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
3643 <DD>
3644 <A NAME="IDX260"></A>
3645 <CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.
3646
3647 <DT><CODE>cl_MI expt (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
3648 <DD>
3649 <A NAME="IDX261"></A>
3650 Returns <CODE>x^y</CODE>. If <CODE>y</CODE> is negative, <CODE>x</CODE> must be coprime to the
3651 modulus, else an error message is issued.
3652
3653 <DT><CODE>cl_MI operator&#60;&#60; (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
3654 <DD>
3655 <A NAME="IDX262"></A>
3656 Returns <CODE>x*2^y</CODE>.
3657
3658 <DT><CODE>cl_MI operator&#62;&#62; (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
3659 <DD>
3660 <A NAME="IDX263"></A>
3661 Returns <CODE>x*2^-y</CODE>. When <CODE>y</CODE> is positive, the modulus must be odd,
3662 or an error message is issued.
3663
3664 <DT><CODE>bool operator== (const cl_MI&#38;, const cl_MI&#38;)</CODE>
3665 <DD>
3666 <A NAME="IDX264"></A>
3667 <DT><CODE>bool operator!= (const cl_MI&#38;, const cl_MI&#38;)</CODE>
3668 <DD>
3669 <A NAME="IDX265"></A>
3670 Compares two modular integers, belonging to the same modular integer ring,
3671 for equality.
3672
3673 <DT><CODE>cl_boolean zerop (const cl_MI&#38; x)</CODE>
3674 <DD>
3675 <A NAME="IDX266"></A>
3676 Returns true if <CODE>x</CODE> is <CODE>0 mod N</CODE>.
3677 </DL>
3678
3679 <P>
3680 The following output functions are defined (see also the chapter on
3681 input/output).
3682
3683
3684 <DL COMPACT>
3685
3686 <DT><CODE>void fprint (cl_ostream stream, const cl_MI&#38; x)</CODE>
3687 <DD>
3688 <A NAME="IDX267"></A>
3689 <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const cl_MI&#38; x)</CODE>
3690 <DD>
3691 <A NAME="IDX268"></A>
3692 Prints the modular integer <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
3693 on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
3694 </DL>
3695
3696
3697
3698 <H1><A NAME="SEC52" HREF="cln.html#TOC52">8. Symbolic data types</A></H1>
3699 <P>
3700 <A NAME="IDX269"></A>
3701
3702
3703 <P>
3704 CLN implements two symbolic (non-numeric) data types: strings and symbols.
3705
3706
3707
3708
3709 <H2><A NAME="SEC53" HREF="cln.html#TOC53">8.1 Strings</A></H2>
3710 <P>
3711 <A NAME="IDX270"></A>
3712
3713
3714 <P>
3715 The class
3716
3717
3718
3719 <PRE>
3720                       String
3721                      cl_string
3722                     &#60;cl_string.h&#62;
3723 </PRE>
3724
3725 <P>
3726 implements immutable strings.
3727
3728
3729 <P>
3730 Strings are constructed through the following constructors:
3731
3732
3733 <DL COMPACT>
3734
3735 <DT><CODE>cl_string (const char * s)</CODE>
3736 <DD>
3737 <A NAME="IDX271"></A>
3738 Returns an immutable copy of the (zero-terminated) C string <CODE>s</CODE>.
3739
3740 <DT><CODE>cl_string (const char * ptr, unsigned long len)</CODE>
3741 <DD>
3742 Returns an immutable copy of the <CODE>len</CODE> characters at
3743 <CODE>ptr[0]</CODE>, ..., <CODE>ptr[len-1]</CODE>. NUL characters are allowed.
3744 </DL>
3745
3746 <P>
3747 The following functions are available on strings:
3748
3749
3750 <DL COMPACT>
3751
3752 <DT><CODE>operator =</CODE>
3753 <DD>
3754 Assignment from <CODE>cl_string</CODE> and <CODE>const char *</CODE>.
3755
3756 <DT><CODE>s.length()</CODE>
3757 <DD>
3758 <A NAME="IDX272"></A>
3759 <DT><CODE>strlen(s)</CODE>
3760 <DD>
3761 <A NAME="IDX273"></A>
3762 Returns the length of the string <CODE>s</CODE>.
3763
3764 <DT><CODE>s[i]</CODE>
3765 <DD>
3766 <A NAME="IDX274"></A>
3767 Returns the <CODE>i</CODE>th character of the string <CODE>s</CODE>.
3768 <CODE>i</CODE> must be in the range <CODE>0 &#60;= i &#60; s.length()</CODE>.
3769
3770 <DT><CODE>bool equal (const cl_string&#38; s1, const cl_string&#38; s2)</CODE>
3771 <DD>
3772 <A NAME="IDX275"></A>
3773 Compares two strings for equality. One of the arguments may also be a
3774 plain <CODE>const char *</CODE>.
3775 </DL>
3776
3777
3778
3779 <H2><A NAME="SEC54" HREF="cln.html#TOC54">8.2 Symbols</A></H2>
3780 <P>
3781 <A NAME="IDX276"></A>
3782
3783
3784 <P>
3785 Symbols are uniquified strings: all symbols with the same name are shared.
3786 This means that comparison of two symbols is fast (effectively just a pointer
3787 comparison), whereas comparison of two strings must in the worst case walk
3788 both strings until their end.
3789 Symbols are used, for example, as tags for properties, as names of variables
3790 in polynomial rings, etc.
3791
3792
3793 <P>
3794 Symbols are constructed through the following constructor:
3795
3796
3797 <DL COMPACT>
3798
3799 <DT><CODE>cl_symbol (const cl_string&#38; s)</CODE>
3800 <DD>
3801 <A NAME="IDX277"></A>
3802 Looks up or creates a new symbol with a given name.
3803 </DL>
3804
3805 <P>
3806 The following operations are available on symbols:
3807
3808
3809 <DL COMPACT>
3810
3811 <DT><CODE>cl_string (const cl_symbol&#38; sym)</CODE>
3812 <DD>
3813 Conversion to <CODE>cl_string</CODE>: Returns the string which names the symbol
3814 <CODE>sym</CODE>.
3815
3816 <DT><CODE>bool equal (const cl_symbol&#38; sym1, const cl_symbol&#38; sym2)</CODE>
3817 <DD>
3818 <A NAME="IDX278"></A>
3819 Compares two symbols for equality. This is very fast.
3820 </DL>
3821
3822
3823
3824 <H1><A NAME="SEC55" HREF="cln.html#TOC55">9. Univariate polynomials</A></H1>
3825 <P>
3826 <A NAME="IDX279"></A>
3827 <A NAME="IDX280"></A>
3828
3829
3830
3831
3832 <H2><A NAME="SEC56" HREF="cln.html#TOC56">9.1 Univariate polynomial rings</A></H2>
3833
3834 <P>
3835 CLN implements univariate polynomials (polynomials in one variable) over an
3836 arbitrary ring. The indeterminate variable may be either unnamed (and will be
3837 printed according to <CODE>cl_default_print_flags.univpoly_varname</CODE>, which
3838 defaults to <SAMP>`x'</SAMP>) or carry a given name. The base ring and the
3839 indeterminate are explicitly part of every polynomial. CLN doesn't allow you to
3840 (accidentally) mix elements of different polynomial rings, e.g.
3841 <CODE>(a^2+1) * (b^3-1)</CODE> will result in a runtime error. (Ideally this should
3842 return a multivariate polynomial, but they are not yet implemented in CLN.)
3843
3844
3845 <P>
3846 The classes of univariate polynomial rings are
3847
3848
3849
3850 <PRE>
3851                            Ring
3852                          cl_ring
3853                         &#60;cl_ring.h&#62;
3854                             |
3855                             |
3856                  Univariate polynomial ring
3857                       cl_univpoly_ring
3858                       &#60;cl_univpoly.h&#62;
3859                             |
3860            +----------------+-------------------+
3861            |                |                   |
3862  Complex polynomial ring    |    Modular integer polynomial ring
3863  cl_univpoly_complex_ring   |        cl_univpoly_modint_ring
3864   &#60;cl_univpoly_complex.h&#62;   |        &#60;cl_univpoly_modint.h&#62;
3865                             |
3866            +----------------+
3867            |                |
3868    Real polynomial ring     |
3869    cl_univpoly_real_ring    |
3870     &#60;cl_univpoly_real.h&#62;    |
3871                             |
3872            +----------------+
3873            |                |
3874  Rational polynomial ring   |
3875  cl_univpoly_rational_ring  |
3876   &#60;cl_univpoly_rational.h&#62;  |
3877                             |
3878            +----------------+
3879            |
3880  Integer polynomial ring
3881  cl_univpoly_integer_ring
3882   &#60;cl_univpoly_integer.h&#62;
3883 </PRE>
3884
3885 <P>
3886 and the corresponding classes of univariate polynomials are
3887
3888
3889
3890 <PRE>
3891                    Univariate polynomial
3892                           cl_UP
3893                       &#60;cl_univpoly.h&#62;
3894                             |
3895            +----------------+-------------------+
3896            |                |                   |
3897    Complex polynomial       |      Modular integer polynomial
3898         cl_UP_N             |                cl_UP_MI
3899   &#60;cl_univpoly_complex.h&#62;   |        &#60;cl_univpoly_modint.h&#62;
3900                             |
3901            +----------------+
3902            |                |
3903      Real polynomial        |
3904         cl_UP_R             |
3905     &#60;cl_univpoly_real.h&#62;    |
3906                             |
3907            +----------------+
3908            |                |
3909    Rational polynomial      |
3910         cl_UP_RA            |
3911   &#60;cl_univpoly_rational.h&#62;  |
3912                             |
3913            +----------------+
3914            |
3915    Integer polynomial
3916         cl_UP_I
3917   &#60;cl_univpoly_integer.h&#62;
3918 </PRE>
3919
3920 <P>
3921 Univariate polynomial rings are constructed using the functions
3922
3923
3924 <DL COMPACT>
3925
3926 <DT><CODE>cl_univpoly_ring cl_find_univpoly_ring (const cl_ring&#38; R)</CODE>
3927 <DD>
3928 <DT><CODE>cl_univpoly_ring cl_find_univpoly_ring (const cl_ring&#38; R, const cl_symbol&#38; varname)</CODE>
3929 <DD>
3930 This function returns the polynomial ring <SAMP>`R[X]'</SAMP>, unnamed or named.
3931 <CODE>R</CODE> may be an arbitrary ring. This function takes care of finding out
3932 about special cases of <CODE>R</CODE>, such as the rings of complex numbers,
3933 real numbers, rational numbers, integers, or modular integer rings.
3934 There is a cache table of rings, indexed by <CODE>R</CODE> and <CODE>varname</CODE>.
3935 This ensures that two calls of this function with the same arguments will
3936 return the same polynomial ring.
3937
3938 <DT><CODE>cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring&#38; R)</CODE>
3939 <DD>
3940 <A NAME="IDX281"></A>
3941 <DT><CODE>cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring&#38; R, const cl_symbol&#38; varname)</CODE>
3942 <DD>
3943 <DT><CODE>cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring&#38; R)</CODE>
3944 <DD>
3945 <DT><CODE>cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring&#38; R, const cl_symbol&#38; varname)</CODE>
3946 <DD>
3947 <DT><CODE>cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring&#38; R)</CODE>
3948 <DD>
3949 <DT><CODE>cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring&#38; R, const cl_symbol&#38; varname)</CODE>
3950 <DD>
3951 <DT><CODE>cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring&#38; R)</CODE>
3952 <DD>
3953 <DT><CODE>cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring&#38; R, const cl_symbol&#38; varname)</CODE>
3954 <DD>
3955 <DT><CODE>cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring&#38; R)</CODE>
3956 <DD>
3957 <DT><CODE>cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring&#38; R, const cl_symbol&#38; varname)</CODE>
3958 <DD>
3959 These functions are equivalent to the general <CODE>cl_find_univpoly_ring</CODE>,
3960 only the return type is more specific, according to the base ring's type.
3961 </DL>
3962
3963
3964
3965 <H2><A NAME="SEC57" HREF="cln.html#TOC57">9.2 Functions on univariate polynomials</A></H2>
3966
3967 <P>
3968 Given a univariate polynomial ring <CODE>R</CODE>, the following members can be used.
3969
3970
3971 <DL COMPACT>
3972
3973 <DT><CODE>cl_ring R-&#62;basering()</CODE>
3974 <DD>
3975 <A NAME="IDX282"></A>
3976 This returns the base ring, as passed to <SAMP>`cl_find_univpoly_ring'</SAMP>.
3977
3978 <DT><CODE>cl_UP R-&#62;zero()</CODE>
3979 <DD>
3980 <A NAME="IDX283"></A>
3981 This returns <CODE>0 in R</CODE>, a polynomial of degree -1.
3982
3983 <DT><CODE>cl_UP R-&#62;one()</CODE>
3984 <DD>
3985 <A NAME="IDX284"></A>
3986 This returns <CODE>1 in R</CODE>, a polynomial of degree &#60;= 0.
3987
3988 <DT><CODE>cl_UP R-&#62;canonhom (const cl_I&#38; x)</CODE>
3989 <DD>
3990 <A NAME="IDX285"></A>
3991 This returns <CODE>x in R</CODE>, a polynomial of degree &#60;= 0.
3992
3993 <DT><CODE>cl_UP R-&#62;monomial (const cl_ring_element&#38; x, uintL e)</CODE>
3994 <DD>
3995 <A NAME="IDX286"></A>
3996 This returns a sparse polynomial: <CODE>x * X^e</CODE>, where <CODE>X</CODE> is the
3997 indeterminate.
3998
3999 <DT><CODE>cl_UP R-&#62;create (sintL degree)</CODE>
4000 <DD>
4001 <A NAME="IDX287"></A>
4002 Creates a new polynomial with a given degree. The zero polynomial has degree
4003 <CODE>-1</CODE>. After creating the polynomial, you should put in the coefficients,
4004 using the <CODE>set_coeff</CODE> member function, and then call the <CODE>finalize</CODE>
4005 member function.
4006 </DL>
4007
4008 <P>
4009 The following are the only destructive operations on univariate polynomials.
4010
4011
4012 <DL COMPACT>
4013
4014 <DT><CODE>void set_coeff (cl_UP&#38; x, uintL index, const cl_ring_element&#38; y)</CODE>
4015 <DD>
4016 <A NAME="IDX288"></A>
4017 This changes the coefficient of <CODE>X^index</CODE> in <CODE>x</CODE> to be <CODE>y</CODE>.
4018 After changing a polynomial and before applying any "normal" operation on it,
4019 you should call its <CODE>finalize</CODE> member function.
4020
4021 <DT><CODE>void finalize (cl_UP&#38; x)</CODE>
4022 <DD>
4023 <A NAME="IDX289"></A>
4024 This function marks the endpoint of destructive modifications of a polynomial.
4025 It normalizes the internal representation so that subsequent computations have
4026 less overhead. Doing normal computations on unnormalized polynomials may
4027 produce wrong results or crash the program.
4028 </DL>
4029
4030 <P>
4031 The following operations are defined on univariate polynomials.
4032
4033
4034 <DL COMPACT>
4035
4036 <DT><CODE>cl_univpoly_ring x.ring ()</CODE>
4037 <DD>
4038 <A NAME="IDX290"></A>
4039 Returns the ring to which the univariate polynomial <CODE>x</CODE> belongs.
4040
4041 <DT><CODE>cl_UP operator+ (const cl_UP&#38;, const cl_UP&#38;)</CODE>
4042 <DD>
4043 <A NAME="IDX291"></A>
4044 Returns the sum of two univariate polynomials.
4045
4046 <DT><CODE>cl_UP operator- (const cl_UP&#38;, const cl_UP&#38;)</CODE>
4047 <DD>
4048 <A NAME="IDX292"></A>
4049 Returns the difference of two univariate polynomials.
4050
4051 <DT><CODE>cl_UP operator- (const cl_UP&#38;)</CODE>
4052 <DD>
4053 Returns the negative of a univariate polynomial.
4054
4055 <DT><CODE>cl_UP operator* (const cl_UP&#38;, const cl_UP&#38;)</CODE>
4056 <DD>
4057 <A NAME="IDX293"></A>
4058 Returns the product of two univariate polynomials. One of the arguments may
4059 also be a plain integer or an element of the base ring.
4060
4061 <DT><CODE>cl_UP square (const cl_UP&#38;)</CODE>
4062 <DD>
4063 <A NAME="IDX294"></A>
4064 Returns the square of a univariate polynomial.
4065
4066 <DT><CODE>cl_UP expt_pos (const cl_UP&#38; x, const cl_I&#38; y)</CODE>
4067 <DD>
4068 <A NAME="IDX295"></A>
4069 <CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.
4070
4071 <DT><CODE>bool operator== (const cl_UP&#38;, const cl_UP&#38;)</CODE>
4072 <DD>
4073 <A NAME="IDX296"></A>
4074 <DT><CODE>bool operator!= (const cl_UP&#38;, const cl_UP&#38;)</CODE>
4075 <DD>
4076 <A NAME="IDX297"></A>
4077 Compares two univariate polynomials, belonging to the same univariate
4078 polynomial ring, for equality.
4079
4080 <DT><CODE>cl_boolean zerop (const cl_UP&#38; x)</CODE>
4081 <DD>
4082 <A NAME="IDX298"></A>
4083 Returns true if <CODE>x</CODE> is <CODE>0 in R</CODE>.
4084
4085 <DT><CODE>sintL degree (const cl_UP&#38; x)</CODE>
4086 <DD>
4087 <A NAME="IDX299"></A>
4088 Returns the degree of the polynomial. The zero polynomial has degree <CODE>-1</CODE>.
4089
4090 <DT><CODE>cl_ring_element coeff (const cl_UP&#38; x, uintL index)</CODE>
4091 <DD>
4092 <A NAME="IDX300"></A>
4093 Returns the coefficient of <CODE>X^index</CODE> in the polynomial <CODE>x</CODE>.
4094
4095 <DT><CODE>cl_ring_element x (const cl_ring_element&#38; y)</CODE>
4096 <DD>
4097 <A NAME="IDX301"></A>
4098 Evaluation: If <CODE>x</CODE> is a polynomial and <CODE>y</CODE> belongs to the base ring,
4099 then <SAMP>`x(y)'</SAMP> returns the value of the substitution of <CODE>y</CODE> into
4100 <CODE>x</CODE>.
4101
4102 <DT><CODE>cl_UP deriv (const cl_UP&#38; x)</CODE>
4103 <DD>
4104 <A NAME="IDX302"></A>
4105 Returns the derivative of the polynomial <CODE>x</CODE> with respect to the
4106 indeterminate <CODE>X</CODE>.
4107 </DL>
4108
4109 <P>
4110 The following output functions are defined (see also the chapter on
4111 input/output).
4112
4113
4114 <DL COMPACT>
4115
4116 <DT><CODE>void fprint (cl_ostream stream, const cl_UP&#38; x)</CODE>
4117 <DD>
4118 <A NAME="IDX303"></A>
4119 <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const cl_UP&#38; x)</CODE>
4120 <DD>
4121 <A NAME="IDX304"></A>
4122 Prints the univariate polynomial <CODE>x</CODE> on the <CODE>stream</CODE>. The output may
4123 depend on the global printer settings in the variable
4124 <CODE>cl_default_print_flags</CODE>.
4125 </DL>
4126
4127
4128
4129 <H2><A NAME="SEC58" HREF="cln.html#TOC58">9.3 Special polynomials</A></H2>
4130
4131 <P>
4132 The following functions return special polynomials.
4133
4134
4135 <DL COMPACT>
4136
4137 <DT><CODE>cl_UP_I cl_tschebychev (sintL n)</CODE>
4138 <DD>
4139 <A NAME="IDX305"></A>
4140 <A NAME="IDX306"></A>
4141 Returns the n-th Tchebychev polynomial (n &#62;= 0).
4142
4143 <DT><CODE>cl_UP_I cl_hermite (sintL n)</CODE>
4144 <DD>
4145 <A NAME="IDX307"></A>
4146 <A NAME="IDX308"></A>
4147 Returns the n-th Hermite polynomial (n &#62;= 0).
4148
4149 <DT><CODE>cl_UP_RA cl_legendre (sintL n)</CODE>
4150 <DD>
4151 <A NAME="IDX309"></A>
4152 <A NAME="IDX310"></A>
4153 Returns the n-th Legendre polynomial (n &#62;= 0).
4154
4155 <DT><CODE>cl_UP_I cl_laguerre (sintL n)</CODE>
4156 <DD>
4157 <A NAME="IDX311"></A>
4158 <A NAME="IDX312"></A>
4159 Returns the n-th Laguerre polynomial (n &#62;= 0).
4160 </DL>
4161
4162 <P>
4163 Information how to derive the differential equation satisfied by each
4164 of these polynomials from their definition can be found in the
4165 <CODE>doc/polynomial/</CODE> directory.
4166
4167
4168
4169
4170 <H1><A NAME="SEC59" HREF="cln.html#TOC59">10. Internals</A></H1>
4171
4172
4173
4174 <H2><A NAME="SEC60" HREF="cln.html#TOC60">10.1 Why C++ ?</A></H2>
4175 <P>
4176 <A NAME="IDX313"></A>
4177
4178
4179 <P>
4180 Using C++ as an implementation language provides
4181
4182
4183
4184 <UL>
4185 <LI>
4186
4187 Efficiency: It compiles to machine code.
4188
4189 <LI>
4190
4191 <A NAME="IDX314"></A>
4192 Portability: It runs on all platforms supporting a C++ compiler. Because
4193 of the availability of GNU C++, this includes all currently used 32-bit and
4194 64-bit platforms, independently of the quality of the vendor's C++ compiler.
4195
4196 <LI>
4197
4198 Type safety: The C++ compilers knows about the number types and complains if,
4199 for example, you try to assign a float to an integer variable. However,
4200 a drawback is that C++ doesn't know about generic types, hence a restriction
4201 like that <CODE>operator+ (const cl_MI&#38;, const cl_MI&#38;)</CODE> requires that both
4202 arguments belong to the same modular ring cannot be expressed as a compile-time
4203 information.
4204
4205 <LI>
4206
4207 Algebraic syntax: The elementary operations <CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>,
4208 <CODE>=</CODE>, <CODE>==</CODE>, ... can be used in infix notation, which is more
4209 convenient than Lisp notation <SAMP>`(+ x y)'</SAMP> or C notation <SAMP>`add(x,y,&#38;z)'</SAMP>.
4210 </UL>
4211
4212 <P>
4213 With these language features, there is no need for two separate languages,
4214 one for the implementation of the library and one in which the library's users
4215 can program. This means that a prototype implementation of an algorithm
4216 can be integrated into the library immediately after it has been tested and
4217 debugged. No need to rewrite it in a low-level language after having prototyped
4218 in a high-level language.
4219
4220
4221
4222
4223 <H2><A NAME="SEC61" HREF="cln.html#TOC61">10.2 Memory efficiency</A></H2>
4224
4225 <P>
4226 In order to save memory allocations, CLN implements:
4227
4228
4229
4230 <UL>
4231 <LI>
4232
4233 Object sharing: An operation like <CODE>x+0</CODE> returns <CODE>x</CODE> without copying
4234 it.
4235 <LI>
4236
4237 <A NAME="IDX315"></A>
4238 <A NAME="IDX316"></A>
4239 Garbage collection: A reference counting mechanism makes sure that any
4240 number object's storage is freed immediately when the last reference to the
4241 object is gone.
4242 <LI>
4243
4244 Small integers are represented as immediate values instead of pointers
4245 to heap allocated storage. This means that integers <CODE>&#62; -2^29</CODE>,
4246 <CODE>&#60; 2^29</CODE> don't consume heap memory, unless they were explicitly allocated
4247 on the heap.
4248 </UL>
4249
4250
4251
4252 <H2><A NAME="SEC62" HREF="cln.html#TOC62">10.3 Speed efficiency</A></H2>
4253
4254 <P>
4255 Speed efficiency is obtained by the combination of the following tricks
4256 and algorithms:
4257
4258
4259
4260 <UL>
4261 <LI>
4262
4263 Small integers, being represented as immediate values, don't require
4264 memory access, just a couple of instructions for each elementary operation.
4265 <LI>
4266
4267 The kernel of CLN has been written in assembly language for some CPUs
4268 (<CODE>i386</CODE>, <CODE>m68k</CODE>, <CODE>sparc</CODE>, <CODE>mips</CODE>, <CODE>arm</CODE>).
4269 <LI>
4270
4271 On all CPUs, CLN may be configured to use the superefficient low-level
4272 routines from GNU GMP version 3.
4273 <LI>
4274
4275 For large numbers, CLN uses, instead of the standard <CODE>O(N^2)</CODE>
4276 algorithm, the Karatsuba multiplication, which is an
4277 <CODE>O(N^1.6)</CODE>
4278 algorithm.
4279 <LI>
4280
4281 For very large numbers (more than 12000 decimal digits), CLN uses
4282 Schönhage-Strassen
4283 <A NAME="IDX317"></A>
4284 multiplication, which is an asymptotically optimal multiplication
4285 algorithm.
4286 <LI>
4287
4288 These fast multiplication algorithms also give improvements in the speed
4289 of division and radix conversion.
4290 </UL>
4291
4292
4293
4294 <H2><A NAME="SEC63" HREF="cln.html#TOC63">10.4 Garbage collection</A></H2>
4295 <P>
4296 <A NAME="IDX318"></A>
4297
4298
4299 <P>
4300 All the number classes are reference count classes: They only contain a pointer
4301 to an object in the heap. Upon construction, assignment and destruction of
4302 number objects, only the objects' reference count are manipulated.
4303
4304
4305 <P>
4306 Memory occupied by number objects are automatically reclaimed as soon as
4307 their reference count drops to zero.
4308
4309
4310 <P>
4311 For number rings, another strategy is implemented: There is a cache of,
4312 for example, the modular integer rings. A modular integer ring is destroyed
4313 only if its reference count dropped to zero and the cache is about to be
4314 resized. The effect of this strategy is that recently used rings remain
4315 cached, whereas undue memory consumption through cached rings is avoided.
4316
4317
4318
4319
4320 <H1><A NAME="SEC64" HREF="cln.html#TOC64">11. Using the library</A></H1>
4321
4322 <P>
4323 For the following discussion, we will assume that you have installed
4324 the CLN source in <CODE>$CLN_DIR</CODE> and built it in <CODE>$CLN_TARGETDIR</CODE>.
4325 For example, for me it's <CODE>CLN_DIR="$HOME/cln"</CODE> and
4326 <CODE>CLN_TARGETDIR="$HOME/cln/linuxelf"</CODE>. You might define these as
4327 environment variables, or directly substitute the appropriate values.
4328
4329
4330
4331
4332 <H2><A NAME="SEC65" HREF="cln.html#TOC65">11.1 Compiler options</A></H2>
4333 <P>
4334 <A NAME="IDX319"></A>
4335
4336
4337 <P>
4338 Until you have installed CLN in a public place, the following options are
4339 needed:
4340
4341
4342 <P>
4343 When you compile CLN application code, add the flags
4344
4345 <PRE>
4346    -I$CLN_DIR/include -I$CLN_TARGETDIR/include
4347 </PRE>
4348
4349 <P>
4350 to the C++ compiler's command line (<CODE>make</CODE> variable CFLAGS or CXXFLAGS).
4351 When you link CLN application code to form an executable, add the flags
4352
4353 <PRE>
4354    $CLN_TARGETDIR/src/libcln.a
4355 </PRE>
4356
4357 <P>
4358 to the C/C++ compiler's command line (<CODE>make</CODE> variable LIBS).
4359
4360
4361 <P>
4362 If you did a <CODE>make install</CODE>, the include files are installed in a
4363 public directory (normally <CODE>/usr/local/include</CODE>), hence you don't
4364 need special flags for compiling. The library has been installed to a
4365 public directory as well (normally <CODE>/usr/local/lib</CODE>), hence when
4366 linking a CLN application it is sufficient to give the flag <CODE>-lcln</CODE>.
4367
4368
4369
4370
4371 <H2><A NAME="SEC66" HREF="cln.html#TOC66">11.2 Include files</A></H2>
4372 <P>
4373 <A NAME="IDX320"></A>
4374 <A NAME="IDX321"></A>
4375
4376
4377 <P>
4378 Here is a summary of the include files and their contents.
4379
4380
4381 <DL COMPACT>
4382
4383 <DT><CODE>&#60;cl_object.h&#62;</CODE>
4384 <DD>
4385 General definitions, reference counting, garbage collection.
4386 <DT><CODE>&#60;cl_number.h&#62;</CODE>
4387 <DD>
4388 The class cl_number.
4389 <DT><CODE>&#60;cl_complex.h&#62;</CODE>
4390 <DD>
4391 Functions for class cl_N, the complex numbers.
4392 <DT><CODE>&#60;cl_real.h&#62;</CODE>
4393 <DD>
4394 Functions for class cl_R, the real numbers.
4395 <DT><CODE>&#60;cl_float.h&#62;</CODE>
4396 <DD>
4397 Functions for class cl_F, the floats.
4398 <DT><CODE>&#60;cl_sfloat.h&#62;</CODE>
4399 <DD>
4400 Functions for class cl_SF, the short-floats.
4401 <DT><CODE>&#60;cl_ffloat.h&#62;</CODE>
4402 <DD>
4403 Functions for class cl_FF, the single-floats.
4404 <DT><CODE>&#60;cl_dfloat.h&#62;</CODE>
4405 <DD>
4406 Functions for class cl_DF, the double-floats.
4407 <DT><CODE>&#60;cl_lfloat.h&#62;</CODE>
4408 <DD>
4409 Functions for class cl_LF, the long-floats.
4410 <DT><CODE>&#60;cl_rational.h&#62;</CODE>
4411 <DD>
4412 Functions for class cl_RA, the rational numbers.
4413 <DT><CODE>&#60;cl_integer.h&#62;</CODE>
4414 <DD>
4415 Functions for class cl_I, the integers.
4416 <DT><CODE>&#60;cl_io.h&#62;</CODE>
4417 <DD>
4418 Input/Output.
4419 <DT><CODE>&#60;cl_complex_io.h&#62;</CODE>
4420 <DD>
4421 Input/Output for class cl_N, the complex numbers.
4422 <DT><CODE>&#60;cl_real_io.h&#62;</CODE>
4423 <DD>
4424 Input/Output for class cl_R, the real numbers.
4425 <DT><CODE>&#60;cl_float_io.h&#62;</CODE>
4426 <DD>
4427 Input/Output for class cl_F, the floats.
4428 <DT><CODE>&#60;cl_sfloat_io.h&#62;</CODE>
4429 <DD>
4430 Input/Output for class cl_SF, the short-floats.
4431 <DT><CODE>&#60;cl_ffloat_io.h&#62;</CODE>
4432 <DD>
4433 Input/Output for class cl_FF, the single-floats.
4434 <DT><CODE>&#60;cl_dfloat_io.h&#62;</CODE>
4435 <DD>
4436 Input/Output for class cl_DF, the double-floats.
4437 <DT><CODE>&#60;cl_lfloat_io.h&#62;</CODE>
4438 <DD>
4439 Input/Output for class cl_LF, the long-floats.
4440 <DT><CODE>&#60;cl_rational_io.h&#62;</CODE>
4441 <DD>
4442 Input/Output for class cl_RA, the rational numbers.
4443 <DT><CODE>&#60;cl_integer_io.h&#62;</CODE>
4444 <DD>
4445 Input/Output for class cl_I, the integers.
4446 <DT><CODE>&#60;cl_input.h&#62;</CODE>
4447 <DD>
4448 Flags for customizing input operations.
4449 <DT><CODE>&#60;cl_output.h&#62;</CODE>
4450 <DD>
4451 Flags for customizing output operations.
4452 <DT><CODE>&#60;cl_malloc.h&#62;</CODE>
4453 <DD>
4454 <CODE>cl_malloc_hook</CODE>, <CODE>cl_free_hook</CODE>.
4455 <DT><CODE>&#60;cl_abort.h&#62;</CODE>
4456 <DD>
4457 <CODE>cl_abort</CODE>.
4458 <DT><CODE>&#60;cl_condition.h&#62;</CODE>
4459 <DD>
4460 Conditions/exceptions.
4461 <DT><CODE>&#60;cl_string.h&#62;</CODE>
4462 <DD>
4463 Strings.
4464 <DT><CODE>&#60;cl_symbol.h&#62;</CODE>
4465 <DD>
4466 Symbols.
4467 <DT><CODE>&#60;cl_proplist.h&#62;</CODE>
4468 <DD>
4469 Property lists.
4470 <DT><CODE>&#60;cl_ring.h&#62;</CODE>
4471 <DD>
4472 General rings.
4473 <DT><CODE>&#60;cl_null_ring.h&#62;</CODE>
4474 <DD>
4475 The null ring.
4476 <DT><CODE>&#60;cl_complex_ring.h&#62;</CODE>
4477 <DD>
4478 The ring of complex numbers.
4479 <DT><CODE>&#60;cl_real_ring.h&#62;</CODE>
4480 <DD>
4481 The ring of real numbers.
4482 <DT><CODE>&#60;cl_rational_ring.h&#62;</CODE>
4483 <DD>
4484 The ring of rational numbers.
4485 <DT><CODE>&#60;cl_integer_ring.h&#62;</CODE>
4486 <DD>
4487 The ring of integers.
4488 <DT><CODE>&#60;cl_numtheory.h&#62;</CODE>
4489 <DD>
4490 Number threory functions.
4491 <DT><CODE>&#60;cl_modinteger.h&#62;</CODE>
4492 <DD>
4493 Modular integers.
4494 <DT><CODE>&#60;cl_V.h&#62;</CODE>
4495 <DD>
4496 Vectors.
4497 <DT><CODE>&#60;cl_GV.h&#62;</CODE>
4498 <DD>
4499 General vectors.
4500 <DT><CODE>&#60;cl_GV_number.h&#62;</CODE>
4501 <DD>
4502 General vectors over cl_number.
4503 <DT><CODE>&#60;cl_GV_complex.h&#62;</CODE>
4504 <DD>
4505 General vectors over cl_N.
4506 <DT><CODE>&#60;cl_GV_real.h&#62;</CODE>
4507 <DD>
4508 General vectors over cl_R.
4509 <DT><CODE>&#60;cl_GV_rational.h&#62;</CODE>
4510 <DD>
4511 General vectors over cl_RA.
4512 <DT><CODE>&#60;cl_GV_integer.h&#62;</CODE>
4513 <DD>
4514 General vectors over cl_I.
4515 <DT><CODE>&#60;cl_GV_modinteger.h&#62;</CODE>
4516 <DD>
4517 General vectors of modular integers.
4518 <DT><CODE>&#60;cl_SV.h&#62;</CODE>
4519 <DD>
4520 Simple vectors.
4521 <DT><CODE>&#60;cl_SV_number.h&#62;</CODE>
4522 <DD>
4523 Simple vectors over cl_number.
4524 <DT><CODE>&#60;cl_SV_complex.h&#62;</CODE>
4525 <DD>
4526 Simple vectors over cl_N.
4527 <DT><CODE>&#60;cl_SV_real.h&#62;</CODE>
4528 <DD>
4529 Simple vectors over cl_R.
4530 <DT><CODE>&#60;cl_SV_rational.h&#62;</CODE>
4531 <DD>
4532 Simple vectors over cl_RA.
4533 <DT><CODE>&#60;cl_SV_integer.h&#62;</CODE>
4534 <DD>
4535 Simple vectors over cl_I.
4536 <DT><CODE>&#60;cl_SV_ringelt.h&#62;</CODE>
4537 <DD>
4538 Simple vectors of general ring elements.
4539 <DT><CODE>&#60;cl_univpoly.h&#62;</CODE>
4540 <DD>
4541 Univariate polynomials.
4542 <DT><CODE>&#60;cl_univpoly_integer.h&#62;</CODE>
4543 <DD>
4544 Univariate polynomials over the integers.
4545 <DT><CODE>&#60;cl_univpoly_rational.h&#62;</CODE>
4546 <DD>
4547 Univariate polynomials over the rational numbers.
4548 <DT><CODE>&#60;cl_univpoly_real.h&#62;</CODE>
4549 <DD>
4550 Univariate polynomials over the real numbers.
4551 <DT><CODE>&#60;cl_univpoly_complex.h&#62;</CODE>
4552 <DD>
4553 Univariate polynomials over the complex numbers.
4554 <DT><CODE>&#60;cl_univpoly_modint.h&#62;</CODE>
4555 <DD>
4556 Univariate polynomials over modular integer rings.
4557 <DT><CODE>&#60;cl_timing.h&#62;</CODE>
4558 <DD>
4559 Timing facilities.
4560 <DT><CODE>&#60;cln.h&#62;</CODE>
4561 <DD>
4562 Includes all of the above.
4563 </DL>
4564
4565
4566
4567 <H2><A NAME="SEC67" HREF="cln.html#TOC67">11.3 An Example</A></H2>
4568
4569 <P>
4570 A function which computes the nth Fibonacci number can be written as follows.
4571 <A NAME="IDX322"></A>
4572
4573
4574
4575 <PRE>
4576 #include &#60;cl_integer.h&#62;
4577 #include &#60;cl_real.h&#62;
4578
4579 // Returns F_n, computed as the nearest integer to
4580 // ((1+sqrt(5))/2)^n/sqrt(5). Assume n&#62;=0.
4581 const cl_I fibonacci (int n)
4582 {
4583         // Need a precision of ((1+sqrt(5))/2)^-n.
4584         cl_float_format_t prec = cl_float_format((int)(0.208987641*n+5));
4585         cl_R sqrt5 = sqrt(cl_float(5,prec));
4586         cl_R phi = (1+sqrt5)/2;
4587         return round1( expt(phi,n)/sqrt5 );
4588 }
4589 </PRE>
4590
4591 <P>
4592 Let's explain what is going on in detail.
4593
4594
4595 <P>
4596 The include file <CODE>&#60;cl_integer.h&#62;</CODE> is necessary because the type
4597 <CODE>cl_I</CODE> is used in the function, and the include file <CODE>&#60;cl_real.h&#62;</CODE>
4598 is needed for the type <CODE>cl_R</CODE> and the floating point number functions.
4599 The order of the include files does not matter.
4600
4601
4602 <P>
4603 Then comes the function declaration. The argument is an <CODE>int</CODE>, the
4604 result an integer. The return type is defined as <SAMP>`const cl_I'</SAMP>, not
4605 simply <SAMP>`cl_I'</SAMP>, because that allows the compiler to detect typos like
4606 <SAMP>`fibonacci(n) = 100'</SAMP>. It would be possible to declare the return
4607 type as <CODE>const cl_R</CODE> (real number) or even <CODE>const cl_N</CODE> (complex
4608 number). We use the most specialized possible return type because functions
4609 which call <SAMP>`fibonacci'</SAMP> will be able to profit from the compiler's type
4610 analysis: Adding two integers is slightly more efficient than adding the
4611 same objects declared as complex numbers, because it needs less type
4612 dispatch. Also, when linking to CLN as a non-shared library, this minimizes
4613 the size of the resulting executable program.
4614
4615
4616 <P>
4617 The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
4618 integer. In order to get a correct result, the absolute error should be less
4619 than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
4620 To this end, the first line computes a floating point precision for sqrt(5)
4621 and phi.
4622
4623
4624 <P>
4625 Then sqrt(5) is computed by first converting the integer 5 to a floating point
4626 number and than taking the square root. The converse, first taking the square
4627 root of 5, and then converting to the desired precision, would not work in
4628 CLN: The square root would be computed to a default precision (normally
4629 single-float precision), and the following conversion could not help about
4630 the lacking accuracy. This is because CLN is not a symbolic computer algebra
4631 system and does not represent sqrt(5) in a non-numeric way.
4632
4633
4634 <P>
4635 The type <CODE>cl_R</CODE> for sqrt5 and, in the following line, phi is the only
4636 possible choice. You cannot write <CODE>cl_F</CODE> because the C++ compiler can
4637 only infer that <CODE>cl_float(5,prec)</CODE> is a real number. You cannot write
4638 <CODE>cl_N</CODE> because a <SAMP>`round1'</SAMP> does not exist for general complex
4639 numbers.
4640
4641
4642 <P>
4643 When the function returns, all the local variables in the function are
4644 automatically reclaimed (garbage collected). Only the result survives and
4645 gets passed to the caller.
4646
4647
4648 <P>
4649 The file <CODE>fibonacci.cc</CODE> in the subdirectory <CODE>examples</CODE>
4650 contains this implementation together with an even faster algorithm.
4651
4652
4653
4654
4655 <H2><A NAME="SEC68" HREF="cln.html#TOC68">11.4 Debugging support</A></H2>
4656 <P>
4657 <A NAME="IDX323"></A>
4658
4659
4660 <P>
4661 When debugging a CLN application with GNU <CODE>gdb</CODE>, two facilities are
4662 available from the library:
4663
4664
4665
4666 <UL>
4667 <LI>The library does type checks, range checks, consistency checks at
4668
4669 many places. When one of these fails, the function <CODE>cl_abort()</CODE> is
4670 called. Its default implementation is to perform an <CODE>exit(1)</CODE>, so
4671 you won't have a core dump. But for debugging, it is best to set a
4672 breakpoint at this function:
4673
4674 <PRE>
4675 (gdb) break cl_abort
4676 </PRE>
4677
4678 When this breakpoint is hit, look at the stack's backtrace:
4679
4680 <PRE>
4681 (gdb) where
4682 </PRE>
4683
4684 <LI>The debugger's normal <CODE>print</CODE> command doesn't know about
4685
4686 CLN's types and therefore prints mostly useless hexadecimal addresses.
4687 CLN offers a function <CODE>cl_print</CODE>, callable from the debugger,
4688 for printing number objects. In order to get this function, you have
4689 to define the macro <SAMP>`CL_DEBUG'</SAMP> and then include all the header files
4690 for which you want <CODE>cl_print</CODE> debugging support. For example:
4691 <A NAME="IDX324"></A>
4692
4693 <PRE>
4694 #define CL_DEBUG
4695 #include &#60;cl_string.h&#62;
4696 </PRE>
4697
4698 Now, if you have in your program a variable <CODE>cl_string s</CODE>, and
4699 inspect it under <CODE>gdb</CODE>, the output may look like this:
4700
4701 <PRE>
4702 (gdb) print s
4703 $7 = {&#60;cl_gcpointer&#62; = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
4704   word = 134568800}}, }
4705 (gdb) call cl_print(s)
4706 (cl_string) ""
4707 $8 = 134568800
4708 </PRE>
4709
4710 Note that the output of <CODE>cl_print</CODE> goes to the program's error output,
4711 not to gdb's standard output.
4712
4713 Note, however, that the above facility does not work with all CLN types,
4714 only with number objects and similar. Therefore CLN offers a member function
4715 <CODE>debug_print()</CODE> on all CLN types. The same macro <SAMP>`CL_DEBUG'</SAMP>
4716 is needed for this member function to be implemented. Under <CODE>gdb</CODE>,
4717 you call it like this:
4718 <A NAME="IDX325"></A>
4719
4720 <PRE>
4721 (gdb) print s
4722 $7 = {&#60;cl_gcpointer&#62; = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
4723   word = 134568800}}, }
4724 (gdb) call s.debug_print()
4725 (cl_string) ""
4726 (gdb) define cprint
4727 &#62;call ($1).debug_print()
4728 &#62;end
4729 (gdb) cprint s
4730 (cl_string) ""
4731 </PRE>
4732
4733 Unfortunately, this feature does not seem to work under all circumstances.
4734 </UL>
4735
4736
4737
4738 <H1><A NAME="SEC69" HREF="cln.html#TOC69">12. Customizing</A></H1>
4739 <P>
4740 <A NAME="IDX326"></A>
4741
4742
4743
4744
4745 <H2><A NAME="SEC70" HREF="cln.html#TOC70">12.1 Error handling</A></H2>
4746
4747 <P>
4748 When a fatal error occurs, an error message is output to the standard error
4749 output stream, and the function <CODE>cl_abort</CODE> is called. The default
4750 version of this function (provided in the library) terminates the application.
4751 To catch such a fatal error, you need to define the function <CODE>cl_abort</CODE>
4752 yourself, with the prototype
4753
4754 <PRE>
4755 #include &#60;cl_abort.h&#62;
4756 void cl_abort (void);
4757 </PRE>
4758
4759 <P>
4760 <A NAME="IDX327"></A>
4761 This function must not return control to its caller.
4762
4763
4764
4765
4766 <H2><A NAME="SEC71" HREF="cln.html#TOC71">12.2 Floating-point underflow</A></H2>
4767 <P>
4768 <A NAME="IDX328"></A>
4769
4770
4771 <P>
4772 Floating point underflow denotes the situation when a floating-point number
4773 is to be created which is so close to <CODE>0</CODE> that its exponent is too
4774 low to be represented internally. By default, this causes a fatal error.
4775 If you set the global variable
4776
4777 <PRE>
4778 cl_boolean cl_inhibit_floating_point_underflow
4779 </PRE>
4780
4781 <P>
4782 to <CODE>cl_true</CODE>, the error will be inhibited, and a floating-point zero
4783 will be generated instead.  The default value of
4784 <CODE>cl_inhibit_floating_point_underflow</CODE> is <CODE>cl_false</CODE>.
4785
4786
4787
4788
4789 <H2><A NAME="SEC72" HREF="cln.html#TOC72">12.3 Customizing I/O</A></H2>
4790
4791 <P>
4792 The output of the function <CODE>fprint</CODE> may be customized by changing the
4793 value of the global variable <CODE>cl_default_print_flags</CODE>.
4794 <A NAME="IDX329"></A>
4795
4796
4797
4798
4799 <H2><A NAME="SEC73" HREF="cln.html#TOC73">12.4 Customizing the memory allocator</A></H2>
4800
4801 <P>
4802 Every memory allocation of CLN is done through the function pointer
4803 <CODE>cl_malloc_hook</CODE>. Freeing of this memory is done through the function
4804 pointer <CODE>cl_free_hook</CODE>. The default versions of these functions,
4805 provided in the library, call <CODE>malloc</CODE> and <CODE>free</CODE> and check
4806 the <CODE>malloc</CODE> result against <CODE>NULL</CODE>.
4807 If you want to provide another memory allocator, you need to define
4808 the variables <CODE>cl_malloc_hook</CODE> and <CODE>cl_free_hook</CODE> yourself,
4809 like this:
4810
4811 <PRE>
4812 #include &#60;cl_malloc.h&#62;
4813 void* (*cl_malloc_hook) (size_t size) = ...;
4814 void (*cl_free_hook) (void* ptr)      = ...;
4815 </PRE>
4816
4817 <P>
4818 <A NAME="IDX330"></A>
4819 <A NAME="IDX331"></A>
4820 The <CODE>cl_malloc_hook</CODE> function must not return a <CODE>NULL</CODE> pointer.
4821
4822
4823 <P>
4824 It is not possible to change the memory allocator at runtime, because
4825 it is already called at program startup by the constructors of some
4826 global variables.
4827
4828
4829
4830
4831 <H1><A NAME="SEC74" HREF="cln.html#TOC74">Index</A></H1>
4832
4833 <P>
4834 Jump to:
4835 <P>
4836
4837
4838 <P><HR><P>
4839 This document was generated on 5 May 2000 using
4840 <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.
4841 </BODY>
4842 </HTML>