doc/cln.html

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