doc/cln_3.html

   1 <HTML>
   2 <HEAD>
   3 <!-- Created by texi2html 1.56k from cln.texi on 2 June 2000 -->
   4
   5 <TITLE>CLN, a Class Library for Numbers - 3. Ordinary number types</TITLE>
   6 </HEAD>
   7 <BODY>
   8 Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_2.html">previous</A>, <A HREF="cln_4.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
   9 <P><HR><P>
  10
  11
  12 <H1><A NAME="SEC11" HREF="cln_toc.html#TOC11">3. Ordinary number types</A></H1>
  13
  14 <P>
  15 CLN implements the following class hierarchy:
  16
  17
  18
  19 <PRE>
  20                         Number
  21                        cl_number
  22                      &#60;cl_number.h&#62;
  23                           |
  24                           |
  25                  Real or complex number
  26                         cl_N
  27                      &#60;cl_complex.h&#62;
  28                           |
  29                           |
  30                      Real number
  31                         cl_R
  32                       &#60;cl_real.h&#62;
  33                           |
  34       +-------------------+-------------------+
  35       |                                       |
  36 Rational number                     Floating-point number
  37     cl_RA                                   cl_F
  38 &#60;cl_rational.h&#62;                          &#60;cl_float.h&#62;
  39       |                                       |
  40       |                  +-------------+-------------+-------------+
  41    Integer               |             |             |             |
  42     cl_I            Short-Float   Single-Float  Double-Float   Long-Float
  43  &#60;cl_integer.h&#62;        cl_SF         cl_FF         cl_DF         cl_LF
  44                    &#60;cl_sfloat.h&#62; &#60;cl_ffloat.h&#62; &#60;cl_dfloat.h&#62; &#60;cl_lfloat.h&#62;
  45 </PRE>
  46
  47 <P>
  48 <A NAME="IDX7"></A>
  49 <A NAME="IDX8"></A>
  50 The base class <CODE>cl_number</CODE> is an abstract base class.
  51 It is not useful to declare a variable of this type except if you want
  52 to completely disable compile-time type checking and use run-time type
  53 checking instead.
  54
  55
  56 <P>
  57 <A NAME="IDX9"></A>
  58 <A NAME="IDX10"></A>
  59 <A NAME="IDX11"></A>
  60 The class <CODE>cl_N</CODE> comprises real and complex numbers. There is
  61 no special class for complex numbers since complex numbers with imaginary
  62 part <CODE>0</CODE> are automatically converted to real numbers.
  63
  64
  65 <P>
  66 <A NAME="IDX12"></A>
  67 The class <CODE>cl_R</CODE> comprises real numbers of different kinds. It is an
  68 abstract class.
  69
  70
  71 <P>
  72 <A NAME="IDX13"></A>
  73 <A NAME="IDX14"></A>
  74 <A NAME="IDX15"></A>
  75 The class <CODE>cl_RA</CODE> comprises exact real numbers: rational numbers, including
  76 integers. There is no special class for non-integral rational numbers
  77 since rational numbers with denominator <CODE>1</CODE> are automatically converted
  78 to integers.
  79
  80
  81 <P>
  82 <A NAME="IDX16"></A>
  83 The class <CODE>cl_F</CODE> implements floating-point approximations to real numbers.
  84 It is an abstract class.
  85
  86
  87
  88
  89 <H2><A NAME="SEC12" HREF="cln_toc.html#TOC12">3.1 Exact numbers</A></H2>
  90 <P>
  91 <A NAME="IDX17"></A>
  92
  93
  94 <P>
  95 Some numbers are represented as exact numbers: there is no loss of information
  96 when such a number is converted from its mathematical value to its internal
  97 representation. On exact numbers, the elementary operations (<CODE>+</CODE>,
  98 <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, comparisons, ...) compute the completely
  99 correct result.
 100
 101
 102 <P>
 103 In CLN, the exact numbers are:
 104
 105
 106
 107 <UL>
 108 <LI>
 109
 110 rational numbers (including integers),
 111 <LI>
 112
 113 complex numbers whose real and imaginary parts are both rational numbers.
 114 </UL>
 115
 116 <P>
 117 Rational numbers are always normalized to the form
 118 <CODE><VAR>numerator</VAR>/<VAR>denominator</VAR></CODE> where the numerator and denominator
 119 are coprime integers and the denominator is positive. If the resulting
 120 denominator is <CODE>1</CODE>, the rational number is converted to an integer.
 121
 122
 123 <P>
 124 Small integers (typically in the range <CODE>-2^30</CODE>...<CODE>2^30-1</CODE>,
 125 for 32-bit machines) are especially efficient, because they consume no heap
 126 allocation. Otherwise the distinction between these immediate integers
 127 (called "fixnums") and heap allocated integers (called "bignums")
 128 is completely transparent.
 129
 130
 131
 132
 133 <H2><A NAME="SEC13" HREF="cln_toc.html#TOC13">3.2 Floating-point numbers</A></H2>
 134 <P>
 135 <A NAME="IDX18"></A>
 136
 137
 138 <P>
 139 Not all real numbers can be represented exactly. (There is an easy mathematical
 140 proof for this: Only a countable set of numbers can be stored exactly in
 141 a computer, even if one assumes that it has unlimited storage. But there
 142 are uncountably many real numbers.) So some approximation is needed.
 143 CLN implements ordinary floating-point numbers, with mantissa and exponent.
 144
 145
 146 <P>
 147 <A NAME="IDX19"></A>
 148 The elementary operations (<CODE>+</CODE>, <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, ...)
 149 only return approximate results. For example, the value of the expression
 150 <CODE>(cl_F) 0.3 + (cl_F) 0.4</CODE> prints as <SAMP>`0.70000005'</SAMP>, not as
 151 <SAMP>`0.7'</SAMP>. Rounding errors like this one are inevitable when computing
 152 with floating-point numbers.
 153
 154
 155 <P>
 156 Nevertheless, CLN rounds the floating-point results of the operations <CODE>+</CODE>,
 157 <CODE>-</CODE>, <CODE>*</CODE>, <CODE>/</CODE>, <CODE>sqrt</CODE> according to the "round-to-even"
 158 rule: It first computes the exact mathematical result and then returns the
 159 floating-point number which is nearest to this. If two floating-point numbers
 160 are equally distant from the ideal result, the one with a <CODE>0</CODE> in its least
 161 significant mantissa bit is chosen.
 162
 163
 164 <P>
 165 Similarly, testing floating point numbers for equality <SAMP>`x == y'</SAMP>
 166 is gambling with random errors. Better check for <SAMP>`abs(x - y) &#60; epsilon'</SAMP>
 167 for some well-chosen <CODE>epsilon</CODE>.
 168
 169
 170 <P>
 171 Floating point numbers come in four flavors:
 172
 173
 174
 175 <UL>
 176 <LI>
 177
 178 <A NAME="IDX20"></A>
 179 Short floats, type <CODE>cl_SF</CODE>.
 180 They have 1 sign bit, 8 exponent bits (including the exponent's sign),
 181 and 17 mantissa bits (including the "hidden" bit).
 182 They don't consume heap allocation.
 183
 184 <LI>
 185
 186 <A NAME="IDX21"></A>
 187 Single floats, type <CODE>cl_FF</CODE>.
 188 They have 1 sign bit, 8 exponent bits (including the exponent's sign),
 189 and 24 mantissa bits (including the "hidden" bit).
 190 In CLN, they are represented as IEEE single-precision floating point numbers.
 191 This corresponds closely to the C/C++ type <SAMP>`float'</SAMP>.
 192
 193 <LI>
 194
 195 <A NAME="IDX22"></A>
 196 Double floats, type <CODE>cl_DF</CODE>.
 197 They have 1 sign bit, 11 exponent bits (including the exponent's sign),
 198 and 53 mantissa bits (including the "hidden" bit).
 199 In CLN, they are represented as IEEE double-precision floating point numbers.
 200 This corresponds closely to the C/C++ type <SAMP>`double'</SAMP>.
 201
 202 <LI>
 203
 204 <A NAME="IDX23"></A>
 205 Long floats, type <CODE>cl_LF</CODE>.
 206 They have 1 sign bit, 32 exponent bits (including the exponent's sign),
 207 and n mantissa bits (including the "hidden" bit), where n &#62;= 64.
 208 The precision of a long float is unlimited, but once created, a long float
 209 has a fixed precision. (No "lazy recomputation".)
 210 </UL>
 211
 212 <P>
 213 Of course, computations with long floats are more expensive than those
 214 with smaller floating-point formats.
 215
 216
 217 <P>
 218 CLN does not implement features like NaNs, denormalized numbers and
 219 gradual underflow. If the exponent range of some floating-point type
 220 is too limited for your application, choose another floating-point type
 221 with larger exponent range.
 222
 223
 224 <P>
 225 <A NAME="IDX24"></A>
 226 As a user of CLN, you can forget about the differences between the
 227 four floating-point types and just declare all your floating-point
 228 variables as being of type <CODE>cl_F</CODE>. This has the advantage that
 229 when you change the precision of some computation (say, from <CODE>cl_DF</CODE>
 230 to <CODE>cl_LF</CODE>), you don't have to change the code, only the precision
 231 of the initial values. Also, many transcendental functions have been
 232 declared as returning a <CODE>cl_F</CODE> when the argument is a <CODE>cl_F</CODE>,
 233 but such declarations are missing for the types <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>,
 234 <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>. (Such declarations would be wrong if
 235 the floating point contagion rule happened to change in the future.)
 236
 237
 238
 239
 240 <H2><A NAME="SEC14" HREF="cln_toc.html#TOC14">3.3 Complex numbers</A></H2>
 241 <P>
 242 <A NAME="IDX25"></A>
 243
 244
 245 <P>
 246 Complex numbers, as implemented by the class <CODE>cl_N</CODE>, have a real
 247 part and an imaginary part, both real numbers. A complex number whose
 248 imaginary part is the exact number <CODE>0</CODE> is automatically converted
 249 to a real number.
 250
 251
 252 <P>
 253 Complex numbers can arise from real numbers alone, for example
 254 through application of <CODE>sqrt</CODE> or transcendental functions.
 255
 256
 257
 258
 259 <H2><A NAME="SEC15" HREF="cln_toc.html#TOC15">3.4 Conversions</A></H2>
 260 <P>
 261 <A NAME="IDX26"></A>
 262
 263
 264 <P>
 265 Conversions from any class to any its superclasses ("base classes" in
 266 C++ terminology) is done automatically.
 267
 268
 269 <P>
 270 Conversions from the C built-in types <SAMP>`long'</SAMP> and <SAMP>`unsigned long'</SAMP>
 271 are provided for the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_R</CODE>,
 272 <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
 273
 274
 275 <P>
 276 Conversions from the C built-in types <SAMP>`int'</SAMP> and <SAMP>`unsigned int'</SAMP>
 277 are provided for the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_R</CODE>,
 278 <CODE>cl_N</CODE> and <CODE>cl_number</CODE>. However, these conversions emphasize
 279 efficiency. Their range is therefore limited:
 280
 281
 282
 283 <UL>
 284 <LI>
 285
 286 The conversion from <SAMP>`int'</SAMP> works only if the argument is &#60; 2^29 and &#62; -2^29.
 287 <LI>
 288
 289 The conversion from <SAMP>`unsigned int'</SAMP> works only if the argument is &#60; 2^29.
 290 </UL>
 291
 292 <P>
 293 In a declaration like <SAMP>`cl_I x = 10;'</SAMP> the C++ compiler is able to
 294 do the conversion of <CODE>10</CODE> from <SAMP>`int'</SAMP> to <SAMP>`cl_I'</SAMP> at compile time
 295 already. On the other hand, code like <SAMP>`cl_I x = 1000000000;'</SAMP> is
 296 in error.
 297 So, if you want to be sure that an <SAMP>`int'</SAMP> whose magnitude is not guaranteed
 298 to be &#60; 2^29 is correctly converted to a <SAMP>`cl_I'</SAMP>, first convert it to a
 299 <SAMP>`long'</SAMP>. Similarly, if a large <SAMP>`unsigned int'</SAMP> is to be converted to a
 300 <SAMP>`cl_I'</SAMP>, first convert it to an <SAMP>`unsigned long'</SAMP>.
 301
 302
 303 <P>
 304 Conversions from the C built-in type <SAMP>`float'</SAMP> are provided for the classes
 305 <CODE>cl_FF</CODE>, <CODE>cl_F</CODE>, <CODE>cl_R</CODE>, <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
 306
 307
 308 <P>
 309 Conversions from the C built-in type <SAMP>`double'</SAMP> are provided for the classes
 310 <CODE>cl_DF</CODE>, <CODE>cl_F</CODE>, <CODE>cl_R</CODE>, <CODE>cl_N</CODE> and <CODE>cl_number</CODE>.
 311
 312
 313 <P>
 314 Conversions from <SAMP>`const char *'</SAMP> are provided for the classes
 315 <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
 316 <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>, <CODE>cl_F</CODE>,
 317 <CODE>cl_R</CODE>, <CODE>cl_N</CODE>.
 318 The easiest way to specify a value which is outside of the range of the
 319 C++ built-in types is therefore to specify it as a string, like this:
 320 <A NAME="IDX27"></A>
 321
 322 <PRE>
 323    cl_I order_of_rubiks_cube_group = "43252003274489856000";
 324 </PRE>
 325
 326 <P>
 327 Note that this conversion is done at runtime, not at compile-time.
 328
 329
 330 <P>
 331 Conversions from <CODE>cl_I</CODE> to the C built-in types <SAMP>`int'</SAMP>,
 332 <SAMP>`unsigned int'</SAMP>, <SAMP>`long'</SAMP>, <SAMP>`unsigned long'</SAMP> are provided through
 333 the functions
 334
 335
 336 <DL COMPACT>
 337
 338 <DT><CODE>int cl_I_to_int (const cl_I&#38; x)</CODE>
 339 <DD>
 340 <A NAME="IDX28"></A>
 341 <DT><CODE>unsigned int cl_I_to_uint (const cl_I&#38; x)</CODE>
 342 <DD>
 343 <A NAME="IDX29"></A>
 344 <DT><CODE>long cl_I_to_long (const cl_I&#38; x)</CODE>
 345 <DD>
 346 <A NAME="IDX30"></A>
 347 <DT><CODE>unsigned long cl_I_to_ulong (const cl_I&#38; x)</CODE>
 348 <DD>
 349 <A NAME="IDX31"></A>
 350 Returns <CODE>x</CODE> as element of the C type <VAR>ctype</VAR>. If <CODE>x</CODE> is not
 351 representable in the range of <VAR>ctype</VAR>, a runtime error occurs.
 352 </DL>
 353
 354 <P>
 355 Conversions from the classes <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
 356 <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>, <CODE>cl_F</CODE> and
 357 <CODE>cl_R</CODE>
 358 to the C built-in types <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP> are provided through
 359 the functions
 360
 361
 362 <DL COMPACT>
 363
 364 <DT><CODE>float cl_float_approx (const <VAR>type</VAR>&#38; x)</CODE>
 365 <DD>
 366 <A NAME="IDX32"></A>
 367 <DT><CODE>double cl_double_approx (const <VAR>type</VAR>&#38; x)</CODE>
 368 <DD>
 369 <A NAME="IDX33"></A>
 370 Returns an approximation of <CODE>x</CODE> of C type <VAR>ctype</VAR>.
 371 If <CODE>abs(x)</CODE> is too close to 0 (underflow), 0 is returned.
 372 If <CODE>abs(x)</CODE> is too large (overflow), an IEEE infinity is returned.
 373 </DL>
 374
 375 <P>
 376 Conversions from any class to any of its subclasses ("derived classes" in
 377 C++ terminology) are not provided. Instead, you can assert and check
 378 that a value belongs to a certain subclass, and return it as element of that
 379 class, using the <SAMP>`As'</SAMP> and <SAMP>`The'</SAMP> macros.
 380 <A NAME="IDX34"></A>
 381 <CODE>As(<VAR>type</VAR>)(<VAR>value</VAR>)</CODE> checks that <VAR>value</VAR> belongs to
 382 <VAR>type</VAR> and returns it as such.
 383 <A NAME="IDX35"></A>
 384 <CODE>The(<VAR>type</VAR>)(<VAR>value</VAR>)</CODE> assumes that <VAR>value</VAR> belongs to
 385 <VAR>type</VAR> and returns it as such. It is your responsibility to ensure
 386 that this assumption is valid.
 387 Example:
 388
 389
 390
 391 <PRE>
 392    cl_I x = ...;
 393    if (!(x &#62;= 0)) abort();
 394    cl_I ten_x = The(cl_I)(expt(10,x)); // If x &#62;= 0, 10^x is an integer.
 395                 // In general, it would be a rational number.
 396 </PRE>
 397
 398 <P><HR><P>
 399 Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_2.html">previous</A>, <A HREF="cln_4.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
 400 </BODY>
 401 </HTML>