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.

3783 lines
129 KiB

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