3 <!-- Created by texi2html 1.56k from cln.texi on 28 August 2000 -->
5 <TITLE>CLN, a Class Library for Numbers - 11. Using the library</TITLE>
8 Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_10.html">previous</A>, <A HREF="cln_12.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
12 <H1><A NAME="SEC64" HREF="cln_toc.html#TOC64">11. Using the library</A></H1>
15 For the following discussion, we will assume that you have installed
16 the CLN source in <CODE>$CLN_DIR</CODE> and built it in <CODE>$CLN_TARGETDIR</CODE>.
17 For example, for me it's <CODE>CLN_DIR="$HOME/cln"</CODE> and
18 <CODE>CLN_TARGETDIR="$HOME/cln/linuxelf"</CODE>. You might define these as
19 environment variables, or directly substitute the appropriate values.
24 <H2><A NAME="SEC65" HREF="cln_toc.html#TOC65">11.1 Compiler options</A></H2>
30 Until you have installed CLN in a public place, the following options are
35 When you compile CLN application code, add the flags
38 -I$CLN_DIR/include -I$CLN_TARGETDIR/include
42 to the C++ compiler's command line (<CODE>make</CODE> variable CFLAGS or CXXFLAGS).
43 When you link CLN application code to form an executable, add the flags
46 $CLN_TARGETDIR/src/libcln.a
50 to the C/C++ compiler's command line (<CODE>make</CODE> variable LIBS).
54 If you did a <CODE>make install</CODE>, the include files are installed in a
55 public directory (normally <CODE>/usr/local/include</CODE>), hence you don't
56 need special flags for compiling. The library has been installed to a
57 public directory as well (normally <CODE>/usr/local/lib</CODE>), hence when
58 linking a CLN application it is sufficient to give the flag <CODE>-lcln</CODE>.
63 <H2><A NAME="SEC66" HREF="cln_toc.html#TOC66">11.2 Compatibility to old CLN versions</A></H2>
70 As of CLN version 1.1 all non-macro identifiers were hidden in namespace
71 <CODE>cln</CODE> in order to avoid potential name clashes with other C++
72 libraries. If you have an old application, you will have to manually
73 port it to the new scheme. The following principles will help during
79 All headers are now in a separate subdirectory. Instead of including
80 <CODE>cl_</CODE><VAR>something</VAR><CODE>.h</CODE>, include
81 <CODE>cln/</CODE><VAR>something</VAR><CODE>.h</CODE> now.
84 All public identifiers (typenames and functions) have lost their
85 <CODE>cl_</CODE> prefix. Exceptions are all the typenames of number types,
86 (cl_N, cl_I, cl_MI, ...), rings, symbolic types (cl_string,
87 cl_symbol) and polynomials (cl_UP_<VAR>type</VAR>). (This is because their
88 names would not be mnemonic enough once the namespace <CODE>cln</CODE> is
89 imported. Even in a namespace we favor <CODE>cl_N</CODE> over <CODE>N</CODE>.)
92 All public <EM>functions</EM> that had by a <CODE>cl_</CODE> in their name still
93 carry that <CODE>cl_</CODE> if it is intrinsic part of a typename (as in
94 <CODE>cl_I_to_int ()</CODE>).
98 When developing other libraries, please keep in mind not to import the
99 namespace <CODE>cln</CODE> in one of your public header files by saying
100 <CODE>using namespace cln;</CODE>. This would propagate to other applications
101 and can cause name clashes there.
106 <H2><A NAME="SEC67" HREF="cln_toc.html#TOC67">11.3 Include files</A></H2>
108 <A NAME="IDX336"></A>
109 <A NAME="IDX337"></A>
113 Here is a summary of the include files and their contents.
118 <DT><CODE><cln/object.h></CODE>
120 General definitions, reference counting, garbage collection.
121 <DT><CODE><cln/number.h></CODE>
124 <DT><CODE><cln/complex.h></CODE>
126 Functions for class cl_N, the complex numbers.
127 <DT><CODE><cln/real.h></CODE>
129 Functions for class cl_R, the real numbers.
130 <DT><CODE><cln/float.h></CODE>
132 Functions for class cl_F, the floats.
133 <DT><CODE><cln/sfloat.h></CODE>
135 Functions for class cl_SF, the short-floats.
136 <DT><CODE><cln/ffloat.h></CODE>
138 Functions for class cl_FF, the single-floats.
139 <DT><CODE><cln/dfloat.h></CODE>
141 Functions for class cl_DF, the double-floats.
142 <DT><CODE><cln/lfloat.h></CODE>
144 Functions for class cl_LF, the long-floats.
145 <DT><CODE><cln/rational.h></CODE>
147 Functions for class cl_RA, the rational numbers.
148 <DT><CODE><cln/integer.h></CODE>
150 Functions for class cl_I, the integers.
151 <DT><CODE><cln/io.h></CODE>
154 <DT><CODE><cln/complex_io.h></CODE>
156 Input/Output for class cl_N, the complex numbers.
157 <DT><CODE><cln/real_io.h></CODE>
159 Input/Output for class cl_R, the real numbers.
160 <DT><CODE><cln/float_io.h></CODE>
162 Input/Output for class cl_F, the floats.
163 <DT><CODE><cln/sfloat_io.h></CODE>
165 Input/Output for class cl_SF, the short-floats.
166 <DT><CODE><cln/ffloat_io.h></CODE>
168 Input/Output for class cl_FF, the single-floats.
169 <DT><CODE><cln/dfloat_io.h></CODE>
171 Input/Output for class cl_DF, the double-floats.
172 <DT><CODE><cln/lfloat_io.h></CODE>
174 Input/Output for class cl_LF, the long-floats.
175 <DT><CODE><cln/rational_io.h></CODE>
177 Input/Output for class cl_RA, the rational numbers.
178 <DT><CODE><cln/integer_io.h></CODE>
180 Input/Output for class cl_I, the integers.
181 <DT><CODE><cln/input.h></CODE>
183 Flags for customizing input operations.
184 <DT><CODE><cln/output.h></CODE>
186 Flags for customizing output operations.
187 <DT><CODE><cln/malloc.h></CODE>
189 <CODE>malloc_hook</CODE>, <CODE>free_hook</CODE>.
190 <DT><CODE><cln/abort.h></CODE>
192 <CODE>cl_abort</CODE>.
193 <DT><CODE><cln/condition.h></CODE>
195 Conditions/exceptions.
196 <DT><CODE><cln/string.h></CODE>
199 <DT><CODE><cln/symbol.h></CODE>
202 <DT><CODE><cln/proplist.h></CODE>
205 <DT><CODE><cln/ring.h></CODE>
208 <DT><CODE><cln/null_ring.h></CODE>
211 <DT><CODE><cln/complex_ring.h></CODE>
213 The ring of complex numbers.
214 <DT><CODE><cln/real_ring.h></CODE>
216 The ring of real numbers.
217 <DT><CODE><cln/rational_ring.h></CODE>
219 The ring of rational numbers.
220 <DT><CODE><cln/integer_ring.h></CODE>
222 The ring of integers.
223 <DT><CODE><cln/numtheory.h></CODE>
225 Number threory functions.
226 <DT><CODE><cln/modinteger.h></CODE>
229 <DT><CODE><cln/V.h></CODE>
232 <DT><CODE><cln/GV.h></CODE>
235 <DT><CODE><cln/GV_number.h></CODE>
237 General vectors over cl_number.
238 <DT><CODE><cln/GV_complex.h></CODE>
240 General vectors over cl_N.
241 <DT><CODE><cln/GV_real.h></CODE>
243 General vectors over cl_R.
244 <DT><CODE><cln/GV_rational.h></CODE>
246 General vectors over cl_RA.
247 <DT><CODE><cln/GV_integer.h></CODE>
249 General vectors over cl_I.
250 <DT><CODE><cln/GV_modinteger.h></CODE>
252 General vectors of modular integers.
253 <DT><CODE><cln/SV.h></CODE>
256 <DT><CODE><cln/SV_number.h></CODE>
258 Simple vectors over cl_number.
259 <DT><CODE><cln/SV_complex.h></CODE>
261 Simple vectors over cl_N.
262 <DT><CODE><cln/SV_real.h></CODE>
264 Simple vectors over cl_R.
265 <DT><CODE><cln/SV_rational.h></CODE>
267 Simple vectors over cl_RA.
268 <DT><CODE><cln/SV_integer.h></CODE>
270 Simple vectors over cl_I.
271 <DT><CODE><cln/SV_ringelt.h></CODE>
273 Simple vectors of general ring elements.
274 <DT><CODE><cln/univpoly.h></CODE>
276 Univariate polynomials.
277 <DT><CODE><cln/univpoly_integer.h></CODE>
279 Univariate polynomials over the integers.
280 <DT><CODE><cln/univpoly_rational.h></CODE>
282 Univariate polynomials over the rational numbers.
283 <DT><CODE><cln/univpoly_real.h></CODE>
285 Univariate polynomials over the real numbers.
286 <DT><CODE><cln/univpoly_complex.h></CODE>
288 Univariate polynomials over the complex numbers.
289 <DT><CODE><cln/univpoly_modint.h></CODE>
291 Univariate polynomials over modular integer rings.
292 <DT><CODE><cln/timing.h></CODE>
295 <DT><CODE><cln/cln.h></CODE>
297 Includes all of the above.
302 <H2><A NAME="SEC68" HREF="cln_toc.html#TOC68">11.4 An Example</A></H2>
305 A function which computes the nth Fibonacci number can be written as follows.
306 <A NAME="IDX338"></A>
311 #include <cln/integer.h>
312 #include <cln/real.h>
315 // Returns F_n, computed as the nearest integer to
316 // ((1+sqrt(5))/2)^n/sqrt(5). Assume n>=0.
317 const cl_I fibonacci (int n)
319 // Need a precision of ((1+sqrt(5))/2)^-n.
320 cl_float_format_t prec = cl_float_format((int)(0.208987641*n+5));
321 cl_R sqrt5 = sqrt(cl_float(5,prec));
322 cl_R phi = (1+sqrt5)/2;
323 return round1( expt(phi,n)/sqrt5 );
328 Let's explain what is going on in detail.
332 The include file <CODE><cln/integer.h></CODE> is necessary because the type
333 <CODE>cl_I</CODE> is used in the function, and the include file <CODE><cln/real.h></CODE>
334 is needed for the type <CODE>cl_R</CODE> and the floating point number functions.
335 The order of the include files does not matter. In order not to write out
336 <CODE>cln::</CODE><VAR>foo</VAR> we can safely import the whole namespace <CODE>cln</CODE>.
340 Then comes the function declaration. The argument is an <CODE>int</CODE>, the
341 result an integer. The return type is defined as <SAMP>`const cl_I'</SAMP>, not
342 simply <SAMP>`cl_I'</SAMP>, because that allows the compiler to detect typos like
343 <SAMP>`fibonacci(n) = 100'</SAMP>. It would be possible to declare the return
344 type as <CODE>const cl_R</CODE> (real number) or even <CODE>const cl_N</CODE> (complex
345 number). We use the most specialized possible return type because functions
346 which call <SAMP>`fibonacci'</SAMP> will be able to profit from the compiler's type
347 analysis: Adding two integers is slightly more efficient than adding the
348 same objects declared as complex numbers, because it needs less type
349 dispatch. Also, when linking to CLN as a non-shared library, this minimizes
350 the size of the resulting executable program.
354 The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
355 integer. In order to get a correct result, the absolute error should be less
356 than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
357 To this end, the first line computes a floating point precision for sqrt(5)
362 Then sqrt(5) is computed by first converting the integer 5 to a floating point
363 number and than taking the square root. The converse, first taking the square
364 root of 5, and then converting to the desired precision, would not work in
365 CLN: The square root would be computed to a default precision (normally
366 single-float precision), and the following conversion could not help about
367 the lacking accuracy. This is because CLN is not a symbolic computer algebra
368 system and does not represent sqrt(5) in a non-numeric way.
372 The type <CODE>cl_R</CODE> for sqrt5 and, in the following line, phi is the only
373 possible choice. You cannot write <CODE>cl_F</CODE> because the C++ compiler can
374 only infer that <CODE>cl_float(5,prec)</CODE> is a real number. You cannot write
375 <CODE>cl_N</CODE> because a <SAMP>`round1'</SAMP> does not exist for general complex
380 When the function returns, all the local variables in the function are
381 automatically reclaimed (garbage collected). Only the result survives and
382 gets passed to the caller.
386 The file <CODE>fibonacci.cc</CODE> in the subdirectory <CODE>examples</CODE>
387 contains this implementation together with an even faster algorithm.
392 <H2><A NAME="SEC69" HREF="cln_toc.html#TOC69">11.5 Debugging support</A></H2>
394 <A NAME="IDX339"></A>
398 When debugging a CLN application with GNU <CODE>gdb</CODE>, two facilities are
399 available from the library:
404 <LI>The library does type checks, range checks, consistency checks at
406 many places. When one of these fails, the function <CODE>cl_abort()</CODE> is
407 called. Its default implementation is to perform an <CODE>exit(1)</CODE>, so
408 you won't have a core dump. But for debugging, it is best to set a
409 breakpoint at this function:
415 When this breakpoint is hit, look at the stack's backtrace:
421 <LI>The debugger's normal <CODE>print</CODE> command doesn't know about
423 CLN's types and therefore prints mostly useless hexadecimal addresses.
424 CLN offers a function <CODE>cl_print</CODE>, callable from the debugger,
425 for printing number objects. In order to get this function, you have
426 to define the macro <SAMP>`CL_DEBUG'</SAMP> and then include all the header files
427 for which you want <CODE>cl_print</CODE> debugging support. For example:
428 <A NAME="IDX340"></A>
432 #include <cln/string.h>
435 Now, if you have in your program a variable <CODE>cl_string s</CODE>, and
436 inspect it under <CODE>gdb</CODE>, the output may look like this:
440 $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
441 word = 134568800}}, }
442 (gdb) call cl_print(s)
447 Note that the output of <CODE>cl_print</CODE> goes to the program's error output,
448 not to gdb's standard output.
450 Note, however, that the above facility does not work with all CLN types,
451 only with number objects and similar. Therefore CLN offers a member function
452 <CODE>debug_print()</CODE> on all CLN types. The same macro <SAMP>`CL_DEBUG'</SAMP>
453 is needed for this member function to be implemented. Under <CODE>gdb</CODE>,
454 you call it like this:
455 <A NAME="IDX341"></A>
459 $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
460 word = 134568800}}, }
461 (gdb) call s.debug_print()
464 >call ($1).debug_print()
470 Unfortunately, this feature does not seem to work under all circumstances.
474 Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_10.html">previous</A>, <A HREF="cln_12.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
git://www.ginac.de / cln.git / blob