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.
431 lines
12 KiB
431 lines
12 KiB
<HTML>
|
|
<HEAD>
|
|
<!-- Created by texi2html 1.56k from cln.texi on 5 May 2000 -->
|
|
|
|
<TITLE>CLN, a Class Library for Numbers - 11. Using the library</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
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>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC64" HREF="cln_toc.html#TOC64">11. Using the library</A></H1>
|
|
|
|
<P>
|
|
For the following discussion, we will assume that you have installed
|
|
the CLN source in <CODE>$CLN_DIR</CODE> and built it in <CODE>$CLN_TARGETDIR</CODE>.
|
|
For example, for me it's <CODE>CLN_DIR="$HOME/cln"</CODE> and
|
|
<CODE>CLN_TARGETDIR="$HOME/cln/linuxelf"</CODE>. You might define these as
|
|
environment variables, or directly substitute the appropriate values.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC65" HREF="cln_toc.html#TOC65">11.1 Compiler options</A></H2>
|
|
<P>
|
|
<A NAME="IDX319"></A>
|
|
|
|
|
|
<P>
|
|
Until you have installed CLN in a public place, the following options are
|
|
needed:
|
|
|
|
|
|
<P>
|
|
When you compile CLN application code, add the flags
|
|
|
|
<PRE>
|
|
-I$CLN_DIR/include -I$CLN_TARGETDIR/include
|
|
</PRE>
|
|
|
|
<P>
|
|
to the C++ compiler's command line (<CODE>make</CODE> variable CFLAGS or CXXFLAGS).
|
|
When you link CLN application code to form an executable, add the flags
|
|
|
|
<PRE>
|
|
$CLN_TARGETDIR/src/libcln.a
|
|
</PRE>
|
|
|
|
<P>
|
|
to the C/C++ compiler's command line (<CODE>make</CODE> variable LIBS).
|
|
|
|
|
|
<P>
|
|
If you did a <CODE>make install</CODE>, the include files are installed in a
|
|
public directory (normally <CODE>/usr/local/include</CODE>), hence you don't
|
|
need special flags for compiling. The library has been installed to a
|
|
public directory as well (normally <CODE>/usr/local/lib</CODE>), hence when
|
|
linking a CLN application it is sufficient to give the flag <CODE>-lcln</CODE>.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC66" HREF="cln_toc.html#TOC66">11.2 Include files</A></H2>
|
|
<P>
|
|
<A NAME="IDX320"></A>
|
|
<A NAME="IDX321"></A>
|
|
|
|
|
|
<P>
|
|
Here is a summary of the include files and their contents.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><cl_object.h></CODE>
|
|
<DD>
|
|
General definitions, reference counting, garbage collection.
|
|
<DT><CODE><cl_number.h></CODE>
|
|
<DD>
|
|
The class cl_number.
|
|
<DT><CODE><cl_complex.h></CODE>
|
|
<DD>
|
|
Functions for class cl_N, the complex numbers.
|
|
<DT><CODE><cl_real.h></CODE>
|
|
<DD>
|
|
Functions for class cl_R, the real numbers.
|
|
<DT><CODE><cl_float.h></CODE>
|
|
<DD>
|
|
Functions for class cl_F, the floats.
|
|
<DT><CODE><cl_sfloat.h></CODE>
|
|
<DD>
|
|
Functions for class cl_SF, the short-floats.
|
|
<DT><CODE><cl_ffloat.h></CODE>
|
|
<DD>
|
|
Functions for class cl_FF, the single-floats.
|
|
<DT><CODE><cl_dfloat.h></CODE>
|
|
<DD>
|
|
Functions for class cl_DF, the double-floats.
|
|
<DT><CODE><cl_lfloat.h></CODE>
|
|
<DD>
|
|
Functions for class cl_LF, the long-floats.
|
|
<DT><CODE><cl_rational.h></CODE>
|
|
<DD>
|
|
Functions for class cl_RA, the rational numbers.
|
|
<DT><CODE><cl_integer.h></CODE>
|
|
<DD>
|
|
Functions for class cl_I, the integers.
|
|
<DT><CODE><cl_io.h></CODE>
|
|
<DD>
|
|
Input/Output.
|
|
<DT><CODE><cl_complex_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_N, the complex numbers.
|
|
<DT><CODE><cl_real_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_R, the real numbers.
|
|
<DT><CODE><cl_float_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_F, the floats.
|
|
<DT><CODE><cl_sfloat_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_SF, the short-floats.
|
|
<DT><CODE><cl_ffloat_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_FF, the single-floats.
|
|
<DT><CODE><cl_dfloat_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_DF, the double-floats.
|
|
<DT><CODE><cl_lfloat_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_LF, the long-floats.
|
|
<DT><CODE><cl_rational_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_RA, the rational numbers.
|
|
<DT><CODE><cl_integer_io.h></CODE>
|
|
<DD>
|
|
Input/Output for class cl_I, the integers.
|
|
<DT><CODE><cl_input.h></CODE>
|
|
<DD>
|
|
Flags for customizing input operations.
|
|
<DT><CODE><cl_output.h></CODE>
|
|
<DD>
|
|
Flags for customizing output operations.
|
|
<DT><CODE><cl_malloc.h></CODE>
|
|
<DD>
|
|
<CODE>cl_malloc_hook</CODE>, <CODE>cl_free_hook</CODE>.
|
|
<DT><CODE><cl_abort.h></CODE>
|
|
<DD>
|
|
<CODE>cl_abort</CODE>.
|
|
<DT><CODE><cl_condition.h></CODE>
|
|
<DD>
|
|
Conditions/exceptions.
|
|
<DT><CODE><cl_string.h></CODE>
|
|
<DD>
|
|
Strings.
|
|
<DT><CODE><cl_symbol.h></CODE>
|
|
<DD>
|
|
Symbols.
|
|
<DT><CODE><cl_proplist.h></CODE>
|
|
<DD>
|
|
Property lists.
|
|
<DT><CODE><cl_ring.h></CODE>
|
|
<DD>
|
|
General rings.
|
|
<DT><CODE><cl_null_ring.h></CODE>
|
|
<DD>
|
|
The null ring.
|
|
<DT><CODE><cl_complex_ring.h></CODE>
|
|
<DD>
|
|
The ring of complex numbers.
|
|
<DT><CODE><cl_real_ring.h></CODE>
|
|
<DD>
|
|
The ring of real numbers.
|
|
<DT><CODE><cl_rational_ring.h></CODE>
|
|
<DD>
|
|
The ring of rational numbers.
|
|
<DT><CODE><cl_integer_ring.h></CODE>
|
|
<DD>
|
|
The ring of integers.
|
|
<DT><CODE><cl_numtheory.h></CODE>
|
|
<DD>
|
|
Number threory functions.
|
|
<DT><CODE><cl_modinteger.h></CODE>
|
|
<DD>
|
|
Modular integers.
|
|
<DT><CODE><cl_V.h></CODE>
|
|
<DD>
|
|
Vectors.
|
|
<DT><CODE><cl_GV.h></CODE>
|
|
<DD>
|
|
General vectors.
|
|
<DT><CODE><cl_GV_number.h></CODE>
|
|
<DD>
|
|
General vectors over cl_number.
|
|
<DT><CODE><cl_GV_complex.h></CODE>
|
|
<DD>
|
|
General vectors over cl_N.
|
|
<DT><CODE><cl_GV_real.h></CODE>
|
|
<DD>
|
|
General vectors over cl_R.
|
|
<DT><CODE><cl_GV_rational.h></CODE>
|
|
<DD>
|
|
General vectors over cl_RA.
|
|
<DT><CODE><cl_GV_integer.h></CODE>
|
|
<DD>
|
|
General vectors over cl_I.
|
|
<DT><CODE><cl_GV_modinteger.h></CODE>
|
|
<DD>
|
|
General vectors of modular integers.
|
|
<DT><CODE><cl_SV.h></CODE>
|
|
<DD>
|
|
Simple vectors.
|
|
<DT><CODE><cl_SV_number.h></CODE>
|
|
<DD>
|
|
Simple vectors over cl_number.
|
|
<DT><CODE><cl_SV_complex.h></CODE>
|
|
<DD>
|
|
Simple vectors over cl_N.
|
|
<DT><CODE><cl_SV_real.h></CODE>
|
|
<DD>
|
|
Simple vectors over cl_R.
|
|
<DT><CODE><cl_SV_rational.h></CODE>
|
|
<DD>
|
|
Simple vectors over cl_RA.
|
|
<DT><CODE><cl_SV_integer.h></CODE>
|
|
<DD>
|
|
Simple vectors over cl_I.
|
|
<DT><CODE><cl_SV_ringelt.h></CODE>
|
|
<DD>
|
|
Simple vectors of general ring elements.
|
|
<DT><CODE><cl_univpoly.h></CODE>
|
|
<DD>
|
|
Univariate polynomials.
|
|
<DT><CODE><cl_univpoly_integer.h></CODE>
|
|
<DD>
|
|
Univariate polynomials over the integers.
|
|
<DT><CODE><cl_univpoly_rational.h></CODE>
|
|
<DD>
|
|
Univariate polynomials over the rational numbers.
|
|
<DT><CODE><cl_univpoly_real.h></CODE>
|
|
<DD>
|
|
Univariate polynomials over the real numbers.
|
|
<DT><CODE><cl_univpoly_complex.h></CODE>
|
|
<DD>
|
|
Univariate polynomials over the complex numbers.
|
|
<DT><CODE><cl_univpoly_modint.h></CODE>
|
|
<DD>
|
|
Univariate polynomials over modular integer rings.
|
|
<DT><CODE><cl_timing.h></CODE>
|
|
<DD>
|
|
Timing facilities.
|
|
<DT><CODE><cln.h></CODE>
|
|
<DD>
|
|
Includes all of the above.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC67" HREF="cln_toc.html#TOC67">11.3 An Example</A></H2>
|
|
|
|
<P>
|
|
A function which computes the nth Fibonacci number can be written as follows.
|
|
<A NAME="IDX322"></A>
|
|
|
|
|
|
|
|
<PRE>
|
|
#include <cl_integer.h>
|
|
#include <cl_real.h>
|
|
|
|
// Returns F_n, computed as the nearest integer to
|
|
// ((1+sqrt(5))/2)^n/sqrt(5). Assume n>=0.
|
|
const cl_I fibonacci (int n)
|
|
{
|
|
// Need a precision of ((1+sqrt(5))/2)^-n.
|
|
cl_float_format_t prec = cl_float_format((int)(0.208987641*n+5));
|
|
cl_R sqrt5 = sqrt(cl_float(5,prec));
|
|
cl_R phi = (1+sqrt5)/2;
|
|
return round1( expt(phi,n)/sqrt5 );
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
Let's explain what is going on in detail.
|
|
|
|
|
|
<P>
|
|
The include file <CODE><cl_integer.h></CODE> is necessary because the type
|
|
<CODE>cl_I</CODE> is used in the function, and the include file <CODE><cl_real.h></CODE>
|
|
is needed for the type <CODE>cl_R</CODE> and the floating point number functions.
|
|
The order of the include files does not matter.
|
|
|
|
|
|
<P>
|
|
Then comes the function declaration. The argument is an <CODE>int</CODE>, the
|
|
result an integer. The return type is defined as <SAMP>`const cl_I'</SAMP>, not
|
|
simply <SAMP>`cl_I'</SAMP>, because that allows the compiler to detect typos like
|
|
<SAMP>`fibonacci(n) = 100'</SAMP>. It would be possible to declare the return
|
|
type as <CODE>const cl_R</CODE> (real number) or even <CODE>const cl_N</CODE> (complex
|
|
number). We use the most specialized possible return type because functions
|
|
which call <SAMP>`fibonacci'</SAMP> will be able to profit from the compiler's type
|
|
analysis: Adding two integers is slightly more efficient than adding the
|
|
same objects declared as complex numbers, because it needs less type
|
|
dispatch. Also, when linking to CLN as a non-shared library, this minimizes
|
|
the size of the resulting executable program.
|
|
|
|
|
|
<P>
|
|
The result will be computed as expt(phi,n)/sqrt(5), rounded to the nearest
|
|
integer. In order to get a correct result, the absolute error should be less
|
|
than 1/2, i.e. the relative error should be less than sqrt(5)/(2*expt(phi,n)).
|
|
To this end, the first line computes a floating point precision for sqrt(5)
|
|
and phi.
|
|
|
|
|
|
<P>
|
|
Then sqrt(5) is computed by first converting the integer 5 to a floating point
|
|
number and than taking the square root. The converse, first taking the square
|
|
root of 5, and then converting to the desired precision, would not work in
|
|
CLN: The square root would be computed to a default precision (normally
|
|
single-float precision), and the following conversion could not help about
|
|
the lacking accuracy. This is because CLN is not a symbolic computer algebra
|
|
system and does not represent sqrt(5) in a non-numeric way.
|
|
|
|
|
|
<P>
|
|
The type <CODE>cl_R</CODE> for sqrt5 and, in the following line, phi is the only
|
|
possible choice. You cannot write <CODE>cl_F</CODE> because the C++ compiler can
|
|
only infer that <CODE>cl_float(5,prec)</CODE> is a real number. You cannot write
|
|
<CODE>cl_N</CODE> because a <SAMP>`round1'</SAMP> does not exist for general complex
|
|
numbers.
|
|
|
|
|
|
<P>
|
|
When the function returns, all the local variables in the function are
|
|
automatically reclaimed (garbage collected). Only the result survives and
|
|
gets passed to the caller.
|
|
|
|
|
|
<P>
|
|
The file <CODE>fibonacci.cc</CODE> in the subdirectory <CODE>examples</CODE>
|
|
contains this implementation together with an even faster algorithm.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC68" HREF="cln_toc.html#TOC68">11.4 Debugging support</A></H2>
|
|
<P>
|
|
<A NAME="IDX323"></A>
|
|
|
|
|
|
<P>
|
|
When debugging a CLN application with GNU <CODE>gdb</CODE>, two facilities are
|
|
available from the library:
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>The library does type checks, range checks, consistency checks at
|
|
|
|
many places. When one of these fails, the function <CODE>cl_abort()</CODE> is
|
|
called. Its default implementation is to perform an <CODE>exit(1)</CODE>, so
|
|
you won't have a core dump. But for debugging, it is best to set a
|
|
breakpoint at this function:
|
|
|
|
<PRE>
|
|
(gdb) break cl_abort
|
|
</PRE>
|
|
|
|
When this breakpoint is hit, look at the stack's backtrace:
|
|
|
|
<PRE>
|
|
(gdb) where
|
|
</PRE>
|
|
|
|
<LI>The debugger's normal <CODE>print</CODE> command doesn't know about
|
|
|
|
CLN's types and therefore prints mostly useless hexadecimal addresses.
|
|
CLN offers a function <CODE>cl_print</CODE>, callable from the debugger,
|
|
for printing number objects. In order to get this function, you have
|
|
to define the macro <SAMP>`CL_DEBUG'</SAMP> and then include all the header files
|
|
for which you want <CODE>cl_print</CODE> debugging support. For example:
|
|
<A NAME="IDX324"></A>
|
|
|
|
<PRE>
|
|
#define CL_DEBUG
|
|
#include <cl_string.h>
|
|
</PRE>
|
|
|
|
Now, if you have in your program a variable <CODE>cl_string s</CODE>, and
|
|
inspect it under <CODE>gdb</CODE>, the output may look like this:
|
|
|
|
<PRE>
|
|
(gdb) print s
|
|
$7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
|
|
word = 134568800}}, }
|
|
(gdb) call cl_print(s)
|
|
(cl_string) ""
|
|
$8 = 134568800
|
|
</PRE>
|
|
|
|
Note that the output of <CODE>cl_print</CODE> goes to the program's error output,
|
|
not to gdb's standard output.
|
|
|
|
Note, however, that the above facility does not work with all CLN types,
|
|
only with number objects and similar. Therefore CLN offers a member function
|
|
<CODE>debug_print()</CODE> on all CLN types. The same macro <SAMP>`CL_DEBUG'</SAMP>
|
|
is needed for this member function to be implemented. Under <CODE>gdb</CODE>,
|
|
you call it like this:
|
|
<A NAME="IDX325"></A>
|
|
|
|
<PRE>
|
|
(gdb) print s
|
|
$7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
|
|
word = 134568800}}, }
|
|
(gdb) call s.debug_print()
|
|
(cl_string) ""
|
|
(gdb) define cprint
|
|
>call ($1).debug_print()
|
|
>end
|
|
(gdb) cprint s
|
|
(cl_string) ""
|
|
</PRE>
|
|
|
|
Unfortunately, this feature does not seem to work under all circumstances.
|
|
</UL>
|
|
|
|
<P><HR><P>
|
|
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>.
|
|
</BODY>
|
|
</HTML>
|