[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 11. Using the library

For the following discussion, we will assume that you have installed the CLN source in `$CLN_DIR` and built it in `$CLN_TARGETDIR`. For example, for me it's `CLN_DIR="$HOME/cln"` and `CLN_TARGETDIR="$HOME/cln/linuxelf"`. You might define these as environment variables, or directly substitute the appropriate values.

11.1 Compiler options |  |
11.2 Compatibility to old CLN versions |  |
11.3 Include files |  |
11.4 An Example |  |
11.5 Debugging support |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 11.1 Compiler options

Until you have installed CLN in a public place, the following options are needed:

When you compile CLN application code, add the flags

       -I$CLN_DIR/include -I$CLN_TARGETDIR/include

to the C++ compiler's command line (`make` variable CFLAGS or CXXFLAGS). When you link CLN application code to form an executable, add the flags

       $CLN_TARGETDIR/src/libcln.a

to the C/C++ compiler's command line (`make` variable LIBS).

If you did a `make install`, the include files are installed in a public directory (normally `/usr/local/include`), hence you don't need special flags for compiling. The library has been installed to a public directory as well (normally `/usr/local/lib`), hence when linking a CLN application it is sufficient to give the flag `-lcln`.

Since CLN version 1.1, there are two tools to make the creation of software packages that use CLN easier:

- `cln-config` is a shell script that you can use to determine the compiler and linker command line options required to compile and link a program with CLN. Start it with `--help` to learn about its options or consult the manpage that comes with it.
- `AC_PATH_CLN` is for packages configured using GNU automake. The synopsis is:

      AC_PATH_CLN([MIN-VERSION, [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]])

  This macro determines the location of CLN using `cln-config`, which is either found in the user's path, or from the environment variable `CLN_CONFIG`. It tests the installed libraries to make sure that their version is not earlier than MIN-VERSION (a default version will be used if not specified). If the required version was found, sets the `CLN_CPPFLAGS` and the `CLN_LIBS` variables. This macro is in the file ``cln.m4`' which is installed in ``$datadir/aclocal`'. Note that if automake was installed with a different ``--prefix`' than CLN, you will either have to manually move ``cln.m4`' to automake's ``$datadir/aclocal`', or give aclocal the ``-I`' option when running it. Here is a possible example to be included in your package's ``configure.ac`':

      AC_PATH_CLN(1.1.0, [
        LIBS="$LIBS $CLN_LIBS"
        CPPFLAGS="$CPPFLAGS $CLN_CPPFLAGS"
      ], AC_MSG_ERROR([No suitable installed version of CLN could be found.]))

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 11.2 Compatibility to old CLN versions

As of CLN version 1.1 all non-macro identifiers were hidden in namespace `cln` in order to avoid potential name clashes with other C++ libraries. If you have an old application, you will have to manually port it to the new scheme. The following principles will help during the transition:

- All headers are now in a separate subdirectory. Instead of including `cl_`something`.h`, include `cln/`something`.h` now.
- All public identifiers (typenames and functions) have lost their `cl_` prefix. Exceptions are all the typenames of number types, (cl_N, cl_I, cl_MI, ...), rings, symbolic types (cl_string, cl_symbol) and polynomials (cl_UP_type). (This is because their names would not be mnemonic enough once the namespace `cln` is imported. Even in a namespace we favor `cl_N` over `N`.)
- All public functions that had by a `cl_` in their name still carry that `cl_` if it is intrinsic part of a typename (as in `cl_I_to_int ()`).

When developing other libraries, please keep in mind not to import the namespace `cln` in one of your public header files by saying `using namespace cln;`. This would propagate to other applications and can cause name clashes there.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 11.3 Include files

Here is a summary of the include files and their contents.

`<cln/object.h>`
  General definitions, reference counting, garbage collection.
`<cln/number.h>`
  The class cl_number.
`<cln/complex.h>`
  Functions for class cl_N, the complex numbers.
`<cln/real.h>`
  Functions for class cl_R, the real numbers.
`<cln/float.h>`
  Functions for class cl_F, the floats.
`<cln/sfloat.h>`
  Functions for class cl_SF, the short-floats.
`<cln/ffloat.h>`
  Functions for class cl_FF, the single-floats.
`<cln/dfloat.h>`
  Functions for class cl_DF, the double-floats.
`<cln/lfloat.h>`
  Functions for class cl_LF, the long-floats.
`<cln/rational.h>`
  Functions for class cl_RA, the rational numbers.
`<cln/integer.h>`
  Functions for class cl_I, the integers.
`<cln/io.h>`
  Input/Output.
`<cln/complex_io.h>`
  Input/Output for class cl_N, the complex numbers.
`<cln/real_io.h>`
  Input/Output for class cl_R, the real numbers.
`<cln/float_io.h>`
  Input/Output for class cl_F, the floats.
`<cln/sfloat_io.h>`
  Input/Output for class cl_SF, the short-floats.
`<cln/ffloat_io.h>`
  Input/Output for class cl_FF, the single-floats.
`<cln/dfloat_io.h>`
  Input/Output for class cl_DF, the double-floats.
`<cln/lfloat_io.h>`
  Input/Output for class cl_LF, the long-floats.
`<cln/rational_io.h>`
  Input/Output for class cl_RA, the rational numbers.
`<cln/integer_io.h>`
  Input/Output for class cl_I, the integers.
`<cln/input.h>`
  Flags for customizing input operations.
`<cln/output.h>`
  Flags for customizing output operations.
`<cln/malloc.h>`
  `malloc_hook`, `free_hook`.
`<cln/abort.h>`
  `cl_abort`.
`<cln/condition.h>`
  Conditions/exceptions.
`<cln/string.h>`
  Strings.
`<cln/symbol.h>`
  Symbols.
`<cln/proplist.h>`
  Property lists.
`<cln/ring.h>`
  General rings.
`<cln/null_ring.h>`
  The null ring.
`<cln/complex_ring.h>`
  The ring of complex numbers.
`<cln/real_ring.h>`
  The ring of real numbers.
`<cln/rational_ring.h>`
  The ring of rational numbers.
`<cln/integer_ring.h>`
  The ring of integers.
`<cln/numtheory.h>`
  Number threory functions.
`<cln/modinteger.h>`
  Modular integers.
`<cln/V.h>`
  Vectors.
`<cln/GV.h>`
  General vectors.
`<cln/GV_number.h>`
  General vectors over cl_number.
`<cln/GV_complex.h>`
  General vectors over cl_N.
`<cln/GV_real.h>`
  General vectors over cl_R.
`<cln/GV_rational.h>`
  General vectors over cl_RA.
`<cln/GV_integer.h>`
  General vectors over cl_I.
`<cln/GV_modinteger.h>`
  General vectors of modular integers.
`<cln/SV.h>`
  Simple vectors.
`<cln/SV_number.h>`
  Simple vectors over cl_number.
`<cln/SV_complex.h>`
  Simple vectors over cl_N.
`<cln/SV_real.h>`
  Simple vectors over cl_R.
`<cln/SV_rational.h>`
  Simple vectors over cl_RA.
`<cln/SV_integer.h>`
  Simple vectors over cl_I.
`<cln/SV_ringelt.h>`
  Simple vectors of general ring elements.
`<cln/univpoly.h>`
  Univariate polynomials.
`<cln/univpoly_integer.h>`
  Univariate polynomials over the integers.
`<cln/univpoly_rational.h>`
  Univariate polynomials over the rational numbers.
`<cln/univpoly_real.h>`
  Univariate polynomials over the real numbers.
`<cln/univpoly_complex.h>`
  Univariate polynomials over the complex numbers.
`<cln/univpoly_modint.h>`
  Univariate polynomials over modular integer rings.
`<cln/timing.h>`
  Timing facilities.
`<cln/cln.h>`
  Includes all of the above.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 11.4 An Example

A function which computes the nth Fibonacci number can be written as follows.

    #include <cln/integer.h>
    #include <cln/real.h>
    using namespace cln;

    // 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.
            float_format_t prec = 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 );
    }

