You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

4422 lines
135 KiB

25 years ago
  1. <HTML>
  2. <HEAD>
  3. <!-- Created by texi2html 1.56k from cln.texi on 14 January 2000 -->
  4. <TITLE>CLN, a Class Library for Numbers</TITLE>
  5. </HEAD>
  6. <BODY>
  7. <H1>CLN, a Class Library for Numbers</H1>
  8. <ADDRESS>by Bruno Haible</ADDRESS>
  9. <P>
  10. <P><HR><P>
  11. <H1>Table of Contents</H1>
  12. <UL>
  13. <LI><A NAME="TOC1" HREF="cln.html#SEC1">1. Introduction</A>
  14. <LI><A NAME="TOC2" HREF="cln.html#SEC2">2. Installation</A>
  15. <UL>
  16. <LI><A NAME="TOC3" HREF="cln.html#SEC3">2.1 Prerequisites</A>
  17. <UL>
  18. <LI><A NAME="TOC4" HREF="cln.html#SEC4">2.1.1 C++ compiler</A>
  19. <LI><A NAME="TOC5" HREF="cln.html#SEC5">2.1.2 Make utility</A>
  20. <LI><A NAME="TOC6" HREF="cln.html#SEC6">2.1.3 Sed utility</A>
  21. </UL>
  22. <LI><A NAME="TOC7" HREF="cln.html#SEC7">2.2 Building the library</A>
  23. <LI><A NAME="TOC8" HREF="cln.html#SEC8">2.3 Installing the library</A>
  24. <LI><A NAME="TOC9" HREF="cln.html#SEC9">2.4 Cleaning up</A>
  25. </UL>
  26. <LI><A NAME="TOC10" HREF="cln.html#SEC10">3. Ordinary number types</A>
  27. <UL>
  28. <LI><A NAME="TOC11" HREF="cln.html#SEC11">3.1 Exact numbers</A>
  29. <LI><A NAME="TOC12" HREF="cln.html#SEC12">3.2 Floating-point numbers</A>
  30. <LI><A NAME="TOC13" HREF="cln.html#SEC13">3.3 Complex numbers</A>
  31. <LI><A NAME="TOC14" HREF="cln.html#SEC14">3.4 Conversions</A>
  32. </UL>
  33. <LI><A NAME="TOC15" HREF="cln.html#SEC15">4. Functions on numbers</A>
  34. <UL>
  35. <LI><A NAME="TOC16" HREF="cln.html#SEC16">4.1 Constructing numbers</A>
  36. <UL>
  37. <LI><A NAME="TOC17" HREF="cln.html#SEC17">4.1.1 Constructing integers</A>
  38. <LI><A NAME="TOC18" HREF="cln.html#SEC18">4.1.2 Constructing rational numbers</A>
  39. <LI><A NAME="TOC19" HREF="cln.html#SEC19">4.1.3 Constructing floating-point numbers</A>
  40. <LI><A NAME="TOC20" HREF="cln.html#SEC20">4.1.4 Constructing complex numbers</A>
  41. </UL>
  42. <LI><A NAME="TOC21" HREF="cln.html#SEC21">4.2 Elementary functions</A>
  43. <LI><A NAME="TOC22" HREF="cln.html#SEC22">4.3 Elementary rational functions</A>
  44. <LI><A NAME="TOC23" HREF="cln.html#SEC23">4.4 Elementary complex functions</A>
  45. <LI><A NAME="TOC24" HREF="cln.html#SEC24">4.5 Comparisons</A>
  46. <LI><A NAME="TOC25" HREF="cln.html#SEC25">4.6 Rounding functions</A>
  47. <LI><A NAME="TOC26" HREF="cln.html#SEC26">4.7 Roots</A>
  48. <LI><A NAME="TOC27" HREF="cln.html#SEC27">4.8 Transcendental functions</A>
  49. <UL>
  50. <LI><A NAME="TOC28" HREF="cln.html#SEC28">4.8.1 Exponential and logarithmic functions</A>
  51. <LI><A NAME="TOC29" HREF="cln.html#SEC29">4.8.2 Trigonometric functions</A>
  52. <LI><A NAME="TOC30" HREF="cln.html#SEC30">4.8.3 Hyperbolic functions</A>
  53. <LI><A NAME="TOC31" HREF="cln.html#SEC31">4.8.4 Euler gamma</A>
  54. <LI><A NAME="TOC32" HREF="cln.html#SEC32">4.8.5 Riemann zeta</A>
  55. </UL>
  56. <LI><A NAME="TOC33" HREF="cln.html#SEC33">4.9 Functions on integers</A>
  57. <UL>
  58. <LI><A NAME="TOC34" HREF="cln.html#SEC34">4.9.1 Logical functions</A>
  59. <LI><A NAME="TOC35" HREF="cln.html#SEC35">4.9.2 Number theoretic functions</A>
  60. <LI><A NAME="TOC36" HREF="cln.html#SEC36">4.9.3 Combinatorial functions</A>
  61. </UL>
  62. <LI><A NAME="TOC37" HREF="cln.html#SEC37">4.10 Functions on floating-point numbers</A>
  63. <LI><A NAME="TOC38" HREF="cln.html#SEC38">4.11 Conversion functions</A>
  64. <UL>
  65. <LI><A NAME="TOC39" HREF="cln.html#SEC39">4.11.1 Conversion to floating-point numbers</A>
  66. <LI><A NAME="TOC40" HREF="cln.html#SEC40">4.11.2 Conversion to rational numbers</A>
  67. </UL>
  68. <LI><A NAME="TOC41" HREF="cln.html#SEC41">4.12 Random number generators</A>
  69. <LI><A NAME="TOC42" HREF="cln.html#SEC42">4.13 Obfuscating operators</A>
  70. </UL>
  71. <LI><A NAME="TOC43" HREF="cln.html#SEC43">5. Input/Output</A>
  72. <UL>
  73. <LI><A NAME="TOC44" HREF="cln.html#SEC44">5.1 Internal and printed representation</A>
  74. <LI><A NAME="TOC45" HREF="cln.html#SEC45">5.2 Input functions</A>
  75. <LI><A NAME="TOC46" HREF="cln.html#SEC46">5.3 Output functions</A>
  76. </UL>
  77. <LI><A NAME="TOC47" HREF="cln.html#SEC47">6. Rings</A>
  78. <LI><A NAME="TOC48" HREF="cln.html#SEC48">7. Modular integers</A>
  79. <UL>
  80. <LI><A NAME="TOC49" HREF="cln.html#SEC49">7.1 Modular integer rings</A>
  81. <LI><A NAME="TOC50" HREF="cln.html#SEC50">7.2 Functions on modular integers</A>
  82. </UL>
  83. <LI><A NAME="TOC51" HREF="cln.html#SEC51">8. Symbolic data types</A>
  84. <UL>
  85. <LI><A NAME="TOC52" HREF="cln.html#SEC52">8.1 Strings</A>
  86. <LI><A NAME="TOC53" HREF="cln.html#SEC53">8.2 Symbols</A>
  87. </UL>
  88. <LI><A NAME="TOC54" HREF="cln.html#SEC54">9. Univariate polynomials</A>
  89. <UL>
  90. <LI><A NAME="TOC55" HREF="cln.html#SEC55">9.1 Univariate polynomial rings</A>
  91. <LI><A NAME="TOC56" HREF="cln.html#SEC56">9.2 Functions on univariate polynomials</A>
  92. <LI><A NAME="TOC57" HREF="cln.html#SEC57">9.3 Special polynomials</A>
  93. </UL>
  94. <LI><A NAME="TOC58" HREF="cln.html#SEC58">10. Internals</A>
  95. <UL>
  96. <LI><A NAME="TOC59" HREF="cln.html#SEC59">10.1 Why C++ ?</A>
  97. <LI><A NAME="TOC60" HREF="cln.html#SEC60">10.2 Memory efficiency</A>
  98. <LI><A NAME="TOC61" HREF="cln.html#SEC61">10.3 Speed efficiency</A>
  99. <LI><A NAME="TOC62" HREF="cln.html#SEC62">10.4 Garbage collection</A>
  100. </UL>
  101. <LI><A NAME="TOC63" HREF="cln.html#SEC63">11. Using the library</A>
  102. <UL>
  103. <LI><A NAME="TOC64" HREF="cln.html#SEC64">11.1 Compiler options</A>
  104. <LI><A NAME="TOC65" HREF="cln.html#SEC65">11.2 Include files</A>
  105. <LI><A NAME="TOC66" HREF="cln.html#SEC66">11.3 An Example</A>
  106. <LI><A NAME="TOC67" HREF="cln.html#SEC67">11.4 Debugging support</A>
  107. </UL>
  108. <LI><A NAME="TOC68" HREF="cln.html#SEC68">12. Customizing</A>
  109. <UL>
  110. <LI><A NAME="TOC69" HREF="cln.html#SEC69">12.1 Error handling</A>
  111. <LI><A NAME="TOC70" HREF="cln.html#SEC70">12.2 Floating-point underflow</A>
  112. <LI><A NAME="TOC71" HREF="cln.html#SEC71">12.3 Customizing I/O</A>
  113. <LI><A NAME="TOC72" HREF="cln.html#SEC72">12.4 Customizing the memory allocator</A>
  114. </UL>
  115. <LI><A NAME="TOC73" HREF="cln.html#SEC73">Index</A>
  116. </UL>
  117. <P><HR><P>
  118. <H1><A NAME="SEC1" HREF="cln.html#TOC1">1. Introduction</A></H1>
  119. <P>
  120. CLN is a library for computations with all kinds of numbers.
  121. It has a rich set of number classes:
  122. <UL>
  123. <LI>
  124. Integers (with unlimited precision),
  125. <LI>
  126. Rational numbers,
  127. <LI>
  128. Floating-point numbers:
  129. <UL>
  130. <LI>
  131. Short float,
  132. <LI>
  133. Single float,
  134. <LI>
  135. Double float,
  136. <LI>
  137. Long float (with unlimited precision),
  138. </UL>
  139. <LI>
  140. Complex numbers,
  141. <LI>
  142. Modular integers (integers modulo a fixed integer),
  143. <LI>
  144. Univariate polynomials.
  145. </UL>
  146. <P>
  147. The subtypes of the complex numbers among these are exactly the
  148. types of numbers known to the Common Lisp language. Therefore
  149. <CODE>CLN</CODE> can be used for Common Lisp implementations, giving
  150. <SAMP>`CLN'</SAMP> another meaning: it becomes an abbreviation of
  151. "Common Lisp Numbers".
  152. <P>
  153. The CLN package implements
  154. <UL>
  155. <LI>
  156. Elementary functions (<CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, <CODE>sqrt</CODE>,
  157. comparisons, ...),
  158. <LI>
  159. Logical functions (logical <CODE>and</CODE>, <CODE>or</CODE>, <CODE>not</CODE>, ...),
  160. <LI>
  161. Transcendental functions (exponential, logarithmic, trigonometric, hyperbolic
  162. functions and their inverse functions).
  163. </UL>
  164. <P>
  165. CLN is a C++ library. Using C++ as an implementation language provides
  166. <UL>
  167. <LI>
  168. efficiency: it compiles to machine code,
  169. <LI>
  170. type safety: the C++ compiler knows about the number types and complains
  171. if, for example, you try to assign a float to an integer variable.
  172. <LI>
  173. algebraic syntax: You can use the <CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>=</CODE>,
  174. <CODE>==</CODE>, ... operators as in C or C++.
  175. </UL>
  176. <P>
  177. CLN is memory efficient:
  178. <UL>
  179. <LI>
  180. Small integers and short floats are immediate, not heap allocated.
  181. <LI>
  182. Heap-allocated memory is reclaimed through an automatic, non-interruptive
  183. garbage collection.
  184. </UL>
  185. <P>
  186. CLN is speed efficient:
  187. <UL>
  188. <LI>
  189. The kernel of CLN has been written in assembly language for some CPUs
  190. (<CODE>i386</CODE>, <CODE>m68k</CODE>, <CODE>sparc</CODE>, <CODE>mips</CODE>, <CODE>arm</CODE>).
  191. <LI>
  192. On all CPUs, CLN uses the superefficient low-level routines from GNU
  193. GMP version 2.
  194. <LI>
  195. It uses Karatsuba multiplication, which is significantly faster
  196. for large numbers than the standard multiplication algorithm.
  197. <LI>
  198. For very large numbers (more than 12000 decimal digits), it uses
  199. Sch�nhage-Strassen
  200. multiplication, which is an asymptotically
  201. optimal multiplication algorithm, for multiplication, division and
  202. radix conversion.
  203. </UL>
  204. <P>
  205. CLN aims at being easily integrated into larger software packages:
  206. <UL>
  207. <LI>
  208. The garbage collection imposes no burden on the main application.
  209. <LI>
  210. The library provides hooks for memory allocation and exceptions.
  211. </UL>
  212. <H1><A NAME="SEC2" HREF="cln.html#TOC2">2. Installation</A></H1>
  213. <P>
  214. This section describes how to install the CLN package on your system.
  215. <H2><A NAME="SEC3" HREF="cln.html#TOC3">2.1 Prerequisites</A></H2>
  216. <H3><A NAME="SEC4" HREF="cln.html#TOC4">2.1.1 C++ compiler</A></H3>
  217. <P>
  218. To build CLN, you need a C++ compiler.
  219. Actually, you need GNU <CODE>g++ 2.7.0</CODE> or newer.
  220. On HPPA, you need GNU <CODE>g++ 2.8.0</CODE> or newer.
  221. I recommend GNU <CODE>egcs 1.1</CODE> or newer.
  222. <P>
  223. The following C++ features are used:
  224. classes, member functions,
  225. overloading of functions and operators,
  226. constructors and destructors, inline, const,
  227. multiple inheritance, templates.
  228. <P>
  229. The following C++ features are not used:
  230. <CODE>new</CODE>, <CODE>delete</CODE>, virtual inheritance,
  231. exceptions.
  232. <P>
  233. CLN relies on semi-automatic ordering of initializations
  234. of static and global variables, a feature which I could
  235. implement for GNU g++ only.
  236. <H3><A NAME="SEC5" HREF="cln.html#TOC5">2.1.2 Make utility</A></H3>
  237. <P>
  238. To build CLN, you also need to have GNU <CODE>make</CODE> installed.
  239. <H3><A NAME="SEC6" HREF="cln.html#TOC6">2.1.3 Sed utility</A></H3>
  240. <P>
  241. To build CLN on HP-UX, you also need to have GNU <CODE>sed</CODE> installed.
  242. This is because the libtool script, which creates the CLN library, relies
  243. on <CODE>sed</CODE>, and the vendor's <CODE>sed</CODE> utility on these systems is too
  244. limited.
  245. <H2><A NAME="SEC7" HREF="cln.html#TOC7">2.2 Building the library</A></H2>
  246. <P>
  247. As with any autoconfiguring GNU software, installation is as easy as this:
  248. <PRE>
  249. $ ./configure
  250. $ make
  251. $ make check
  252. </PRE>
  253. <P>
  254. If on your system, <SAMP>`make'</SAMP> is not GNU <CODE>make</CODE>, you have to use
  255. <SAMP>`gmake'</SAMP> instead of <SAMP>`make'</SAMP> above.
  256. <P>
  257. The <CODE>configure</CODE> command checks out some features of your system and
  258. C++ compiler and builds the <CODE>Makefile</CODE>s. The <CODE>make</CODE> command
  259. builds the library. This step may take 4 hours on an average workstation.
  260. The <CODE>make check</CODE> runs some test to check that no important subroutine
  261. has been miscompiled.
  262. <P>
  263. The <CODE>configure</CODE> command accepts options. To get a summary of them, try
  264. <PRE>
  265. $ ./configure --help
  266. </PRE>
  267. <P>
  268. Some of the options are explained in detail in the <SAMP>`INSTALL.generic'</SAMP> file.
  269. <P>
  270. You can specify the C compiler, the C++ compiler and their options through
  271. the following environment variables when running <CODE>configure</CODE>:
  272. <DL COMPACT>
  273. <DT><CODE>CC</CODE>
  274. <DD>
  275. Specifies the C compiler.
  276. <DT><CODE>CFLAGS</CODE>
  277. <DD>
  278. Flags to be given to the C compiler when compiling programs (not when linking).
  279. <DT><CODE>CXX</CODE>
  280. <DD>
  281. Specifies the C++ compiler.
  282. <DT><CODE>CXXFLAGS</CODE>
  283. <DD>
  284. Flags to be given to the C++ compiler when compiling programs (not when linking).
  285. </DL>
  286. <P>
  287. Examples:
  288. <PRE>
  289. $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
  290. $ CC="gcc -V 2.7.2" CFLAGS="-O -g" \
  291. CXX="g++ -V 2.7.2" CXXFLAGS="-O -g" ./configure
  292. $ CC="gcc -V 2.8.1" CFLAGS="-O -fno-exceptions" \
  293. CXX="g++ -V 2.8.1" CXXFLAGS="-O -fno-exceptions" ./configure
  294. $ CC="gcc -V egcs-2.91.60" CFLAGS="-O2 -fno-exceptions" \
  295. CXX="g++ -V egcs-2.91.60" CFLAGS="-O2 -fno-exceptions" ./configure
  296. </PRE>
  297. <P>
  298. Note that for these environment variables to take effect, you have to set
  299. them (assuming a Bourne-compatible shell) on the same line as the
  300. <CODE>configure</CODE> command. If you made the settings in earlier shell
  301. commands, you have to <CODE>export</CODE> the environment variables before
  302. calling <CODE>configure</CODE>. In a <CODE>csh</CODE> shell, you have to use the
  303. <SAMP>`setenv'</SAMP> command for setting each of the environment variables.
  304. <P>
  305. On Linux, <CODE>g++</CODE> needs 15 MB to compile the tests. So you should better
  306. have 17 MB swap space and 1 MB room in $TMPDIR.
  307. <P>
  308. If you use <CODE>g++</CODE> version 2.7.x, don't add <SAMP>`-O2'</SAMP> to the CXXFLAGS,
  309. because <SAMP>`g++ -O'</SAMP> generates better code for CLN than <SAMP>`g++ -O2'</SAMP>.
  310. <P>
  311. If you use <CODE>g++</CODE> version 2.8.x or egcs-2.91.x (a.k.a. egcs-1.1) or
  312. gcc-2.95.x, I recommend adding <SAMP>`-fno-exceptions'</SAMP> to the CXXFLAGS.
  313. This will likely generate better code.
  314. <P>
  315. If you use <CODE>g++</CODE> version egcs-2.91.x (egcs-1.1) or gcc-2.95.x on Sparc,
  316. add either <SAMP>`-O'</SAMP> or <SAMP>`-O2 -fno-schedule-insns'</SAMP> to the CXXFLAGS.
  317. With full <SAMP>`-O2'</SAMP>, <CODE>g++</CODE> miscompiles the division routines. Also, for
  318. --enable-shared to work, you need egcs-1.1.2 or newer.
  319. <P>
  320. On MIPS (SGI Irix 6), pass option <CODE>--without-gmp</CODE> to configure. gmp does
  321. not work when compiled in <SAMP>`n32'</SAMP> binary format on Irix.
  322. <P>
  323. By default, only a static library is built. You can build CLN as a shared
  324. library too, by calling <CODE>configure</CODE> with the option <SAMP>`--enable-shared'</SAMP>.
  325. To get it built as a shared library only, call <CODE>configure</CODE> with the options
  326. <SAMP>`--enable-shared --disable-static'</SAMP>.
  327. <P>
  328. If you use <CODE>g++</CODE> version egcs-2.91.x (egcs-1.1) on Sparc, you cannot
  329. use <SAMP>`--enable-shared'</SAMP> because <CODE>g++</CODE> would miscompile parts of the
  330. library.
  331. <H2><A NAME="SEC8" HREF="cln.html#TOC8">2.3 Installing the library</A></H2>
  332. <P>
  333. As with any autoconfiguring GNU software, installation is as easy as this:
  334. <PRE>
  335. $ make install
  336. </PRE>
  337. <P>
  338. The <SAMP>`make install'</SAMP> command installs the library and the include files
  339. into public places (<TT>`/usr/local/lib/'</TT> and <TT>`/usr/local/include/'</TT>,
  340. if you haven't specified a <CODE>--prefix</CODE> option to <CODE>configure</CODE>).
  341. This step may require superuser privileges.
  342. <P>
  343. If you have already built the library and wish to install it, but didn't
  344. specify <CODE>--prefix=...</CODE> at configure time, just re-run
  345. <CODE>configure</CODE>, giving it the same options as the first time, plus
  346. the <CODE>--prefix=...</CODE> option.
  347. <H2><A NAME="SEC9" HREF="cln.html#TOC9">2.4 Cleaning up</A></H2>
  348. <P>
  349. You can remove system-dependent files generated by <CODE>make</CODE> through
  350. <PRE>
  351. $ make clean
  352. </PRE>
  353. <P>
  354. You can remove all files generated by <CODE>make</CODE>, thus reverting to a
  355. virgin distribution of CLN, through
  356. <PRE>
  357. $ make distclean
  358. </PRE>
  359. <H1><A NAME="SEC10" HREF="cln.html#TOC10">3. Ordinary number types</A></H1>
  360. <P>
  361. CLN implements the following class hierarchy:
  362. <PRE>
  363. Number
  364. cl_number
  365. &#60;cl_number.h&#62;
  366. |
  367. |
  368. Real or complex number
  369. cl_N
  370. &#60;cl_complex.h&#62;
  371. |
  372. |
  373. Real number
  374. cl_R
  375. &#60;cl_real.h&#62;
  376. |
  377. +-------------------+-------------------+
  378. | |
  379. Rational number Floating-point number
  380. cl_RA cl_F
  381. &#60;cl_rational.h&#62; &#60;cl_float.h&#62;
  382. | |
  383. | +-------------+-------------+-------------+
  384. Integer | | | |
  385. cl_I Short-Float Single-Float Double-Float Long-Float
  386. &#60;cl_integer.h&#62; cl_SF cl_FF cl_DF cl_LF
  387. &#60;cl_sfloat.h&#62; &#60;cl_ffloat.h&#62; &#60;cl_dfloat.h&#62; &#60;cl_lfloat.h&#62;
  388. </PRE>
  389. <P>
  390. The base class <CODE>cl_number</CODE> is an abstract base class.
  391. It is not useful to declare a variable of this type except if you want
  392. to completely disable compile-time type checking and use run-time type
  393. checking instead.
  394. <P>
  395. The class <CODE>cl_N</CODE> comprises real and complex numbers. There is
  396. no special class for complex numbers since complex numbers with imaginary
  397. part <CODE>0</CODE> are automatically converted to real numbers.
  398. <P>
  399. The class <CODE>cl_R</CODE> comprises real numbers of different kinds. It is an
  400. abstract class.
  401. <P>
  402. The class <CODE>cl_RA</CODE> comprises exact real numbers: rational numbers, including
  403. integers. There is no special class for non-integral rational numbers
  404. since rational numbers with denominator <CODE>1</CODE> are automatically converted
  405. to integers.
  406. <P>
  407. The class <CODE>cl_F</CODE> implements floating-point approximations to real numbers.
  408. It is an abstract class.
  409. <H2><A NAME="SEC11" HREF="cln.html#TOC11">3.1 Exact numbers</A></H2>
  410. <P>
  411. Some numbers are represented as exact numbers: there is no loss of information
  412. when such a number is converted from its mathematical value to its internal
  413. representation. On exact numbers, the elementary operations (<CODE>+</CODE>,
  414. <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, comparisons, ...) compute the completely
  415. correct result.
  416. <P>
  417. In CLN, the exact numbers are:
  418. <UL>
  419. <LI>
  420. rational numbers (including integers),
  421. <LI>
  422. complex numbers whose real and imaginary parts are both rational numbers.
  423. </UL>
  424. <P>
  425. Rational numbers are always normalized to the form
  426. <CODE><VAR>numerator</VAR>/<VAR>denominator</VAR></CODE> where the numerator and denominator
  427. are coprime integers and the denominator is positive. If the resulting
  428. denominator is <CODE>1</CODE>, the rational number is converted to an integer.
  429. <P>
  430. Small integers (typically in the range <CODE>-2^30</CODE>...<CODE>2^30-1</CODE>,
  431. for 32-bit machines) are especially efficient, because they consume no heap
  432. allocation. Otherwise the distinction between these immediate integers
  433. (called "fixnums") and heap allocated integers (called "bignums")
  434. is completely transparent.
  435. <H2><A NAME="SEC12" HREF="cln.html#TOC12">3.2 Floating-point numbers</A></H2>
  436. <P>
  437. Not all real numbers can be represented exactly. (There is an easy mathematical
  438. proof for this: Only a countable set of numbers can be stored exactly in
  439. a computer, even if one assumes that it has unlimited storage. But there
  440. are uncountably many real numbers.) So some approximation is needed.
  441. CLN implements ordinary floating-point numbers, with mantissa and exponent.
  442. <P>
  443. The elementary operations (<CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, ...)
  444. only return approximate results. For example, the value of the expression
  445. <CODE>(cl_F) 0.3 + (cl_F) 0.4</CODE> prints as <SAMP>`0.70000005'</SAMP>, not as
  446. <SAMP>`0.7'</SAMP>. Rounding errors like this one are inevitable when computing
  447. with floating-point numbers.
  448. <P>
  449. Nevertheless, CLN rounds the floating-point results of the operations <CODE>+</CODE>,
  450. <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, <CODE>sqrt</CODE> according to the "round-to-even"
  451. rule: It first computes the exact mathematical result and then returns the
  452. floating-point number which is nearest to this. If two floating-point numbers
  453. are equally distant from the ideal result, the one with a <CODE>0</CODE> in its least
  454. significant mantissa bit is chosen.
  455. <P>
  456. Similarly, testing floating point numbers for equality <SAMP>`x == y'</SAMP>
  457. is gambling with random errors. Better check for <SAMP>`abs(x - y) &#60; epsilon'</SAMP>
  458. for some well-chosen <CODE>epsilon</CODE>.
  459. <P>
  460. Floating point numbers come in four flavors:
  461. <UL>
  462. <LI>
  463. Short floats, type <CODE>cl_SF</CODE>.
  464. They have 1 sign bit, 8 exponent bits (including the exponent's sign),
  465. and 17 mantissa bits (including the "hidden" bit).
  466. They don't consume heap allocation.
  467. <LI>
  468. Single floats, type <CODE>cl_FF</CODE>.
  469. They have 1 sign bit, 8 exponent bits (including the exponent's sign),
  470. and 24 mantissa bits (including the "hidden" bit).
  471. In CLN, they are represented as IEEE single-precision floating point numbers.
  472. This corresponds closely to the C/C++ type <SAMP>`float'</SAMP>.
  473. <LI>
  474. Double floats, type <CODE>cl_DF</CODE>.
  475. They have 1 sign bit, 11 exponent bits (including the exponent's sign),
  476. and 53 mantissa bits (including the "hidden" bit).
  477. In CLN, they are represented as IEEE double-precision floating point numbers.
  478. This corresponds closely to the C/C++ type <SAMP>`double'</SAMP>.
  479. <LI>
  480. Long floats, type <CODE>cl_LF</CODE>.
  481. They have 1 sign bit, 32 exponent bits (including the exponent's sign),
  482. and n mantissa bits (including the "hidden" bit), where n &#62;= 64.
  483. The precision of a long float is unlimited, but once created, a long float
  484. has a fixed precision. (No "lazy recomputation".)
  485. </UL>
  486. <P>
  487. Of course, computations with long floats are more expensive than those
  488. with smaller floating-point formats.
  489. <P>
  490. CLN does not implement features like NaNs, denormalized numbers and
  491. gradual underflow. If the exponent range of some floating-point type
  492. is too limited for your application, choose another floating-point type
  493. with larger exponent range.
  494. <P>
  495. As a user of CLN, you can forget about the differences between the
  496. four floating-point types and just declare all your floating-point
  497. variables as being of type <CODE>cl_F</CODE>. This has the advantage that
  498. when you change the precision of some computation (say, from <CODE>cl_DF</CODE>
  499. to <CODE>cl_LF</CODE>), you don't have to change the code, only the precision
  500. of the initial values. Also, many transcendental functions have been
  501. declared as returning a <CODE>cl_F</CODE> when the argument is a <CODE>cl_F</CODE>,
  502. but such declarations are missing for the types <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>,
  503. <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>. (Such declarations would be wrong if
  504. the floating point contagion rule happened to change in the future.)
  505. <H2><A NAME="SEC13" HREF="cln.html#TOC13">3.3 Complex numbers</A></H2>
  506. <P>
  507. Complex numbers, as implemented by the class <CODE>cl_N</CODE>, have a real
  508. part and an imaginary part, both real numbers. A complex number whose
  509. imaginary part is the exact number <CODE>0</CODE> is automatically converted
  510. to a real number.
  511. <P>
  512. Complex numbers can arise from real numbers alone, for example
  513. through application of <CODE>sqrt</CODE> or transcendental functions.
  514. <H2><A NAME="SEC14" HREF="cln.html#TOC14">3.4 Conversions</A></H2>
  515. <P>
  516. Conversions from any class to any its superclasses ("base classes" in
  517. C++ terminology) is done automatically.
  518. <P>
  519. Conversions from the C built-in types <SAMP>`long'</SAMP> and <SAMP>`unsigned long'</SAMP>
  520. are provided for the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_R</CODE>,
  521. <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
  522. <P>
  523. Conversions from the C built-in types <SAMP>`int'</SAMP> and <SAMP>`unsigned int'</SAMP>
  524. are provided for the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_R</CODE>,
  525. <CODE>cl_N</CODE> and <CODE>cl_number</CODE>. However, these conversions emphasize
  526. efficiency. Their range is therefore limited:
  527. <UL>
  528. <LI>
  529. The conversion from <SAMP>`int'</SAMP> works only if the argument is &#60; 2^29 and &#62; -2^29.
  530. <LI>
  531. The conversion from <SAMP>`unsigned int'</SAMP> works only if the argument is &#60; 2^29.
  532. </UL>
  533. <P>
  534. In a declaration like <SAMP>`cl_I x = 10;'</SAMP> the C++ compiler is able to
  535. do the conversion of <CODE>10</CODE> from <SAMP>`int'</SAMP> to <SAMP>`cl_I'</SAMP> at compile time
  536. already. On the other hand, code like <SAMP>`cl_I x = 1000000000;'</SAMP> is
  537. in error.
  538. So, if you want to be sure that an <SAMP>`int'</SAMP> whose magnitude is not guaranteed
  539. to be &#60; 2^29 is correctly converted to a <SAMP>`cl_I'</SAMP>, first convert it to a
  540. <SAMP>`long'</SAMP>. Similarly, if a large <SAMP>`unsigned int'</SAMP> is to be converted to a
  541. <SAMP>`cl_I'</SAMP>, first convert it to an <SAMP>`unsigned long'</SAMP>.
  542. <P>
  543. Conversions from the C built-in type <SAMP>`float'</SAMP> are provided for the classes
  544. <CODE>cl_FF</CODE>, <CODE>cl_F</CODE>, <CODE>cl_R</CODE>, <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
  545. <P>
  546. Conversions from the C built-in type <SAMP>`double'</SAMP> are provided for the classes
  547. <CODE>cl_DF</CODE>, <CODE>cl_F</CODE>, <CODE>cl_R</CODE>, <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
  548. <P>
  549. Conversions from <SAMP>`const char *'</SAMP> are provided for the classes
  550. <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
  551. <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>, <CODE>cl_F</CODE>,
  552. <CODE>cl_R</CODE>, <CODE>cl_N</CODE>.
  553. The easiest way to specify a value which is outside of the range of the
  554. C++ built-in types is therefore to specify it as a string, like this:
  555. <PRE>
  556. cl_I order_of_rubiks_cube_group = "43252003274489856000";
  557. </PRE>
  558. <P>
  559. Note that this conversion is done at runtime, not at compile-time.
  560. <P>
  561. Conversions from <CODE>cl_I</CODE> to the C built-in types <SAMP>`int'</SAMP>,
  562. <SAMP>`unsigned int'</SAMP>, <SAMP>`long'</SAMP>, <SAMP>`unsigned long'</SAMP> are provided through
  563. the functions
  564. <DL COMPACT>
  565. <DT><CODE>int cl_I_to_int (const cl_I&#38; x)</CODE>
  566. <DD>
  567. <DT><CODE>unsigned int cl_I_to_uint (const cl_I&#38; x)</CODE>
  568. <DD>
  569. <DT><CODE>long cl_I_to_long (const cl_I&#38; x)</CODE>
  570. <DD>
  571. <DT><CODE>unsigned long cl_I_to_ulong (const cl_I&#38; x)</CODE>
  572. <DD>
  573. Returns <CODE>x</CODE> as element of the C type <VAR>ctype</VAR>. If <CODE>x</CODE> is not
  574. representable in the range of <VAR>ctype</VAR>, a runtime error occurs.
  575. </DL>
  576. <P>
  577. Conversions from the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
  578. <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>, <CODE>cl_F</CODE> and
  579. <CODE>cl_R</CODE>
  580. to the C built-in types <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP> are provided through
  581. the functions
  582. <DL COMPACT>
  583. <DT><CODE>float cl_float_approx (const <VAR>type</VAR>&#38; x)</CODE>
  584. <DD>
  585. <DT><CODE>double cl_double_approx (const <VAR>type</VAR>&#38; x)</CODE>
  586. <DD>
  587. Returns an approximation of <CODE>x</CODE> of C type <VAR>ctype</VAR>.
  588. If <CODE>abs(x)</CODE> is too close to 0 (underflow), 0 is returned.
  589. If <CODE>abs(x)</CODE> is too large (overflow), an IEEE infinity is returned.
  590. </DL>
  591. <P>
  592. Conversions from any class to any of its subclasses ("derived classes" in
  593. C++ terminology) are not provided. Instead, you can assert and check
  594. that a value belongs to a certain subclass, and return it as element of that
  595. class, using the <SAMP>`As'</SAMP> and <SAMP>`The'</SAMP> macros.
  596. <CODE>As(<VAR>type</VAR>)(<VAR>value</VAR>)</CODE> checks that <VAR>value</VAR> belongs to
  597. <VAR>type</VAR> and returns it as such.
  598. <CODE>The(<VAR>type</VAR>)(<VAR>value</VAR>)</CODE> assumes that <VAR>value</VAR> belongs to
  599. <VAR>type</VAR> and returns it as such. It is your responsibility to ensure
  600. that this assumption is valid.
  601. Example:
  602. <PRE>
  603. cl_I x = ...;
  604. if (!(x &#62;= 0)) abort();
  605. cl_I ten_x = The(cl_I)(expt(10,x)); // If x &#62;= 0, 10^x is an integer.
  606. // In general, it would be a rational number.
  607. </PRE>
  608. <H1><A NAME="SEC15" HREF="cln.html#TOC15">4. Functions on numbers</A></H1>
  609. <P>
  610. Each of the number classes declares its mathematical operations in the
  611. corresponding include file. For example, if your code operates with
  612. objects of type <CODE>cl_I</CODE>, it should <CODE>#include &#60;cl_integer.h&#62;</CODE>.
  613. <H2><A NAME="SEC16" HREF="cln.html#TOC16">4.1 Constructing numbers</A></H2>
  614. <P>
  615. Here is how to create number objects "from nothing".
  616. <H3><A NAME="SEC17" HREF="cln.html#TOC17">4.1.1 Constructing integers</A></H3>
  617. <P>
  618. <CODE>cl_I</CODE> objects are most easily constructed from C integers and from
  619. strings. See section <A HREF="cln.html#SEC14">3.4 Conversions</A>.
  620. <H3><A NAME="SEC18" HREF="cln.html#TOC18">4.1.2 Constructing rational numbers</A></H3>
  621. <P>
  622. <CODE>cl_RA</CODE> objects can be constructed from strings. The syntax
  623. for rational numbers is described in section <A HREF="cln.html#SEC44">5.1 Internal and printed representation</A>.
  624. Another standard way to produce a rational number is through application
  625. of <SAMP>`operator /'</SAMP> or <SAMP>`recip'</SAMP> on integers.
  626. <H3><A NAME="SEC19" HREF="cln.html#TOC19">4.1.3 Constructing floating-point numbers</A></H3>
  627. <P>
  628. <CODE>cl_F</CODE> objects with low precision are most easily constructed from
  629. C <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP>. See section <A HREF="cln.html#SEC14">3.4 Conversions</A>.
  630. <P>
  631. To construct a <CODE>cl_F</CODE> with high precision, you can use the conversion
  632. from <SAMP>`const char *'</SAMP>, but you have to specify the desired precision
  633. within the string. (See section <A HREF="cln.html#SEC44">5.1 Internal and printed representation</A>.)
  634. Example:
  635. <PRE>
  636. cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
  637. </PRE>
  638. <P>
  639. will set <SAMP>`e'</SAMP> to the given value, with a precision of 40 decimal digits.
  640. <P>
  641. The programmatic way to construct a <CODE>cl_F</CODE> with high precision is
  642. through the <CODE>cl_float</CODE> conversion function, see
  643. section <A HREF="cln.html#SEC39">4.11.1 Conversion to floating-point numbers</A>. For example, to compute
  644. <CODE>e</CODE> to 40 decimal places, first construct 1.0 to 40 decimal places
  645. and then apply the exponential function:
  646. <PRE>
  647. cl_float_format_t precision = cl_float_format(40);
  648. cl_F e = exp(cl_float(1,precision));
  649. </PRE>
  650. <H3><A NAME="SEC20" HREF="cln.html#TOC20">4.1.4 Constructing complex numbers</A></H3>
  651. <P>
  652. Non-real <CODE>cl_N</CODE> objects are normally constructed through the function
  653. <PRE>
  654. cl_N complex (const cl_R&#38; realpart, const cl_R&#38; imagpart)
  655. </PRE>
  656. <P>
  657. See section <A HREF="cln.html#SEC23">4.4 Elementary complex functions</A>.
  658. <H2><A NAME="SEC21" HREF="cln.html#TOC21">4.2 Elementary functions</A></H2>
  659. <P>
  660. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  661. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  662. defines the following operations:
  663. <DL COMPACT>
  664. <DT><CODE><VAR>type</VAR> operator + (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  665. <DD>
  666. Addition.
  667. <DT><CODE><VAR>type</VAR> operator - (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  668. <DD>
  669. Subtraction.
  670. <DT><CODE><VAR>type</VAR> operator - (const <VAR>type</VAR>&#38;)</CODE>
  671. <DD>
  672. Returns the negative of the argument.
  673. <DT><CODE><VAR>type</VAR> plus1 (const <VAR>type</VAR>&#38; x)</CODE>
  674. <DD>
  675. Returns <CODE>x + 1</CODE>.
  676. <DT><CODE><VAR>type</VAR> minus1 (const <VAR>type</VAR>&#38; x)</CODE>
  677. <DD>
  678. Returns <CODE>x - 1</CODE>.
  679. <DT><CODE><VAR>type</VAR> operator * (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  680. <DD>
  681. Multiplication.
  682. <DT><CODE><VAR>type</VAR> square (const <VAR>type</VAR>&#38; x)</CODE>
  683. <DD>
  684. Returns <CODE>x * x</CODE>.
  685. </DL>
  686. <P>
  687. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
  688. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  689. defines the following operations:
  690. <DL COMPACT>
  691. <DT><CODE><VAR>type</VAR> operator / (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  692. <DD>
  693. Division.
  694. <DT><CODE><VAR>type</VAR> recip (const <VAR>type</VAR>&#38;)</CODE>
  695. <DD>
  696. Returns the reciprocal of the argument.
  697. </DL>
  698. <P>
  699. The class <CODE>cl_I</CODE> doesn't define a <SAMP>`/'</SAMP> operation because
  700. in the C/C++ language this operator, applied to integral types,
  701. denotes the <SAMP>`floor'</SAMP> or <SAMP>`truncate'</SAMP> operation (which one of these,
  702. is implementation dependent). (See section <A HREF="cln.html#SEC25">4.6 Rounding functions</A>)
  703. Instead, <CODE>cl_I</CODE> defines an "exact quotient" function:
  704. <DL COMPACT>
  705. <DT><CODE>cl_I exquo (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  706. <DD>
  707. Checks that <CODE>y</CODE> divides <CODE>x</CODE>, and returns the quotient <CODE>x</CODE>/<CODE>y</CODE>.
  708. </DL>
  709. <P>
  710. The following exponentiation functions are defined:
  711. <DL COMPACT>
  712. <DT><CODE>cl_I expt_pos (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  713. <DD>
  714. <DT><CODE>cl_RA expt_pos (const cl_RA&#38; x, const cl_I&#38; y)</CODE>
  715. <DD>
  716. <CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.
  717. <DT><CODE>cl_RA expt (const cl_RA&#38; x, const cl_I&#38; y)</CODE>
  718. <DD>
  719. <DT><CODE>cl_R expt (const cl_R&#38; x, const cl_I&#38; y)</CODE>
  720. <DD>
  721. <DT><CODE>cl_N expt (const cl_N&#38; x, const cl_I&#38; y)</CODE>
  722. <DD>
  723. Returns <CODE>x^y</CODE>.
  724. </DL>
  725. <P>
  726. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  727. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  728. defines the following operation:
  729. <DL COMPACT>
  730. <DT><CODE><VAR>type</VAR> abs (const <VAR>type</VAR>&#38; x)</CODE>
  731. <DD>
  732. Returns the absolute value of <CODE>x</CODE>.
  733. This is <CODE>x</CODE> if <CODE>x &#62;= 0</CODE>, and <CODE>-x</CODE> if <CODE>x &#60;= 0</CODE>.
  734. </DL>
  735. <P>
  736. The class <CODE>cl_N</CODE> implements this as follows:
  737. <DL COMPACT>
  738. <DT><CODE>cl_R abs (const cl_N x)</CODE>
  739. <DD>
  740. Returns the absolute value of <CODE>x</CODE>.
  741. </DL>
  742. <P>
  743. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  744. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  745. defines the following operation:
  746. <DL COMPACT>
  747. <DT><CODE><VAR>type</VAR> signum (const <VAR>type</VAR>&#38; x)</CODE>
  748. <DD>
  749. Returns the sign of <CODE>x</CODE>, in the same number format as <CODE>x</CODE>.
  750. This is defined as <CODE>x / abs(x)</CODE> if <CODE>x</CODE> is non-zero, and
  751. <CODE>x</CODE> if <CODE>x</CODE> is zero. If <CODE>x</CODE> is real, the value is either
  752. 0 or 1 or -1.
  753. </DL>
  754. <H2><A NAME="SEC22" HREF="cln.html#TOC22">4.3 Elementary rational functions</A></H2>
  755. <P>
  756. Each of the classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE> defines the following operations:
  757. <DL COMPACT>
  758. <DT><CODE>cl_I numerator (const <VAR>type</VAR>&#38; x)</CODE>
  759. <DD>
  760. Returns the numerator of <CODE>x</CODE>.
  761. <DT><CODE>cl_I denominator (const <VAR>type</VAR>&#38; x)</CODE>
  762. <DD>
  763. Returns the denominator of <CODE>x</CODE>.
  764. </DL>
  765. <P>
  766. The numerator and denominator of a rational number are normalized in such
  767. a way that they have no factor in common and the denominator is positive.
  768. <H2><A NAME="SEC23" HREF="cln.html#TOC23">4.4 Elementary complex functions</A></H2>
  769. <P>
  770. The class <CODE>cl_N</CODE> defines the following operation:
  771. <DL COMPACT>
  772. <DT><CODE>cl_N complex (const cl_R&#38; a, const cl_R&#38; b)</CODE>
  773. <DD>
  774. Returns the complex number <CODE>a+bi</CODE>, that is, the complex number with
  775. real part <CODE>a</CODE> and imaginary part <CODE>b</CODE>.
  776. </DL>
  777. <P>
  778. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE> defines the following operations:
  779. <DL COMPACT>
  780. <DT><CODE>cl_R realpart (const <VAR>type</VAR>&#38; x)</CODE>
  781. <DD>
  782. Returns the real part of <CODE>x</CODE>.
  783. <DT><CODE>cl_R imagpart (const <VAR>type</VAR>&#38; x)</CODE>
  784. <DD>
  785. Returns the imaginary part of <CODE>x</CODE>.
  786. <DT><CODE><VAR>type</VAR> conjugate (const <VAR>type</VAR>&#38; x)</CODE>
  787. <DD>
  788. Returns the complex conjugate of <CODE>x</CODE>.
  789. </DL>
  790. <P>
  791. We have the relations
  792. <UL>
  793. <LI>
  794. <CODE>x = complex(realpart(x), imagpart(x))</CODE>
  795. <LI>
  796. <CODE>conjugate(x) = complex(realpart(x), -imagpart(x))</CODE>
  797. </UL>
  798. <H2><A NAME="SEC24" HREF="cln.html#TOC24">4.5 Comparisons</A></H2>
  799. <P>
  800. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  801. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  802. defines the following operations:
  803. <DL COMPACT>
  804. <DT><CODE>bool operator == (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  805. <DD>
  806. <DT><CODE>bool operator != (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  807. <DD>
  808. Comparison, as in C and C++.
  809. <DT><CODE>uint32 cl_equal_hashcode (const <VAR>type</VAR>&#38;)</CODE>
  810. <DD>
  811. Returns a 32-bit hash code that is the same for any two numbers which are
  812. the same according to <CODE>==</CODE>. This hash code depends on the number's value,
  813. not its type or precision.
  814. <DT><CODE>cl_boolean zerop (const <VAR>type</VAR>&#38; x)</CODE>
  815. <DD>
  816. Compare against zero: <CODE>x == 0</CODE>
  817. </DL>
  818. <P>
  819. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  820. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  821. defines the following operations:
  822. <DL COMPACT>
  823. <DT><CODE>cl_signean cl_compare (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  824. <DD>
  825. Compares <CODE>x</CODE> and <CODE>y</CODE>. Returns +1 if <CODE>x</CODE>&#62;<CODE>y</CODE>,
  826. -1 if <CODE>x</CODE>&#60;<CODE>y</CODE>, 0 if <CODE>x</CODE>=<CODE>y</CODE>.
  827. <DT><CODE>bool operator &#60;= (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  828. <DD>
  829. <DT><CODE>bool operator &#60; (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  830. <DD>
  831. <DT><CODE>bool operator &#62;= (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  832. <DD>
  833. <DT><CODE>bool operator &#62; (const <VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  834. <DD>
  835. Comparison, as in C and C++.
  836. <DT><CODE>cl_boolean minusp (const <VAR>type</VAR>&#38; x)</CODE>
  837. <DD>
  838. Compare against zero: <CODE>x &#60; 0</CODE>
  839. <DT><CODE>cl_boolean plusp (const <VAR>type</VAR>&#38; x)</CODE>
  840. <DD>
  841. Compare against zero: <CODE>x &#62; 0</CODE>
  842. <DT><CODE><VAR>type</VAR> max (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  843. <DD>
  844. Return the maximum of <CODE>x</CODE> and <CODE>y</CODE>.
  845. <DT><CODE><VAR>type</VAR> min (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  846. <DD>
  847. Return the minimum of <CODE>x</CODE> and <CODE>y</CODE>.
  848. </DL>
  849. <P>
  850. When a floating point number and a rational number are compared, the float
  851. is first converted to a rational number using the function <CODE>rational</CODE>.
  852. Since a floating point number actually represents an interval of real numbers,
  853. the result might be surprising.
  854. For example, <CODE>(cl_F)(cl_R)"1/3" == (cl_R)"1/3"</CODE> returns false because
  855. there is no floating point number whose value is exactly <CODE>1/3</CODE>.
  856. <H2><A NAME="SEC25" HREF="cln.html#TOC25">4.6 Rounding functions</A></H2>
  857. <P>
  858. When a real number is to be converted to an integer, there is no "best"
  859. rounding. The desired rounding function depends on the application.
  860. The Common Lisp and ISO Lisp standards offer four rounding functions:
  861. <DL COMPACT>
  862. <DT><CODE>floor(x)</CODE>
  863. <DD>
  864. This is the largest integer &#60;=<CODE>x</CODE>.
  865. <DT><CODE>ceiling(x)</CODE>
  866. <DD>
  867. This is the smallest integer &#62;=<CODE>x</CODE>.
  868. <DT><CODE>truncate(x)</CODE>
  869. <DD>
  870. Among the integers between 0 and <CODE>x</CODE> (inclusive) the one nearest to <CODE>x</CODE>.
  871. <DT><CODE>round(x)</CODE>
  872. <DD>
  873. The integer nearest to <CODE>x</CODE>. If <CODE>x</CODE> is exactly halfway between two
  874. integers, choose the even one.
  875. </DL>
  876. <P>
  877. These functions have different advantages:
  878. <P>
  879. <CODE>floor</CODE> and <CODE>ceiling</CODE> are translation invariant:
  880. <CODE>floor(x+n) = floor(x) + n</CODE> and <CODE>ceiling(x+n) = ceiling(x) + n</CODE>
  881. for every <CODE>x</CODE> and every integer <CODE>n</CODE>.
  882. <P>
  883. On the other hand, <CODE>truncate</CODE> and <CODE>round</CODE> are symmetric:
  884. <CODE>truncate(-x) = -truncate(x)</CODE> and <CODE>round(-x) = -round(x)</CODE>,
  885. and furthermore <CODE>round</CODE> is unbiased: on the "average", it rounds
  886. down exactly as often as it rounds up.
  887. <P>
  888. The functions are related like this:
  889. <UL>
  890. <LI>
  891. <CODE>ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1</CODE>
  892. for rational numbers <CODE>m/n</CODE> (<CODE>m</CODE>, <CODE>n</CODE> integers, <CODE>n</CODE>&#62;0), and
  893. <LI>
  894. <CODE>truncate(x) = sign(x) * floor(abs(x))</CODE>
  895. </UL>
  896. <P>
  897. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
  898. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  899. defines the following operations:
  900. <DL COMPACT>
  901. <DT><CODE>cl_I floor1 (const <VAR>type</VAR>&#38; x)</CODE>
  902. <DD>
  903. Returns <CODE>floor(x)</CODE>.
  904. <DT><CODE>cl_I ceiling1 (const <VAR>type</VAR>&#38; x)</CODE>
  905. <DD>
  906. Returns <CODE>ceiling(x)</CODE>.
  907. <DT><CODE>cl_I truncate1 (const <VAR>type</VAR>&#38; x)</CODE>
  908. <DD>
  909. Returns <CODE>truncate(x)</CODE>.
  910. <DT><CODE>cl_I round1 (const <VAR>type</VAR>&#38; x)</CODE>
  911. <DD>
  912. Returns <CODE>round(x)</CODE>.
  913. </DL>
  914. <P>
  915. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  916. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  917. defines the following operations:
  918. <DL COMPACT>
  919. <DT><CODE>cl_I floor1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  920. <DD>
  921. Returns <CODE>floor(x/y)</CODE>.
  922. <DT><CODE>cl_I ceiling1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  923. <DD>
  924. Returns <CODE>ceiling(x/y)</CODE>.
  925. <DT><CODE>cl_I truncate1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  926. <DD>
  927. Returns <CODE>truncate(x/y)</CODE>.
  928. <DT><CODE>cl_I round1 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  929. <DD>
  930. Returns <CODE>round(x/y)</CODE>.
  931. </DL>
  932. <P>
  933. These functions are called <SAMP>`floor1'</SAMP>, ... here instead of
  934. <SAMP>`floor'</SAMP>, ..., because on some systems, system dependent include
  935. files define <SAMP>`floor'</SAMP> and <SAMP>`ceiling'</SAMP> as macros.
  936. <P>
  937. In many cases, one needs both the quotient and the remainder of a division.
  938. It is more efficient to compute both at the same time than to perform
  939. two divisions, one for quotient and the next one for the remainder.
  940. The following functions therefore return a structure containing both
  941. the quotient and the remainder. The suffix <SAMP>`2'</SAMP> indicates the number
  942. of "return values". The remainder is defined as follows:
  943. <UL>
  944. <LI>
  945. for the computation of <CODE>quotient = floor(x)</CODE>,
  946. <CODE>remainder = x - quotient</CODE>,
  947. <LI>
  948. for the computation of <CODE>quotient = floor(x,y)</CODE>,
  949. <CODE>remainder = x - quotient*y</CODE>,
  950. </UL>
  951. <P>
  952. and similarly for the other three operations.
  953. <P>
  954. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
  955. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  956. defines the following operations:
  957. <DL COMPACT>
  958. <DT><CODE>struct <VAR>type</VAR>_div_t { cl_I quotient; <VAR>type</VAR> remainder; };</CODE>
  959. <DD>
  960. <DT><CODE><VAR>type</VAR>_div_t floor2 (const <VAR>type</VAR>&#38; x)</CODE>
  961. <DD>
  962. <DT><CODE><VAR>type</VAR>_div_t ceiling2 (const <VAR>type</VAR>&#38; x)</CODE>
  963. <DD>
  964. <DT><CODE><VAR>type</VAR>_div_t truncate2 (const <VAR>type</VAR>&#38; x)</CODE>
  965. <DD>
  966. <DT><CODE><VAR>type</VAR>_div_t round2 (const <VAR>type</VAR>&#38; x)</CODE>
  967. <DD>
  968. </DL>
  969. <P>
  970. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  971. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  972. defines the following operations:
  973. <DL COMPACT>
  974. <DT><CODE>struct <VAR>type</VAR>_div_t { cl_I quotient; <VAR>type</VAR> remainder; };</CODE>
  975. <DD>
  976. <DT><CODE><VAR>type</VAR>_div_t floor2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  977. <DD>
  978. <DT><CODE><VAR>type</VAR>_div_t ceiling2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  979. <DD>
  980. <DT><CODE><VAR>type</VAR>_div_t truncate2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  981. <DD>
  982. <DT><CODE><VAR>type</VAR>_div_t round2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  983. <DD>
  984. </DL>
  985. <P>
  986. Sometimes, one wants the quotient as a floating-point number (of the
  987. same format as the argument, if the argument is a float) instead of as
  988. an integer. The prefix <SAMP>`f'</SAMP> indicates this.
  989. <P>
  990. Each of the classes
  991. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  992. defines the following operations:
  993. <DL COMPACT>
  994. <DT><CODE><VAR>type</VAR> ffloor (const <VAR>type</VAR>&#38; x)</CODE>
  995. <DD>
  996. <DT><CODE><VAR>type</VAR> fceiling (const <VAR>type</VAR>&#38; x)</CODE>
  997. <DD>
  998. <DT><CODE><VAR>type</VAR> ftruncate (const <VAR>type</VAR>&#38; x)</CODE>
  999. <DD>
  1000. <DT><CODE><VAR>type</VAR> fround (const <VAR>type</VAR>&#38; x)</CODE>
  1001. <DD>
  1002. </DL>
  1003. <P>
  1004. and similarly for class <CODE>cl_R</CODE>, but with return type <CODE>cl_F</CODE>.
  1005. <P>
  1006. The class <CODE>cl_R</CODE> defines the following operations:
  1007. <DL COMPACT>
  1008. <DT><CODE>cl_F ffloor (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1009. <DD>
  1010. <DT><CODE>cl_F fceiling (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1011. <DD>
  1012. <DT><CODE>cl_F ftruncate (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1013. <DD>
  1014. <DT><CODE>cl_F fround (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1015. <DD>
  1016. </DL>
  1017. <P>
  1018. These functions also exist in versions which return both the quotient
  1019. and the remainder. The suffix <SAMP>`2'</SAMP> indicates this.
  1020. <P>
  1021. Each of the classes
  1022. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  1023. defines the following operations:
  1024. <DL COMPACT>
  1025. <DT><CODE>struct <VAR>type</VAR>_fdiv_t { <VAR>type</VAR> quotient; <VAR>type</VAR> remainder; };</CODE>
  1026. <DD>
  1027. <DT><CODE><VAR>type</VAR>_fdiv_t ffloor2 (const <VAR>type</VAR>&#38; x)</CODE>
  1028. <DD>
  1029. <DT><CODE><VAR>type</VAR>_fdiv_t fceiling2 (const <VAR>type</VAR>&#38; x)</CODE>
  1030. <DD>
  1031. <DT><CODE><VAR>type</VAR>_fdiv_t ftruncate2 (const <VAR>type</VAR>&#38; x)</CODE>
  1032. <DD>
  1033. <DT><CODE><VAR>type</VAR>_fdiv_t fround2 (const <VAR>type</VAR>&#38; x)</CODE>
  1034. <DD>
  1035. </DL>
  1036. <P>
  1037. and similarly for class <CODE>cl_R</CODE>, but with quotient type <CODE>cl_F</CODE>.
  1038. <P>
  1039. The class <CODE>cl_R</CODE> defines the following operations:
  1040. <DL COMPACT>
  1041. <DT><CODE>struct <VAR>type</VAR>_fdiv_t { cl_F quotient; cl_R remainder; };</CODE>
  1042. <DD>
  1043. <DT><CODE><VAR>type</VAR>_fdiv_t ffloor2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1044. <DD>
  1045. <DT><CODE><VAR>type</VAR>_fdiv_t fceiling2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1046. <DD>
  1047. <DT><CODE><VAR>type</VAR>_fdiv_t ftruncate2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1048. <DD>
  1049. <DT><CODE><VAR>type</VAR>_fdiv_t fround2 (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1050. <DD>
  1051. </DL>
  1052. <P>
  1053. Other applications need only the remainder of a division.
  1054. The remainder of <SAMP>`floor'</SAMP> and <SAMP>`ffloor'</SAMP> is called <SAMP>`mod'</SAMP>
  1055. (abbreviation of "modulo"). The remainder <SAMP>`truncate'</SAMP> and
  1056. <SAMP>`ftruncate'</SAMP> is called <SAMP>`rem'</SAMP> (abbreviation of "remainder").
  1057. <UL>
  1058. <LI>
  1059. <CODE>mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y</CODE>
  1060. <LI>
  1061. <CODE>rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y</CODE>
  1062. </UL>
  1063. <P>
  1064. If <CODE>x</CODE> and <CODE>y</CODE> are both &#62;= 0, <CODE>mod(x,y) = rem(x,y) &#62;= 0</CODE>.
  1065. In general, <CODE>mod(x,y)</CODE> has the sign of <CODE>y</CODE> or is zero,
  1066. and <CODE>rem(x,y)</CODE> has the sign of <CODE>x</CODE> or is zero.
  1067. <P>
  1068. The classes <CODE>cl_R</CODE>, <CODE>cl_I</CODE> define the following operations:
  1069. <DL COMPACT>
  1070. <DT><CODE><VAR>type</VAR> mod (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1071. <DD>
  1072. <DT><CODE><VAR>type</VAR> rem (const <VAR>type</VAR>&#38; x, const <VAR>type</VAR>&#38; y)</CODE>
  1073. <DD>
  1074. </DL>
  1075. <H2><A NAME="SEC26" HREF="cln.html#TOC26">4.7 Roots</A></H2>
  1076. <P>
  1077. Each of the classes <CODE>cl_R</CODE>,
  1078. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  1079. defines the following operation:
  1080. <DL COMPACT>
  1081. <DT><CODE><VAR>type</VAR> sqrt (const <VAR>type</VAR>&#38; x)</CODE>
  1082. <DD>
  1083. <CODE>x</CODE> must be &#62;= 0. This function returns the square root of <CODE>x</CODE>,
  1084. normalized to be &#62;= 0. If <CODE>x</CODE> is the square of a rational number,
  1085. <CODE>sqrt(x)</CODE> will be a rational number, else it will return a
  1086. floating-point approximation.
  1087. </DL>
  1088. <P>
  1089. The classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE> define the following operation:
  1090. <DL COMPACT>
  1091. <DT><CODE>cl_boolean sqrtp (const <VAR>type</VAR>&#38; x, <VAR>type</VAR>* root)</CODE>
  1092. <DD>
  1093. This tests whether <CODE>x</CODE> is a perfect square. If so, it returns true
  1094. and the exact square root in <CODE>*root</CODE>, else it returns false.
  1095. </DL>
  1096. <P>
  1097. Furthermore, for integers, similarly:
  1098. <DL COMPACT>
  1099. <DT><CODE>cl_boolean isqrt (const <VAR>type</VAR>&#38; x, <VAR>type</VAR>* root)</CODE>
  1100. <DD>
  1101. <CODE>x</CODE> should be &#62;= 0. This function sets <CODE>*root</CODE> to
  1102. <CODE>floor(sqrt(x))</CODE> and returns the same value as <CODE>sqrtp</CODE>:
  1103. the boolean value <CODE>(expt(*root,2) == x)</CODE>.
  1104. </DL>
  1105. <P>
  1106. For <CODE>n</CODE>th roots, the classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>
  1107. define the following operation:
  1108. <DL COMPACT>
  1109. <DT><CODE>cl_boolean rootp (const <VAR>type</VAR>&#38; x, const cl_I&#38; n, <VAR>type</VAR>* root)</CODE>
  1110. <DD>
  1111. <CODE>x</CODE> must be &#62;= 0. <CODE>n</CODE> must be &#62; 0.
  1112. This tests whether <CODE>x</CODE> is an <CODE>n</CODE>th power of a rational number.
  1113. If so, it returns true and the exact root in <CODE>*root</CODE>, else it returns
  1114. false.
  1115. </DL>
  1116. <P>
  1117. The only square root function which accepts negative numbers is the one
  1118. for class <CODE>cl_N</CODE>:
  1119. <DL COMPACT>
  1120. <DT><CODE>cl_N sqrt (const cl_N&#38; z)</CODE>
  1121. <DD>
  1122. Returns the square root of <CODE>z</CODE>, as defined by the formula
  1123. <CODE>sqrt(z) = exp(log(z)/2)</CODE>. Conversion to a floating-point type
  1124. or to a complex number are done if necessary. The range of the result is the
  1125. right half plane <CODE>realpart(sqrt(z)) &#62;= 0</CODE>
  1126. including the positive imaginary axis and 0, but excluding
  1127. the negative imaginary axis.
  1128. The result is an exact number only if <CODE>z</CODE> is an exact number.
  1129. </DL>
  1130. <H2><A NAME="SEC27" HREF="cln.html#TOC27">4.8 Transcendental functions</A></H2>
  1131. <P>
  1132. The transcendental functions return an exact result if the argument
  1133. is exact and the result is exact as well. Otherwise they must return
  1134. inexact numbers even if the argument is exact.
  1135. For example, <CODE>cos(0) = 1</CODE> returns the rational number <CODE>1</CODE>.
  1136. <H3><A NAME="SEC28" HREF="cln.html#TOC28">4.8.1 Exponential and logarithmic functions</A></H3>
  1137. <DL COMPACT>
  1138. <DT><CODE>cl_R exp (const cl_R&#38; x)</CODE>
  1139. <DD>
  1140. <DT><CODE>cl_N exp (const cl_N&#38; x)</CODE>
  1141. <DD>
  1142. Returns the exponential function of <CODE>x</CODE>. This is <CODE>e^x</CODE> where
  1143. <CODE>e</CODE> is the base of the natural logarithms. The range of the result
  1144. is the entire complex plane excluding 0.
  1145. <DT><CODE>cl_R ln (const cl_R&#38; x)</CODE>
  1146. <DD>
  1147. <CODE>x</CODE> must be &#62; 0. Returns the (natural) logarithm of x.
  1148. <DT><CODE>cl_N log (const cl_N&#38; x)</CODE>
  1149. <DD>
  1150. Returns the (natural) logarithm of x. If <CODE>x</CODE> is real and positive,
  1151. this is <CODE>ln(x)</CODE>. In general, <CODE>log(x) = log(abs(x)) + i*phase(x)</CODE>.
  1152. The range of the result is the strip in the complex plane
  1153. <CODE>-pi &#60; imagpart(log(x)) &#60;= pi</CODE>.
  1154. <DT><CODE>cl_R phase (const cl_N&#38; x)</CODE>
  1155. <DD>
  1156. Returns the angle part of <CODE>x</CODE> in its polar representation as a
  1157. complex number. That is, <CODE>phase(x) = atan(realpart(x),imagpart(x))</CODE>.
  1158. This is also the imaginary part of <CODE>log(x)</CODE>.
  1159. The range of the result is the interval <CODE>-pi &#60; phase(x) &#60;= pi</CODE>.
  1160. The result will be an exact number only if <CODE>zerop(x)</CODE> or
  1161. if <CODE>x</CODE> is real and positive.
  1162. <DT><CODE>cl_R log (const cl_R&#38; a, const cl_R&#38; b)</CODE>
  1163. <DD>
  1164. <CODE>a</CODE> and <CODE>b</CODE> must be &#62; 0. Returns the logarithm of <CODE>a</CODE> with
  1165. respect to base <CODE>b</CODE>. <CODE>log(a,b) = ln(a)/ln(b)</CODE>.
  1166. The result can be exact only if <CODE>a = 1</CODE> or if <CODE>a</CODE> and <CODE>b</CODE>
  1167. are both rational.
  1168. <DT><CODE>cl_N log (const cl_N&#38; a, const cl_N&#38; b)</CODE>
  1169. <DD>
  1170. Returns the logarithm of <CODE>a</CODE> with respect to base <CODE>b</CODE>.
  1171. <CODE>log(a,b) = log(a)/log(b)</CODE>.
  1172. <DT><CODE>cl_N expt (const cl_N&#38; x, const cl_N&#38; y)</CODE>
  1173. <DD>
  1174. Exponentiation: Returns <CODE>x^y = exp(y*log(x))</CODE>.
  1175. </DL>
  1176. <P>
  1177. The constant e = exp(1) = 2.71828... is returned by the following functions:
  1178. <DL COMPACT>
  1179. <DT><CODE>cl_F cl_exp1 (cl_float_format_t f)</CODE>
  1180. <DD>
  1181. Returns e as a float of format <CODE>f</CODE>.
  1182. <DT><CODE>cl_F cl_exp1 (const cl_F&#38; y)</CODE>
  1183. <DD>
  1184. Returns e in the float format of <CODE>y</CODE>.
  1185. <DT><CODE>cl_F cl_exp1 (void)</CODE>
  1186. <DD>
  1187. Returns e as a float of format <CODE>cl_default_float_format</CODE>.
  1188. </DL>
  1189. <H3><A NAME="SEC29" HREF="cln.html#TOC29">4.8.2 Trigonometric functions</A></H3>
  1190. <DL COMPACT>
  1191. <DT><CODE>cl_R sin (const cl_R&#38; x)</CODE>
  1192. <DD>
  1193. Returns <CODE>sin(x)</CODE>. The range of the result is the interval
  1194. <CODE>-1 &#60;= sin(x) &#60;= 1</CODE>.
  1195. <DT><CODE>cl_N sin (const cl_N&#38; z)</CODE>
  1196. <DD>
  1197. Returns <CODE>sin(z)</CODE>. The range of the result is the entire complex plane.
  1198. <DT><CODE>cl_R cos (const cl_R&#38; x)</CODE>
  1199. <DD>
  1200. Returns <CODE>cos(x)</CODE>. The range of the result is the interval
  1201. <CODE>-1 &#60;= cos(x) &#60;= 1</CODE>.
  1202. <DT><CODE>cl_N cos (const cl_N&#38; x)</CODE>
  1203. <DD>
  1204. Returns <CODE>cos(z)</CODE>. The range of the result is the entire complex plane.
  1205. <DT><CODE>struct cl_cos_sin_t { cl_R cos; cl_R sin; };</CODE>
  1206. <DD>
  1207. <DT><CODE>cl_cos_sin_t cl_cos_sin (const cl_R&#38; x)</CODE>
  1208. <DD>
  1209. Returns both <CODE>sin(x)</CODE> and <CODE>cos(x)</CODE>. This is more efficient than
  1210. computing them separately. The relation <CODE>cos^2 + sin^2 = 1</CODE> will
  1211. hold only approximately.
  1212. <DT><CODE>cl_R tan (const cl_R&#38; x)</CODE>
  1213. <DD>
  1214. <DT><CODE>cl_N tan (const cl_N&#38; x)</CODE>
  1215. <DD>
  1216. Returns <CODE>tan(x) = sin(x)/cos(x)</CODE>.
  1217. <DT><CODE>cl_N cis (const cl_R&#38; x)</CODE>
  1218. <DD>
  1219. <DT><CODE>cl_N cis (const cl_N&#38; x)</CODE>
  1220. <DD>
  1221. Returns <CODE>exp(i*x)</CODE>. The name <SAMP>`cis'</SAMP> means "cos + i sin", because
  1222. <CODE>e^(i*x) = cos(x) + i*sin(x)</CODE>.
  1223. <DT><CODE>cl_N asin (const cl_N&#38; z)</CODE>
  1224. <DD>
  1225. Returns <CODE>arcsin(z)</CODE>. This is defined as
  1226. <CODE>arcsin(z) = log(iz+sqrt(1-z^2))/i</CODE> and satisfies
  1227. <CODE>arcsin(-z) = -arcsin(z)</CODE>.
  1228. The range of the result is the strip in the complex domain
  1229. <CODE>-pi/2 &#60;= realpart(arcsin(z)) &#60;= pi/2</CODE>, excluding the numbers
  1230. with <CODE>realpart = -pi/2</CODE> and <CODE>imagpart &#60; 0</CODE> and the numbers
  1231. with <CODE>realpart = pi/2</CODE> and <CODE>imagpart &#62; 0</CODE>.
  1232. <DT><CODE>cl_N acos (const cl_N&#38; z)</CODE>
  1233. <DD>
  1234. Returns <CODE>arccos(z)</CODE>. This is defined as
  1235. <CODE>arccos(z) = pi/2 - arcsin(z) = log(z+i*sqrt(1-z^2))/i</CODE>
  1236. and satisfies <CODE>arccos(-z) = pi - arccos(z)</CODE>.
  1237. The range of the result is the strip in the complex domain
  1238. <CODE>0 &#60;= realpart(arcsin(z)) &#60;= pi</CODE>, excluding the numbers
  1239. with <CODE>realpart = 0</CODE> and <CODE>imagpart &#60; 0</CODE> and the numbers
  1240. with <CODE>realpart = pi</CODE> and <CODE>imagpart &#62; 0</CODE>.
  1241. <DT><CODE>cl_R atan (const cl_R&#38; x, const cl_R&#38; y)</CODE>
  1242. <DD>
  1243. Returns the angle of the polar representation of the complex number
  1244. <CODE>x+iy</CODE>. This is <CODE>atan(y/x)</CODE> if <CODE>x&#62;0</CODE>. The range of
  1245. the result is the interval <CODE>-pi &#60; atan(x,y) &#60;= pi</CODE>. The result will
  1246. be an exact number only if <CODE>x &#62; 0</CODE> and <CODE>y</CODE> is the exact <CODE>0</CODE>.
  1247. WARNING: In Common Lisp, this function is called as <CODE>(atan y x)</CODE>,
  1248. with reversed order of arguments.
  1249. <DT><CODE>cl_R atan (const cl_R&#38; x)</CODE>
  1250. <DD>
  1251. Returns <CODE>arctan(x)</CODE>. This is the same as <CODE>atan(1,x)</CODE>. The range
  1252. of the result is the interval <CODE>-pi/2 &#60; atan(x) &#60; pi/2</CODE>. The result
  1253. will be an exact number only if <CODE>x</CODE> is the exact <CODE>0</CODE>.
  1254. <DT><CODE>cl_N atan (const cl_N&#38; z)</CODE>
  1255. <DD>
  1256. Returns <CODE>arctan(z)</CODE>. This is defined as
  1257. <CODE>arctan(z) = (log(1+iz)-log(1-iz)) / 2i</CODE> and satisfies
  1258. <CODE>arctan(-z) = -arctan(z)</CODE>. The range of the result is
  1259. the strip in the complex domain
  1260. <CODE>-pi/2 &#60;= realpart(arctan(z)) &#60;= pi/2</CODE>, excluding the numbers
  1261. with <CODE>realpart = -pi/2</CODE> and <CODE>imagpart &#62;= 0</CODE> and the numbers
  1262. with <CODE>realpart = pi/2</CODE> and <CODE>imagpart &#60;= 0</CODE>.
  1263. </DL>
  1264. <P>
  1265. The constant pi = 3.14... is returned by the following functions:
  1266. <DL COMPACT>
  1267. <DT><CODE>cl_F cl_pi (cl_float_format_t f)</CODE>
  1268. <DD>
  1269. Returns pi as a float of format <CODE>f</CODE>.
  1270. <DT><CODE>cl_F cl_pi (const cl_F&#38; y)</CODE>
  1271. <DD>
  1272. Returns pi in the float format of <CODE>y</CODE>.
  1273. <DT><CODE>cl_F cl_pi (void)</CODE>
  1274. <DD>
  1275. Returns pi as a float of format <CODE>cl_default_float_format</CODE>.
  1276. </DL>
  1277. <H3><A NAME="SEC30" HREF="cln.html#TOC30">4.8.3 Hyperbolic functions</A></H3>
  1278. <DL COMPACT>
  1279. <DT><CODE>cl_R sinh (const cl_R&#38; x)</CODE>
  1280. <DD>
  1281. Returns <CODE>sinh(x)</CODE>.
  1282. <DT><CODE>cl_N sinh (const cl_N&#38; z)</CODE>
  1283. <DD>
  1284. Returns <CODE>sinh(z)</CODE>. The range of the result is the entire complex plane.
  1285. <DT><CODE>cl_R cosh (const cl_R&#38; x)</CODE>
  1286. <DD>
  1287. Returns <CODE>cosh(x)</CODE>. The range of the result is the interval
  1288. <CODE>cosh(x) &#62;= 1</CODE>.
  1289. <DT><CODE>cl_N cosh (const cl_N&#38; z)</CODE>
  1290. <DD>
  1291. Returns <CODE>cosh(z)</CODE>. The range of the result is the entire complex plane.
  1292. <DT><CODE>struct cl_cosh_sinh_t { cl_R cosh; cl_R sinh; };</CODE>
  1293. <DD>
  1294. <DT><CODE>cl_cosh_sinh_t cl_cosh_sinh (const cl_R&#38; x)</CODE>
  1295. <DD>
  1296. Returns both <CODE>sinh(x)</CODE> and <CODE>cosh(x)</CODE>. This is more efficient than
  1297. computing them separately. The relation <CODE>cosh^2 - sinh^2 = 1</CODE> will
  1298. hold only approximately.
  1299. <DT><CODE>cl_R tanh (const cl_R&#38; x)</CODE>
  1300. <DD>
  1301. <DT><CODE>cl_N tanh (const cl_N&#38; x)</CODE>
  1302. <DD>
  1303. Returns <CODE>tanh(x) = sinh(x)/cosh(x)</CODE>.
  1304. <DT><CODE>cl_N asinh (const cl_N&#38; z)</CODE>
  1305. <DD>
  1306. Returns <CODE>arsinh(z)</CODE>. This is defined as
  1307. <CODE>arsinh(z) = log(z+sqrt(1+z^2))</CODE> and satisfies
  1308. <CODE>arsinh(-z) = -arsinh(z)</CODE>.
  1309. The range of the result is the strip in the complex domain
  1310. <CODE>-pi/2 &#60;= imagpart(arsinh(z)) &#60;= pi/2</CODE>, excluding the numbers
  1311. with <CODE>imagpart = -pi/2</CODE> and <CODE>realpart &#62; 0</CODE> and the numbers
  1312. with <CODE>imagpart = pi/2</CODE> and <CODE>realpart &#60; 0</CODE>.
  1313. <DT><CODE>cl_N acosh (const cl_N&#38; z)</CODE>
  1314. <DD>
  1315. Returns <CODE>arcosh(z)</CODE>. This is defined as
  1316. <CODE>arcosh(z) = 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))</CODE>.
  1317. The range of the result is the half-strip in the complex domain
  1318. <CODE>-pi &#60; imagpart(arcosh(z)) &#60;= pi, realpart(arcosh(z)) &#62;= 0</CODE>,
  1319. excluding the numbers with <CODE>realpart = 0</CODE> and <CODE>-pi &#60; imagpart &#60; 0</CODE>.
  1320. <DT><CODE>cl_N atanh (const cl_N&#38; z)</CODE>
  1321. <DD>
  1322. Returns <CODE>artanh(z)</CODE>. This is defined as
  1323. <CODE>artanh(z) = (log(1+z)-log(1-z)) / 2</CODE> and satisfies
  1324. <CODE>artanh(-z) = -artanh(z)</CODE>. The range of the result is
  1325. the strip in the complex domain
  1326. <CODE>-pi/2 &#60;= imagpart(artanh(z)) &#60;= pi/2</CODE>, excluding the numbers
  1327. with <CODE>imagpart = -pi/2</CODE> and <CODE>realpart &#60;= 0</CODE> and the numbers
  1328. with <CODE>imagpart = pi/2</CODE> and <CODE>realpart &#62;= 0</CODE>.
  1329. </DL>
  1330. <H3><A NAME="SEC31" HREF="cln.html#TOC31">4.8.4 Euler gamma</A></H3>
  1331. <P>
  1332. Euler's constant C = 0.577... is returned by the following functions:
  1333. <DL COMPACT>
  1334. <DT><CODE>cl_F cl_eulerconst (cl_float_format_t f)</CODE>
  1335. <DD>
  1336. Returns Euler's constant as a float of format <CODE>f</CODE>.
  1337. <DT><CODE>cl_F cl_eulerconst (const cl_F&#38; y)</CODE>
  1338. <DD>
  1339. Returns Euler's constant in the float format of <CODE>y</CODE>.
  1340. <DT><CODE>cl_F cl_eulerconst (void)</CODE>
  1341. <DD>
  1342. Returns Euler's constant as a float of format <CODE>cl_default_float_format</CODE>.
  1343. </DL>
  1344. <P>
  1345. Catalan's constant G = 0.915... is returned by the following functions:
  1346. <DL COMPACT>
  1347. <DT><CODE>cl_F cl_catalanconst (cl_float_format_t f)</CODE>
  1348. <DD>
  1349. Returns Catalan's constant as a float of format <CODE>f</CODE>.
  1350. <DT><CODE>cl_F cl_catalanconst (const cl_F&#38; y)</CODE>
  1351. <DD>
  1352. Returns Catalan's constant in the float format of <CODE>y</CODE>.
  1353. <DT><CODE>cl_F cl_catalanconst (void)</CODE>
  1354. <DD>
  1355. Returns Catalan's constant as a float of format <CODE>cl_default_float_format</CODE>.
  1356. </DL>
  1357. <H3><A NAME="SEC32" HREF="cln.html#TOC32">4.8.5 Riemann zeta</A></H3>
  1358. <P>
  1359. Riemann's zeta function at an integral point <CODE>s&#62;1</CODE> is returned by the
  1360. following functions:
  1361. <DL COMPACT>
  1362. <DT><CODE>cl_F cl_zeta (int s, cl_float_format_t f)</CODE>
  1363. <DD>
  1364. Returns Riemann's zeta function at <CODE>s</CODE> as a float of format <CODE>f</CODE>.
  1365. <DT><CODE>cl_F cl_zeta (int s, const cl_F&#38; y)</CODE>
  1366. <DD>
  1367. Returns Riemann's zeta function at <CODE>s</CODE> in the float format of <CODE>y</CODE>.
  1368. <DT><CODE>cl_F cl_zeta (int s)</CODE>
  1369. <DD>
  1370. Returns Riemann's zeta function at <CODE>s</CODE> as a float of format
  1371. <CODE>cl_default_float_format</CODE>.
  1372. </DL>
  1373. <H2><A NAME="SEC33" HREF="cln.html#TOC33">4.9 Functions on integers</A></H2>
  1374. <H3><A NAME="SEC34" HREF="cln.html#TOC34">4.9.1 Logical functions</A></H3>
  1375. <P>
  1376. Integers, when viewed as in two's complement notation, can be thought as
  1377. infinite bit strings where the bits' values eventually are constant.
  1378. For example,
  1379. <PRE>
  1380. 17 = ......00010001
  1381. -6 = ......11111010
  1382. </PRE>
  1383. <P>
  1384. The logical operations view integers as such bit strings and operate
  1385. on each of the bit positions in parallel.
  1386. <DL COMPACT>
  1387. <DT><CODE>cl_I lognot (const cl_I&#38; x)</CODE>
  1388. <DD>
  1389. <DT><CODE>cl_I operator ~ (const cl_I&#38; x)</CODE>
  1390. <DD>
  1391. Logical not, like <CODE>~x</CODE> in C. This is the same as <CODE>-1-x</CODE>.
  1392. <DT><CODE>cl_I logand (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1393. <DD>
  1394. <DT><CODE>cl_I operator &#38; (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1395. <DD>
  1396. Logical and, like <CODE>x &#38; y</CODE> in C.
  1397. <DT><CODE>cl_I logior (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1398. <DD>
  1399. <DT><CODE>cl_I operator | (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1400. <DD>
  1401. Logical (inclusive) or, like <CODE>x | y</CODE> in C.
  1402. <DT><CODE>cl_I logxor (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1403. <DD>
  1404. <DT><CODE>cl_I operator ^ (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1405. <DD>
  1406. Exclusive or, like <CODE>x ^ y</CODE> in C.
  1407. <DT><CODE>cl_I logeqv (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1408. <DD>
  1409. Bitwise equivalence, like <CODE>~(x ^ y)</CODE> in C.
  1410. <DT><CODE>cl_I lognand (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1411. <DD>
  1412. Bitwise not and, like <CODE>~(x &#38; y)</CODE> in C.
  1413. <DT><CODE>cl_I lognor (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1414. <DD>
  1415. Bitwise not or, like <CODE>~(x | y)</CODE> in C.
  1416. <DT><CODE>cl_I logandc1 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1417. <DD>
  1418. Logical and, complementing the first argument, like <CODE>~x &#38; y</CODE> in C.
  1419. <DT><CODE>cl_I logandc2 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1420. <DD>
  1421. Logical and, complementing the second argument, like <CODE>x &#38; ~y</CODE> in C.
  1422. <DT><CODE>cl_I logorc1 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1423. <DD>
  1424. Logical or, complementing the first argument, like <CODE>~x | y</CODE> in C.
  1425. <DT><CODE>cl_I logorc2 (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1426. <DD>
  1427. Logical or, complementing the second argument, like <CODE>x | ~y</CODE> in C.
  1428. </DL>
  1429. <P>
  1430. These operations are all available though the function
  1431. <DL COMPACT>
  1432. <DT><CODE>cl_I boole (cl_boole op, const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1433. <DD>
  1434. </DL>
  1435. <P>
  1436. where <CODE>op</CODE> must have one of the 16 values (each one stands for a function
  1437. which combines two bits into one bit): <CODE>boole_clr</CODE>, <CODE>boole_set</CODE>,
  1438. <CODE>boole_1</CODE>, <CODE>boole_2</CODE>, <CODE>boole_c1</CODE>, <CODE>boole_c2</CODE>,
  1439. <CODE>boole_and</CODE>, <CODE>boole_ior</CODE>, <CODE>boole_xor</CODE>, <CODE>boole_eqv</CODE>,
  1440. <CODE>boole_nand</CODE>, <CODE>boole_nor</CODE>, <CODE>boole_andc1</CODE>, <CODE>boole_andc2</CODE>,
  1441. <CODE>boole_orc1</CODE>, <CODE>boole_orc2</CODE>.
  1442. <P>
  1443. Other functions that view integers as bit strings:
  1444. <DL COMPACT>
  1445. <DT><CODE>cl_boolean logtest (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1446. <DD>
  1447. Returns true if some bit is set in both <CODE>x</CODE> and <CODE>y</CODE>, i.e. if
  1448. <CODE>logand(x,y) != 0</CODE>.
  1449. <DT><CODE>cl_boolean logbitp (const cl_I&#38; n, const cl_I&#38; x)</CODE>
  1450. <DD>
  1451. Returns true if the <CODE>n</CODE>th bit (from the right) of <CODE>x</CODE> is set.
  1452. Bit 0 is the least significant bit.
  1453. <DT><CODE>uintL logcount (const cl_I&#38; x)</CODE>
  1454. <DD>
  1455. Returns the number of one bits in <CODE>x</CODE>, if <CODE>x</CODE> &#62;= 0, or
  1456. the number of zero bits in <CODE>x</CODE>, if <CODE>x</CODE> &#60; 0.
  1457. </DL>
  1458. <P>
  1459. The following functions operate on intervals of bits in integers.
  1460. The type
  1461. <PRE>
  1462. struct cl_byte { uintL size; uintL position; };
  1463. </PRE>
  1464. <P>
  1465. represents the bit interval containing the bits
  1466. <CODE>position</CODE>...<CODE>position+size-1</CODE> of an integer.
  1467. The constructor <CODE>cl_byte(size,position)</CODE> constructs a <CODE>cl_byte</CODE>.
  1468. <DL COMPACT>
  1469. <DT><CODE>cl_I ldb (const cl_I&#38; n, const cl_byte&#38; b)</CODE>
  1470. <DD>
  1471. extracts the bits of <CODE>n</CODE> described by the bit interval <CODE>b</CODE>
  1472. and returns them as a nonnegative integer with <CODE>b.size</CODE> bits.
  1473. <DT><CODE>cl_boolean ldb_test (const cl_I&#38; n, const cl_byte&#38; b)</CODE>
  1474. <DD>
  1475. Returns true if some bit described by the bit interval <CODE>b</CODE> is set in
  1476. <CODE>n</CODE>.
  1477. <DT><CODE>cl_I dpb (const cl_I&#38; newbyte, const cl_I&#38; n, const cl_byte&#38; b)</CODE>
  1478. <DD>
  1479. Returns <CODE>n</CODE>, with the bits described by the bit interval <CODE>b</CODE>
  1480. replaced by <CODE>newbyte</CODE>. Only the lowest <CODE>b.size</CODE> bits of
  1481. <CODE>newbyte</CODE> are relevant.
  1482. </DL>
  1483. <P>
  1484. The functions <CODE>ldb</CODE> and <CODE>dpb</CODE> implicitly shift. The following
  1485. functions are their counterparts without shifting:
  1486. <DL COMPACT>
  1487. <DT><CODE>cl_I mask_field (const cl_I&#38; n, const cl_byte&#38; b)</CODE>
  1488. <DD>
  1489. returns an integer with the bits described by the bit interval <CODE>b</CODE>
  1490. copied from the corresponding bits in <CODE>n</CODE>, the other bits zero.
  1491. <DT><CODE>cl_I deposit_field (const cl_I&#38; newbyte, const cl_I&#38; n, const cl_byte&#38; b)</CODE>
  1492. <DD>
  1493. returns an integer where the bits described by the bit interval <CODE>b</CODE>
  1494. come from <CODE>newbyte</CODE> and the other bits come from <CODE>n</CODE>.
  1495. </DL>
  1496. <P>
  1497. The following relations hold:
  1498. <UL>
  1499. <LI>
  1500. <CODE>ldb (n, b) = mask_field(n, b) &#62;&#62; b.position</CODE>,
  1501. <LI>
  1502. <CODE>dpb (newbyte, n, b) = deposit_field (newbyte &#60;&#60; b.position, n, b)</CODE>,
  1503. <LI>
  1504. <CODE>deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^ mask_field(new_byte,b)</CODE>.
  1505. </UL>
  1506. <P>
  1507. The following operations on integers as bit strings are efficient shortcuts
  1508. for common arithmetic operations:
  1509. <DL COMPACT>
  1510. <DT><CODE>cl_boolean oddp (const cl_I&#38; x)</CODE>
  1511. <DD>
  1512. Returns true if the least significant bit of <CODE>x</CODE> is 1. Equivalent to
  1513. <CODE>mod(x,2) != 0</CODE>.
  1514. <DT><CODE>cl_boolean evenp (const cl_I&#38; x)</CODE>
  1515. <DD>
  1516. Returns true if the least significant bit of <CODE>x</CODE> is 0. Equivalent to
  1517. <CODE>mod(x,2) == 0</CODE>.
  1518. <DT><CODE>cl_I operator &#60;&#60; (const cl_I&#38; x, const cl_I&#38; n)</CODE>
  1519. <DD>
  1520. Shifts <CODE>x</CODE> by <CODE>n</CODE> bits to the left. <CODE>n</CODE> should be &#62;=0.
  1521. Equivalent to <CODE>x * expt(2,n)</CODE>.
  1522. <DT><CODE>cl_I operator &#62;&#62; (const cl_I&#38; x, const cl_I&#38; n)</CODE>
  1523. <DD>
  1524. Shifts <CODE>x</CODE> by <CODE>n</CODE> bits to the right. <CODE>n</CODE> should be &#62;=0.
  1525. Bits shifted out to the right are thrown away.
  1526. Equivalent to <CODE>floor(x / expt(2,n))</CODE>.
  1527. <DT><CODE>cl_I ash (const cl_I&#38; x, const cl_I&#38; y)</CODE>
  1528. <DD>
  1529. Shifts <CODE>x</CODE> by <CODE>y</CODE> bits to the left (if <CODE>y</CODE>&#62;=0) or
  1530. by <CODE>-y</CODE> bits to the right (if <CODE>y</CODE>&#60;=0). In other words, this
  1531. returns <CODE>floor(x * expt(2,y))</CODE>.
  1532. <DT><CODE>uintL integer_length (const cl_I&#38; x)</CODE>
  1533. <DD>
  1534. Returns the number of bits (excluding the sign bit) needed to represent <CODE>x</CODE>
  1535. in two's complement notation. This is the smallest n &#62;= 0 such that
  1536. -2^n &#60;= x &#60; 2^n. If x &#62; 0, this is the unique n &#62; 0 such that
  1537. 2^(n-1) &#60;= x &#60; 2^n.
  1538. <DT><CODE>uintL ord2 (const cl_I&#38; x)</CODE>
  1539. <DD>
  1540. <CODE>x</CODE> must be non-zero. This function returns the number of 0 bits at the
  1541. right of <CODE>x</CODE> in two's complement notation. This is the largest n &#62;= 0
  1542. such that 2^n divides <CODE>x</CODE>.
  1543. <DT><CODE>uintL power2p (const cl_I&#38; x)</CODE>
  1544. <DD>
  1545. <CODE>x</CODE> must be &#62; 0. This function checks whether <CODE>x</CODE> is a power of 2.
  1546. If <CODE>x</CODE> = 2^(n-1), it returns n. Else it returns 0.
  1547. (See also the function <CODE>logp</CODE>.)
  1548. </DL>
  1549. <H3><A NAME="SEC35" HREF="cln.html#TOC35">4.9.2 Number theoretic functions</A></H3>
  1550. <DL COMPACT>
  1551. <DT><CODE>uint32 gcd (uint32 a, uint32 b)</CODE>
  1552. <DD>
  1553. <DT><CODE>cl_I gcd (const cl_I&#38; a, const cl_I&#38; b)</CODE>
  1554. <DD>
  1555. This function returns the greatest common divisor of <CODE>a</CODE> and <CODE>b</CODE>,
  1556. normalized to be &#62;= 0.
  1557. <DT><CODE>cl_I xgcd (const cl_I&#38; a, const cl_I&#38; b, cl_I* u, cl_I* v)</CODE>
  1558. <DD>
  1559. This function ("extended gcd") returns the greatest common divisor <CODE>g</CODE> of
  1560. <CODE>a</CODE> and <CODE>b</CODE> and at the same time the representation of <CODE>g</CODE>
  1561. as an integral linear combination of <CODE>a</CODE> and <CODE>b</CODE>:
  1562. <CODE>u</CODE> and <CODE>v</CODE> with <CODE>u*a+v*b = g</CODE>, <CODE>g</CODE> &#62;= 0.
  1563. <CODE>u</CODE> and <CODE>v</CODE> will be normalized to be of smallest possible absolute
  1564. value, in the following sense: If <CODE>a</CODE> and <CODE>b</CODE> are non-zero, and
  1565. <CODE>abs(a) != abs(b)</CODE>, <CODE>u</CODE> and <CODE>v</CODE> will satisfy the inequalities
  1566. <CODE>abs(u) &#60;= abs(b)/(2*g)</CODE>, <CODE>abs(v) &#60;= abs(a)/(2*g)</CODE>.
  1567. <DT><CODE>cl_I lcm (const cl_I&#38; a, const cl_I&#38; b)</CODE>
  1568. <DD>
  1569. This function returns the least common multiple of <CODE>a</CODE> and <CODE>b</CODE>,
  1570. normalized to be &#62;= 0.
  1571. <DT><CODE>cl_boolean logp (const cl_I&#38; a, const cl_I&#38; b, cl_RA* l)</CODE>
  1572. <DD>
  1573. <DT><CODE>cl_boolean logp (const cl_RA&#38; a, const cl_RA&#38; b, cl_RA* l)</CODE>
  1574. <DD>
  1575. <CODE>a</CODE> must be &#62; 0. <CODE>b</CODE> must be &#62;0 and != 1. If log(a,b) is
  1576. rational number, this function returns true and sets *l = log(a,b), else
  1577. it returns false.
  1578. </DL>
  1579. <H3><A NAME="SEC36" HREF="cln.html#TOC36">4.9.3 Combinatorial functions</A></H3>
  1580. <DL COMPACT>
  1581. <DT><CODE>cl_I factorial (uintL n)</CODE>
  1582. <DD>
  1583. <CODE>n</CODE> must be a small integer &#62;= 0. This function returns the factorial
  1584. <CODE>n</CODE>! = <CODE>1*2*...*n</CODE>.
  1585. <DT><CODE>cl_I doublefactorial (uintL n)</CODE>
  1586. <DD>
  1587. <CODE>n</CODE> must be a small integer &#62;= 0. This function returns the
  1588. doublefactorial <CODE>n</CODE>!! = <CODE>1*3*...*n</CODE> or
  1589. <CODE>n</CODE>!! = <CODE>2*4*...*n</CODE>, respectively.
  1590. <DT><CODE>cl_I binomial (uintL n, uintL k)</CODE>
  1591. <DD>
  1592. <CODE>n</CODE> and <CODE>k</CODE> must be small integers &#62;= 0. This function returns the
  1593. binomial coefficient
  1594. (<CODE>n</CODE> choose <CODE>k</CODE>) = <CODE>n</CODE>! / <CODE>k</CODE>! <CODE>(n-k)</CODE>!
  1595. for 0 &#60;= k &#60;= n, 0 else.
  1596. </DL>
  1597. <H2><A NAME="SEC37" HREF="cln.html#TOC37">4.10 Functions on floating-point numbers</A></H2>
  1598. <P>
  1599. Recall that a floating-point number consists of a sign <CODE>s</CODE>, an
  1600. exponent <CODE>e</CODE> and a mantissa <CODE>m</CODE>. The value of the number is
  1601. <CODE>(-1)^s * 2^e * m</CODE>.
  1602. <P>
  1603. Each of the classes
  1604. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  1605. defines the following operations.
  1606. <DL COMPACT>
  1607. <DT><CODE><VAR>type</VAR> scale_float (const <VAR>type</VAR>&#38; x, sintL delta)</CODE>
  1608. <DD>
  1609. <DT><CODE><VAR>type</VAR> scale_float (const <VAR>type</VAR>&#38; x, const cl_I&#38; delta)</CODE>
  1610. <DD>
  1611. Returns <CODE>x*2^delta</CODE>. This is more efficient than an explicit multiplication
  1612. because it copies <CODE>x</CODE> and modifies the exponent.
  1613. </DL>
  1614. <P>
  1615. The following functions provide an abstract interface to the underlying
  1616. representation of floating-point numbers.
  1617. <DL COMPACT>
  1618. <DT><CODE>sintL float_exponent (const <VAR>type</VAR>&#38; x)</CODE>
  1619. <DD>
  1620. Returns the exponent <CODE>e</CODE> of <CODE>x</CODE>.
  1621. For <CODE>x = 0.0</CODE>, this is 0. For <CODE>x</CODE> non-zero, this is the unique
  1622. integer with <CODE>2^(e-1) &#60;= abs(x) &#60; 2^e</CODE>.
  1623. <DT><CODE>sintL float_radix (const <VAR>type</VAR>&#38; x)</CODE>
  1624. <DD>
  1625. Returns the base of the floating-point representation. This is always <CODE>2</CODE>.
  1626. <DT><CODE><VAR>type</VAR> float_sign (const <VAR>type</VAR>&#38; x)</CODE>
  1627. <DD>
  1628. Returns the sign <CODE>s</CODE> of <CODE>x</CODE> as a float. The value is 1 for
  1629. <CODE>x</CODE> &#62;= 0, -1 for <CODE>x</CODE> &#60; 0.
  1630. <DT><CODE>uintL float_digits (const <VAR>type</VAR>&#38; x)</CODE>
  1631. <DD>
  1632. Returns the number of mantissa bits in the floating-point representation
  1633. of <CODE>x</CODE>, including the hidden bit. The value only depends on the type
  1634. of <CODE>x</CODE>, not on its value.
  1635. <DT><CODE>uintL float_precision (const <VAR>type</VAR>&#38; x)</CODE>
  1636. <DD>
  1637. Returns the number of significant mantissa bits in the floating-point
  1638. representation of <CODE>x</CODE>. Since denormalized numbers are not supported,
  1639. this is the same as <CODE>float_digits(x)</CODE> if <CODE>x</CODE> is non-zero, and
  1640. 0 if <CODE>x</CODE> = 0.
  1641. </DL>
  1642. <P>
  1643. The complete internal representation of a float is encoded in the type
  1644. <CODE>cl_decoded_float</CODE> (or <CODE>cl_decoded_sfloat</CODE>, <CODE>cl_decoded_ffloat</CODE>,
  1645. <CODE>cl_decoded_dfloat</CODE>, <CODE>cl_decoded_lfloat</CODE>, respectively), defined by
  1646. <PRE>
  1647. struct cl_decoded_<VAR>type</VAR>float {
  1648. <VAR>type</VAR> mantissa; cl_I exponent; <VAR>type</VAR> sign;
  1649. };
  1650. </PRE>
  1651. <P>
  1652. and returned by the function
  1653. <DL COMPACT>
  1654. <DT><CODE>cl_decoded_<VAR>type</VAR>float decode_float (const <VAR>type</VAR>&#38; x)</CODE>
  1655. <DD>
  1656. For <CODE>x</CODE> non-zero, this returns <CODE>(-1)^s</CODE>, <CODE>e</CODE>, <CODE>m</CODE> with
  1657. <CODE>x = (-1)^s * 2^e * m</CODE> and <CODE>0.5 &#60;= m &#60; 1.0</CODE>. For <CODE>x</CODE> = 0,
  1658. it returns <CODE>(-1)^s</CODE>=1, <CODE>e</CODE>=0, <CODE>m</CODE>=0.
  1659. <CODE>e</CODE> is the same as returned by the function <CODE>float_exponent</CODE>.
  1660. </DL>
  1661. <P>
  1662. A complete decoding in terms of integers is provided as type
  1663. <PRE>
  1664. struct cl_idecoded_float {
  1665. cl_I mantissa; cl_I exponent; cl_I sign;
  1666. };
  1667. </PRE>
  1668. <P>
  1669. by the following function:
  1670. <DL COMPACT>
  1671. <DT><CODE>cl_idecoded_float integer_decode_float (const <VAR>type</VAR>&#38; x)</CODE>
  1672. <DD>
  1673. For <CODE>x</CODE> non-zero, this returns <CODE>(-1)^s</CODE>, <CODE>e</CODE>, <CODE>m</CODE> with
  1674. <CODE>x = (-1)^s * 2^e * m</CODE> and <CODE>m</CODE> an integer with <CODE>float_digits(x)</CODE>
  1675. bits. For <CODE>x</CODE> = 0, it returns <CODE>(-1)^s</CODE>=1, <CODE>e</CODE>=0, <CODE>m</CODE>=0.
  1676. WARNING: The exponent <CODE>e</CODE> is not the same as the one returned by
  1677. the functions <CODE>decode_float</CODE> and <CODE>float_exponent</CODE>.
  1678. </DL>
  1679. <P>
  1680. Some other function, implemented only for class <CODE>cl_F</CODE>:
  1681. <DL COMPACT>
  1682. <DT><CODE>cl_F float_sign (const cl_F&#38; x, const cl_F&#38; y)</CODE>
  1683. <DD>
  1684. This returns a floating point number whose precision and absolute value
  1685. is that of <CODE>y</CODE> and whose sign is that of <CODE>x</CODE>. If <CODE>x</CODE> is
  1686. zero, it is treated as positive. Same for <CODE>y</CODE>.
  1687. </DL>
  1688. <H2><A NAME="SEC38" HREF="cln.html#TOC38">4.11 Conversion functions</A></H2>
  1689. <H3><A NAME="SEC39" HREF="cln.html#TOC39">4.11.1 Conversion to floating-point numbers</A></H3>
  1690. <P>
  1691. The type <CODE>cl_float_format_t</CODE> describes a floating-point format.
  1692. <DL COMPACT>
  1693. <DT><CODE>cl_float_format_t cl_float_format (uintL n)</CODE>
  1694. <DD>
  1695. Returns the smallest float format which guarantees at least <CODE>n</CODE>
  1696. decimal digits in the mantissa (after the decimal point).
  1697. <DT><CODE>cl_float_format_t cl_float_format (const cl_F&#38; x)</CODE>
  1698. <DD>
  1699. Returns the floating point format of <CODE>x</CODE>.
  1700. <DT><CODE>cl_float_format_t cl_default_float_format</CODE>
  1701. <DD>
  1702. Global variable: the default float format used when converting rational numbers
  1703. to floats.
  1704. </DL>
  1705. <P>
  1706. To convert a real number to a float, each of the types
  1707. <CODE>cl_R</CODE>, <CODE>cl_F</CODE>, <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
  1708. <CODE>int</CODE>, <CODE>unsigned int</CODE>, <CODE>float</CODE>, <CODE>double</CODE>
  1709. defines the following operations:
  1710. <DL COMPACT>
  1711. <DT><CODE>cl_F cl_float (const <VAR>type</VAR>&#38;x, cl_float_format_t f)</CODE>
  1712. <DD>
  1713. Returns <CODE>x</CODE> as a float of format <CODE>f</CODE>.
  1714. <DT><CODE>cl_F cl_float (const <VAR>type</VAR>&#38;x, const cl_F&#38; y)</CODE>
  1715. <DD>
  1716. Returns <CODE>x</CODE> in the float format of <CODE>y</CODE>.
  1717. <DT><CODE>cl_F cl_float (const <VAR>type</VAR>&#38;x)</CODE>
  1718. <DD>
  1719. Returns <CODE>x</CODE> as a float of format <CODE>cl_default_float_format</CODE> if
  1720. it is an exact number, or <CODE>x</CODE> itself if it is already a float.
  1721. </DL>
  1722. <P>
  1723. Of course, converting a number to a float can lose precision.
  1724. <P>
  1725. Every floating-point format has some characteristic numbers:
  1726. <DL COMPACT>
  1727. <DT><CODE>cl_F most_positive_float (cl_float_format_t f)</CODE>
  1728. <DD>
  1729. Returns the largest (most positive) floating point number in float format <CODE>f</CODE>.
  1730. <DT><CODE>cl_F most_negative_float (cl_float_format_t f)</CODE>
  1731. <DD>
  1732. Returns the smallest (most negative) floating point number in float format <CODE>f</CODE>.
  1733. <DT><CODE>cl_F least_positive_float (cl_float_format_t f)</CODE>
  1734. <DD>
  1735. Returns the least positive floating point number (i.e. &#62; 0 but closest to 0)
  1736. in float format <CODE>f</CODE>.
  1737. <DT><CODE>cl_F least_negative_float (cl_float_format_t f)</CODE>
  1738. <DD>
  1739. Returns the least negative floating point number (i.e. &#60; 0 but closest to 0)
  1740. in float format <CODE>f</CODE>.
  1741. <DT><CODE>cl_F float_epsilon (cl_float_format_t f)</CODE>
  1742. <DD>
  1743. Returns the smallest floating point number e &#62; 0 such that <CODE>1+e != 1</CODE>.
  1744. <DT><CODE>cl_F float_negative_epsilon (cl_float_format_t f)</CODE>
  1745. <DD>
  1746. Returns the smallest floating point number e &#62; 0 such that <CODE>1-e != 1</CODE>.
  1747. </DL>
  1748. <H3><A NAME="SEC40" HREF="cln.html#TOC40">4.11.2 Conversion to rational numbers</A></H3>
  1749. <P>
  1750. Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_F</CODE>
  1751. defines the following operation:
  1752. <DL COMPACT>
  1753. <DT><CODE>cl_RA rational (const <VAR>type</VAR>&#38; x)</CODE>
  1754. <DD>
  1755. Returns the value of <CODE>x</CODE> as an exact number. If <CODE>x</CODE> is already
  1756. an exact number, this is <CODE>x</CODE>. If <CODE>x</CODE> is a floating-point number,
  1757. the value is a rational number whose denominator is a power of 2.
  1758. </DL>
  1759. <P>
  1760. In order to convert back, say, <CODE>(cl_F)(cl_R)"1/3"</CODE> to <CODE>1/3</CODE>, there is
  1761. the function
  1762. <DL COMPACT>
  1763. <DT><CODE>cl_RA rationalize (const cl_R&#38; x)</CODE>
  1764. <DD>
  1765. If <CODE>x</CODE> is a floating-point number, it actually represents an interval
  1766. of real numbers, and this function returns the rational number with
  1767. smallest denominator (and smallest numerator, in magnitude)
  1768. which lies in this interval.
  1769. If <CODE>x</CODE> is already an exact number, this function returns <CODE>x</CODE>.
  1770. </DL>
  1771. <P>
  1772. If <CODE>x</CODE> is any float, one has
  1773. <UL>
  1774. <LI>
  1775. <CODE>cl_float(rational(x),x) = x</CODE>
  1776. <LI>
  1777. <CODE>cl_float(rationalize(x),x) = x</CODE>
  1778. </UL>
  1779. <H2><A NAME="SEC41" HREF="cln.html#TOC41">4.12 Random number generators</A></H2>
  1780. <P>
  1781. A random generator is a machine which produces (pseudo-)random numbers.
  1782. The include file <CODE>&#60;cl_random.h&#62;</CODE> defines a class <CODE>cl_random_state</CODE>
  1783. which contains the state of a random generator. If you make a copy
  1784. of the random number generator, the original one and the copy will produce
  1785. the same sequence of random numbers.
  1786. <P>
  1787. The following functions return (pseudo-)random numbers in different formats.
  1788. Calling one of these modifies the state of the random number generator in
  1789. a complicated but deterministic way.
  1790. <P>
  1791. The global variable
  1792. <PRE>
  1793. cl_random_state cl_default_random_state
  1794. </PRE>
  1795. <P>
  1796. contains a default random number generator. It is used when the functions
  1797. below are called without <CODE>cl_random_state</CODE> argument.
  1798. <DL COMPACT>
  1799. <DT><CODE>uint32 random32 (cl_random_state&#38; randomstate)</CODE>
  1800. <DD>
  1801. <DT><CODE>uint32 random32 ()</CODE>
  1802. <DD>
  1803. Returns a random unsigned 32-bit number. All bits are equally random.
  1804. <DT><CODE>cl_I random_I (cl_random_state&#38; randomstate, const cl_I&#38; n)</CODE>
  1805. <DD>
  1806. <DT><CODE>cl_I random_I (const cl_I&#38; n)</CODE>
  1807. <DD>
  1808. <CODE>n</CODE> must be an integer &#62; 0. This function returns a random integer <CODE>x</CODE>
  1809. in the range <CODE>0 &#60;= x &#60; n</CODE>.
  1810. <DT><CODE>cl_F random_F (cl_random_state&#38; randomstate, const cl_F&#38; n)</CODE>
  1811. <DD>
  1812. <DT><CODE>cl_F random_F (const cl_F&#38; n)</CODE>
  1813. <DD>
  1814. <CODE>n</CODE> must be a float &#62; 0. This function returns a random floating-point
  1815. number of the same format as <CODE>n</CODE> in the range <CODE>0 &#60;= x &#60; n</CODE>.
  1816. <DT><CODE>cl_R random_R (cl_random_state&#38; randomstate, const cl_R&#38; n)</CODE>
  1817. <DD>
  1818. <DT><CODE>cl_R random_R (const cl_R&#38; n)</CODE>
  1819. <DD>
  1820. Behaves like <CODE>random_I</CODE> if <CODE>n</CODE> is an integer and like <CODE>random_F</CODE>
  1821. if <CODE>n</CODE> is a float.
  1822. </DL>
  1823. <H2><A NAME="SEC42" HREF="cln.html#TOC42">4.13 Obfuscating operators</A></H2>
  1824. <P>
  1825. The modifying C/C++ operators <CODE>+=</CODE>, <CODE>-=</CODE>, <CODE>*=</CODE>, <CODE>/=</CODE>,
  1826. <CODE>&#38;=</CODE>, <CODE>|=</CODE>, <CODE>^=</CODE>, <CODE>&#60;&#60;=</CODE>, <CODE>&#62;&#62;=</CODE>
  1827. are not available by default because their
  1828. use tends to make programs unreadable. It is trivial to get away without
  1829. them. However, if you feel that you absolutely need these operators
  1830. to get happy, then add
  1831. <PRE>
  1832. #define WANT_OBFUSCATING_OPERATORS
  1833. </PRE>
  1834. <P>
  1835. to the beginning of your source files, before the inclusion of any CLN
  1836. include files. This flag will enable the following operators:
  1837. <P>
  1838. For the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
  1839. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>:
  1840. <DL COMPACT>
  1841. <DT><CODE><VAR>type</VAR>&#38; operator += (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1842. <DD>
  1843. <DT><CODE><VAR>type</VAR>&#38; operator -= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1844. <DD>
  1845. <DT><CODE><VAR>type</VAR>&#38; operator *= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1846. <DD>
  1847. <DT><CODE><VAR>type</VAR>&#38; operator /= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1848. <DD>
  1849. </DL>
  1850. <P>
  1851. For the class <CODE>cl_I</CODE>:
  1852. <DL COMPACT>
  1853. <DT><CODE><VAR>type</VAR>&#38; operator += (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1854. <DD>
  1855. <DT><CODE><VAR>type</VAR>&#38; operator -= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1856. <DD>
  1857. <DT><CODE><VAR>type</VAR>&#38; operator *= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1858. <DD>
  1859. <DT><CODE><VAR>type</VAR>&#38; operator &#38;= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1860. <DD>
  1861. <DT><CODE><VAR>type</VAR>&#38; operator |= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1862. <DD>
  1863. <DT><CODE><VAR>type</VAR>&#38; operator ^= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1864. <DD>
  1865. <DT><CODE><VAR>type</VAR>&#38; operator &#60;&#60;= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1866. <DD>
  1867. <DT><CODE><VAR>type</VAR>&#38; operator &#62;&#62;= (<VAR>type</VAR>&#38;, const <VAR>type</VAR>&#38;)</CODE>
  1868. <DD>
  1869. </DL>
  1870. <P>
  1871. For the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  1872. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>:
  1873. <DL COMPACT>
  1874. <DT><CODE><VAR>type</VAR>&#38; operator ++ (<VAR>type</VAR>&#38; x)</CODE>
  1875. <DD>
  1876. The prefix operator <CODE>++x</CODE>.
  1877. <DT><CODE>void operator ++ (<VAR>type</VAR>&#38; x, int)</CODE>
  1878. <DD>
  1879. The postfix operator <CODE>x++</CODE>.
  1880. <DT><CODE><VAR>type</VAR>&#38; operator -- (<VAR>type</VAR>&#38; x)</CODE>
  1881. <DD>
  1882. The prefix operator <CODE>--x</CODE>.
  1883. <DT><CODE>void operator -- (<VAR>type</VAR>&#38; x, int)</CODE>
  1884. <DD>
  1885. The postfix operator <CODE>x--</CODE>.
  1886. </DL>
  1887. <P>
  1888. Note that by using these obfuscating operators, you wouldn't gain efficiency:
  1889. In CLN <SAMP>`x += y;'</SAMP> is exactly the same as <SAMP>`x = x+y;'</SAMP>, not more
  1890. efficient.
  1891. <H1><A NAME="SEC43" HREF="cln.html#TOC43">5. Input/Output</A></H1>
  1892. <H2><A NAME="SEC44" HREF="cln.html#TOC44">5.1 Internal and printed representation</A></H2>
  1893. <P>
  1894. All computations deal with the internal representations of the numbers.
  1895. <P>
  1896. Every number has an external representation as a sequence of ASCII characters.
  1897. Several external representations may denote the same number, for example,
  1898. "20.0" and "20.000".
  1899. <P>
  1900. Converting an internal to an external representation is called "printing",
  1901. converting an external to an internal representation is called "reading".
  1902. In CLN, is it always true that conversion of an internal to an external
  1903. representation and then back to an internal representation will yield the
  1904. same internal representation. Symbolically: <CODE>read(print(x)) == x</CODE>.
  1905. This is called "print-read consistency".
  1906. <P>
  1907. Different types of numbers have different external representations (case
  1908. is insignificant):
  1909. <DL COMPACT>
  1910. <DT>Integers
  1911. <DD>
  1912. External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+. The reader also accepts the
  1913. Common Lisp syntaxes <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>.</CODE> with a trailing dot
  1914. for decimal integers
  1915. and the <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes.
  1916. <DT>Rational numbers
  1917. <DD>
  1918. External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}+<CODE>/</CODE>{<VAR>digit</VAR>}+.
  1919. The <CODE>#<VAR>n</VAR>R</CODE>, <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> prefixes are allowed
  1920. here as well.
  1921. <DT>Floating-point numbers
  1922. <DD>
  1923. External representation: <VAR>sign</VAR>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
  1924. <VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}*<VAR>exponent</VAR> or
  1925. <VAR>sign</VAR>{<VAR>digit</VAR>}*<CODE>.</CODE>{<VAR>digit</VAR>}+. A precision specifier
  1926. of the form _<VAR>prec</VAR> may be appended. There must be at least
  1927. one digit in the non-exponent part. The exponent has the syntax
  1928. <VAR>expmarker</VAR> <VAR>expsign</VAR> {<VAR>digit</VAR>}+.
  1929. The exponent marker is
  1930. <UL>
  1931. <LI>
  1932. <SAMP>`s'</SAMP> for short-floats,
  1933. <LI>
  1934. <SAMP>`f'</SAMP> for single-floats,
  1935. <LI>
  1936. <SAMP>`d'</SAMP> for double-floats,
  1937. <LI>
  1938. <SAMP>`L'</SAMP> for long-floats,
  1939. </UL>
  1940. or <SAMP>`e'</SAMP>, which denotes a default float format. The precision specifying
  1941. suffix has the syntax _<VAR>prec</VAR> where <VAR>prec</VAR> denotes the number of
  1942. valid mantissa digits (in decimal, excluding leading zeroes), cf. also
  1943. function <SAMP>`cl_float_format'</SAMP>.
  1944. <DT>Complex numbers
  1945. <DD>
  1946. External representation:
  1947. <UL>
  1948. <LI>
  1949. In algebraic notation: <CODE><VAR>realpart</VAR>+<VAR>imagpart</VAR>i</CODE>. Of course,
  1950. if <VAR>imagpart</VAR> is negative, its printed representation begins with
  1951. a <SAMP>`-'</SAMP>, and the <SAMP>`+'</SAMP> between <VAR>realpart</VAR> and <VAR>imagpart</VAR>
  1952. may be omitted. Note that this notation cannot be used when the <VAR>imagpart</VAR>
  1953. is rational and the rational number's base is &#62;18, because the <SAMP>`i'</SAMP>
  1954. is then read as a digit.
  1955. <LI>
  1956. In Common Lisp notation: <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>.
  1957. </UL>
  1958. </DL>
  1959. <H2><A NAME="SEC45" HREF="cln.html#TOC45">5.2 Input functions</A></H2>
  1960. <P>
  1961. Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_istream</CODE>, which is
  1962. the type of the first argument to all input functions. Unless you build
  1963. and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_istream</CODE>
  1964. is the same as <CODE>istream&#38;</CODE>.
  1965. <P>
  1966. The variable
  1967. <UL>
  1968. <LI>
  1969. <CODE>cl_istream cl_stdin</CODE>
  1970. </UL>
  1971. <P>
  1972. contains the standard input stream.
  1973. <P>
  1974. These are the simple input functions:
  1975. <DL COMPACT>
  1976. <DT><CODE>int freadchar (cl_istream stream)</CODE>
  1977. <DD>
  1978. Reads a character from <CODE>stream</CODE>. Returns <CODE>cl_EOF</CODE> (not a <SAMP>`char'</SAMP>!)
  1979. if the end of stream was encountered or an error occurred.
  1980. <DT><CODE>int funreadchar (cl_istream stream, int c)</CODE>
  1981. <DD>
  1982. Puts back <CODE>c</CODE> onto <CODE>stream</CODE>. <CODE>c</CODE> must be the result of the
  1983. last <CODE>freadchar</CODE> operation on <CODE>stream</CODE>.
  1984. </DL>
  1985. <P>
  1986. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  1987. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  1988. defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following input function:
  1989. <DL COMPACT>
  1990. <DT><CODE>cl_istream operator&#62;&#62; (cl_istream stream, <VAR>type</VAR>&#38; result)</CODE>
  1991. <DD>
  1992. Reads a number from <CODE>stream</CODE> and stores it in the <CODE>result</CODE>.
  1993. </DL>
  1994. <P>
  1995. The most flexible input functions, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
  1996. are the following:
  1997. <DL COMPACT>
  1998. <DT><CODE>cl_N read_complex (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
  1999. <DD>
  2000. <DT><CODE>cl_R read_real (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
  2001. <DD>
  2002. <DT><CODE>cl_F read_float (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
  2003. <DD>
  2004. <DT><CODE>cl_RA read_rational (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
  2005. <DD>
  2006. <DT><CODE>cl_I read_integer (cl_istream stream, const cl_read_flags&#38; flags)</CODE>
  2007. <DD>
  2008. Reads a number from <CODE>stream</CODE>. The <CODE>flags</CODE> are parameters which
  2009. affect the input syntax. Whitespace before the number is silently skipped.
  2010. <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>
  2011. <DD>
  2012. <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>
  2013. <DD>
  2014. <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>
  2015. <DD>
  2016. <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>
  2017. <DD>
  2018. <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>
  2019. <DD>
  2020. Reads a number from a string in memory. The <CODE>flags</CODE> are parameters which
  2021. affect the input syntax. The string starts at <CODE>string</CODE> and ends at
  2022. <CODE>string_limit</CODE> (exclusive limit). <CODE>string_limit</CODE> may also be
  2023. <CODE>NULL</CODE>, denoting the entire string, i.e. equivalent to
  2024. <CODE>string_limit = string + strlen(string)</CODE>. If <CODE>end_of_parse</CODE> is
  2025. <CODE>NULL</CODE>, the string in memory must contain exactly one number and nothing
  2026. more, else a fatal error will be signalled. If <CODE>end_of_parse</CODE>
  2027. is not <CODE>NULL</CODE>, <CODE>*end_of_parse</CODE> will be assigned a pointer past
  2028. the last parsed character (i.e. <CODE>string_limit</CODE> if nothing came after
  2029. the number). Whitespace is not allowed.
  2030. </DL>
  2031. <P>
  2032. The structure <CODE>cl_read_flags</CODE> contains the following fields:
  2033. <DL COMPACT>
  2034. <DT><CODE>cl_read_syntax_t syntax</CODE>
  2035. <DD>
  2036. The possible results of the read operation. Possible values are
  2037. <CODE>syntax_number</CODE>, <CODE>syntax_real</CODE>, <CODE>syntax_rational</CODE>,
  2038. <CODE>syntax_integer</CODE>, <CODE>syntax_float</CODE>, <CODE>syntax_sfloat</CODE>,
  2039. <CODE>syntax_ffloat</CODE>, <CODE>syntax_dfloat</CODE>, <CODE>syntax_lfloat</CODE>.
  2040. <DT><CODE>cl_read_lsyntax_t lsyntax</CODE>
  2041. <DD>
  2042. Specifies the language-dependent syntax variant for the read operation.
  2043. Possible values are
  2044. <DL COMPACT>
  2045. <DT><CODE>lsyntax_standard</CODE>
  2046. <DD>
  2047. accept standard algebraic notation only, no complex numbers,
  2048. <DT><CODE>lsyntax_algebraic</CODE>
  2049. <DD>
  2050. accept the algebraic notation <CODE><VAR>x</VAR>+<VAR>y</VAR>i</CODE> for complex numbers,
  2051. <DT><CODE>lsyntax_commonlisp</CODE>
  2052. <DD>
  2053. accept the <CODE>#b</CODE>, <CODE>#o</CODE>, <CODE>#x</CODE> syntaxes for binary, octal,
  2054. hexadecimal numbers,
  2055. <CODE>#<VAR>base</VAR>R</CODE> for rational numbers in a given base,
  2056. <CODE>#c(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE> for complex numbers,
  2057. <DT><CODE>lsyntax_all</CODE>
  2058. <DD>
  2059. accept all of these extensions.
  2060. </DL>
  2061. <DT><CODE>unsigned int rational_base</CODE>
  2062. <DD>
  2063. The base in which rational numbers are read.
  2064. <DT><CODE>cl_float_format_t float_flags.default_float_format</CODE>
  2065. <DD>
  2066. The float format used when reading floats with exponent marker <SAMP>`e'</SAMP>.
  2067. <DT><CODE>cl_float_format_t float_flags.default_lfloat_format</CODE>
  2068. <DD>
  2069. The float format used when reading floats with exponent marker <SAMP>`l'</SAMP>.
  2070. <DT><CODE>cl_boolean float_flags.mantissa_dependent_float_format</CODE>
  2071. <DD>
  2072. When this flag is true, floats specified with more digits than corresponding
  2073. to the exponent marker they contain, but without <VAR>_nnn</VAR> suffix, will get a
  2074. precision corresponding to their number of significant digits.
  2075. </DL>
  2076. <H2><A NAME="SEC46" HREF="cln.html#TOC46">5.3 Output functions</A></H2>
  2077. <P>
  2078. Including <CODE>&#60;cl_io.h&#62;</CODE> defines a type <CODE>cl_ostream</CODE>, which is
  2079. the type of the first argument to all output functions. Unless you build
  2080. and use CLN with the macro CL_IO_STDIO being defined, <CODE>cl_ostream</CODE>
  2081. is the same as <CODE>ostream&#38;</CODE>.
  2082. <P>
  2083. The variable
  2084. <UL>
  2085. <LI>
  2086. <CODE>cl_ostream cl_stdout</CODE>
  2087. </UL>
  2088. <P>
  2089. contains the standard output stream.
  2090. <P>
  2091. The variable
  2092. <UL>
  2093. <LI>
  2094. <CODE>cl_ostream cl_stderr</CODE>
  2095. </UL>
  2096. <P>
  2097. contains the standard error output stream.
  2098. <P>
  2099. These are the simple output functions:
  2100. <DL COMPACT>
  2101. <DT><CODE>void fprintchar (cl_ostream stream, char c)</CODE>
  2102. <DD>
  2103. Prints the character <CODE>x</CODE> literally on the <CODE>stream</CODE>.
  2104. <DT><CODE>void fprint (cl_ostream stream, const char * string)</CODE>
  2105. <DD>
  2106. Prints the <CODE>string</CODE> literally on the <CODE>stream</CODE>.
  2107. <DT><CODE>void fprintdecimal (cl_ostream stream, int x)</CODE>
  2108. <DD>
  2109. <DT><CODE>void fprintdecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
  2110. <DD>
  2111. Prints the integer <CODE>x</CODE> in decimal on the <CODE>stream</CODE>.
  2112. <DT><CODE>void fprintbinary (cl_ostream stream, const cl_I&#38; x)</CODE>
  2113. <DD>
  2114. Prints the integer <CODE>x</CODE> in binary (base 2, without prefix)
  2115. on the <CODE>stream</CODE>.
  2116. <DT><CODE>void fprintoctal (cl_ostream stream, const cl_I&#38; x)</CODE>
  2117. <DD>
  2118. Prints the integer <CODE>x</CODE> in octal (base 8, without prefix)
  2119. on the <CODE>stream</CODE>.
  2120. <DT><CODE>void fprinthexadecimal (cl_ostream stream, const cl_I&#38; x)</CODE>
  2121. <DD>
  2122. Prints the integer <CODE>x</CODE> in hexadecimal (base 16, without prefix)
  2123. on the <CODE>stream</CODE>.
  2124. </DL>
  2125. <P>
  2126. Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
  2127. <CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
  2128. defines, in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>, the following output functions:
  2129. <DL COMPACT>
  2130. <DT><CODE>void fprint (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
  2131. <DD>
  2132. <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const <VAR>type</VAR>&#38; x)</CODE>
  2133. <DD>
  2134. Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
  2135. on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
  2136. The <CODE>ostream</CODE> flags and settings (flags, width and locale) are
  2137. ignored.
  2138. </DL>
  2139. <P>
  2140. The most flexible output function, defined in <CODE>&#60;cl_<VAR>type</VAR>_io.h&#62;</CODE>,
  2141. are the following:
  2142. <PRE>
  2143. void print_complex (cl_ostream stream, const cl_print_flags&#38; flags,
  2144. const cl_N&#38; z);
  2145. void print_real (cl_ostream stream, const cl_print_flags&#38; flags,
  2146. const cl_R&#38; z);
  2147. void print_float (cl_ostream stream, const cl_print_flags&#38; flags,
  2148. const cl_F&#38; z);
  2149. void print_rational (cl_ostream stream, const cl_print_flags&#38; flags,
  2150. const cl_RA&#38; z);
  2151. void print_integer (cl_ostream stream, const cl_print_flags&#38; flags,
  2152. const cl_I&#38; z);
  2153. </PRE>
  2154. <P>
  2155. Prints the number <CODE>x</CODE> on the <CODE>stream</CODE>. The <CODE>flags</CODE> are
  2156. parameters which affect the output.
  2157. <P>
  2158. The structure type <CODE>cl_print_flags</CODE> contains the following fields:
  2159. <DL COMPACT>
  2160. <DT><CODE>unsigned int rational_base</CODE>
  2161. <DD>
  2162. The base in which rational numbers are printed. Default is <CODE>10</CODE>.
  2163. <DT><CODE>cl_boolean rational_readably</CODE>
  2164. <DD>
  2165. If this flag is true, rational numbers are printed with radix specifiers in
  2166. Common Lisp syntax (<CODE>#<VAR>n</VAR>R</CODE> or <CODE>#b</CODE> or <CODE>#o</CODE> or <CODE>#x</CODE>
  2167. prefixes, trailing dot). Default is false.
  2168. <DT><CODE>cl_boolean float_readably</CODE>
  2169. <DD>
  2170. If this flag is true, type specific exponent markers have precedence over 'E'.
  2171. Default is false.
  2172. <DT><CODE>cl_float_format_t default_float_format</CODE>
  2173. <DD>
  2174. Floating point numbers of this format will be printed using the 'E' exponent
  2175. marker. Default is <CODE>cl_float_format_ffloat</CODE>.
  2176. <DT><CODE>cl_boolean complex_readably</CODE>
  2177. <DD>
  2178. If this flag is true, complex numbers will be printed using the Common Lisp
  2179. syntax <CODE>#C(<VAR>realpart</VAR> <VAR>imagpart</VAR>)</CODE>. Default is false.
  2180. <DT><CODE>cl_string univpoly_varname</CODE>
  2181. <DD>
  2182. Univariate polynomials with no explicit indeterminate name will be printed
  2183. using this variable name. Default is <CODE>"x"</CODE>.
  2184. </DL>
  2185. <P>
  2186. The global variable <CODE>cl_default_print_flags</CODE> contains the default values,
  2187. used by the function <CODE>fprint</CODE>,
  2188. <H1><A NAME="SEC47" HREF="cln.html#TOC47">6. Rings</A></H1>
  2189. <P>
  2190. CLN has a class of abstract rings.
  2191. <PRE>
  2192. Ring
  2193. cl_ring
  2194. &#60;cl_ring.h&#62;
  2195. </PRE>
  2196. <P>
  2197. Rings can be compared for equality:
  2198. <DL COMPACT>
  2199. <DT><CODE>bool operator== (const cl_ring&#38;, const cl_ring&#38;)</CODE>
  2200. <DD>
  2201. <DT><CODE>bool operator!= (const cl_ring&#38;, const cl_ring&#38;)</CODE>
  2202. <DD>
  2203. These compare two rings for equality.
  2204. </DL>
  2205. <P>
  2206. Given a ring <CODE>R</CODE>, the following members can be used.
  2207. <DL COMPACT>
  2208. <DT><CODE>void R-&#62;fprint (cl_ostream stream, const cl_ring_element&#38; x)</CODE>
  2209. <DD>
  2210. <DT><CODE>cl_boolean R-&#62;equal (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
  2211. <DD>
  2212. <DT><CODE>cl_ring_element R-&#62;zero ()</CODE>
  2213. <DD>
  2214. <DT><CODE>cl_boolean R-&#62;zerop (const cl_ring_element&#38; x)</CODE>
  2215. <DD>
  2216. <DT><CODE>cl_ring_element R-&#62;plus (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
  2217. <DD>
  2218. <DT><CODE>cl_ring_element R-&#62;minus (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
  2219. <DD>
  2220. <DT><CODE>cl_ring_element R-&#62;uminus (const cl_ring_element&#38; x)</CODE>
  2221. <DD>
  2222. <DT><CODE>cl_ring_element R-&#62;one ()</CODE>
  2223. <DD>
  2224. <DT><CODE>cl_ring_element R-&#62;canonhom (const cl_I&#38; x)</CODE>
  2225. <DD>
  2226. <DT><CODE>cl_ring_element R-&#62;mul (const cl_ring_element&#38; x, const cl_ring_element&#38; y)</CODE>
  2227. <DD>
  2228. <DT><CODE>cl_ring_element R-&#62;square (const cl_ring_element&#38; x)</CODE>
  2229. <DD>
  2230. <DT><CODE>cl_ring_element R-&#62;expt_pos (const cl_ring_element&#38; x, const cl_I&#38; y)</CODE>
  2231. <DD>
  2232. </DL>
  2233. <P>
  2234. The following rings are built-in.
  2235. <DL COMPACT>
  2236. <DT><CODE>cl_null_ring cl_0_ring</CODE>
  2237. <DD>
  2238. The null ring, containing only zero.
  2239. <DT><CODE>cl_complex_ring cl_C_ring</CODE>
  2240. <DD>
  2241. The ring of complex numbers. This corresponds to the type <CODE>cl_N</CODE>.
  2242. <DT><CODE>cl_real_ring cl_R_ring</CODE>
  2243. <DD>
  2244. The ring of real numbers. This corresponds to the type <CODE>cl_R</CODE>.
  2245. <DT><CODE>cl_rational_ring cl_RA_ring</CODE>
  2246. <DD>
  2247. The ring of rational numbers. This corresponds to the type <CODE>cl_RA</CODE>.
  2248. <DT><CODE>cl_integer_ring cl_I_ring</CODE>
  2249. <DD>
  2250. The ring of integers. This corresponds to the type <CODE>cl_I</CODE>.
  2251. </DL>
  2252. <P>
  2253. Type tests can be performed for any of <CODE>cl_C_ring</CODE>, <CODE>cl_R_ring</CODE>,
  2254. <CODE>cl_RA_ring</CODE>, <CODE>cl_I_ring</CODE>:
  2255. <DL COMPACT>
  2256. <DT><CODE>cl_boolean instanceof (const cl_number&#38; x, const cl_number_ring&#38; R)</CODE>
  2257. <DD>
  2258. Tests whether the given number is an element of the number ring R.
  2259. </DL>
  2260. <H1><A NAME="SEC48" HREF="cln.html#TOC48">7. Modular integers</A></H1>
  2261. <H2><A NAME="SEC49" HREF="cln.html#TOC49">7.1 Modular integer rings</A></H2>
  2262. <P>
  2263. CLN implements modular integers, i.e. integers modulo a fixed integer N.
  2264. The modulus is explicitly part of every modular integer. CLN doesn't
  2265. allow you to (accidentally) mix elements of different modular rings,
  2266. e.g. <CODE>(3 mod 4) + (2 mod 5)</CODE> will result in a runtime error.
  2267. (Ideally one would imagine a generic data type <CODE>cl_MI(N)</CODE>, but C++
  2268. doesn't have generic types. So one has to live with runtime checks.)
  2269. <P>
  2270. The class of modular integer rings is
  2271. <PRE>
  2272. Ring
  2273. cl_ring
  2274. &#60;cl_ring.h&#62;
  2275. |
  2276. |
  2277. Modular integer ring
  2278. cl_modint_ring
  2279. &#60;cl_modinteger.h&#62;
  2280. </PRE>
  2281. <P>
  2282. and the class of all modular integers (elements of modular integer rings) is
  2283. <PRE>
  2284. Modular integer
  2285. cl_MI
  2286. &#60;cl_modinteger.h&#62;
  2287. </PRE>
  2288. <P>
  2289. Modular integer rings are constructed using the function
  2290. <DL COMPACT>
  2291. <DT><CODE>cl_modint_ring cl_find_modint_ring (const cl_I&#38; N)</CODE>
  2292. <DD>
  2293. This function returns the modular ring <SAMP>`Z/NZ'</SAMP>. It takes care
  2294. of finding out about special cases of <CODE>N</CODE>, like powers of two
  2295. and odd numbers for which Montgomery multiplication will be a win,
  2296. and precomputes any necessary auxiliary data for computing modulo <CODE>N</CODE>.
  2297. There is a cache table of rings, indexed by <CODE>N</CODE> (or, more precisely,
  2298. by <CODE>abs(N)</CODE>). This ensures that the precomputation costs are reduced
  2299. to a minimum.
  2300. </DL>
  2301. <P>
  2302. Modular integer rings can be compared for equality:
  2303. <DL COMPACT>
  2304. <DT><CODE>bool operator== (const cl_modint_ring&#38;, const cl_modint_ring&#38;)</CODE>
  2305. <DD>
  2306. <DT><CODE>bool operator!= (const cl_modint_ring&#38;, const cl_modint_ring&#38;)</CODE>
  2307. <DD>
  2308. These compare two modular integer rings for equality. Two different calls
  2309. to <CODE>cl_find_modint_ring</CODE> with the same argument necessarily return the
  2310. same ring because it is memoized in the cache table.
  2311. </DL>
  2312. <H2><A NAME="SEC50" HREF="cln.html#TOC50">7.2 Functions on modular integers</A></H2>
  2313. <P>
  2314. Given a modular integer ring <CODE>R</CODE>, the following members can be used.
  2315. <DL COMPACT>
  2316. <DT><CODE>cl_I R-&#62;modulus</CODE>
  2317. <DD>
  2318. This is the ring's modulus, normalized to be nonnegative: <CODE>abs(N)</CODE>.
  2319. <DT><CODE>cl_MI R-&#62;zero()</CODE>
  2320. <DD>
  2321. This returns <CODE>0 mod N</CODE>.
  2322. <DT><CODE>cl_MI R-&#62;one()</CODE>
  2323. <DD>
  2324. This returns <CODE>1 mod N</CODE>.
  2325. <DT><CODE>cl_MI R-&#62;canonhom (const cl_I&#38; x)</CODE>
  2326. <DD>
  2327. This returns <CODE>x mod N</CODE>.
  2328. <DT><CODE>cl_I R-&#62;retract (const cl_MI&#38; x)</CODE>
  2329. <DD>
  2330. This is a partial inverse function to <CODE>R-&#62;canonhom</CODE>. It returns the
  2331. standard representative (<CODE>&#62;=0</CODE>, <CODE>&#60;N</CODE>) of <CODE>x</CODE>.
  2332. <DT><CODE>cl_MI R-&#62;random(cl_random_state&#38; randomstate)</CODE>
  2333. <DD>
  2334. <DT><CODE>cl_MI R-&#62;random()</CODE>
  2335. <DD>
  2336. This returns a random integer modulo <CODE>N</CODE>.
  2337. </DL>
  2338. <P>
  2339. The following operations are defined on modular integers.
  2340. <DL COMPACT>
  2341. <DT><CODE>cl_modint_ring x.ring ()</CODE>
  2342. <DD>
  2343. Returns the ring to which the modular integer <CODE>x</CODE> belongs.
  2344. <DT><CODE>cl_MI operator+ (const cl_MI&#38;, const cl_MI&#38;)</CODE>
  2345. <DD>
  2346. Returns the sum of two modular integers. One of the arguments may also be
  2347. a plain integer.
  2348. <DT><CODE>cl_MI operator- (const cl_MI&#38;, const cl_MI&#38;)</CODE>
  2349. <DD>
  2350. Returns the difference of two modular integers. One of the arguments may also be
  2351. a plain integer.
  2352. <DT><CODE>cl_MI operator- (const cl_MI&#38;)</CODE>
  2353. <DD>
  2354. Returns the negative of a modular integer.
  2355. <DT><CODE>cl_MI operator* (const cl_MI&#38;, const cl_MI&#38;)</CODE>
  2356. <DD>
  2357. Returns the product of two modular integers. One of the arguments may also be
  2358. a plain integer.
  2359. <DT><CODE>cl_MI square (const cl_MI&#38;)</CODE>
  2360. <DD>
  2361. Returns the square of a modular integer.
  2362. <DT><CODE>cl_MI recip (const cl_MI&#38; x)</CODE>
  2363. <DD>
  2364. Returns the reciprocal <CODE>x^-1</CODE> of a modular integer <CODE>x</CODE>. <CODE>x</CODE>
  2365. must be coprime to the modulus, otherwise an error message is issued.
  2366. <DT><CODE>cl_MI div (const cl_MI&#38; x, const cl_MI&#38; y)</CODE>
  2367. <DD>
  2368. Returns the quotient <CODE>x*y^-1</CODE> of two modular integers <CODE>x</CODE>, <CODE>y</CODE>.
  2369. <CODE>y</CODE> must be coprime to the modulus, otherwise an error message is issued.
  2370. <DT><CODE>cl_MI expt_pos (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
  2371. <DD>
  2372. <CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.
  2373. <DT><CODE>cl_MI expt (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
  2374. <DD>
  2375. Returns <CODE>x^y</CODE>. If <CODE>y</CODE> is negative, <CODE>x</CODE> must be coprime to the
  2376. modulus, else an error message is issued.
  2377. <DT><CODE>cl_MI operator&#60;&#60; (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
  2378. <DD>
  2379. Returns <CODE>x*2^y</CODE>.
  2380. <DT><CODE>cl_MI operator&#62;&#62; (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
  2381. <DD>
  2382. Returns <CODE>x*2^-y</CODE>. When <CODE>y</CODE> is positive, the modulus must be odd,
  2383. or an error message is issued.
  2384. <DT><CODE>bool operator== (const cl_MI&#38;, const cl_MI&#38;)</CODE>
  2385. <DD>
  2386. <DT><CODE>bool operator!= (const cl_MI&#38;, const cl_MI&#38;)</CODE>
  2387. <DD>
  2388. Compares two modular integers, belonging to the same modular integer ring,
  2389. for equality.
  2390. <DT><CODE>cl_boolean zerop (const cl_MI&#38; x)</CODE>
  2391. <DD>
  2392. Returns true if <CODE>x</CODE> is <CODE>0 mod N</CODE>.
  2393. </DL>
  2394. <P>
  2395. The following output functions are defined (see also the chapter on
  2396. input/output).
  2397. <DL COMPACT>
  2398. <DT><CODE>void fprint (cl_ostream stream, const cl_MI&#38; x)</CODE>
  2399. <DD>
  2400. <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const cl_MI&#38; x)</CODE>
  2401. <DD>
  2402. Prints the modular integer <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
  2403. on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
  2404. </DL>
  2405. <H1><A NAME="SEC51" HREF="cln.html#TOC51">8. Symbolic data types</A></H1>
  2406. <P>
  2407. CLN implements two symbolic (non-numeric) data types: strings and symbols.
  2408. <H2><A NAME="SEC52" HREF="cln.html#TOC52">8.1 Strings</A></H2>
  2409. <P>
  2410. The class
  2411. <PRE>
  2412. String
  2413. cl_string
  2414. &#60;cl_string.h&#62;
  2415. </PRE>
  2416. <P>
  2417. implements immutable strings.
  2418. <P>
  2419. Strings are constructed through the following constructors:
  2420. <DL COMPACT>
  2421. <DT><CODE>cl_string (const char * s)</CODE>
  2422. <DD>
  2423. Returns an immutable copy of the (zero-terminated) C string <CODE>s</CODE>.
  2424. <DT><CODE>cl_string (const char * ptr, unsigned long len)</CODE>
  2425. <DD>
  2426. Returns an immutable copy of the <CODE>len</CODE> characters at
  2427. <CODE>ptr[0]</CODE>, ..., <CODE>ptr[len-1]</CODE>. NUL characters are allowed.
  2428. </DL>
  2429. <P>
  2430. The following functions are available on strings:
  2431. <DL COMPACT>
  2432. <DT><CODE>operator =</CODE>
  2433. <DD>
  2434. Assignment from <CODE>cl_string</CODE> and <CODE>const char *</CODE>.
  2435. <DT><CODE>s.length()</CODE>
  2436. <DD>
  2437. <DT><CODE>strlen(s)</CODE>
  2438. <DD>
  2439. Returns the length of the string <CODE>s</CODE>.
  2440. <DT><CODE>s[i]</CODE>
  2441. <DD>
  2442. Returns the <CODE>i</CODE>th character of the string <CODE>s</CODE>.
  2443. <CODE>i</CODE> must be in the range <CODE>0 &#60;= i &#60; s.length()</CODE>.
  2444. <DT><CODE>bool equal (const cl_string&#38; s1, const cl_string&#38; s2)</CODE>
  2445. <DD>
  2446. Compares two strings for equality. One of the arguments may also be a
  2447. plain <CODE>const char *</CODE>.
  2448. </DL>
  2449. <H2><A NAME="SEC53" HREF="cln.html#TOC53">8.2 Symbols</A></H2>
  2450. <P>
  2451. Symbols are uniquified strings: all symbols with the same name are shared.
  2452. This means that comparison of two symbols is fast (effectively just a pointer
  2453. comparison), whereas comparison of two strings must in the worst case walk
  2454. both strings until their end.
  2455. Symbols are used, for example, as tags for properties, as names of variables
  2456. in polynomial rings, etc.
  2457. <P>
  2458. Symbols are constructed through the following constructor:
  2459. <DL COMPACT>
  2460. <DT><CODE>cl_symbol (const cl_string&#38; s)</CODE>
  2461. <DD>
  2462. Looks up or creates a new symbol with a given name.
  2463. </DL>
  2464. <P>
  2465. The following operations are available on symbols:
  2466. <DL COMPACT>
  2467. <DT><CODE>cl_string (const cl_symbol&#38; sym)</CODE>
  2468. <DD>
  2469. Conversion to <CODE>cl_string</CODE>: Returns the string which names the symbol
  2470. <CODE>sym</CODE>.
  2471. <DT><CODE>bool equal (const cl_symbol&#38; sym1, const cl_symbol&#38; sym2)</CODE>
  2472. <DD>
  2473. Compares two symbols for equality. This is very fast.
  2474. </DL>
  2475. <H1><A NAME="SEC54" HREF="cln.html#TOC54">9. Univariate polynomials</A></H1>
  2476. <H2><A NAME="SEC55" HREF="cln.html#TOC55">9.1 Univariate polynomial rings</A></H2>
  2477. <P>
  2478. CLN implements univariate polynomials (polynomials in one variable) over an
  2479. arbitrary ring. The indeterminate variable may be either unnamed (and will be
  2480. printed according to <CODE>cl_default_print_flags.univpoly_varname</CODE>, which
  2481. defaults to <SAMP>`x'</SAMP>) or carry a given name. The base ring and the
  2482. indeterminate are explicitly part of every polynomial. CLN doesn't allow you to
  2483. (accidentally) mix elements of different polynomial rings, e.g.
  2484. <CODE>(a^2+1) * (b^3-1)</CODE> will result in a runtime error. (Ideally this should
  2485. return a multivariate polynomial, but they are not yet implemented in CLN.)
  2486. <P>
  2487. The classes of univariate polynomial rings are
  2488. <PRE>
  2489. Ring
  2490. cl_ring
  2491. &#60;cl_ring.h&#62;
  2492. |
  2493. |
  2494. Univariate polynomial ring
  2495. cl_univpoly_ring
  2496. &#60;cl_univpoly.h&#62;
  2497. |
  2498. +----------------+-------------------+
  2499. | | |
  2500. Complex polynomial ring | Modular integer polynomial ring
  2501. cl_univpoly_complex_ring | cl_univpoly_modint_ring
  2502. &#60;cl_univpoly_complex.h&#62; | &#60;cl_univpoly_modint.h&#62;
  2503. |
  2504. +----------------+
  2505. | |
  2506. Real polynomial ring |
  2507. cl_univpoly_real_ring |
  2508. &#60;cl_univpoly_real.h&#62; |
  2509. |
  2510. +----------------+
  2511. | |
  2512. Rational polynomial ring |
  2513. cl_univpoly_rational_ring |
  2514. &#60;cl_univpoly_rational.h&#62; |
  2515. |
  2516. +----------------+
  2517. |
  2518. Integer polynomial ring
  2519. cl_univpoly_integer_ring
  2520. &#60;cl_univpoly_integer.h&#62;
  2521. </PRE>
  2522. <P>
  2523. and the corresponding classes of univariate polynomials are
  2524. <PRE>
  2525. Univariate polynomial
  2526. cl_UP
  2527. &#60;cl_univpoly.h&#62;
  2528. |
  2529. +----------------+-------------------+
  2530. | | |
  2531. Complex polynomial | Modular integer polynomial
  2532. cl_UP_N | cl_UP_MI
  2533. &#60;cl_univpoly_complex.h&#62; | &#60;cl_univpoly_modint.h&#62;
  2534. |
  2535. +----------------+
  2536. | |
  2537. Real polynomial |
  2538. cl_UP_R |
  2539. &#60;cl_univpoly_real.h&#62; |
  2540. |
  2541. +----------------+
  2542. | |
  2543. Rational polynomial |
  2544. cl_UP_RA |
  2545. &#60;cl_univpoly_rational.h&#62; |
  2546. |
  2547. +----------------+
  2548. |
  2549. Integer polynomial
  2550. cl_UP_I
  2551. &#60;cl_univpoly_integer.h&#62;
  2552. </PRE>
  2553. <P>
  2554. Univariate polynomial rings are constructed using the functions
  2555. <DL COMPACT>
  2556. <DT><CODE>cl_univpoly_ring cl_find_univpoly_ring (const cl_ring&#38; R)</CODE>
  2557. <DD>
  2558. <DT><CODE>cl_univpoly_ring cl_find_univpoly_ring (const cl_ring&#38; R, const cl_symbol&#38; varname)</CODE>
  2559. <DD>
  2560. This function returns the polynomial ring <SAMP>`R[X]'</SAMP>, unnamed or named.
  2561. <CODE>R</CODE> may be an arbitrary ring. This function takes care of finding out
  2562. about special cases of <CODE>R</CODE>, such as the rings of complex numbers,
  2563. real numbers, rational numbers, integers, or modular integer rings.
  2564. There is a cache table of rings, indexed by <CODE>R</CODE> and <CODE>varname</CODE>.
  2565. This ensures that two calls of this function with the same arguments will
  2566. return the same polynomial ring.
  2567. <DT><CODE>cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring&#38; R)</CODE>
  2568. <DD>
  2569. <DT><CODE>cl_univpoly_complex_ring cl_find_univpoly_ring (const cl_complex_ring&#38; R, const cl_symbol&#38; varname)</CODE>
  2570. <DD>
  2571. <DT><CODE>cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring&#38; R)</CODE>
  2572. <DD>
  2573. <DT><CODE>cl_univpoly_real_ring cl_find_univpoly_ring (const cl_real_ring&#38; R, const cl_symbol&#38; varname)</CODE>
  2574. <DD>
  2575. <DT><CODE>cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring&#38; R)</CODE>
  2576. <DD>
  2577. <DT><CODE>cl_univpoly_rational_ring cl_find_univpoly_ring (const cl_rational_ring&#38; R, const cl_symbol&#38; varname)</CODE>
  2578. <DD>
  2579. <DT><CODE>cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring&#38; R)</CODE>
  2580. <DD>
  2581. <DT><CODE>cl_univpoly_integer_ring cl_find_univpoly_ring (const cl_integer_ring&#38; R, const cl_symbol&#38; varname)</CODE>
  2582. <DD>
  2583. <DT><CODE>cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring&#38; R)</CODE>
  2584. <DD>
  2585. <DT><CODE>cl_univpoly_modint_ring cl_find_univpoly_ring (const cl_modint_ring&#38; R, const cl_symbol&#38; varname)</CODE>
  2586. <DD>
  2587. These functions are equivalent to the general <CODE>cl_find_univpoly_ring</CODE>,
  2588. only the return type is more specific, according to the base ring's type.
  2589. </DL>
  2590. <H2><A NAME="SEC56" HREF="cln.html#TOC56">9.2 Functions on univariate polynomials</A></H2>
  2591. <P>
  2592. Given a univariate polynomial ring <CODE>R</CODE>, the following members can be used.
  2593. <DL COMPACT>
  2594. <DT><CODE>cl_ring R-&#62;basering()</CODE>
  2595. <DD>
  2596. This returns the base ring, as passed to <SAMP>`cl_find_univpoly_ring'</SAMP>.
  2597. <DT><CODE>cl_UP R-&#62;zero()</CODE>
  2598. <DD>
  2599. This returns <CODE>0 in R</CODE>, a polynomial of degree -1.
  2600. <DT><CODE>cl_UP R-&#62;one()</CODE>
  2601. <DD>
  2602. This returns <CODE>1 in R</CODE>, a polynomial of degree &#60;= 0.
  2603. <DT><CODE>cl_UP R-&#62;canonhom (const cl_I&#38; x)</CODE>
  2604. <DD>
  2605. This returns <CODE>x in R</CODE>, a polynomial of degree &#60;= 0.
  2606. <DT><CODE>cl_UP R-&#62;monomial (const cl_ring_element&#38; x, uintL e)</CODE>
  2607. <DD>
  2608. This returns a sparse polynomial: <CODE>x * X^e</CODE>, where <CODE>X</CODE> is the
  2609. indeterminate.
  2610. <DT><CODE>cl_UP R-&#62;create (sintL degree)</CODE>
  2611. <DD>
  2612. Creates a new polynomial with a given degree. The zero polynomial has degree
  2613. <CODE>-1</CODE>. After creating the polynomial, you should put in the coefficients,
  2614. using the <CODE>set_coeff</CODE> member function, and then call the <CODE>finalize</CODE>
  2615. member function.
  2616. </DL>
  2617. <P>
  2618. The following are the only destructive operations on univariate polynomials.
  2619. <DL COMPACT>
  2620. <DT><CODE>void set_coeff (cl_UP&#38; x, uintL index, const cl_ring_element&#38; y)</CODE>
  2621. <DD>
  2622. This changes the coefficient of <CODE>X^index</CODE> in <CODE>x</CODE> to be <CODE>y</CODE>.
  2623. After changing a polynomial and before applying any "normal" operation on it,
  2624. you should call its <CODE>finalize</CODE> member function.
  2625. <DT><CODE>void finalize (cl_UP&#38; x)</CODE>
  2626. <DD>
  2627. This function marks the endpoint of destructive modifications of a polynomial.
  2628. It normalizes the internal representation so that subsequent computations have
  2629. less overhead. Doing normal computations on unnormalized polynomials may
  2630. produce wrong results or crash the program.
  2631. </DL>
  2632. <P>
  2633. The following operations are defined on univariate polynomials.
  2634. <DL COMPACT>
  2635. <DT><CODE>cl_univpoly_ring x.ring ()</CODE>
  2636. <DD>
  2637. Returns the ring to which the univariate polynomial <CODE>x</CODE> belongs.
  2638. <DT><CODE>cl_UP operator+ (const cl_UP&#38;, const cl_UP&#38;)</CODE>
  2639. <DD>
  2640. Returns the sum of two univariate polynomials.
  2641. <DT><CODE>cl_UP operator- (const cl_UP&#38;, const cl_UP&#38;)</CODE>
  2642. <DD>
  2643. Returns the difference of two univariate polynomials.
  2644. <DT><CODE>cl_UP operator- (const cl_UP&#38;)</CODE>
  2645. <DD>
  2646. Returns the negative of a univariate polynomial.
  2647. <DT><CODE>cl_UP operator* (const cl_UP&#38;, const cl_UP&#38;)</CODE>
  2648. <DD>
  2649. Returns the product of two univariate polynomials. One of the arguments may
  2650. also be a plain integer or an element of the base ring.
  2651. <DT><CODE>cl_UP square (const cl_UP&#38;)</CODE>
  2652. <DD>
  2653. Returns the square of a univariate polynomial.
  2654. <DT><CODE>cl_UP expt_pos (const cl_UP&#38; x, const cl_I&#38; y)</CODE>
  2655. <DD>
  2656. <CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.
  2657. <DT><CODE>bool operator== (const cl_UP&#38;, const cl_UP&#38;)</CODE>
  2658. <DD>
  2659. <DT><CODE>bool operator!= (const cl_UP&#38;, const cl_UP&#38;)</CODE>
  2660. <DD>
  2661. Compares two univariate polynomials, belonging to the same univariate
  2662. polynomial ring, for equality.
  2663. <DT><CODE>cl_boolean zerop (const cl_UP&#38; x)</CODE>
  2664. <DD>
  2665. Returns true if <CODE>x</CODE> is <CODE>0 in R</CODE>.
  2666. <DT><CODE>sintL degree (const cl_UP&#38; x)</CODE>
  2667. <DD>
  2668. Returns the degree of the polynomial. The zero polynomial has degree <CODE>-1</CODE>.
  2669. <DT><CODE>cl_ring_element coeff (const cl_UP&#38; x, uintL index)</CODE>
  2670. <DD>
  2671. Returns the coefficient of <CODE>X^index</CODE> in the polynomial <CODE>x</CODE>.
  2672. <DT><CODE>cl_ring_element x (const cl_ring_element&#38; y)</CODE>
  2673. <DD>
  2674. Evaluation: If <CODE>x</CODE> is a polynomial and <CODE>y</CODE> belongs to the base ring,
  2675. then <SAMP>`x(y)'</SAMP> returns the value of the substitution of <CODE>y</CODE> into
  2676. <CODE>x</CODE>.
  2677. <DT><CODE>cl_UP deriv (const cl_UP&#38; x)</CODE>
  2678. <DD>
  2679. Returns the derivative of the polynomial <CODE>x</CODE> with respect to the
  2680. indeterminate <CODE>X</CODE>.
  2681. </DL>
  2682. <P>
  2683. The following output functions are defined (see also the chapter on
  2684. input/output).
  2685. <DL COMPACT>
  2686. <DT><CODE>void fprint (cl_ostream stream, const cl_UP&#38; x)</CODE>
  2687. <DD>
  2688. <DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const cl_UP&#38; x)</CODE>
  2689. <DD>
  2690. Prints the univariate polynomial <CODE>x</CODE> on the <CODE>stream</CODE>. The output may
  2691. depend on the global printer settings in the variable
  2692. <CODE>cl_default_print_flags</CODE>.
  2693. </DL>
  2694. <H2><A NAME="SEC57" HREF="cln.html#TOC57">9.3 Special polynomials</A></H2>
  2695. <P>
  2696. The following functions return special polynomials.
  2697. <DL COMPACT>
  2698. <DT><CODE>cl_UP_I cl_tschebychev (sintL n)</CODE>
  2699. <DD>
  2700. Returns the n-th Tchebychev polynomial (n &#62;= 0).
  2701. <DT><CODE>cl_UP_I cl_hermite (sintL n)</CODE>
  2702. <DD>
  2703. Returns the n-th Hermite polynomial (n &#62;= 0).
  2704. <DT><CODE>cl_UP_RA cl_legendre (sintL n)</CODE>
  2705. <DD>
  2706. Returns the n-th Legendre polynomial (n &#62;= 0).
  2707. <DT><CODE>cl_UP_I cl_laguerre (sintL n)</CODE>
  2708. <DD>
  2709. Returns the n-th Laguerre polynomial (n &#62;= 0).
  2710. </DL>
  2711. <P>
  2712. Information how to derive the differential equation satisfied by each
  2713. of these polynomials from their definition can be found in the
  2714. <CODE>doc/polynomial/</CODE> directory.
  2715. <H1><A NAME="SEC58" HREF="cln.html#TOC58">10. Internals</A></H1>
  2716. <H2><A NAME="SEC59" HREF="cln.html#TOC59">10.1 Why C++ ?</A></H2>
  2717. <P>
  2718. Using C++ as an implementation language provides
  2719. <UL>
  2720. <LI>
  2721. Efficiency: It compiles to machine code.
  2722. <LI>
  2723. Portability: It runs on all platforms supporting a C++ compiler. Because
  2724. of the availability of GNU C++, this includes all currently used 32-bit and
  2725. 64-bit platforms, independently of the quality of the vendor's C++ compiler.
  2726. <LI>
  2727. Type safety: The C++ compilers knows about the number types and complains if,
  2728. for example, you try to assign a float to an integer variable. However,
  2729. a drawback is that C++ doesn't know about generic types, hence a restriction
  2730. like that <CODE>operation+ (const cl_MI&#38;, const cl_MI&#38;)</CODE> requires that both
  2731. arguments belong to the same modular ring cannot be expressed as a compile-time
  2732. information.
  2733. <LI>
  2734. Algebraic syntax: The elementary operations <CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>,
  2735. <CODE>=</CODE>, <CODE>==</CODE>, ... can be used in infix notation, which is more
  2736. convenient than Lisp notation <SAMP>`(+ x y)'</SAMP> or C notation <SAMP>`add(x,y,&#38;z)'</SAMP>.
  2737. </UL>
  2738. <P>
  2739. With these language features, there is no need for two separate languages,
  2740. one for the implementation of the library and one in which the library's users
  2741. can program. This means that a prototype implementation of an algorithm
  2742. can be integrated into the library immediately after it has been tested and
  2743. debugged. No need to rewrite it in a low-level language after having prototyped
  2744. in a high-level language.
  2745. <H2><A NAME="SEC60" HREF="cln.html#TOC60">10.2 Memory efficiency</A></H2>
  2746. <P>
  2747. In order to save memory allocations, CLN implements:
  2748. <UL>
  2749. <LI>
  2750. Object sharing: An operation like <CODE>x+0</CODE> returns <CODE>x</CODE> without copying
  2751. it.
  2752. <LI>
  2753. Garbage collection: A reference counting mechanism makes sure that any
  2754. number object's storage is freed immediately when the last reference to the
  2755. object is gone.
  2756. <LI>
  2757. Small integers are represented as immediate values instead of pointers
  2758. to heap allocated storage. This means that integers <CODE>&#62; -2^29</CODE>,
  2759. <CODE>&#60; 2^29</CODE> don't consume heap memory, unless they were explicitly allocated
  2760. on the heap.
  2761. </UL>
  2762. <H2><A NAME="SEC61" HREF="cln.html#TOC61">10.3 Speed efficiency</A></H2>
  2763. <P>
  2764. Speed efficiency is obtained by the combination of the following tricks
  2765. and algorithms:
  2766. <UL>
  2767. <LI>
  2768. Small integers, being represented as immediate values, don't require
  2769. memory access, just a couple of instructions for each elementary operation.
  2770. <LI>
  2771. The kernel of CLN has been written in assembly language for some CPUs
  2772. (<CODE>i386</CODE>, <CODE>m68k</CODE>, <CODE>sparc</CODE>, <CODE>mips</CODE>, <CODE>arm</CODE>).
  2773. <LI>
  2774. On all CPUs, CLN uses the superefficient low-level routines from GNU
  2775. GMP version 2.
  2776. <LI>
  2777. For large numbers, CLN uses, instead of the standard <CODE>O(N^2)</CODE>
  2778. algorithm, the Karatsuba multiplication, which is an
  2779. <CODE>O(N^1.6)</CODE>
  2780. algorithm.
  2781. <LI>
  2782. For very large numbers (more than 12000 decimal digits), CLN uses
  2783. Sch�nhage-Strassen
  2784. multiplication, which is an asymptotically
  2785. optimal multiplication algorithm.
  2786. <LI>
  2787. These fast multiplication algorithms also give improvements in the speed
  2788. of division and radix conversion.
  2789. </UL>
  2790. <H2><A NAME="SEC62" HREF="cln.html#TOC62">10.4 Garbage collection</A></H2>
  2791. <P>
  2792. All the number classes are reference count classes: They only contain a pointer
  2793. to an object in the heap. Upon construction, assignment and destruction of
  2794. number objects, only the objects' reference count are manipulated.
  2795. <P>
  2796. Memory occupied by number objects are automatically reclaimed as soon as
  2797. their reference count drops to zero.
  2798. <P>
  2799. For number rings, another strategy is implemented: There is a cache of,
  2800. for example, the modular integer rings. A modular integer ring is destroyed
  2801. only if its reference count dropped to zero and the cache is about to be
  2802. resized. The effect of this strategy is that recently used rings remain
  2803. cached, whereas undue memory consumption through cached rings is avoided.
  2804. <H1><A NAME="SEC63" HREF="cln.html#TOC63">11. Using the library</A></H1>
  2805. <P>
  2806. For the following discussion, we will assume that you have installed
  2807. the CLN source in <CODE>$CLN_DIR</CODE> and built it in <CODE>$CLN_TARGETDIR</CODE>.
  2808. For example, for me it's <CODE>CLN_DIR="$HOME/cln"</CODE> and
  2809. <CODE>CLN_TARGETDIR="$HOME/cln/linuxelf"</CODE>. You might define these as
  2810. environment variables, or directly substitute the appropriate values.
  2811. <H2><A NAME="SEC64" HREF="cln.html#TOC64">11.1 Compiler options</A></H2>
  2812. <P>
  2813. Until you have installed CLN in a public place, the following options are
  2814. needed:
  2815. <P>
  2816. When you compile CLN application code, add the flags
  2817. <PRE>
  2818. -I$CLN_DIR/include -I$CLN_TARGETDIR/include
  2819. </PRE>
  2820. <P>
  2821. to the C++ compiler's command line (<CODE>make</CODE> variable CFLAGS or CXXFLAGS).
  2822. When you link CLN application code to form an executable, add the flags
  2823. <PRE>
  2824. $CLN_TARGETDIR/src/libcln.a
  2825. </PRE>
  2826. <P>
  2827. to the C/C++ compiler's command line (<CODE>make</CODE> variable LIBS).
  2828. <P>
  2829. If you did a <CODE>make install</CODE>, the include files are installed in a
  2830. public directory (normally <CODE>/usr/local/include</CODE>), hence you don't
  2831. need special flags for compiling. The library has been installed to a
  2832. public directory as well (normally <CODE>/usr/local/lib</CODE>), hence when
  2833. linking a CLN application it is sufficient to give the flag <CODE>-lcln</CODE>.
  2834. <H2><A NAME="SEC65" HREF="cln.html#TOC65">11.2 Include files</A></H2>
  2835. <P>
  2836. Here is a summary of the include files and their contents.
  2837. <DL COMPACT>
  2838. <DT><CODE>&#60;cl_object.h&#62;</CODE>
  2839. <DD>
  2840. General definitions, reference counting, garbage collection.
  2841. <DT><CODE>&#60;cl_number.h&#62;</CODE>
  2842. <DD>
  2843. The class cl_number.
  2844. <DT><CODE>&#60;cl_complex.h&#62;</CODE>
  2845. <DD>
  2846. Functions for class cl_N, the complex numbers.
  2847. <DT><CODE>&#60;cl_real.h&#62;</CODE>
  2848. <DD>
  2849. Functions for class cl_R, the real numbers.
  2850. <DT><CODE>&#60;cl_float.h&#62;</CODE>
  2851. <DD>
  2852. Functions for class cl_F, the floats.
  2853. <DT><CODE>&#60;cl_sfloat.h&#62;</CODE>
  2854. <DD>
  2855. Functions for class cl_SF, the short-floats.
  2856. <DT><CODE>&#60;cl_ffloat.h&#62;</CODE>
  2857. <DD>
  2858. Functions for class cl_FF, the single-floats.
  2859. <DT><CODE>&#60;cl_dfloat.h&#62;</CODE>
  2860. <DD>
  2861. Functions for class cl_DF, the double-floats.
  2862. <DT><CODE>&#60;cl_lfloat.h&#62;</CODE>
  2863. <DD>
  2864. Functions for class cl_LF, the long-floats.
  2865. <DT><CODE>&#60;cl_rational.h&#62;</CODE>
  2866. <DD>
  2867. Functions for class cl_RA, the rational numbers.
  2868. <DT><CODE>&#60;cl_integer.h&#62;</CODE>
  2869. <DD>
  2870. Functions for class cl_I, the integers.
  2871. <DT><CODE>&#60;cl_io.h&#62;</CODE>
  2872. <DD>
  2873. Input/Output.
  2874. <DT><CODE>&#60;cl_complex_io.h&#62;</CODE>
  2875. <DD>
  2876. Input/Output for class cl_N, the complex numbers.
  2877. <DT><CODE>&#60;cl_real_io.h&#62;</CODE>
  2878. <DD>
  2879. Input/Output for class cl_R, the real numbers.
  2880. <DT><CODE>&#60;cl_float_io.h&#62;</CODE>
  2881. <DD>
  2882. Input/Output for class cl_F, the floats.
  2883. <DT><CODE>&#60;cl_sfloat_io.h&#62;</CODE>
  2884. <DD>
  2885. Input/Output for class cl_SF, the short-floats.
  2886. <DT><CODE>&#60;cl_ffloat_io.h&#62;</CODE>
  2887. <DD>
  2888. Input/Output for class cl_FF, the single-floats.
  2889. <DT><CODE>&#60;cl_dfloat_io.h&#62;</CODE>
  2890. <DD>
  2891. Input/Output for class cl_DF, the double-floats.
  2892. <DT><CODE>&#60;cl_lfloat_io.h&#62;</CODE>
  2893. <DD>
  2894. Input/Output for class cl_LF, the long-floats.
  2895. <DT><CODE>&#60;cl_rational_io.h&#62;</CODE>
  2896. <DD>
  2897. Input/Output for class cl_RA, the rational numbers.
  2898. <DT><CODE>&#60;cl_integer_io.h&#62;</CODE>
  2899. <DD>
  2900. Input/Output for class cl_I, the integers.
  2901. <DT><CODE>&#60;cl_input.h&#62;</CODE>
  2902. <DD>
  2903. Flags for customizing input operations.
  2904. <DT><CODE>&#60;cl_output.h&#62;</CODE>
  2905. <DD>
  2906. Flags for customizing output operations.
  2907. <DT><CODE>&#60;cl_malloc.h&#62;</CODE>
  2908. <DD>
  2909. <CODE>cl_malloc_hook</CODE>, <CODE>cl_free_hook</CODE>.
  2910. <DT><CODE>&#60;cl_abort.h&#62;</CODE>
  2911. <DD>
  2912. <CODE>cl_abort</CODE>.
  2913. <DT><CODE>&#60;cl_condition.h&#62;</CODE>
  2914. <DD>
  2915. Conditions/exceptions.
  2916. <DT><CODE>&#60;cl_string.h&#62;</CODE>
  2917. <DD>
  2918. Strings.
  2919. <DT><CODE>&#60;cl_symbol.h&#62;</CODE>
  2920. <DD>
  2921. Symbols.
  2922. <DT><CODE>&#60;cl_proplist.h&#62;</CODE>
  2923. <DD>
  2924. Property lists.
  2925. <DT><CODE>&#60;cl_ring.h&#62;</CODE>
  2926. <DD>
  2927. General rings.
  2928. <DT><CODE>&#60;cl_null_ring.h&#62;</CODE>
  2929. <DD>
  2930. The null ring.
  2931. <DT><CODE>&#60;cl_complex_ring.h&#62;</CODE>
  2932. <DD>
  2933. The ring of complex numbers.
  2934. <DT><CODE>&#60;cl_real_ring.h&#62;</CODE>
  2935. <DD>
  2936. The ring of real numbers.
  2937. <DT><CODE>&#60;cl_rational_ring.h&#62;</CODE>
  2938. <DD>
  2939. The ring of rational numbers.
  2940. <DT><CODE>&#60;cl_integer_ring.h&#62;</CODE>
  2941. <DD>
  2942. The ring of integers.
  2943. <DT><CODE>&#60;cl_numtheory.h&#62;</CODE>
  2944. <DD>
  2945. Number threory functions.
  2946. <DT><CODE>&#60;cl_modinteger.h&#62;</CODE>
  2947. <DD>
  2948. Modular integers.
  2949. <DT><CODE>&#60;cl_V.h&#62;</CODE>
  2950. <DD>
  2951. Vectors.
  2952. <DT><CODE>&#60;cl_GV.h&#62;</CODE>
  2953. <DD>
  2954. General vectors.
  2955. <DT><CODE>&#60;cl_GV_number.h&#62;</CODE>
  2956. <DD>
  2957. General vectors over cl_number.
  2958. <DT><CODE>&#60;cl_GV_complex.h&#62;</CODE>
  2959. <DD>
  2960. General vectors over cl_N.
  2961. <DT><CODE>&#60;cl_GV_real.h&#62;</CODE>
  2962. <DD>
  2963. General vectors over cl_R.
  2964. <DT><CODE>&#60;cl_GV_rational.h&#62;</CODE>
  2965. <DD>
  2966. General vectors over cl_RA.
  2967. <DT><CODE>&#60;cl_GV_integer.h&#62;</CODE>
  2968. <DD>
  2969. General vectors over cl_I.
  2970. <DT><CODE>&#60;cl_GV_modinteger.h&#62;</CODE>
  2971. <DD>
  2972. General vectors of modular integers.
  2973. <DT><CODE>&#60;cl_SV.h&#62;</CODE>
  2974. <DD>
  2975. Simple vectors.
  2976. <DT><CODE>&#60;cl_SV_number.h&#62;</CODE>
  2977. <DD>
  2978. Simple vectors over cl_number.
  2979. <DT><CODE>&#60;cl_SV_complex.h&#62;</CODE>
  2980. <DD>
  2981. Simple vectors over cl_N.
  2982. <DT><CODE>&#60;cl_SV_real.h&#62;</CODE>
  2983. <DD>
  2984. Simple vectors over cl_R.
  2985. <DT><CODE>&#60;cl_SV_rational.h&#62;</CODE>
  2986. <DD>
  2987. Simple vectors over cl_RA.
  2988. <DT><CODE>&#60;cl_SV_integer.h&#62;</CODE>
  2989. <DD>
  2990. Simple vectors over cl_I.
  2991. <DT><CODE>&#60;cl_SV_ringelt.h&#62;</CODE>
  2992. <DD>
  2993. Simple vectors of general ring elements.
  2994. <DT><CODE>&#60;cl_univpoly.h&#62;</CODE>
  2995. <DD>
  2996. Univariate polynomials.
  2997. <DT><CODE>&#60;cl_univpoly_integer.h&#62;</CODE>
  2998. <DD>
  2999. Univariate polynomials over the integers.
  3000. <DT><CODE>&#60;cl_univpoly_rational.h&#62;</CODE>
  3001. <DD>
  3002. Univariate polynomials over the rational numbers.
  3003. <DT><CODE>&#60;cl_univpoly_real.h&#62;</CODE>
  3004. <DD>
  3005. Univariate polynomials over the real numbers.
  3006. <DT><CODE>&#60;cl_univpoly_complex.h&#62;</CODE>
  3007. <DD>
  3008. Univariate polynomials over the complex numbers.
  3009. <DT><CODE>&#60;cl_univpoly_modint.h&#62;</CODE>
  3010. <DD>
  3011. Univariate polynomials over modular integer rings.
  3012. <DT><CODE>&#60;cl_timing.h&#62;</CODE>
  3013. <DD>
  3014. Timing facilities.
  3015. <DT><CODE>&#60;cln.h&#62;</CODE>
  3016. <DD>
  3017. Includes all of the above.
  3018. </DL>
  3019. <H2><A NAME="SEC66" HREF="cln.html#TOC66">11.3 An Example</A></H2>
  3020. <P>
  3021. A function which computes the nth Fibonacci number can be written as follows.
  3022. <PRE>
  3023. #include &#60;cl_integer.h&#62;
  3024. #include &#60;cl_real.h&#62;
  3025. // Returns F_n, computed as the nearest integer to
  3026. // ((1+sqrt(5))/2)^n/sqrt(5). Assume n&#62;=0.
  3027. const cl_I fibonacci (int n)
  3028. {
  3029. // Need a precision of ((1+sqrt(5))/2)^-n.
  3030. cl_float_format_t prec = cl_float_format((int)(0.208987641*n+5));
  3031. cl_R sqrt5 = sqrt(cl_float(5,prec));
  3032. cl_R phi = (1+sqrt5)/2;
  3033. return round1( expt(phi,n)/sqrt5 );
  3034. }
  3035. </PRE>
  3036. <P>
  3037. Let's explain what is going on in detail.
  3038. <P>
  3039. The include file <CODE>&#60;cl_integer.h&#62;</CODE> is necessary because the type
  3040. <CODE>cl_I</CODE> is used in the function, and the include file <CODE>&#60;cl_real.h&#62;</CODE>
  3041. is needed for the type <CODE>cl_R</CODE> and the floating point number functions.
  3042. The order of the include files does not matter.
  3043. <P>
  3044. Then comes the function declaration. The argument is an <CODE>int</CODE>, the
  3045. result an integer. The return type is defined as <SAMP>`const cl_I'</SAMP>, not
  3046. simply <SAMP>`cl_I'</SAMP>, because that allows the compiler to detect typos like
  3047. <SAMP>`fibonacci(n) = 100'</SAMP>. It would be possible to declare the return
  3048. type as <CODE>const cl_R</CODE> (real number) or even <CODE>const cl_N</CODE> (complex
  3049. number). We use the most specialized possible return type because functions
  3050. which call <SAMP>`fibonacci'</SAMP> will be able to profit from the compiler's type
  3051. analysis: Adding two integers is slightly more efficient than adding the
  3052. same objects declared as complex numbers, because it needs less type
  3053. dispatch. Also, when linking to CLN as a non-shared library, this minimizes
  3054. the size of the resulting executable program.
  3055. <P>
  3056. The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
  3057. integer. In order to get a correct result, the absolute error should be less
  3058. than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
  3059. To this end, the first line computes a floating point precision for sqrt(5)
  3060. and phi.
  3061. <P>
  3062. Then sqrt(5) is computed by first converting the integer 5 to a floating point
  3063. number and than taking the square root. The converse, first taking the square
  3064. root of 5, and then converting to the desired precision, would not work in
  3065. CLN: The square root would be computed to a default precision (normally
  3066. single-float precision), and the following conversion could not help about
  3067. the lacking accuracy. This is because CLN is not a symbolic computer algebra
  3068. system and does not represent sqrt(5) in a non-numeric way.
  3069. <P>
  3070. The type <CODE>cl_R</CODE> for sqrt5 and, in the following line, phi is the only
  3071. possible choice. You cannot write <CODE>cl_F</CODE> because the C++ compiler can
  3072. only infer that <CODE>cl_float(5,prec)</CODE> is a real number. You cannot write
  3073. <CODE>cl_N</CODE> because a <SAMP>`round1'</SAMP> does not exist for general complex
  3074. numbers.
  3075. <P>
  3076. When the function returns, all the local variables in the function are
  3077. automatically reclaimed (garbage collected). Only the result survives and
  3078. gets passed to the caller.
  3079. <H2><A NAME="SEC67" HREF="cln.html#TOC67">11.4 Debugging support</A></H2>
  3080. <P>
  3081. When debugging a CLN application with GNU <CODE>gdb</CODE>, two facilities are
  3082. available from the library:
  3083. <UL>
  3084. <LI>The library does type checks, range checks, consistency checks at
  3085. many places. When one of these fails, the function <CODE>cl_abort()</CODE> is
  3086. called. Its default implementation is to perform an <CODE>exit(1)</CODE>, so
  3087. you won't have a core dump. But for debugging, it is best to set a
  3088. breakpoint at this function:
  3089. <PRE>
  3090. (gdb) break cl_abort
  3091. </PRE>
  3092. When this breakpoint is hit, look at the stack's backtrace:
  3093. <PRE>
  3094. (gdb) where
  3095. </PRE>
  3096. <LI>The debugger's normal <CODE>print</CODE> command doesn't know about
  3097. CLN's types and therefore prints mostly useless hexadecimal addresses.
  3098. CLN offers a function <CODE>cl_print</CODE>, callable from the debugger,
  3099. for printing number objects. In order to get this function, you have
  3100. to define the macro <SAMP>`CL_DEBUG'</SAMP> and then include all the header files
  3101. for which you want <CODE>cl_print</CODE> debugging support. For example:
  3102. <PRE>
  3103. #define CL_DEBUG
  3104. #include &#60;cl_string.h&#62;
  3105. </PRE>
  3106. Now, if you have in your program a variable <CODE>cl_string s</CODE>, and
  3107. inspect it under <CODE>gdb</CODE>, the output may look like this:
  3108. <PRE>
  3109. (gdb) print s
  3110. $7 = {&#60;cl_gcpointer&#62; = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
  3111. word = 134568800}}, }
  3112. (gdb) call cl_print(s)
  3113. (cl_string) ""
  3114. $8 = 134568800
  3115. </PRE>
  3116. Note that the output of <CODE>cl_print</CODE> goes to the program's error output,
  3117. not to gdb's standard output.
  3118. Note, however, that the above facility does not work with all CLN types,
  3119. only with number objects and similar. Therefore CLN offers a member function
  3120. <CODE>debug_print()</CODE> on all CLN types. The same macro <SAMP>`CL_DEBUG'</SAMP>
  3121. is needed for this member function to be implemented. Under <CODE>gdb</CODE>,
  3122. you call it like this:
  3123. <PRE>
  3124. (gdb) print s
  3125. $7 = {&#60;cl_gcpointer&#62; = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
  3126. word = 134568800}}, }
  3127. (gdb) call s.debug_print()
  3128. (cl_string) ""
  3129. (gdb) define cprint
  3130. &#62;call ($1).debug_print()
  3131. &#62;end
  3132. (gdb) cprint s
  3133. (cl_string) ""
  3134. </PRE>
  3135. Unfortunately, this feature does not seem to work under all circumstances.
  3136. </UL>
  3137. <H1><A NAME="SEC68" HREF="cln.html#TOC68">12. Customizing</A></H1>
  3138. <H2><A NAME="SEC69" HREF="cln.html#TOC69">12.1 Error handling</A></H2>
  3139. <P>
  3140. When a fatal error occurs, an error message is output to the standard error
  3141. output stream, and the function <CODE>cl_abort</CODE> is called. The default
  3142. version of this function (provided in the library) terminates the application.
  3143. To catch such a fatal error, you need to define the function <CODE>cl_abort</CODE>
  3144. yourself, with the prototype
  3145. <PRE>
  3146. #include &#60;cl_abort.h&#62;
  3147. void cl_abort (void);
  3148. </PRE>
  3149. <P>
  3150. This function must not return control to its caller.
  3151. <H2><A NAME="SEC70" HREF="cln.html#TOC70">12.2 Floating-point underflow</A></H2>
  3152. <P>
  3153. Floating point underflow denotes the situation when a floating-point number
  3154. is to be created which is so close to <CODE>0</CODE> that its exponent is too
  3155. low to be represented internally. By default, this causes a fatal error.
  3156. If you set the global variable
  3157. <PRE>
  3158. cl_boolean cl_inhibit_floating_point_underflow
  3159. </PRE>
  3160. <P>
  3161. to <CODE>cl_true</CODE>, the error will be inhibited, and a floating-point zero
  3162. will be generated instead.
  3163. The default value of <CODE>cl_inhibit_floating_point_underflow</CODE> is
  3164. <CODE>cl_false</CODE>.
  3165. <H2><A NAME="SEC71" HREF="cln.html#TOC71">12.3 Customizing I/O</A></H2>
  3166. <P>
  3167. The output of the function <CODE>fprint</CODE> may be customized by changing the
  3168. value of the global variable <CODE>cl_default_print_flags</CODE>.
  3169. <H2><A NAME="SEC72" HREF="cln.html#TOC72">12.4 Customizing the memory allocator</A></H2>
  3170. <P>
  3171. Every memory allocation of CLN is done through the function pointer
  3172. <CODE>cl_malloc_hook</CODE>. Freeing of this memory is done through the function
  3173. pointer <CODE>cl_free_hook</CODE>. The default versions of these functions,
  3174. provided in the library, call <CODE>malloc</CODE> and <CODE>free</CODE> and check
  3175. the <CODE>malloc</CODE> result against <CODE>NULL</CODE>.
  3176. If you want to provide another memory allocator, you need to define
  3177. the variables <CODE>cl_malloc_hook</CODE> and <CODE>cl_free_hook</CODE> yourself,
  3178. like this:
  3179. <PRE>
  3180. #include &#60;cl_malloc.h&#62;
  3181. void* (*cl_malloc_hook) (size_t size) = ...;
  3182. void (*cl_free_hook) (void* ptr) = ...;
  3183. </PRE>
  3184. <P>
  3185. The <CODE>cl_malloc_hook</CODE> function must not return a <CODE>NULL</CODE> pointer.
  3186. <P>
  3187. It is not possible to change the memory allocator at runtime, because
  3188. it is already called at program startup by the constructors of some
  3189. global variables.
  3190. <H1><A NAME="SEC73" HREF="cln.html#TOC73">Index</A></H1>
  3191. <P>
  3192. Jump to:
  3193. <P>
  3194. <P><HR><P>
  3195. This document was generated on 14 January 2000 using
  3196. <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.
  3197. </BODY>
  3198. </HTML>