64-bit mingw port: Fix undefined references to cl_I_constructor_from_[U]L.

[cln.git] / doc / cln.texi

diff --git a/doc/cln.texi b/doc/cln.texi
index fcbe9e60de35e91090da6229d1341d2bca83d21f..1d676decf369fd18a72c8a417ce83951678cafdd 100644 (file)
--- a/doc/cln.texi
+++ b/doc/cln.texi
@@ -23,16 +23,21 @@
 @synindex pg my
 @synindex tp my
 
 @synindex pg my
 @synindex tp my
 

+@ifnottex
+@node Top
+@top CLN
+@end ifnottex

 
 @c For `info' only.
 
 @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.
 
 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)  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
 
 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.
 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.
 
 
 @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
 @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
 
 @sp 2
 Published by Bruno Haible, @code{<haible@@clisp.cons.org>} and


@@ -91,17 +98,11 @@ by the authors.
 @end titlepage
 @page
 
 @end titlepage
 @page
 

-
+@iftex

 @c Table of contents
 @c Table of contents

-@c @contents
-
-
-@node Top
-@top CLN
+@contents
+@end iftex

 
 

-@c @menu
-@c * Introduction::                Introduction
-@c @end menu

 
 @menu
 * Introduction::                
 
 @menu
 * Introduction::                


@@ -118,6 +119,7 @@ by the authors.
 * Customizing::                 
 * Index::
 
 * Customizing::                 
 * Index::
 

+@detailmenu

  --- The Detailed Node Listing ---
 
 Installation
  --- The Detailed Node Listing ---
 
 Installation


@@ -158,7 +160,7 @@ Functions on numbers
 * Functions on floating-point numbers::  
 * Conversion functions::        
 * Random number generators::    
 * Functions on floating-point numbers::  
 * Conversion functions::        
 * Random number generators::    

-* Obfuscating operators::       
+* Modifying operators::       

 
 Constructing numbers
 
 
 Constructing numbers
 


@@ -230,6 +232,7 @@ Customizing
 * Customizing I/O::             
 * Customizing the memory allocator::  
 
 * Customizing I/O::             
 * Customizing the memory allocator::  
 

+@end detailmenu

 @end menu
 
 @node Introduction
 @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
 
 @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,
 
 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.
 
 
 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}
 @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 CPPFLAGS
 Flags to be given to the C/C++ preprocessor.

+
+@item LDFLAGS
+Flags to be given to the linker.

 @end table
 
 Examples:
 @end table
 
 Examples:


@@ -480,12 +484,12 @@ Examples:
 $ CC="gcc" CFLAGS="-O" CXX="g++" CXXFLAGS="-O" ./configure
 @end example
 @example
 $ 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
   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
 @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
 
 @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
 
 @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
 
 @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
 
 
 @node Installing the library


@@ -932,7 +942,7 @@ objects of type @code{cl_I}, it should @code{#include <cln/integer.h>}.
 * Functions on floating-point numbers::  
 * Conversion functions::        
 * Random number generators::    
 * Functions on floating-point numbers::  
 * Conversion functions::        
 * Random number generators::    

-* Obfuscating operators::       
+* Modifying operators::       

 @end menu
 
 @node Constructing numbers
 @end menu
 
 @node Constructing numbers


@@ -1158,7 +1168,7 @@ Returns the complex conjugate of @code{x}.
 
 We have the relations
 
 
 We have the relations
 

-@itemize @asis
+@itemize @w{}

 @item
 @code{x = complex(realpart(x), imagpart(x))}
 @item
 @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:
 
 
 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
 @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:
 
 
 The following relations hold:
 

-@itemize @asis
+@itemize @w{}

 @item
 @code{ldb (n, b) = mask_field(n, b) >> b.position},
 @item
 @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
 @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)}!
 @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
 
 
 If @code{x} is any float, one has
 

-@itemize @asis
+@itemize @w{}

 @item
 @code{cl_float(rational(x),x) = x}
 @item
 @item
 @code{cl_float(rational(x),x) = x}
 @item


@@ -2502,22 +2512,13 @@ if @code{n} is a float.
 @end table
 
 
 @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{>>=}
 @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}:
 
 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
 
 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.
 
 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
 
 @var{expmarker} @var{expsign} @{@var{digit}@}+.
 The exponent marker is
 

-@itemize @asis
+@itemize @w{}

 @item
 @samp{s} for short-floats,
 @item
 @item
 @samp{s} for short-floats,
 @item


@@ -2646,7 +2647,7 @@ function @samp{float_format}.
 
 @item Complex numbers
 External representation:
 
 @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
 @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
 
 @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)
 
 @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 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}.
 @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}.
 @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 ()}
 
 @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.
 
 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 ()}
 @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
 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