Let's explain what is going on in detail.

The include file `<cln/integer.h>` is necessary because the type `cl_I` is used in the function, and the include file `<cln/real.h>` is needed for the type `cl_R` and the floating point number functions. The order of the include files does not matter. In order not to write out `cln::`foo in this simple example we can safely import the whole namespace `cln`.

Then comes the function declaration. The argument is an `int`, the result an integer. The return type is defined as ``const cl_I`', not simply ``cl_I`', because that allows the compiler to detect typos like ``fibonacci(n) = 100`'. It would be possible to declare the return type as `const cl_R` (real number) or even `const cl_N` (complex number). We use the most specialized possible return type because functions which call ``fibonacci`' 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.

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.

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.

The type `cl_R` for sqrt5 and, in the following line, phi is the only possible choice. You cannot write `cl_F` because the C++ compiler can only infer that `cl_float(5,prec)` is a real number. You cannot write `cl_N` because a ``round1`' does not exist for general complex numbers.

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.

The file `fibonacci.cc` in the subdirectory `examples` contains this implementation together with an even faster algorithm.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 11.5 Debugging support

When debugging a CLN application with GNU `gdb`, two facilities are available from the library:

- The library does type checks, range checks, consistency checks at many places. When one of these fails, the function `cl_abort()` is called. Its default implementation is to perform an `exit(1)`, so you won't have a core dump. But for debugging, it is best to set a breakpoint at this function:

      (gdb) break cl_abort

  When this breakpoint is hit, look at the stack's backtrace:

      (gdb) where

- The debugger's normal `print` command doesn't know about CLN's types and therefore prints mostly useless hexadecimal addresses. CLN offers a function `cl_print`, callable from the debugger, for printing number objects. In order to get this function, you have to define the macro ``CL_DEBUG`' and then include all the header files for which you want `cl_print` debugging support. For example:

      #define CL_DEBUG
      #include <cln/string.h>

  Now, if you have in your program a variable `cl_string s`, and inspect it under `gdb`, the output may look like this:

      (gdb) print s
      $7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
        word = 134568800}}, }
      (gdb) call cl_print(s)
      (cl_string) ""
      $8 = 134568800

  Note that the output of `cl_print` 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 `debug_print()` on all CLN types. The same macro ``CL_DEBUG`' is needed for this member function to be implemented. Under `gdb`, you call it like this:

      (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) ""

  Unfortunately, this feature does not seem to work under all circumstances.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Richard B. Kreckel on May, 7 2006 using texi2html