X-Git-Url: https://ginac.de/CLN/cln.git//cln.git?a=blobdiff_plain;f=doc%2Fcln.texi;h=1d676decf369fd18a72c8a417ce83951678cafdd;hb=2cbb7a1fb6bf9b68901949bbfaa37ab304dc80cd;hp=fcbe9e60de35e91090da6229d1341d2bca83d21f;hpb=77df36c03800d46af986cc832f6f280d01434cce;p=cln.git diff --git a/doc/cln.texi b/doc/cln.texi index fcbe9e6..1d676de 100644 --- a/doc/cln.texi +++ b/doc/cln.texi @@ -23,16 +23,21 @@ @synindex pg my @synindex tp my +@ifnottex +@node Top +@top CLN +@end ifnottex @c For `info' only. -@ifinfo -This file documents @sc{cln}, a Class Library for Numbers. +@ifnottex +This manual documents @sc{cln}, a Class Library for Numbers. Published by Bruno Haible, @code{} and Richard B. Kreckel, @code{}. Copyright (C) Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008. -Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008. +Copyright (C) Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2017. +Copyright (C) Alexei Sheplyakov 2008, 2010. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -54,7 +59,7 @@ Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the author. -@end ifinfo +@end ifnottex @c For TeX only. @@ -68,7 +73,9 @@ by the author. @vskip 0pt plus 1filll Copyright @copyright{} Bruno Haible 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008. @sp 0 -Copyright @copyright{} Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008. +Copyright @copyright{} Richard B. Kreckel 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014. +@sp 0 +Copyright @copyright{} Alexei Sheplyakov 2008, 2010. @sp 2 Published by Bruno Haible, @code{} and @@ -91,17 +98,11 @@ by the authors. @end titlepage @page - +@iftex @c Table of contents -@c @contents - - -@node Top -@top CLN +@contents +@end iftex -@c @menu -@c * Introduction:: Introduction -@c @end menu @menu * Introduction:: @@ -118,6 +119,7 @@ by the authors. * Customizing:: * Index:: +@detailmenu --- The Detailed Node Listing --- Installation @@ -158,7 +160,7 @@ Functions on numbers * Functions on floating-point numbers:: * Conversion functions:: * Random number generators:: -* Obfuscating operators:: +* Modifying operators:: Constructing numbers @@ -230,6 +232,7 @@ Customizing * Customizing I/O:: * Customizing the memory allocator:: +@end detailmenu @end menu @node Introduction @@ -392,8 +395,8 @@ This section describes how to install the CLN package on your system. @node C++ compiler @subsection C++ compiler -To build CLN, you need a C++ compiler. -Actually, you need GNU @code{g++ 3.0.0} or newer. +To build CLN, you need a C++11 compiler. +GNU @code{g++ 4.8.1} or newer is recommended. The following C++ features are used: classes, member functions, overloading of functions and operators, @@ -414,8 +417,6 @@ on all platforms when a non-GNU assembler is being used. To build CLN, you also need to have GNU @code{make} installed. -Only GNU @code{make} 3.77 is unusable for CLN; other versions work fine. - @node Sed utility @subsection Sed utility @cindex @code{sed} @@ -472,6 +473,9 @@ Flags to be given to the C++ compiler when compiling programs (not when linking) @item CPPFLAGS Flags to be given to the C/C++ preprocessor. + +@item LDFLAGS +Flags to be given to the linker. @end table Examples: @@ -480,12 +484,12 @@ Examples: $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure @end example @example -$ CC="gcc -V 3.2.3" CFLAGS="-O2 -finline-limit=1000" \ - CXX="g++ -V 3.2.3" CXXFLAGS="-O2 -finline-limit=1000" \ +$ CC=gcc CFLAGS="-O2 -finline-limit=1000" \ + CXX=g++ CXXFLAGS="-O2 -finline-limit=1000" \ CPPFLAGS="-DNO_ASM" ./configure @end example @example -$ CC="gcc-4.2" CFLAGS="-O2" CXX="g++-4.2" CXXFLAGS="-O2" ./configure +$ CC="gcc-9" CFLAGS="-O2" CXX="g++-9" CXXFLAGS="-O2" ./configure @end example Note that for these environment variables to take effect, you have to set @@ -539,25 +543,31 @@ libraries so runtime-critical applications should be linked statically. @subsection Using the GNU MP Library @cindex GMP -Starting with version 1.1, CLN may be configured to make use of a -preinstalled @code{gmp} library for some low-level routines. Please -make sure that you have at least @code{gmp} version 3.0 installed -since earlier versions are unsupported and likely not to work. This -feature is known to be quite a boost for CLN's performance. +CLN may be configured to make use of a preinstalled @code{gmp} library +for some low-level routines. Please make sure that you have at least +@code{gmp} version 3.0 installed since earlier versions are unsupported +and likely not to work. Using @code{gmp} is known to be quite a boost +for CLN's performance. -By default, CLN will autodetect @code{gmp} and use it. But if you have -installed the @code{gmp} library and its header file in some place where -your compiler cannot find it by default, you must help @code{configure} -by setting @code{CPPFLAGS} and @code{LDFLAGS}. Here is an example: +By default, CLN will autodetect @code{gmp} and use it. If you do not +want CLN to make use of a preinstalled @code{gmp} library, then you can +explicitly specify so by calling @code{configure} with the option +@samp{--without-gmp}. + +If you have installed the @code{gmp} library and its header files in +some place where the compiler cannot find it by default, you must help +@code{configure} and specify the prefix that was used when @code{gmp} +was configured. Here is an example: @example -$ CFLAGS="-O2" CXXFLAGS="-O2" CPPFLAGS="-I/opt/gmp/include" \ - LDFLAGS="-L/opt/gmp/lib" ./configure --with-gmp +$ ./configure --with-gmp=/opt/gmp-4.2.2 @end example -If you do not want CLN to make use of a preinstalled @code{gmp} -library, then you can explicitly specify so by calling -@code{configure} with the option @samp{--without-gmp}. +This assumes that the @code{gmp} header files have been installed in +@file{/opt/gmp-4.2.2/include/} and the library in +@file{/opt/gmp-4.2.2/lib/}. More uncommon GMP installations can be +handled by setting CPPFLAGS and LDFLAGS appropriately prior to running +@code{configure}. @node Installing the library @@ -932,7 +942,7 @@ objects of type @code{cl_I}, it should @code{#include }. * Functions on floating-point numbers:: * Conversion functions:: * Random number generators:: -* Obfuscating operators:: +* Modifying operators:: @end menu @node Constructing numbers @@ -1158,7 +1168,7 @@ Returns the complex conjugate of @code{x}. We have the relations -@itemize @asis +@itemize @w{} @item @code{x = complex(realpart(x), imagpart(x))} @item @@ -1273,7 +1283,7 @@ down exactly as often as it rounds up. The functions are related like this: -@itemize @asis +@itemize @w{} @item @code{ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1} for rational numbers @code{m/n} (@code{m}, @code{n} integers, @code{n}>0), and @@ -2082,7 +2092,7 @@ come from @code{newbyte} and the other bits come from @code{n}. The following relations hold: -@itemize @asis +@itemize @w{} @item @code{ldb (n, b) = mask_field(n, b) >> b.position}, @item @@ -2221,7 +2231,7 @@ doublefactorial @code{n}!! = @code{1*3*@dots{}*n} or @code{n} and @code{k} must be small integers >= 0. This function returns the binomial coefficient @tex -${n \choose k} = {n! \over n! (n-k)!}$ +${n \choose k} = {n! \over k! (n-k)!}$ @end tex @ifinfo (@code{n} choose @code{k}) = @code{n}! / @code{k}! @code{(n-k)}! @@ -2445,7 +2455,7 @@ If @code{x} is already an exact number, this function returns @code{x}. If @code{x} is any float, one has -@itemize @asis +@itemize @w{} @item @code{cl_float(rational(x),x) = x} @item @@ -2502,22 +2512,13 @@ if @code{n} is a float. @end table -@node Obfuscating operators -@section Obfuscating operators +@node Modifying operators +@section Modifying operators @cindex modifying operators The modifying C/C++ operators @code{+=}, @code{-=}, @code{*=}, @code{/=}, @code{&=}, @code{|=}, @code{^=}, @code{<<=}, @code{>>=} -are not available by default because their -use tends to make programs unreadable. It is trivial to get away without -them. However, if you feel that you absolutely need these operators -to get happy, then add -@example -#define WANT_OBFUSCATING_OPERATORS -@end example -@cindex @code{WANT_OBFUSCATING_OPERATORS} -to the beginning of your source files, before the inclusion of any CLN -include files. This flag will enable the following operators: +are all available. For the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF}: @@ -2570,7 +2571,7 @@ The prefix operator @code{--x}. The postfix operator @code{x--}. @end table -Note that by using these obfuscating operators, you wouldn't gain efficiency: +Note that by using these modifying operators, you don't gain efficiency: In CLN @samp{x += y;} is exactly the same as @samp{x = x+y;}, not more efficient. @@ -2628,7 +2629,7 @@ one digit in the non-exponent part. The exponent has the syntax @var{expmarker} @var{expsign} @{@var{digit}@}+. The exponent marker is -@itemize @asis +@itemize @w{} @item @samp{s} for short-floats, @item @@ -2646,7 +2647,7 @@ function @samp{float_format}. @item Complex numbers External representation: -@itemize @asis +@itemize @w{} @item In algebraic notation: @code{@var{realpart}+@var{imagpart}i}. Of course, if @var{imagpart} is negative, its printed representation begins with @@ -2663,30 +2664,7 @@ In Common Lisp notation: @code{#C(@var{realpart} @var{imagpart})}. @node Input functions @section Input functions -Including @code{} defines a number of simple input functions -that read from @code{std::istream&}: - -@table @code -@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 (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 - -Each of the classes @code{cl_N}, @code{cl_R}, @code{cl_RA}, @code{cl_I}, -@code{cl_F}, @code{cl_SF}, @code{cl_FF}, @code{cl_DF}, @code{cl_LF} -defines, in @code{}, the following input function: - -@table @code -@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 - -The most flexible input functions, defined in @code{}, -are the following: +Including @code{} defines flexible input functions: @table @code @item cl_N read_complex (std::istream& stream, const cl_read_flags& flags) @@ -3153,8 +3131,8 @@ The following functions are available on strings: @item operator = Assignment from @code{cl_string} and @code{const char *}. -@item s.length() -@cindex @code{length ()} +@item s.size() +@cindex @code{size()} @itemx strlen(s) @cindex @code{strlen ()} Returns the length of the string @code{s}. @@ -3162,7 +3140,7 @@ Returns the length of the string @code{s}. @item s[i] @cindex @code{operator [] ()} Returns the @code{i}th character of the string @code{s}. -@code{i} must be in the range @code{0 <= i < s.length()}. +@code{i} must be in the range @code{0 <= i < s.size()}. @item bool equal (const cl_string& s1, const cl_string& s2) @cindex @code{equal ()} @@ -3307,17 +3285,17 @@ There is a cache table of rings, indexed by @code{R} and @code{varname}. This ensures that two calls of this function with the same arguments will return the same polynomial ring. -@itemx cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R) +@item cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R) @cindex @code{find_univpoly_ring ()} -@itemx cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname) -@itemx cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R) -@itemx cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname) -@itemx cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R) -@itemx cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname) -@itemx cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R) -@itemx cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname) -@itemx cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R) -@itemx cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname) +@item cl_univpoly_complex_ring find_univpoly_ring (const cl_complex_ring& R, const cl_symbol& varname) +@item cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R) +@item cl_univpoly_real_ring find_univpoly_ring (const cl_real_ring& R, const cl_symbol& varname) +@item cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R) +@item cl_univpoly_rational_ring find_univpoly_ring (const cl_rational_ring& R, const cl_symbol& varname) +@item cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R) +@item cl_univpoly_integer_ring find_univpoly_ring (const cl_integer_ring& R, const cl_symbol& varname) +@item cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R) +@item cl_univpoly_modint_ring find_univpoly_ring (const cl_modint_ring& R, const cl_symbol& varname) These functions are equivalent to the general @code{find_univpoly_ring}, only the return type is more specific, according to the base ring's type. @end table