Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Math::BigInt::Calc.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Math::BigInt::Calc 3"
.TH Math::BigInt::Calc 3 "2002-06-01" "perl v5.8.0" "Perl Programmers Reference Guide"
.SH "NAME"
Math::BigInt::Calc \- Pure Perl module to support Math::BigInt
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Provides support for big integer calculations. Not intended to be used by other
modules (except Math::BigInt::Cached). Other modules which sport the same
functions can also be used to support Math::Bigint, like Math::BigInt::Pari.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In order to allow for multiple big integer libraries, Math::BigInt was
rewritten to use library modules for core math routines. Any module which
follows the same \s-1API\s0 as this can be used instead by using the following:
.PP
.Vb 1
\&        use Math::BigInt lib => 'libname';
.Ve
.PP
\&'libname' is either the long name ('Math::BigInt::Pari'), or only the short
version like 'Pari'.
.SH "EXPORT"
.IX Header "EXPORT"
The following functions \s-1MUST\s0 be defined in order to support the use by
Math::BigInt:
.PP
.Vb 3
\&        _new(string)    return ref to new object from ref to decimal string
\&        _zero()         return a new object with value 0
\&        _one()          return a new object with value 1
.Ve
.PP
.Vb 5
\&        _str(obj)       return ref to a string representing the object
\&        _num(obj)       returns a Perl integer/floating point number
\&                        NOTE: because of Perl numeric notation defaults,
\&                        the _num'ified obj may lose accuracy due to 
\&                        machine-dependend floating point size limitations
.Ve
.PP
.Vb 13
\&        _add(obj,obj)   Simple addition of two objects
\&        _mul(obj,obj)   Multiplication of two objects
\&        _div(obj,obj)   Division of the 1st object by the 2nd
\&                        In list context, returns (result,remainder).
\&                        NOTE: this is integer math, so no
\&                        fractional part will be returned.
\&        _sub(obj,obj)   Simple subtraction of 1 object from another
\&                        a third, optional parameter indicates that the params
\&                        are swapped. In this case, the first param needs to
\&                        be preserved, while you can destroy the second.
\&                        sub (x,y,1) => return x - y and keep x intact!
\&        _dec(obj)       decrement object by one (input is garant. to be > 0)
\&        _inc(obj)       increment object by one
.Ve
.PP
.Vb 1
\&        _acmp(obj,obj)  <=> operator for objects (return -1, 0 or 1)
.Ve
.PP
.Vb 2
\&        _len(obj)       returns count of the decimal digits of the object
\&        _digit(obj,n)   returns the n'th decimal digit of object
.Ve
.PP
.Vb 4
\&        _is_one(obj)    return true if argument is +1
\&        _is_zero(obj)   return true if argument is 0
\&        _is_even(obj)   return true if argument is even (0,2,4,6..)
\&        _is_odd(obj)    return true if argument is odd (1,3,5,7..)
.Ve
.PP
.Vb 1
\&        _copy           return a ref to a true copy of the object
.Ve
.PP
.Vb 2
\&        _check(obj)     check whether internal representation is still intact
\&                        return 0 for ok, otherwise error message as string
.Ve
.PP
The following functions are optional, and can be defined if the underlying lib
has a fast way to do them. If undefined, Math::BigInt will use pure Perl (hence
slow) fallback routines to emulate these:
.PP
.Vb 2
\&        _from_hex(str)  return ref to new object from ref to hexadecimal string
\&        _from_bin(str)  return ref to new object from ref to binary string
.Ve
.PP
.Vb 6
\&        _as_hex(str)    return ref to scalar string containing the value as
\&                        unsigned hex string, with the '0x' prepended.
\&                        Leading zeros must be stripped.
\&        _as_bin(str)    Like as_hex, only as binary string containing only
\&                        zeros and ones. Leading zeros must be stripped and a
\&                        '0b' must be prepended.
.Ve
.PP
.Vb 4
\&        _rsft(obj,N,B)  shift object in base B by N 'digits' right
\&                        For unsupported bases B, return undef to signal failure
\&        _lsft(obj,N,B)  shift object in base B by N 'digits' left
\&                        For unsupported bases B, return undef to signal failure
.Ve
.PP
.Vb 4
\&        _xor(obj1,obj2) XOR (bit-wise) object 1 with object 2
\&                        Note: XOR, AND and OR pad with zeros if size mismatches
\&        _and(obj1,obj2) AND (bit-wise) object 1 with object 2
\&        _or(obj1,obj2)  OR (bit-wise) object 1 with object 2
.Ve
.PP
.Vb 5
\&        _mod(obj,obj)   Return remainder of div of the 1st by the 2nd object
\&        _sqrt(obj)      return the square root of object (truncate to int)
\&        _fac(obj)       return factorial of object 1 (1*2*3*4..)
\&        _pow(obj,obj)   return object 1 to the power of object 2
\&        _gcd(obj,obj)   return Greatest Common Divisor of two objects
.Ve
.PP
.Vb 3
\&        _zeros(obj)     return number of trailing decimal zeros
\&        _modinv         return inverse modulus
\&        _modpow         return modulus of power ($x ** $y) % $z
.Ve
.PP
Input strings come in as unsigned but with prefix (i.e. as '123', '0xabc'
or '0b1101').
.PP
Testing of input parameter validity is done by the caller, so you need not
worry about underflow (f.i. in \f(CW\*(C`_sub()\*(C'\fR, \f(CW\*(C`_dec()\*(C'\fR) nor about division by
zero or similar cases.
.PP
The first parameter can be modified, that includes the possibility that you
return a reference to a completely different object instead. Although keeping
the reference and just changing it's contents is prefered over creating and
returning a different reference.
.PP
Return values are always references to objects or strings. Exceptions are
\&\f(CW\*(C`_lsft()\*(C'\fR and \f(CW\*(C`_rsft()\*(C'\fR, which return undef if they can not shift the
argument. This is used to delegate shifting of bases different than the one
you can support back to Math::BigInt, which will use some generic code to
calculate the result.
.SH "WRAP YOUR OWN"
.IX Header "WRAP YOUR OWN"
If you want to port your own favourite c\-lib 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 BigInt and 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 => 'yourlib';
.Ve
.PP
This way you ensure that your library really works 100% within Math::BigInt.
.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 "AUTHORS"
.IX Header "AUTHORS"
Original math code by Mark Biggar, rewritten by Tels <http://bloodgate.com/>
in late 2000, 2001.
Seperated from BigInt and shaped \s-1API\s0 with the help of John Peacock.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Math::BigInt, Math::BigFloat, Math::BigInt::BitVect,
Math::BigInt::GMP, Math::BigInt::Cached and Math::BigInt::Pari.