Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 617 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Math::BigInt::Lib.3perl b/upstream/debian-unstable/man3/Math::BigInt::Lib.3perl
new file mode 100644
index 00000000..a8f7cd8d
--- /dev/null
+++ b/upstream/debian-unstable/man3/Math::BigInt::Lib.3perl
@@ -0,0 +1,617 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Math::BigInt::Lib 3perl"
+.TH Math::BigInt::Lib 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Math::BigInt::Lib \- virtual parent class for Math::BigInt libraries
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    # In the backend library for Math::BigInt et al.
+\&
+\&    package Math::BigInt::MyBackend;
+\&
+\&    use Math::BigInt::Lib;
+\&    our @ISA = qw< Math::BigInt::Lib >;
+\&
+\&    sub _new { ... }
+\&    sub _str { ... }
+\&    sub _add { ... }
+\&    str _sub { ... }
+\&    ...
+\&
+\&    # In your main program.
+\&
+\&    use Math::BigInt lib => \*(AqMyBackend\*(Aq;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module provides support for big integer calculations. It is not intended
+to be used directly, but rather as a parent class for backend libraries used by
+Math::BigInt, Math::BigFloat, Math::BigRat, and related modules.
+.PP
+Other backend libraries include Math::BigInt::Calc, Math::BigInt::FastCalc,
+Math::BigInt::GMP, and Math::BigInt::Pari.
+.PP
+In order to allow for multiple big integer libraries, Math::BigInt was
+rewritten to use a plug-in library for core math routines. Any module which
+conforms to the API can be used by Math::BigInt by using this in your program:
+.PP
+.Vb 1
+\&        use Math::BigInt lib => \*(Aqlibname\*(Aq;
+.Ve
+.PP
+\&'libname' is either the long name, like 'Math::BigInt::Pari', or only the short
+version, like 'Pari'.
+.SS "General Notes"
+.IX Subsection "General Notes"
+A library only needs to deal with unsigned big integers. Testing of input
+parameter validity is done by the caller, so there is no need to worry about
+underflow (e.g., in \f(CW_sub()\fR and \f(CW_dec()\fR) or about division by zero (e.g.,
+in \f(CW_div()\fR and \f(CW_mod()\fR)) or similar cases.
+.PP
+Some libraries use methods that don't modify their argument, and some libraries
+don't even use objects, but rather unblessed references. Because of this,
+liberary methods are always called as class methods, not instance methods:
+.PP
+.Vb 3
+\&    $x = Class \-> method($x, $y);     # like this
+\&    $x = $x \-> method($y);            # not like this ...
+\&    $x \-> method($y);                 # ... or like this
+.Ve
+.PP
+And with boolean methods
+.PP
+.Vb 2
+\&    $bool = Class \-> method($x, $y);  # like this
+\&    $bool = $x \-> method($y);         # not like this
+.Ve
+.PP
+Return values are always objects, strings, Perl scalars, or true/false for
+comparison routines.
+.PP
+\fIAPI version\fR
+.IX Subsection "API version"
+.IP CLASS\->\fBapi_version()\fR 4
+.IX Item "CLASS->api_version()"
+This method is no longer used and can be omitted. Methods that are not
+implemented by a subclass will be inherited from this class.
+.PP
+\fIConstructors\fR
+.IX Subsection "Constructors"
+.PP
+The following methods are mandatory: \fB_new()\fR, \fB_str()\fR, \fB_add()\fR, and \fB_sub()\fR.
+However, computations will be very slow without \fB_mul()\fR and \fB_div()\fR.
+.IP CLASS\->_new(STR) 4
+.IX Item "CLASS->_new(STR)"
+Convert a string representing an unsigned decimal number to an object
+representing the same number. The input is normalized, i.e., it matches
+\&\f(CW\*(C`^(0|[1\-9]\ed*)$\*(C'\fR.
+.IP CLASS\->\fB_zero()\fR 4
+.IX Item "CLASS->_zero()"
+Return an object representing the number zero.
+.IP CLASS\->\fB_one()\fR 4
+.IX Item "CLASS->_one()"
+Return an object representing the number one.
+.IP CLASS\->\fB_two()\fR 4
+.IX Item "CLASS->_two()"
+Return an object representing the number two.
+.IP CLASS\->\fB_ten()\fR 4
+.IX Item "CLASS->_ten()"
+Return an object representing the number ten.
+.IP CLASS\->_from_bin(STR) 4
+.IX Item "CLASS->_from_bin(STR)"
+Return an object given a string representing a binary number. The input has a
+\&'0b' prefix and matches the regular expression \f(CW\*(C`^0[bB](0|1[01]*)$\*(C'\fR.
+.IP CLASS\->_from_oct(STR) 4
+.IX Item "CLASS->_from_oct(STR)"
+Return an object given a string representing an octal number. The input has a
+\&'0' prefix and matches the regular expression \f(CW\*(C`^0[1\-7]*$\*(C'\fR.
+.IP CLASS\->_from_hex(STR) 4
+.IX Item "CLASS->_from_hex(STR)"
+Return an object given a string representing a hexadecimal number. The input
+has a '0x' prefix and matches the regular expression
+\&\f(CW\*(C`^0x(0|[1\-9a\-fA\-F][\eda\-fA\-F]*)$\*(C'\fR.
+.IP CLASS\->_from_bytes(STR) 4
+.IX Item "CLASS->_from_bytes(STR)"
+Returns an object given a byte string representing the number. The byte string
+is in big endian byte order, so the two-byte input string "\ex01\ex00" should
+give an output value representing the number 256.
+.IP "CLASS\->_from_base(STR, BASE, COLLSEQ)" 4
+.IX Item "CLASS->_from_base(STR, BASE, COLLSEQ)"
+Returns an object given a string STR, a base BASE, and a collation sequence
+COLLSEQ. Each character in STR represents a numerical value identical to the
+character's position in COLLSEQ. All characters in STR must be present in
+COLLSEQ.
+.Sp
+If BASE is less than or equal to 94, and a collation sequence is not specified,
+the following default collation sequence is used. It contains of all the 94
+printable ASCII characters except space/blank:
+.Sp
+.Vb 7
+\&    0123456789                  # ASCII  48 to  57
+\&    ABCDEFGHIJKLMNOPQRSTUVWXYZ  # ASCII  65 to  90
+\&    abcdefghijklmnopqrstuvwxyz  # ASCII  97 to 122
+\&    !"#$%&\*(Aq()*+,\-./             # ASCII  33 to  47
+\&    :;<=>?@                     # ASCII  58 to  64
+\&    [\e]^_\`                      # ASCII  91 to  96
+\&    {|}~                        # ASCII 123 to 126
+.Ve
+.Sp
+If the default collation sequence is used, and the BASE is less than or equal
+to 36, the letter case in STR is ignored.
+.Sp
+For instance, with base 3 and collation sequence "\-/|", the character "\-"
+represents 0, "/" represents 1, and "|" represents 2. So if STR is "/|\-", the
+output is 1 * 3**2 + 2 * 3**1 + 0 * 3**0 = 15.
+.Sp
+The following examples show standard binary, octal, decimal, and hexadecimal
+conversion. All examples return 250.
+.Sp
+.Vb 4
+\&    $x = $class \-> _from_base("11111010", 2)
+\&    $x = $class \-> _from_base("372", 8)
+\&    $x = $class \-> _from_base("250", 10)
+\&    $x = $class \-> _from_base("FA", 16)
+.Ve
+.Sp
+Some more examples, all returning 250:
+.Sp
+.Vb 6
+\&    $x = $class \-> _from_base("100021", 3)
+\&    $x = $class \-> _from_base("3322", 4)
+\&    $x = $class \-> _from_base("2000", 5)
+\&    $x = $class \-> _from_base("caaa", 5, "abcde")
+\&    $x = $class \-> _from_base("42", 62)
+\&    $x = $class \-> _from_base("2!", 94)
+.Ve
+.IP "CLASS\->_from_base_num(ARRAY, BASE)" 4
+.IX Item "CLASS->_from_base_num(ARRAY, BASE)"
+Returns an object given an array of values and a base. This method is
+equivalent to \f(CW_from_base()\fR, but works on numbers in an array rather than
+characters in a string. Unlike \f(CW_from_base()\fR, all input values may be
+arbitrarily large.
+.Sp
+.Vb 2
+\&    $x = $class \-> _from_base_num([1, 1, 0, 1], 2)    # $x is 13
+\&    $x = $class \-> _from_base_num([3, 125, 39], 128)  # $x is 65191
+.Ve
+.PP
+\fIMathematical functions\fR
+.IX Subsection "Mathematical functions"
+.IP "CLASS\->_add(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_add(OBJ1, OBJ2)"
+Addition. Returns the result of adding OBJ2 to OBJ1.
+.IP "CLASS\->_mul(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_mul(OBJ1, OBJ2)"
+Multiplication. Returns the result of multiplying OBJ2 and OBJ1.
+.IP "CLASS\->_div(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_div(OBJ1, OBJ2)"
+Division. In scalar context, returns the quotient after dividing OBJ1 by OBJ2
+and truncating the result to an integer. In list context, return the quotient
+and the remainder.
+.IP "CLASS\->_sub(OBJ1, OBJ2, FLAG)" 4
+.IX Item "CLASS->_sub(OBJ1, OBJ2, FLAG)"
+.PD 0
+.IP "CLASS\->_sub(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_sub(OBJ1, OBJ2)"
+.PD
+Subtraction. Returns the result of subtracting OBJ2 by OBJ1. If \f(CW\*(C`flag\*(C'\fR is false
+or omitted, OBJ1 might be modified. If \f(CW\*(C`flag\*(C'\fR is true, OBJ2 might be modified.
+.IP "CLASS\->_sadd(OBJ1, SIGN1, OBJ2, SIGN2)" 4
+.IX Item "CLASS->_sadd(OBJ1, SIGN1, OBJ2, SIGN2)"
+Signed addition. Returns the result of adding OBJ2 with sign SIGN2 to OBJ1 with
+sign SIGN1.
+.Sp
+.Vb 1
+\&    ($obj3, $sign3) = $class \-> _sadd($obj1, $sign1, $obj2, $sign2);
+.Ve
+.IP "CLASS\->_ssub(OBJ1, SIGN1, OBJ2, SIGN2)" 4
+.IX Item "CLASS->_ssub(OBJ1, SIGN1, OBJ2, SIGN2)"
+Signed subtraction. Returns the result of subtracting OBJ2 with sign SIGN2 to
+OBJ1 with sign SIGN1.
+.Sp
+.Vb 1
+\&    ($obj3, $sign3) = $class \-> _sadd($obj1, $sign1, $obj2, $sign2);
+.Ve
+.IP CLASS\->_dec(OBJ) 4
+.IX Item "CLASS->_dec(OBJ)"
+Returns the result after decrementing OBJ by one.
+.IP CLASS\->_inc(OBJ) 4
+.IX Item "CLASS->_inc(OBJ)"
+Returns the result after incrementing OBJ by one.
+.IP "CLASS\->_mod(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_mod(OBJ1, OBJ2)"
+Returns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1 by OBJ2.
+.IP CLASS\->_sqrt(OBJ) 4
+.IX Item "CLASS->_sqrt(OBJ)"
+Returns the square root of OBJ, truncated to an integer.
+.IP "CLASS\->_root(OBJ, N)" 4
+.IX Item "CLASS->_root(OBJ, N)"
+Returns the Nth root of OBJ, truncated to an integer.
+.IP CLASS\->_fac(OBJ) 4
+.IX Item "CLASS->_fac(OBJ)"
+Returns the factorial of OBJ, i.e., the product of all positive integers up to
+and including OBJ.
+.IP CLASS\->_dfac(OBJ) 4
+.IX Item "CLASS->_dfac(OBJ)"
+Returns the double factorial of OBJ. If OBJ is an even integer, returns the
+product of all positive, even integers up to and including OBJ, i.e.,
+2*4*6*...*OBJ. If OBJ is an odd integer, returns the product of all positive,
+odd integers, i.e., 1*3*5*...*OBJ.
+.IP "CLASS\->_pow(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_pow(OBJ1, OBJ2)"
+Returns OBJ1 raised to the power of OBJ2. By convention, 0**0 = 1.
+.IP "CLASS\->_modinv(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_modinv(OBJ1, OBJ2)"
+Returns the modular multiplicative inverse, i.e., return OBJ3 so that
+.Sp
+.Vb 1
+\&    (OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2
+.Ve
+.Sp
+The result is returned as two arguments. If the modular multiplicative inverse
+does not exist, both arguments are undefined. Otherwise, the arguments are a
+number (object) and its sign ("+" or "\-").
+.Sp
+The output value, with its sign, must either be a positive value in the range
+1,2,...,OBJ2\-1 or the same value subtracted OBJ2. For instance, if the input
+arguments are objects representing the numbers 7 and 5, the method must either
+return an object representing the number 3 and a "+" sign, since (3*7) % 5 = 1
+% 5, or an object representing the number 2 and a "\-" sign, since (\-2*7) % 5 = 1
+% 5.
+.IP "CLASS\->_modpow(OBJ1, OBJ2, OBJ3)" 4
+.IX Item "CLASS->_modpow(OBJ1, OBJ2, OBJ3)"
+Returns the modular exponentiation, i.e., (OBJ1 ** OBJ2) % OBJ3.
+.IP "CLASS\->_rsft(OBJ, N, B)" 4
+.IX Item "CLASS->_rsft(OBJ, N, B)"
+Returns the result after shifting OBJ N digits to thee right in base B. This is
+equivalent to performing integer division by B**N and discarding the remainder,
+except that it might be much faster.
+.Sp
+For instance, if the object \f(CW$obj\fR represents the hexadecimal number 0xabcde,
+then \f(CW\*(C`_rsft($obj, 2, 16)\*(C'\fR returns an object representing the number 0xabc. The
+"remainer", 0xde, is discarded and not returned.
+.IP "CLASS\->_lsft(OBJ, N, B)" 4
+.IX Item "CLASS->_lsft(OBJ, N, B)"
+Returns the result after shifting OBJ N digits to the left in base B. This is
+equivalent to multiplying by B**N, except that it might be much faster.
+.IP "CLASS\->_log_int(OBJ, B)" 4
+.IX Item "CLASS->_log_int(OBJ, B)"
+Returns the logarithm of OBJ to base BASE truncted to an integer. This method
+has two output arguments, the OBJECT and a STATUS. The STATUS is Perl scalar;
+it is 1 if OBJ is the exact result, 0 if the result was truncted to give OBJ,
+and undef if it is unknown whether OBJ is the exact result.
+.IP "CLASS\->_gcd(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_gcd(OBJ1, OBJ2)"
+Returns the greatest common divisor of OBJ1 and OBJ2.
+.IP "CLASS\->_lcm(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_lcm(OBJ1, OBJ2)"
+Return the least common multiple of OBJ1 and OBJ2.
+.IP CLASS\->_fib(OBJ) 4
+.IX Item "CLASS->_fib(OBJ)"
+In scalar context, returns the nth Fibonacci number: \fB_fib\fR\|(0) returns 0, \fB_fib\fR\|(1)
+returns 1, \fB_fib\fR\|(2) returns 1, \fB_fib\fR\|(3) returns 2 etc. In list context, returns
+the Fibonacci numbers from F(0) to F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...
+.IP CLASS\->_lucas(OBJ) 4
+.IX Item "CLASS->_lucas(OBJ)"
+In scalar context, returns the nth Lucas number: \fB_lucas\fR\|(0) returns 2, \fB_lucas\fR\|(1)
+returns 1, \fB_lucas\fR\|(2) returns 3, etc. In list context, returns the Lucas numbers
+from L(0) to L(n): 2, 1, 3, 4, 7, 11, 18, 29,47, 76, ...
+.PP
+\fIBitwise operators\fR
+.IX Subsection "Bitwise operators"
+.IP "CLASS\->_and(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_and(OBJ1, OBJ2)"
+Returns bitwise and.
+.IP "CLASS\->_or(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_or(OBJ1, OBJ2)"
+Returns bitwise or.
+.IP "CLASS\->_xor(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_xor(OBJ1, OBJ2)"
+Returns bitwise exclusive or.
+.IP "CLASS\->_sand(OBJ1, OBJ2, SIGN1, SIGN2)" 4
+.IX Item "CLASS->_sand(OBJ1, OBJ2, SIGN1, SIGN2)"
+Returns bitwise signed and.
+.IP "CLASS\->_sor(OBJ1, OBJ2, SIGN1, SIGN2)" 4
+.IX Item "CLASS->_sor(OBJ1, OBJ2, SIGN1, SIGN2)"
+Returns bitwise signed or.
+.IP "CLASS\->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)" 4
+.IX Item "CLASS->_sxor(OBJ1, OBJ2, SIGN1, SIGN2)"
+Returns bitwise signed exclusive or.
+.PP
+\fIBoolean operators\fR
+.IX Subsection "Boolean operators"
+.IP CLASS\->_is_zero(OBJ) 4
+.IX Item "CLASS->_is_zero(OBJ)"
+Returns a true value if OBJ is zero, and false value otherwise.
+.IP CLASS\->_is_one(OBJ) 4
+.IX Item "CLASS->_is_one(OBJ)"
+Returns a true value if OBJ is one, and false value otherwise.
+.IP CLASS\->_is_two(OBJ) 4
+.IX Item "CLASS->_is_two(OBJ)"
+Returns a true value if OBJ is two, and false value otherwise.
+.IP CLASS\->_is_ten(OBJ) 4
+.IX Item "CLASS->_is_ten(OBJ)"
+Returns a true value if OBJ is ten, and false value otherwise.
+.IP CLASS\->_is_even(OBJ) 4
+.IX Item "CLASS->_is_even(OBJ)"
+Return a true value if OBJ is an even integer, and a false value otherwise.
+.IP CLASS\->_is_odd(OBJ) 4
+.IX Item "CLASS->_is_odd(OBJ)"
+Return a true value if OBJ is an even integer, and a false value otherwise.
+.IP "CLASS\->_acmp(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_acmp(OBJ1, OBJ2)"
+Compare OBJ1 and OBJ2 and return \-1, 0, or 1, if OBJ1 is numerically less than,
+equal to, or larger than OBJ2, respectively.
+.PP
+\fIString conversion\fR
+.IX Subsection "String conversion"
+.IP CLASS\->_str(OBJ) 4
+.IX Item "CLASS->_str(OBJ)"
+Returns a string representing OBJ in decimal notation. The returned string
+should have no leading zeros, i.e., it should match \f(CW\*(C`^(0|[1\-9]\ed*)$\*(C'\fR.
+.IP CLASS\->_to_bin(OBJ) 4
+.IX Item "CLASS->_to_bin(OBJ)"
+Returns the binary string representation of OBJ.
+.IP CLASS\->_to_oct(OBJ) 4
+.IX Item "CLASS->_to_oct(OBJ)"
+Returns the octal string representation of the number.
+.IP CLASS\->_to_hex(OBJ) 4
+.IX Item "CLASS->_to_hex(OBJ)"
+Returns the hexadecimal string representation of the number.
+.IP CLASS\->_to_bytes(OBJ) 4
+.IX Item "CLASS->_to_bytes(OBJ)"
+Returns a byte string representation of OBJ. The byte string is in big endian
+byte order, so if OBJ represents the number 256, the output should be the
+two-byte string "\ex01\ex00".
+.IP "CLASS\->_to_base(OBJ, BASE, COLLSEQ)" 4
+.IX Item "CLASS->_to_base(OBJ, BASE, COLLSEQ)"
+Returns a string representation of OBJ in base BASE with collation sequence
+COLLSEQ.
+.Sp
+.Vb 2
+\&    $val = $class \-> _new("210");
+\&    $str = $class \-> _to_base($val, 10, "xyz")  # $str is "zyx"
+\&
+\&    $val = $class \-> _new("32");
+\&    $str = $class \-> _to_base($val, 2, "\-|")  # $str is "|\-\-\-\-\-"
+.Ve
+.Sp
+See \fB_from_base()\fR for more information.
+.IP "CLASS\->_to_base_num(OBJ, BASE)" 4
+.IX Item "CLASS->_to_base_num(OBJ, BASE)"
+Converts the given number to the given base. This method is equivalent to
+\&\f(CW_to_base()\fR, but returns numbers in an array rather than characters in a
+string. In the output, the first element is the most significant. Unlike
+\&\f(CW_to_base()\fR, all input values may be arbitrarily large.
+.Sp
+.Vb 2
+\&    $x = $class \-> _to_base_num(13, 2)        # $x is [1, 1, 0, 1]
+\&    $x = $class \-> _to_base_num(65191, 128)   # $x is [3, 125, 39]
+.Ve
+.IP CLASS\->_as_bin(OBJ) 4
+.IX Item "CLASS->_as_bin(OBJ)"
+Like \f(CW_to_bin()\fR but with a '0b' prefix.
+.IP CLASS\->_as_oct(OBJ) 4
+.IX Item "CLASS->_as_oct(OBJ)"
+Like \f(CW_to_oct()\fR but with a '0' prefix.
+.IP CLASS\->_as_hex(OBJ) 4
+.IX Item "CLASS->_as_hex(OBJ)"
+Like \f(CW_to_hex()\fR but with a '0x' prefix.
+.IP CLASS\->_as_bytes(OBJ) 4
+.IX Item "CLASS->_as_bytes(OBJ)"
+This is an alias to \f(CW_to_bytes()\fR.
+.PP
+\fINumeric conversion\fR
+.IX Subsection "Numeric conversion"
+.IP CLASS\->_num(OBJ) 4
+.IX Item "CLASS->_num(OBJ)"
+Returns a Perl scalar number representing the number OBJ as close as
+possible. Since Perl scalars have limited precision, the returned value might
+not be exactly the same as OBJ.
+.PP
+\fIMiscellaneous\fR
+.IX Subsection "Miscellaneous"
+.IP CLASS\->_copy(OBJ) 4
+.IX Item "CLASS->_copy(OBJ)"
+Returns a true copy OBJ.
+.IP CLASS\->_len(OBJ) 4
+.IX Item "CLASS->_len(OBJ)"
+Returns the number of the decimal digits in OBJ. The output is a Perl scalar.
+.IP CLASS\->_zeros(OBJ) 4
+.IX Item "CLASS->_zeros(OBJ)"
+Returns the number of trailing decimal zeros. The output is a Perl scalar. The
+number zero has no trailing decimal zeros.
+.IP "CLASS\->_digit(OBJ, N)" 4
+.IX Item "CLASS->_digit(OBJ, N)"
+Returns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar, where zero
+refers to the rightmost (least significant) digit, and negative values count
+from the left (most significant digit). If \f(CW$obj\fR represents the number 123, then
+.Sp
+.Vb 4
+\&    CLASS\->_digit($obj,  0)     # returns 3
+\&    CLASS\->_digit($obj,  1)     # returns 2
+\&    CLASS\->_digit($obj,  2)     # returns 1
+\&    CLASS\->_digit($obj, \-1)     # returns 1
+.Ve
+.IP CLASS\->_digitsum(OBJ) 4
+.IX Item "CLASS->_digitsum(OBJ)"
+Returns the sum of the base 10 digits.
+.IP CLASS\->_check(OBJ) 4
+.IX Item "CLASS->_check(OBJ)"
+Returns true if the object is invalid and false otherwise. Preferably, the true
+value is a string describing the problem with the object. This is a check
+routine to test the internal state of the object for corruption.
+.IP CLASS\->_set(OBJ) 4
+.IX Item "CLASS->_set(OBJ)"
+xxx
+.SS "API version 2"
+.IX Subsection "API version 2"
+The following methods are required for an API version of 2 or greater.
+.PP
+\fIConstructors\fR
+.IX Subsection "Constructors"
+.IP CLASS\->_1ex(N) 4
+.IX Item "CLASS->_1ex(N)"
+Return an object representing the number 10**N where N >= 0 is a Perl
+scalar.
+.PP
+\fIMathematical functions\fR
+.IX Subsection "Mathematical functions"
+.IP "CLASS\->_nok(OBJ1, OBJ2)" 4
+.IX Item "CLASS->_nok(OBJ1, OBJ2)"
+Return the binomial coefficient OBJ1 over OBJ1.
+.PP
+\fIMiscellaneous\fR
+.IX Subsection "Miscellaneous"
+.IP CLASS\->_alen(OBJ) 4
+.IX Item "CLASS->_alen(OBJ)"
+Return the approximate number of decimal digits of the object. The output is a
+Perl scalar.
+.SH "WRAP YOUR OWN"
+.IX Header "WRAP YOUR OWN"
+If you want to port your own favourite C library for big numbers to the
+Math::BigInt interface, you can take any of the already existing modules as a
+rough guideline. You should really wrap up the latest Math::BigInt and
+Math::BigFloat testsuites with your module, and replace in them any of the
+following:
+.PP
+.Vb 1
+\&        use Math::BigInt;
+.Ve
+.PP
+by this:
+.PP
+.Vb 1
+\&        use Math::BigInt lib => \*(Aqyourlib\*(Aq;
+.Ve
+.PP
+This way you ensure that your library really works 100% within Math::BigInt.
+.SH BUGS
+.IX Header "BUGS"
+Please report any bugs or feature requests to
+\&\f(CW\*(C`bug\-math\-bigint at rt.cpan.org\*(C'\fR, or through the web interface at
+<https://rt.cpan.org/Ticket/Create.html?Queue=Math\-BigInt>
+(requires login).
+We will be notified, and then you'll automatically be notified of progress on
+your bug as I make changes.
+.SH SUPPORT
+.IX Header "SUPPORT"
+You can find documentation for this module with the perldoc command.
+.PP
+.Vb 1
+\&    perldoc Math::BigInt::Calc
+.Ve
+.PP
+You can also look for information at:
+.IP \(bu 4
+RT: CPAN's request tracker
+.Sp
+<https://rt.cpan.org/Public/Dist/Display.html?Name=Math\-BigInt>
+.IP \(bu 4
+AnnoCPAN: Annotated CPAN documentation
+.Sp
+<http://annocpan.org/dist/Math\-BigInt>
+.IP \(bu 4
+CPAN Ratings
+.Sp
+<https://cpanratings.perl.org/dist/Math\-BigInt>
+.IP \(bu 4
+MetaCPAN
+.Sp
+<https://metacpan.org/release/Math\-BigInt>
+.IP \(bu 4
+CPAN Testers Matrix
+.Sp
+<http://matrix.cpantesters.org/?dist=Math\-BigInt>
+.IP \(bu 4
+The Bignum mailing list
+.RS 4
+.IP \(bu 4
+Post to mailing list
+.Sp
+\&\f(CW\*(C`bignum at lists.scsys.co.uk\*(C'\fR
+.IP \(bu 4
+View mailing list
+.Sp
+<http://lists.scsys.co.uk/pipermail/bignum/>
+.IP \(bu 4
+Subscribe/Unsubscribe
+.Sp
+<http://lists.scsys.co.uk/cgi\-bin/mailman/listinfo/bignum>
+.RE
+.RS 4
+.RE
+.SH LICENSE
+.IX Header "LICENSE"
+This program is free software; you may redistribute it and/or modify it under
+the same terms as Perl itself.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Peter John Acklam, <pjacklam@gmail.com>
+.PP
+Code and documentation based on the Math::BigInt::Calc module by Tels
+<nospam\-abuse@bloodgate.com>
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP,
+Math::BigInt::FastCalc and Math::BigInt::Pari.