mpfr-utils: Rmpfr -- Utilities for Precision Setting, Printing, etc

Description

This page documents utilities from package Rmpfr which are typically not called by the user, but may come handy in some situations.

Usage

getPrec(x, base = 10, doNumeric = TRUE, is.mpfr = NA, bigq. = 128L)
getD(x)
mpfr_default_prec(prec)
# S3 method for mpfrArray
print(x, digits = NULL, drop0trailing = FALSE,
      right = TRUE, …)
# S3 method for mpfr
print(x, digits = NULL, drop0trailing = TRUE,
      right = TRUE,
      max.digits = getOption("Rmpfr.print.max.digits", 9999),
      …)
toNum(from, rnd.mode = c('N','D','U','Z','A'))
mpfr2array(x, dim, dimnames = NULL, check = FALSE)
.mpfr2list(x, names = FALSE)
mpfrXport(x, names = FALSE)
mpfrImport(mxp)

Arguments

x, from

typically, an R object of class "'>mpfr", or "'>mpfrArray", respectively. For getPrec(), any number-like R object, or NULL.

base

(only when x is character) the base with respect to which x[i] represent numbers; base \(b\) must fulfill \(2 \le b \le 62\).

doNumeric

logical indicating integer or double typed x should be accepted and a default precision be returned. Should typically be kept at default TRUE.

is.mpfr

logical indicating if class(x) is already known to be "mpfr"; typically should be kept at default, NA.

bigq.

for getPrec(), the precision to use for a big rational (class "bigq"); if not specified gives warning when used.

prec

a positive integer, or missing.

drop0trailing

logical indicating if trailing "0"s should be omitted.

right

logical indicating print()ing should right justify the strings; see print.default() to which it is passed.

digits, …

further arguments to print methods.

max.digits

a number (possibly Inf) to limit the number of (mantissa) digits to be printed, simply passed to formatMpfr. The default is finite to protect from printing very long strings which is often undesirable, notably in interactive use.

rnd.mode

a 1-letter string specifying how rounding should happen at C-level conversion to MPFR, see details of mpfr.

dim, dimnames

for "'>mpfrArray" construction.

check

logical indicating if the mpfrArray construction should happen with internal safety check. Previously, the implicit default used to be true.

names

(for .mpfr2list()) logical or character vector, indicating if the list returned should have names. If character, it specifies the names; if true, the names are set to format(x).

mxp

an "mpfrXport" object, as resulting from mpfrXport().

Value

getPrec(x) returns a integer vector of length one or the same length as x when that is positive, whereas getPrec(NULL) returns mpfr_default_prec(), see below. If you need to change the precision of x, i.e., need something like “setPrec”, use roundMpfr().

getD(x) is intended to be a fast version of x@.Data, and should not be used outside of lower level functions.

mpfr_default_prec() returns the current MPFR default precision, an integer. This is currently not made use of, in all of package Rmpfr, where functions have their own default precision where needed. mpfr_default_prec(prec) sets the current MPFR default precision and returns the previous one; see above.

toNum(m) returns a numeric array or matrix, when m is of class "'>mpfrArray" or "'>mpfrMatrix", respectively. It should be equivalent to as(m, "array") or ... "matrix". Note that the slightly more general asNumeric() is preferred now.

mpfr2array() a slightly more flexible alternative to dim(.) <- dd.

Details

The print method is currently built on the format method for class '>mpfr. This, currently does not format columns jointly which leads to suboptimally looking output. There are plans to change this.

Note that formatMpfr() which is called by print() (or show() or R's implicit printing) uses max.digits = Inf, differing from our print()'s default on purpose. If you do want to see the full accuracy even in cases it is large, use options(Rmpfr.print.max.digits = Inf) or .. = 1e7), say.

Examples

Run this code

# NOT RUN {
getPrec(as(c(1,pi), "mpfr")) # 128 for both

(opr <- mpfr_default_prec()) ## typically  53, the MPFR system default
stopifnot(opr == (oprec <- mpfr_default_prec(70)),
          70  == mpfr_default_prec())
## and reset it:
mpfr_default_prec(opr)

## Explore behavior of rounding modes 'rnd.mode':
x <- mpfr(10,99)^512 # too large for regular (double prec. / numeric):
sapply(c("N", "D", "U", "Z", "A"), function(RM)
       sapply(list(-x,x), function(.) toNum(., RM)))
##    N             D              U              Z    A
## -Inf          -Inf -1.797693e+308 -1.797693e+308 -Inf
##  Inf 1.797693e+308            Inf  1.797693e+308  Inf

## Printing of "MPFR" matrices is less nice than R's usual matrix printing:
m <- outer(c(1, 3.14, -1024.5678), c(1, 1e-3, 10,100))
m[3,3] <- round(m[3,3])
m
mpfr(m, 50)

B6 <- mpfr2array(Bernoulli(1:6, 60), c(2,3),
                 dimnames = list(LETTERS[1:2], letters[1:3]))
B6

## Looking at internal representation [for power users only!]:

i8 <- mpfr(-2:5, 32)
x4 <- mpfr(c(NA, NaN, -Inf, Inf), 32)
## The output of the following depends on the GMP "numb" size
## (32 bit vs. 64 bit), and may be even more platform specifics:
str( .mpfr2list(i8) )
str( .mpfr2list(x4, names = TRUE) )

str(xp4 <- mpfrXport(x4, names = TRUE))
stopifnot(identical(x4, mpfrImport(mpfrXport(x4))),
          identical(i8, mpfrImport(mpfrXport(i8))))
if(FALSE) ## FIXME: not yet working:
  stopifnot(identical(B6, mpfrImport(mpfrXport(B6))))
# }