1\name{bigz operators}
2\alias{add.bigz}
3\alias{+.bigz}
4\alias{sub.bigz}
5\alias{-.bigz}
6\alias{mul.bigz}
7\alias{*.bigz}
8\alias{div.bigz}
9\alias{/.bigz}
10\alias{mod.bigz}
11\alias{\%\%.bigz}
12\alias{\%/\%.bigz}
13\alias{divq.bigz}
14\alias{abs.bigz}
15\alias{inv.bigz}
16\alias{inv}
17\alias{pow.bigz}
18\alias{pow}
19\alias{^.bigz}
20\alias{log.bigz}
21\alias{log2.bigz}
22\alias{log10.bigz}
23\title{Basic Arithmetic Operators for Large Integers ("bigz")}
24\description{
25  Addition, substraction, multiplication, (integer) division,
26  remainder of division, multiplicative inverse,
27  power and logarithm functions.
28}
29\usage{
30add.bigz(e1, e2)
31sub.bigz(e1, e2 = NULL)
32mul.bigz(e1, e2)
33div.bigz(e1, e2)
34divq.bigz(e1,e2) ## ==  e1 \%/\% e2
35mod.bigz(e1, e2) ## ==  e1 \%\%  e2
36\method{abs}{bigz}(x)
37
38inv.bigz(a, b,...)## == (1 / a) (modulo b)
39% inv(a, ...)
40pow.bigz(e1, e2,...)## == e1 ^ e2
41% pow(a, ...)
42\S3method{log}{bigz}(x, base=exp(1))
43\S3method{log2}{bigz}(x)
44\S3method{log10}{bigz}(x)
45}
46
47\arguments{
48  \item{x}{bigz, integer or string from an integer}
49  \item{e1, e2, a,b}{bigz, integer or string from an integer}
50  \item{base}{base of the logarithm; base e as default}
51  \item{...}{Additional parameters}
52}
53\details{
54  Operators can be used directly when objects are of class bigz:
55  a + b, log(a), etc.
56
57  For details about the internal modulus state, \emph{and} the rules
58  applied for arithmetic operations on big integers with a modulus,
59  see the \code{\link{bigz}} help page.
60
61  \code{a / b}  \eqn{=}  \code{div(a,b)} returns a rational number
62  unless the operands have a (matching) modulus where
63  \code{a * b^-1} results.
64  \cr
65  \code{a \%/\% b} (or, equivalently, \code{divq(a,b)}) returns the
66  quotient of simple \emph{integer} division (with truncation towards zero),
67  possibly re-adding a modulus at the end (but \emph{not} using a
68  modulus like in \code{a / b}).
69
70  \code{r <- inv.bigz(a, m)}, the multiplicative inverse of
71  \code{a} modulo \eqn{m}, corresponds to \code{1/a} or \code{a ^-1}
72  from above \emph{when} \code{a} has modulus \code{m}.  Note that
73  \eqn{a} not always has an inverse modulo \eqn{m}, in which case
74  \code{r} will be \code{\link{NA}} with a warning that can be turned
75  off via \preformatted{options("gmp:warnNoInv" = FALSE)}.
76}
77\value{
78  Apart from \code{/} (or \code{div}), where rational numbers
79  (\code{\link{bigq}}) may result, these functions return an object of
80  class \code{"bigz"}, representing the result of the arithmetic
81  operation.
82}
83
84\references{The GNU MP Library, see \url{https://gmplib.org}}
85
86\author{Immanuel Scholz and Antoine Lucas}
87
88\examples{
89# 1+1=2
90as.bigz(1) + 1
91as.bigz(2)^10
92as.bigz(2)^200
93
94# if my.large.num.string is set to a number, this returns the least byte
95(my.large.num.string <- paste(sample(0:9, 200, replace=TRUE), collapse=""))
96mod.bigz(as.bigz(my.large.num.string), "0xff")
97
98# power exponents can be up to MAX_INT in size, or unlimited if a
99# bigz's modulus is set.
100pow.bigz(10,10000)
101
102## Modulo 11,   7 and 8 are inverses :
103as.bigz(7, mod = 11) * 8 ## ==>  1  (mod 11)
104inv.bigz(7, 11)## hence, 8
105a <- 1:10
106(i.a <- inv.bigz(a, 11))
107d <- as.bigz(7)
108a \%/\% d  # = divq(a, d)
109a \%\%  d  # = mod.bigz (a, d)
110
111(ii <- inv.bigz(1:10, 16))
112## with 5 warnings (one for each NA)
113op <- options("gmp:warnNoInv" = FALSE)
114i2 <- inv.bigz(1:10, 16) # no warnings
115(i3 <- 1 / as.bigz(1:10, 16))
116i4 <- as.bigz(1:10, 16) ^ -1
117stopifnot(identical(ii, i2),
118	  identical(as.bigz(i2, 16), i3),
119	  identical(i3, i4))
120options(op)# revert previous options' settings
121
122stopifnot(inv.bigz(7, 11) == 8,
123          all(as.bigz(i.a, 11) * a == 1),
124          identical(a \%/\% d, divq.bigz(1:10, 7)),
125          identical(a \%\%  d, mod.bigz (a, d))
126 )
127
128}
129
130\keyword{arith}
131%\keyword{bigz}
132