3 <!-- Created by texi2html 1.56k from cln.texi on 28 August 2000 -->
5 <TITLE>CLN, a Class Library for Numbers - 3. Ordinary number types</TITLE>
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>.
12 <H1><A NAME="SEC11" HREF="cln_toc.html#TOC11">3. Ordinary number types</A></H1>
15 CLN implements the following class hierarchy:
22 <cln/number.h>
25 Real or complex number
27 <cln/complex.h>
34 +-------------------+-------------------+
36 Rational number Floating-point number
38 <cln/rational.h> <cln/float.h>
40 | +--------------+--------------+--------------+
42 cl_I Short-Float Single-Float Double-Float Long-Float
43 <cln/integer.h> cl_SF cl_FF cl_DF cl_LF
44 <cln/sfloat.h> <cln/ffloat.h> <cln/dfloat.h> <cln/lfloat.h>
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
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.
67 The class <CODE>cl_R</CODE> comprises real numbers of different kinds. It is an
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
83 The class <CODE>cl_F</CODE> implements floating-point approximations to real numbers.
84 It is an abstract class.
89 <H2><A NAME="SEC12" HREF="cln_toc.html#TOC12">3.1 Exact numbers</A></H2>
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
103 In CLN, the exact numbers are:
110 rational numbers (including integers),
113 complex numbers whose real and imaginary parts are both rational numbers.
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.
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.
133 <H2><A NAME="SEC13" HREF="cln_toc.html#TOC13">3.2 Floating-point numbers</A></H2>
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.
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.
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.
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) < epsilon'</SAMP>
167 for some well-chosen <CODE>epsilon</CODE>.
171 Floating point numbers come in four flavors:
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.
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>.
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>.
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 >= 64.
208 The precision of a long float is unlimited, but once created, a long float
209 has a fixed precision. (No "lazy recomputation".)
213 Of course, computations with long floats are more expensive than those
214 with smaller floating-point formats.
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.
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.)
240 <H2><A NAME="SEC14" HREF="cln_toc.html#TOC14">3.3 Complex numbers</A></H2>
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
253 Complex numbers can arise from real numbers alone, for example
254 through application of <CODE>sqrt</CODE> or transcendental functions.
259 <H2><A NAME="SEC15" HREF="cln_toc.html#TOC15">3.4 Conversions</A></H2>
265 Conversions from any class to any its superclasses ("base classes" in
266 C++ terminology) is done automatically.
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>.
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:
286 The conversion from <SAMP>`int'</SAMP> works only if the argument is < 2^29 and > -2^29.
289 The conversion from <SAMP>`unsigned int'</SAMP> works only if the argument is < 2^29.
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
297 So, if you want to be sure that an <SAMP>`int'</SAMP> whose magnitude is not guaranteed
298 to be < 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>.
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>.
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>.
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:
323 cl_I order_of_rubiks_cube_group = "43252003274489856000";
327 Note that this conversion is done at runtime, not at compile-time.
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
338 <DT><CODE>int cl_I_to_int (const cl_I& x)</CODE>
341 <DT><CODE>unsigned int cl_I_to_uint (const cl_I& x)</CODE>
344 <DT><CODE>long cl_I_to_long (const cl_I& x)</CODE>
347 <DT><CODE>unsigned long cl_I_to_ulong (const cl_I& x)</CODE>
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.
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
358 to the C built-in types <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP> are provided through
364 <DT><CODE>float float_approx (const <VAR>type</VAR>& x)</CODE>
367 <DT><CODE>double double_approx (const <VAR>type</VAR>& x)</CODE>
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.
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.
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.
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.
393 if (!(x >= 0)) abort();
394 cl_I ten_x = The(cl_I)(expt(10,x)); // If x >= 0, 10^x is an integer.
395 // In general, it would be a rational number.
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>.