{
    "mode": "perldoc",
    "parameter": "Math::BigInt::Lib",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Math%3A%3ABigInt%3A%3ALib/json",
    "generated": "2026-06-12T06:50:35Z",
    "synopsis": "# In the backend library for Math::BigInt et al.\npackage Math::BigInt::MyBackend;\nuse Math::BigInt::Lib;\nour @ISA = qw< Math::BigInt::Lib >;\nsub new { ... }\nsub str { ... }\nsub add { ... }\nstr sub { ... }\n...\n# In your main program.\nuse Math::BigInt lib => 'MyBackend';",
    "sections": {
        "NAME": {
            "content": "Math::BigInt::Lib - virtual parent class for Math::BigInt libraries\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "# In the backend library for Math::BigInt et al.\n\npackage Math::BigInt::MyBackend;\n\nuse Math::BigInt::Lib;\nour @ISA = qw< Math::BigInt::Lib >;\n\nsub new { ... }\nsub str { ... }\nsub add { ... }\nstr sub { ... }\n...\n\n# In your main program.\n\nuse Math::BigInt lib => 'MyBackend';\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module provides support for big integer calculations. It is not intended to be used\ndirectly, but rather as a parent class for backend libraries used by Math::BigInt,\nMath::BigFloat, Math::BigRat, and related modules.\n\nOther backend libraries include Math::BigInt::Calc, Math::BigInt::FastCalc, Math::BigInt::GMP,\nand Math::BigInt::Pari.\n\nIn order to allow for multiple big integer libraries, Math::BigInt was rewritten to use a\nplug-in library for core math routines. Any module which conforms to the API can be used by\nMath::BigInt by using this in your program:\n\nuse Math::BigInt lib => 'libname';\n\n'libname' is either the long name, like 'Math::BigInt::Pari', or only the short version, like\n'Pari'.\n",
            "subsections": [
                {
                    "name": "General Notes",
                    "content": "A library only needs to deal with unsigned big integers. Testing of input parameter validity is\ndone by the caller, so there is no need to worry about underflow (e.g., in \"sub()\" and\n\"dec()\") or about division by zero (e.g., in \"div()\" and \"mod()\")) or similar cases.\n\nSome libraries use methods that don't modify their argument, and some libraries don't even use\nobjects, but rather unblessed references. Because of this, liberary methods are always called as\nclass methods, not instance methods:\n\n$x = Class -> method($x, $y);     # like this\n$x = $x -> method($y);            # not like this ...\n$x -> method($y);                 # ... or like this\n\nAnd with boolean methods\n\n$bool = Class -> method($x, $y);  # like this\n$bool = $x -> method($y);         # not like this\n\nReturn values are always objects, strings, Perl scalars, or true/false for comparison routines.\n\nAPI version\nCLASS->apiversion()\nThis method is no longer used and can be omitted. Methods that are not implemented by a\nsubclass will be inherited from this class.\n\nConstructors\nThe following methods are mandatory: new(), str(), add(), and sub(). However, computations\nwill be very slow without mul() and div().\n\nCLASS->new(STR)\nConvert a string representing an unsigned decimal number to an object representing the same\nnumber. The input is normalized, i.e., it matches \"^(0|[1-9]\\d*)$\".\n\nCLASS->zero()\nReturn an object representing the number zero.\n\nCLASS->one()\nReturn an object representing the number one.\n\nCLASS->two()\nReturn an object representing the number two.\n\nCLASS->ten()\nReturn an object representing the number ten.\n\nCLASS->frombin(STR)\nReturn an object given a string representing a binary number. The input has a '0b' prefix\nand matches the regular expression \"^0[bB](0|1[01]*)$\".\n\nCLASS->fromoct(STR)\nReturn an object given a string representing an octal number. The input has a '0' prefix and\nmatches the regular expression \"^0[1-7]*$\".\n\nCLASS->fromhex(STR)\nReturn an object given a string representing a hexadecimal number. The input has a '0x'\nprefix and matches the regular expression \"^0x(0|[1-9a-fA-F][\\da-fA-F]*)$\".\n\nCLASS->frombytes(STR)\nReturns an object given a byte string representing the number. The byte string is in big\nendian byte order, so the two-byte input string \"\\x01\\x00\" should give an output value\nrepresenting the number 256.\n\nCLASS->frombase(STR, BASE, COLLSEQ)\nReturns an object given a string STR, a base BASE, and a collation sequence COLLSEQ. Each\ncharacter in STR represents a numerical value identical to the character's position in\nCOLLSEQ. All characters in STR must be present in COLLSEQ.\n\nIf BASE is less than or equal to 94, and a collation sequence is not specified, the\nfollowing default collation sequence is used. It contains of all the 94 printable ASCII\ncharacters except space/blank:\n\n0123456789                  # ASCII  48 to  57\nABCDEFGHIJKLMNOPQRSTUVWXYZ  # ASCII  65 to  90\nabcdefghijklmnopqrstuvwxyz  # ASCII  97 to 122\n!\"#$%&'()*+,-./             # ASCII  33 to  47\n:;<=>?@                     # ASCII  58 to  64\n[\\]^`                      # ASCII  91 to  96\n{|}~                        # ASCII 123 to 126\n\nIf the default collation sequence is used, and the BASE is less than or equal to 36, the\nletter case in STR is ignored.\n\nFor instance, with base 3 and collation sequence \"-/|\", the character \"-\" represents 0, \"/\"\nrepresents 1, and \"|\" represents 2. So if STR is \"/|-\", the output is 1 * 32 + 2 * 31 +\n0 * 30 = 15.\n\nThe following examples show standard binary, octal, decimal, and hexadecimal conversion. All\nexamples return 250.\n\n$x = $class -> frombase(\"11111010\", 2)\n$x = $class -> frombase(\"372\", 8)\n$x = $class -> frombase(\"250\", 10)\n$x = $class -> frombase(\"FA\", 16)\n\nSome more examples, all returning 250:\n\n$x = $class -> frombase(\"100021\", 3)\n$x = $class -> frombase(\"3322\", 4)\n$x = $class -> frombase(\"2000\", 5)\n$x = $class -> frombase(\"caaa\", 5, \"abcde\")\n$x = $class -> frombase(\"42\", 62)\n$x = $class -> frombase(\"2!\", 94)\n\nCLASS->frombasenum(ARRAY, BASE)\nReturns an object given an array of values and a base. This method is equivalent to\n\"frombase()\", but works on numbers in an array rather than characters in a string. Unlike\n\"frombase()\", all input values may be arbitrarily large.\n\n$x = $class -> frombasenum([1, 1, 0, 1], 2)    # $x is 13\n$x = $class -> frombasenum([3, 125, 39], 128)  # $x is 65191\n\nMathematical functions\nCLASS->add(OBJ1, OBJ2)\nAddition. Returns the result of adding OBJ2 to OBJ1.\n\nCLASS->mul(OBJ1, OBJ2)\nMultiplication. Returns the result of multiplying OBJ2 and OBJ1.\n\nCLASS->div(OBJ1, OBJ2)\nDivision. In scalar context, returns the quotient after dividing OBJ1 by OBJ2 and truncating\nthe result to an integer. In list context, return the quotient and the remainder.\n\nCLASS->sub(OBJ1, OBJ2, FLAG)\nCLASS->sub(OBJ1, OBJ2)\nSubtraction. Returns the result of subtracting OBJ2 by OBJ1. If \"flag\" is false or omitted,\nOBJ1 might be modified. If \"flag\" is true, OBJ2 might be modified.\n\nCLASS->sadd(OBJ1, SIGN1, OBJ2, SIGN2)\nSigned addition. Returns the result of adding OBJ2 with sign SIGN2 to OBJ1 with sign SIGN1.\n\n($obj3, $sign3) = $class -> sadd($obj1, $sign1, $obj2, $sign2);\n\nCLASS->ssub(OBJ1, SIGN1, OBJ2, SIGN2)\nSigned subtraction. Returns the result of subtracting OBJ2 with sign SIGN2 to OBJ1 with sign\nSIGN1.\n\n($obj3, $sign3) = $class -> sadd($obj1, $sign1, $obj2, $sign2);\n\nCLASS->dec(OBJ)\nReturns the result after decrementing OBJ by one.\n\nCLASS->inc(OBJ)\nReturns the result after incrementing OBJ by one.\n\nCLASS->mod(OBJ1, OBJ2)\nReturns OBJ1 modulo OBJ2, i.e., the remainder after dividing OBJ1 by OBJ2.\n\nCLASS->sqrt(OBJ)\nReturns the square root of OBJ, truncated to an integer.\n\nCLASS->root(OBJ, N)\nReturns the Nth root of OBJ, truncated to an integer.\n\nCLASS->fac(OBJ)\nReturns the factorial of OBJ, i.e., the product of all positive integers up to and including\nOBJ.\n\nCLASS->dfac(OBJ)\nReturns the double factorial of OBJ. If OBJ is an even integer, returns the product of all\npositive, even integers up to and including OBJ, i.e., 2*4*6*...*OBJ. If OBJ is an odd\ninteger, returns the product of all positive, odd integers, i.e., 1*3*5*...*OBJ.\n\nCLASS->pow(OBJ1, OBJ2)\nReturns OBJ1 raised to the power of OBJ2. By convention, 00 = 1.\n\nCLASS->modinv(OBJ1, OBJ2)\nReturns the modular multiplicative inverse, i.e., return OBJ3 so that\n\n(OBJ3 * OBJ1) % OBJ2 = 1 % OBJ2\n\nThe result is returned as two arguments. If the modular multiplicative inverse does not\nexist, both arguments are undefined. Otherwise, the arguments are a number (object) and its\nsign (\"+\" or \"-\").\n\nThe output value, with its sign, must either be a positive value in the range 1,2,...,OBJ2-1\nor the same value subtracted OBJ2. For instance, if the input arguments are objects\nrepresenting the numbers 7 and 5, the method must either return an object representing the\nnumber 3 and a \"+\" sign, since (3*7) % 5 = 1 % 5, or an object representing the number 2 and\na \"-\" sign, since (-2*7) % 5 = 1 % 5.\n\nCLASS->modpow(OBJ1, OBJ2, OBJ3)\nReturns the modular exponentiation, i.e., (OBJ1  OBJ2) % OBJ3.\n\nCLASS->rsft(OBJ, N, B)\nReturns the result after shifting OBJ N digits to thee right in base B. This is equivalent\nto performing integer division by BN and discarding the remainder, except that it might be\nmuch faster.\n\nFor instance, if the object $obj represents the hexadecimal number 0xabcde, then\n\"rsft($obj, 2, 16)\" returns an object representing the number 0xabc. The \"remainer\", 0xde,\nis discarded and not returned.\n\nCLASS->lsft(OBJ, N, B)\nReturns the result after shifting OBJ N digits to the left in base B. This is equivalent to\nmultiplying by BN, except that it might be much faster.\n\nCLASS->logint(OBJ, B)\nReturns the logarithm of OBJ to base BASE truncted to an integer. This method has two output\narguments, the OBJECT and a STATUS. The STATUS is Perl scalar; it is 1 if OBJ is the exact\nresult, 0 if the result was truncted to give OBJ, and undef if it is unknown whether OBJ is\nthe exact result.\n\nCLASS->gcd(OBJ1, OBJ2)\nReturns the greatest common divisor of OBJ1 and OBJ2.\n\nCLASS->lcm(OBJ1, OBJ2)\nReturn the least common multiple of OBJ1 and OBJ2.\n\nCLASS->fib(OBJ)\nIn scalar context, returns the nth Fibonacci number: fib(0) returns 0, fib(1) returns 1,\nfib(2) returns 1, fib(3) returns 2 etc. In list context, returns the Fibonacci numbers\nfrom F(0) to F(n): 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...\n\nCLASS->lucas(OBJ)\nIn scalar context, returns the nth Lucas number: lucas(0) returns 2, lucas(1) returns 1,\nlucas(2) returns 3, etc. In list context, returns the Lucas numbers from L(0) to L(n): 2,\n1, 3, 4, 7, 11, 18, 29,47, 76, ...\n\nBitwise operators\nCLASS->and(OBJ1, OBJ2)\nReturns bitwise and.\n\nCLASS->or(OBJ1, OBJ2)\nReturns bitwise or.\n\nCLASS->xor(OBJ1, OBJ2)\nReturns bitwise exclusive or.\n\nCLASS->sand(OBJ1, OBJ2, SIGN1, SIGN2)\nReturns bitwise signed and.\n\nCLASS->sor(OBJ1, OBJ2, SIGN1, SIGN2)\nReturns bitwise signed or.\n\nCLASS->sxor(OBJ1, OBJ2, SIGN1, SIGN2)\nReturns bitwise signed exclusive or.\n\nBoolean operators\nCLASS->iszero(OBJ)\nReturns a true value if OBJ is zero, and false value otherwise.\n\nCLASS->isone(OBJ)\nReturns a true value if OBJ is one, and false value otherwise.\n\nCLASS->istwo(OBJ)\nReturns a true value if OBJ is two, and false value otherwise.\n\nCLASS->isten(OBJ)\nReturns a true value if OBJ is ten, and false value otherwise.\n\nCLASS->iseven(OBJ)\nReturn a true value if OBJ is an even integer, and a false value otherwise.\n\nCLASS->isodd(OBJ)\nReturn a true value if OBJ is an even integer, and a false value otherwise.\n\nCLASS->acmp(OBJ1, OBJ2)\nCompare OBJ1 and OBJ2 and return -1, 0, or 1, if OBJ1 is numerically less than, equal to, or\nlarger than OBJ2, respectively.\n\nString conversion\nCLASS->str(OBJ)\nReturns a string representing OBJ in decimal notation. The returned string should have no\nleading zeros, i.e., it should match \"^(0|[1-9]\\d*)$\".\n\nCLASS->tobin(OBJ)\nReturns the binary string representation of OBJ.\n\nCLASS->tooct(OBJ)\nReturns the octal string representation of the number.\n\nCLASS->tohex(OBJ)\nReturns the hexadecimal string representation of the number.\n\nCLASS->tobytes(OBJ)\nReturns a byte string representation of OBJ. The byte string is in big endian byte order, so\nif OBJ represents the number 256, the output should be the two-byte string \"\\x01\\x00\".\n\nCLASS->tobase(OBJ, BASE, COLLSEQ)\nReturns a string representation of OBJ in base BASE with collation sequence COLLSEQ.\n\n$val = $class -> new(\"210\");\n$str = $class -> tobase($val, 10, \"xyz\")  # $str is \"zyx\"\n\n$val = $class -> new(\"32\");\n$str = $class -> tobase($val, 2, \"-|\")  # $str is \"|-----\"\n\nSee frombase() for more information.\n\nCLASS->tobasenum(OBJ, BASE)\nConverts the given number to the given base. This method is equivalent to \"tobase()\", but\nreturns numbers in an array rather than characters in a string. In the output, the first\nelement is the most significant. Unlike \"tobase()\", all input values may be arbitrarily\nlarge.\n\n$x = $class -> tobasenum(13, 2)        # $x is [1, 1, 0, 1]\n$x = $class -> tobasenum(65191, 128)   # $x is [3, 125, 39]\n\nCLASS->asbin(OBJ)\nLike \"tobin()\" but with a '0b' prefix.\n\nCLASS->asoct(OBJ)\nLike \"tooct()\" but with a '0' prefix.\n\nCLASS->ashex(OBJ)\nLike \"tohex()\" but with a '0x' prefix.\n\nCLASS->asbytes(OBJ)\nThis is an alias to \"tobytes()\".\n\nNumeric conversion\nCLASS->num(OBJ)\nReturns a Perl scalar number representing the number OBJ as close as possible. Since Perl\nscalars have limited precision, the returned value might not be exactly the same as OBJ.\n\nMiscellaneous\nCLASS->copy(OBJ)\nReturns a true copy OBJ.\n\nCLASS->len(OBJ)\nReturns the number of the decimal digits in OBJ. The output is a Perl scalar.\n\nCLASS->zeros(OBJ)\nReturns the number of trailing decimal zeros. The output is a Perl scalar. The number zero\nhas no trailing decimal zeros.\n\nCLASS->digit(OBJ, N)\nReturns the Nth digit in OBJ as a Perl scalar. N is a Perl scalar, where zero refers to the\nrightmost (least significant) digit, and negative values count from the left (most\nsignificant digit). If $obj represents the number 123, then\n\nCLASS->digit($obj,  0)     # returns 3\nCLASS->digit($obj,  1)     # returns 2\nCLASS->digit($obj,  2)     # returns 1\nCLASS->digit($obj, -1)     # returns 1\n\nCLASS->digitsum(OBJ)\nReturns the sum of the base 10 digits.\n\nCLASS->check(OBJ)\nReturns true if the object is invalid and false otherwise. Preferably, the true value is a\nstring describing the problem with the object. This is a check routine to test the internal\nstate of the object for corruption.\n\nCLASS->set(OBJ)\nxxx\n\nAPI version 2\nThe following methods are required for an API version of 2 or greater.\n\nConstructors\nCLASS->1ex(N)\nReturn an object representing the number 10N where N >= 0 is a Perl scalar.\n\nMathematical functions\nCLASS->nok(OBJ1, OBJ2)\nReturn the binomial coefficient OBJ1 over OBJ1.\n\nMiscellaneous\nCLASS->alen(OBJ)\nReturn the approximate number of decimal digits of the object. The output is a Perl scalar.\n"
                }
            ]
        },
        "WRAP YOUR OWN": {
            "content": "If you want to port your own favourite C library for big numbers to the Math::BigInt interface,\nyou can take any of the already existing modules as a rough guideline. You should really wrap up\nthe latest Math::BigInt and Math::BigFloat testsuites with your module, and replace in them any\nof the following:\n\nuse Math::BigInt;\n\nby this:\n\nuse Math::BigInt lib => 'yourlib';\n\nThis way you ensure that your library really works 100% within Math::BigInt.\n",
            "subsections": []
        },
        "BUGS": {
            "content": "Please report any bugs or feature requests to \"bug-math-bigint at rt.cpan.org\", or through the\nweb interface at <https://rt.cpan.org/Ticket/Create.html?Queue=Math-BigInt> (requires login). We\nwill be notified, and then you'll automatically be notified of progress on your bug as I make\nchanges.\n",
            "subsections": []
        },
        "SUPPORT": {
            "content": "You can find documentation for this module with the perldoc command.\n\nperldoc Math::BigInt::Calc\n\nYou can also look for information at:\n\n*   RT: CPAN's request tracker\n\n<https://rt.cpan.org/Public/Dist/Display.html?Name=Math-BigInt>\n\n*   AnnoCPAN: Annotated CPAN documentation\n\n<http://annocpan.org/dist/Math-BigInt>\n\n*   CPAN Ratings\n\n<https://cpanratings.perl.org/dist/Math-BigInt>\n\n*   MetaCPAN\n\n<https://metacpan.org/release/Math-BigInt>\n\n*   CPAN Testers Matrix\n\n<http://matrix.cpantesters.org/?dist=Math-BigInt>\n\n*   The Bignum mailing list\n\n*   Post to mailing list\n\n\"bignum at lists.scsys.co.uk\"\n\n*   View mailing list\n\n<http://lists.scsys.co.uk/pipermail/bignum/>\n\n*   Subscribe/Unsubscribe\n\n<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/bignum>\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "This program is free software; you may redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Peter John Acklam, <pjacklam@gmail.com>\n\nCode and documentation based on the Math::BigInt::Calc module by Tels\n<nospam-abuse@bloodgate.com>\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Math::BigInt, Math::BigInt::Calc, Math::BigInt::GMP, Math::BigInt::FastCalc and\nMath::BigInt::Pari.\n",
            "subsections": []
        }
    },
    "summary": "Math::BigInt::Lib - virtual parent class for Math::BigInt libraries",
    "flags": [],
    "examples": [],
    "see_also": []
}