X-Git-Url: https://ginac.de/CLN/cln.git//cln.git?a=blobdiff_plain;ds=sidebyside;f=doc%2Fcln.tex;h=bc6a7fe4c3e09fdc8ba1955b94ce0094497057fe;hb=f3b29e52ea5a7b013f8294065920365e5d17d18f;hp=73bb19c277d01a2fa3aed2041091c1cfe4114bab;hpb=1277b4cb299f10bfa85489723018f191dfb1e1ae;p=cln.git

diff --git a/doc/cln.tex b/doc/cln.tex
index 73bb19c..bc6a7fe 100644
--- a/doc/cln.tex
+++ b/doc/cln.tex
@@ -12,6 +12,9 @@
 @end iftex
 @c %**end of header
 
+@direntry
+* CLN: (cln).                       Class Library for Numbers (C++).
+@end direntry
 
 @c My own index.
 @defindex my
@@ -553,7 +556,8 @@ Rational numbers are always normalized to the form
 are coprime integers and the denominator is positive. If the resulting
 denominator is @code{1}, the rational number is converted to an integer.
 
-Small integers (typically in the range @code{-2^30}@dots{}@code{2^30-1},
+@cindex immediate numbers
+Small integers (typically in the range @code{-2^29}@dots{}@code{2^29-1},
 for 32-bit machines) are especially efficient, because they consume no heap
 allocation. Otherwise the distinction between these immediate integers
 (called ``fixnums'') and heap allocated integers (called ``bignums'')
@@ -810,7 +814,7 @@ through the @code{cl_float} conversion function, see
 @code{e} to 40 decimal places, first construct 1.0 to 40 decimal places
 and then apply the exponential function:
 @example
-   cl_float_format_t precision = cl_float_format(40);
+   float_format_t precision = float_format(40);
    cl_F e = exp(cl_float(1,precision));
 @end example
 
@@ -1395,7 +1399,7 @@ Exponentiation: Returns @code{x^y = exp(y*log(x))}.
 The constant e = exp(1) = 2.71828@dots{} is returned by the following functions:
 
 @table @code
-@item cl_F exp1 (cl_float_format_t f)
+@item cl_F exp1 (float_format_t f)
 @cindex @code{exp1 ()}
 Returns e as a float of format @code{f}.
 
@@ -1511,7 +1515,7 @@ Proof: arctan(z) = artanh(iz)/i, we know the range of the artanh function.
 Archimedes' constant pi = 3.14@dots{} is returned by the following functions:
 
 @table @code
-@item cl_F pi (cl_float_format_t f)
+@item cl_F pi (float_format_t f)
 @cindex @code{pi ()}
 Returns pi as a float of format @code{f}.
 
@@ -1670,7 +1674,7 @@ Proof: Write z = x+iy. Examine
 Euler's constant C = 0.577@dots{} is returned by the following functions:
 
 @table @code
-@item cl_F eulerconst (cl_float_format_t f)
+@item cl_F eulerconst (float_format_t f)
 @cindex @code{eulerconst ()}
 Returns Euler's constant as a float of format @code{f}.
 
@@ -1685,7 +1689,7 @@ Catalan's constant G = 0.915@dots{} is returned by the following functions:
 @cindex Catalan's constant
 
 @table @code
-@item cl_F catalanconst (cl_float_format_t f)
+@item cl_F catalanconst (float_format_t f)
 @cindex @code{catalanconst ()}
 Returns Catalan's constant as a float of format @code{f}.
 
@@ -1704,7 +1708,7 @@ Riemann's zeta function at an integral point @code{s>1} is returned by the
 following functions:
 
 @table @code
-@item cl_F zeta (int s, cl_float_format_t f)
+@item cl_F zeta (int s, float_format_t f)
 @cindex @code{zeta ()}
 Returns Riemann's zeta function at @code{s} as a float of format @code{f}.
 
@@ -2112,19 +2116,19 @@ zero, it is treated as positive. Same for @code{y}.
 
 @subsection Conversion to floating-point numbers
 
-The type @code{cl_float_format_t} describes a floating-point format.
-@cindex @code{cl_float_format_t}
+The type @code{float_format_t} describes a floating-point format.
+@cindex @code{float_format_t}
 
 @table @code
-@item cl_float_format_t cl_float_format (uintL n)
-@cindex @code{cl_float_format ()}
+@item float_format_t float_format (uintL n)
+@cindex @code{float_format ()}
 Returns the smallest float format which guarantees at least @code{n}
 decimal digits in the mantissa (after the decimal point).
 
-@item cl_float_format_t cl_float_format (const cl_F& x)
+@item float_format_t float_format (const cl_F& x)
 Returns the floating point format of @code{x}.
 
-@item cl_float_format_t default_float_format
+@item float_format_t default_float_format
 @cindex @code{default_float_format}
 Global variable: the default float format used when converting rational numbers
 to floats.
@@ -2136,7 +2140,7 @@ To convert a real number to a float, each of the types
 defines the following operations:
 
 @table @code
-@item cl_F cl_float (const @var{type}&x, cl_float_format_t f)
+@item cl_F cl_float (const @var{type}&x, float_format_t f)
 @cindex @code{cl_float ()}
 Returns @code{x} as a float of format @code{f}.
 @item cl_F cl_float (const @var{type}&x, const cl_F& y)
@@ -2151,29 +2155,29 @@ Of course, converting a number to a float can lose precision.
 Every floating-point format has some characteristic numbers:
 
 @table @code
-@item cl_F most_positive_float (cl_float_format_t f)
+@item cl_F most_positive_float (float_format_t f)
 @cindex @code{most_positive_float ()}
 Returns the largest (most positive) floating point number in float format @code{f}.
 
-@item cl_F most_negative_float (cl_float_format_t f)
+@item cl_F most_negative_float (float_format_t f)
 @cindex @code{most_negative_float ()}
 Returns the smallest (most negative) floating point number in float format @code{f}.
 
-@item cl_F least_positive_float (cl_float_format_t f)
+@item cl_F least_positive_float (float_format_t f)
 @cindex @code{least_positive_float ()}
 Returns the least positive floating point number (i.e. > 0 but closest to 0)
 in float format @code{f}.
 
-@item cl_F least_negative_float (cl_float_format_t f)
+@item cl_F least_negative_float (float_format_t f)
 @cindex @code{least_negative_float ()}
 Returns the least negative floating point number (i.e. < 0 but closest to 0)
 in float format @code{f}.
 
-@item cl_F float_epsilon (cl_float_format_t f)
+@item cl_F float_epsilon (float_format_t f)
 @cindex @code{float_epsilon ()}
 Returns the smallest floating point number e > 0 such that @code{1+e != 1}.
 
-@item cl_F float_negative_epsilon (cl_float_format_t f)
+@item cl_F float_negative_epsilon (float_format_t f)
 @cindex @code{float_negative_epsilon ()}
 Returns the smallest floating point number e > 0 such that @code{1-e != 1}.
 @end table
@@ -2394,7 +2398,7 @@ The exponent marker is
 or @samp{e}, which denotes a default float format. The precision specifying
 suffix has the syntax _@var{prec} where @var{prec} denotes the number of
 valid mantissa digits (in decimal, excluding leading zeroes), cf. also
-function @samp{cl_float_format}.
+function @samp{float_format}.
 
 @item Complex numbers
 External representation:
@@ -2414,25 +2418,15 @@ In Common Lisp notation: @code{#C(@var{realpart} @var{imagpart})}.
 
 @section Input functions
 
-Including @code{<cln/io.h>} defines a type @code{cl_istream}, which is
-the type of the first argument to all input functions. @code{cl_istream}
-is the same as @code{std::istream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_istream stdin}
-@end itemize
-contains the standard input stream.
-
-These are the simple input functions:
+Including @code{<cln/io.h>} defines a number of simple input functions
+that read from @code{std::istream&}:
 
 @table @code
-@item int freadchar (cl_istream stream)
+@item int freadchar (std::istream& stream)
 Reads a character from @code{stream}. Returns @code{cl_EOF} (not a @samp{char}!)
 if the end of stream was encountered or an error occurred.
 
-@item int funreadchar (cl_istream stream, int c)
+@item int funreadchar (std::istream& stream, int c)
 Puts back @code{c} onto @code{stream}. @code{c} must be the result of the
 last @code{freadchar} operation on @code{stream}.
 @end table
@@ -2442,7 +2436,7 @@ Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
 defines, in @code{<cln/@var{type}_io.h>}, the following input function:
 
 @table @code
-@item cl_istream operator>> (cl_istream stream, @var{type}& result)
+@item std::istream& operator>> (std::istream& stream, @var{type}& result)
 Reads a number from @code{stream} and stores it in the @code{result}.
 @end table
 
@@ -2450,11 +2444,11 @@ The most flexible input functions, defined in @code{<cln/@var{type}_io.h>},
 are the following:
 
 @table @code
-@item cl_N read_complex (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_R read_real (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_F read_float (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_RA read_rational (cl_istream stream, const cl_read_flags& flags)
-@itemx cl_I read_integer (cl_istream stream, const cl_read_flags& flags)
+@item cl_N read_complex (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_R read_real (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_F read_float (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_RA read_rational (std::istream& stream, const cl_read_flags& flags)
+@itemx cl_I read_integer (std::istream& stream, const cl_read_flags& flags)
 Reads a number from @code{stream}. The @code{flags} are parameters which
 affect the input syntax. Whitespace before the number is silently skipped.
 
@@ -2505,10 +2499,10 @@ accept all of these extensions.
 @item unsigned int rational_base
 The base in which rational numbers are read.
 
-@item cl_float_format_t float_flags.default_float_format
+@item float_format_t float_flags.default_float_format
 The float format used when reading floats with exponent marker @samp{e}.
 
-@item cl_float_format_t float_flags.default_lfloat_format
+@item float_format_t float_flags.default_lfloat_format
 The float format used when reading floats with exponent marker @samp{l}.
 
 @item cl_boolean float_flags.mantissa_dependent_float_format
@@ -2520,46 +2514,29 @@ precision corresponding to their number of significant digits.
 
 @section Output functions
 
-Including @code{<cln/io.h>} defines a type @code{cl_ostream}, which is
-the type of the first argument to all output functions. @code{cl_ostream}
-is the same as @code{std::ostream&}.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream stdout}
-@end itemize
-contains the standard output stream.
-
-The variable
-@itemize @asis
-@item
-@code{cl_ostream stderr}
-@end itemize
-contains the standard error output stream.
-
-These are the simple output functions:
+Including @code{<cln/io.h>} defines a number of simple output functions
+that write to @code{std::ostream&}:
 
 @table @code
-@item void fprintchar (cl_ostream stream, char c)
+@item void fprintchar (std::ostream& stream, char c)
 Prints the character @code{x} literally on the @code{stream}.
 
-@item void fprint (cl_ostream stream, const char * string)
+@item void fprint (std::ostream& stream, const char * string)
 Prints the @code{string} literally on the @code{stream}.
 
-@item void fprintdecimal (cl_ostream stream, int x)
-@itemx void fprintdecimal (cl_ostream stream, const cl_I& x)
+@item void fprintdecimal (std::ostream& stream, int x)
+@itemx void fprintdecimal (std::ostream& stream, const cl_I& x)
 Prints the integer @code{x} in decimal on the @code{stream}.
 
-@item void fprintbinary (cl_ostream stream, const cl_I& x)
+@item void fprintbinary (std::ostream& stream, const cl_I& x)
 Prints the integer @code{x} in binary (base 2, without prefix)
 on the @code{stream}.
 
-@item void fprintoctal (cl_ostream stream, const cl_I& x)
+@item void fprintoctal (std::ostream& stream, const cl_I& x)
 Prints the integer @code{x} in octal (base 8, without prefix)
 on the @code{stream}.
 
-@item void fprinthexadecimal (cl_ostream stream, const cl_I& x)
+@item void fprinthexadecimal (std::ostream& stream, const cl_I& x)
 Prints the integer @code{x} in hexadecimal (base 16, without prefix)
 on the @code{stream}.
 @end table
@@ -2569,8 +2546,8 @@ Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I},
 defines, in @code{<cln/@var{type}_io.h>}, the following output functions:
 
 @table @code
-@item void fprint (cl_ostream stream, const @var{type}& x)
-@itemx cl_ostream operator<< (cl_ostream stream, const @var{type}& x)
+@item void fprint (std::ostream& stream, const @var{type}& x)
+@itemx std::ostream& operator<< (std::ostream& stream, const @var{type}& x)
 Prints the number @code{x} on the @code{stream}. The output may depend
 on the global printer settings in the variable @code{default_print_flags}.
 The @code{ostream} flags and settings (flags, width and locale) are
@@ -2580,15 +2557,15 @@ ignored.
 The most flexible output function, defined in @code{<cln/@var{type}_io.h>},
 are the following:
 @example
-void print_complex  (cl_ostream stream, const cl_print_flags& flags,
+void print_complex  (std::ostream& stream, const cl_print_flags& flags,
                      const cl_N& z);
-void print_real     (cl_ostream stream, const cl_print_flags& flags,
+void print_real     (std::ostream& stream, const cl_print_flags& flags,
                      const cl_R& z);
-void print_float    (cl_ostream stream, const cl_print_flags& flags,
+void print_float    (std::ostream& stream, const cl_print_flags& flags,
                      const cl_F& z);
-void print_rational (cl_ostream stream, const cl_print_flags& flags,
+void print_rational (std::ostream& stream, const cl_print_flags& flags,
                      const cl_RA& z);
-void print_integer  (cl_ostream stream, const cl_print_flags& flags,
+void print_integer  (std::ostream& stream, const cl_print_flags& flags,
                      const cl_I& z);
 @end example
 Prints the number @code{x} on the @code{stream}. The @code{flags} are
@@ -2609,9 +2586,9 @@ prefixes, trailing dot). Default is false.
 If this flag is true, type specific exponent markers have precedence over 'E'.
 Default is false.
 
-@item cl_float_format_t default_float_format
+@item float_format_t default_float_format
 Floating point numbers of this format will be printed using the 'E' exponent
-marker. Default is @code{cl_float_format_ffloat}.
+marker. Default is @code{float_format_ffloat}.
 
 @item cl_boolean complex_readably
 If this flag is true, complex numbers will be printed using the Common Lisp
@@ -2647,7 +2624,7 @@ These compare two rings for equality.
 Given a ring @code{R}, the following members can be used.
 
 @table @code
-@item void R->fprint (cl_ostream stream, const cl_ring_element& x)
+@item void R->fprint (std::ostream& stream, const cl_ring_element& x)
 @cindex @code{fprint ()}
 @itemx cl_boolean R->equal (const cl_ring_element& x, const cl_ring_element& y)
 @cindex @code{equal ()}
@@ -2869,9 +2846,9 @@ The following output functions are defined (see also the chapter on
 input/output).
 
 @table @code
-@item void fprint (cl_ostream stream, const cl_MI& x)
+@item void fprint (std::ostream& stream, const cl_MI& x)
 @cindex @code{fprint ()}
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_MI& x)
+@itemx std::ostream& operator<< (std::ostream& stream, const cl_MI& x)
 @cindex @code{operator << ()}
 Prints the modular integer @code{x} on the @code{stream}. The output may depend
 on the global printer settings in the variable @code{default_print_flags}.
@@ -3191,9 +3168,9 @@ The following output functions are defined (see also the chapter on
 input/output).
 
 @table @code
-@item void fprint (cl_ostream stream, const cl_UP& x)
+@item void fprint (std::ostream& stream, const cl_UP& x)
 @cindex @code{fprint ()}
-@itemx cl_ostream operator<< (cl_ostream stream, const cl_UP& x)
+@itemx std::ostream& operator<< (std::ostream& stream, const cl_UP& x)
 @cindex @code{operator << ()}
 Prints the univariate polynomial @code{x} on the @code{stream}. The output may
 depend on the global printer settings in the variable
@@ -3285,6 +3262,7 @@ Garbage collection: A reference counting mechanism makes sure that any
 number object's storage is freed immediately when the last reference to the
 object is gone.
 @item
+@cindex immediate numbers
 Small integers are represented as immediate values instead of pointers
 to heap allocated storage. This means that integers @code{> -2^29},
 @code{< 2^29} don't consume heap memory, unless they were explicitly allocated
@@ -3386,6 +3364,42 @@ need special flags for compiling. The library has been installed to a
 public directory as well (normally @code{/usr/local/lib}), hence when
 linking a CLN application it is sufficient to give the flag @code{-lcln}.
 
+Since CLN version 1.1, there are two tools to make the creation of
+software packages that use CLN easier:
+@itemize @bullet
+@item
+@cindex @code{cln-config}
+@code{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 @code{--help} to learn about its options
+or consult the manpage that comes with it.
+@item
+@cindex @code{AC_PATH_CLN}
+@code{AC_PATH_CLN} is for packages configured using GNU automake.
+The synopsis is:
+@example
+@code{AC_PATH_CLN([@var{MIN-VERSION}, [@var{ACTION-IF-FOUND} [, @var{ACTION-IF-NOT-FOUND}]]])}
+@end example
+This macro determines the location of CLN using @code{cln-config}, which
+is either found in the user's path, or from the environment variable
+@code{CLN_CONFIG}.  It tests the installed libraries to make sure that
+their version is not earlier than @var{MIN-VERSION} (a default version
+will be used if not specified). If the required version was found, sets
+the @env{CLN_CPPFLAGS} and the @env{CLN_LIBS} variables. This
+macro is in the file @file{cln.m4} which is installed in
+@file{$datadir/aclocal}. Note that if automake was installed with a
+different @samp{--prefix} than CLN, you will either have to manually
+move @file{cln.m4} to automake's @file{$datadir/aclocal}, or give
+aclocal the @samp{-I} option when running it. Here is a possible example
+to be included in your package's @file{configure.in}:
+@example
+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.]))
+@end example
+@end itemize
+
 
 @section Compatibility to old CLN versions
 @cindex namespace
@@ -3564,7 +3578,7 @@ using namespace cln;
 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));
+        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 );
@@ -3576,8 +3590,9 @@ Let's explain what is going on in detail.
 The include file @code{<cln/integer.h>} is necessary because the type
 @code{cl_I} is used in the function, and the include file @code{<cln/real.h>}
 is needed for the type @code{cl_R} and the floating point number functions.
-The order of the include files does not matter.  In order not to write out
-@code{cln::}@var{foo} we can safely import the whole namespace @code{cln}.
+The order of the include files does not matter.  In order not to write
+out @code{cln::}@var{foo} in this simple example we can safely import
+the whole namespace @code{cln}.
 
 Then comes the function declaration. The argument is an @code{int}, the
 result an integer. The return type is defined as @samp{const cl_I}, not