@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{<haible@@clisp.cons.org>} and
Richard B. Kreckel, @code{<kreckel@@ginac.de>}.
-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) Bruno Haible 1995 - 2019.
+Copyright (C) Richard B. Kreckel 2000 - 2019.
+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
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.
@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{<haible@@clisp.cons.org>} and
@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::
* Customizing::
* Index::
+@detailmenu
--- The Detailed Node Listing ---
Installation
* Functions on floating-point numbers::
* Conversion functions::
* Random number generators::
-* Obfuscating operators::
+* Modifying operators::
Constructing numbers
* Customizing I/O::
* Customizing the memory allocator::
+@end detailmenu
@end menu
@node Introduction
@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,
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}
@item CPPFLAGS
Flags to be given to the C/C++ preprocessor.
+
+@item LDFLAGS
+Flags to be given to the linker.
@end table
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
@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
* Functions on floating-point numbers::
* Conversion functions::
* Random number generators::
-* Obfuscating operators::
+* Modifying operators::
@end menu
@node Constructing numbers
We have the relations
-@itemize @asis
+@itemize @w{}
@item
@code{x = complex(realpart(x), imagpart(x))}
@item
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
The following relations hold:
-@itemize @asis
+@itemize @w{}
@item
@code{ldb (n, b) = mask_field(n, b) >> b.position},
@item
@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)}!
If @code{x} is any float, one has
-@itemize @asis
+@itemize @w{}
@item
@code{cl_float(rational(x),x) = x}
@item
@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}:
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.
@var{expmarker} @var{expsign} @{@var{digit}@}+.
The exponent marker is
-@itemize @asis
+@itemize @w{}
@item
@samp{s} for short-floats,
@item
@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
@node Input functions
@section 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 (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{<cln/@var{type}_io.h>}, 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{<cln/@var{type}_io.h>},
-are the following:
+Including @code{<cln/io.h>} defines flexible input functions:
@table @code
@item cl_N read_complex (std::istream& stream, const cl_read_flags& flags)
@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}.
@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 ()}
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
git://www.ginac.de / cln.git / blobdiff