mpfr-utils: Rmpfr - Utilities for Precision Setting, etc
In Rmpfr: Interface R to MPFR - Multiple Precision Floating-Point Reliable
mpfr-utils R Documentation
Rmpfr – Utilities for Precision Setting, etc
Description
This page documents utilities from package Rmpfr which are
typically not called by the user, but may come handy in some
situations.
Notably, the (base-2) maximal (and minimal) precision and the
“erange”, the range of possible (base-2) exponents of
mpfr-numbers can be queried and partly extended.
Usage
getPrec(x, base = 10, doNumeric = TRUE, is.mpfr = NA, bigq. = 128L)
.getPrec(x)
getD(x)
mpfr_default_prec(prec)
toNum(from, rnd.mode = c('N','D','U','Z','A'))
.mpfr2d(from)
.mpfr2i(from)
mpfr2array(x, dim, dimnames = NULL, check = FALSE)
.mpfr2list(x, names = FALSE)
mpfrXport(x, names = FALSE)
mpfrImport(mxp)
.mpfr_formatinfo(x)
.mpfr2exp(x)
.mpfr_erange(kind = c("Emin", "Emax"), names = TRUE)
.mpfr_erange_set(kind = c("Emin", "Emax"), value)
.mpfr_erange_kinds
.mpfr_erange_is_int()
.mpfr_maxPrec()
.mpfr_minPrec()
.mpfr_gmp_numbbits()
.mpfrSizeof()
.mpfrVersion()
## Really Internal and low level, no error checking (for when you know ..)
.mpfr (x, precBits)
.mpfr.(x, precBits, rnd.mode)
.getSign(x)
.mpfr_negative(x)
.mpfr_sign(x)
..bigq2mpfr(x, precB = NULL, rnd.mode = c("N", "D", "U", "Z", "A"))
..bigz2mpfr(x, precB = NULL, rnd.mode = c("N", "D", "U", "Z", "A"))
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, precB, precBits
a positive integer, not larger than
.Machine$ integer.max, or missing.
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().
kind
a character string or vector, specifying the
kind of “erange” value; must be an element of
.mpfr_erange_kinds, i.e., one of "Emin", "Emax",
"min.emin", "max.emin", "min.emax", "max.emax".
value
numeric, for .mpfr_erange_set() one
number per kind. Must be in range specified by the
*."emin" and *."emax" erange values.
Details
The .mpfr_erange* functions (and variable) allow to query and set
the allowed range of values for the base-2 exponents of
"mpfr" numbers.
See the examples below and GNU MPFR library documentation on the C functions
mpfr_get_emin(), mpfr_set_emin(.),
mpfr_get_emin_min(), and mpfr_get_emin_max(),
(and those four with ‘_emin’ replaced by ‘_emax’ above).
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().
.getPrec(x) is a simplified version of getPrec() which only
works for "mpfr" objects x.
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 much in package Rmpfr, where functions have
their own default precision where needed, and otherwise we'd rather not
be dependent of such a global setting.
mpfr_default_prec(prec) sets the current MPFR default
precision and returns the previous one; see above.
.mpfr_maxPrec() and (less interestingly) .mpfr_minPrec()
give the maximal and minimal base-2 precision allowed in the current
version of the MPFR library linked to by R package Rmpfr.
The maximal precision is typically 2^{63}, i.e.,
all.equal(.mpfr_maxPrec(), 2^63)
is typically true.
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() from gmp is preferred now.
.mpfr2d() is similar to but simpler than toNum(), whereas
.mpfr2i() is an analogue low level utility for
as.integer(<mpfr>).
mpfr2array() a slightly more flexible alternative to
dim(.) <- dd.
.mpfr2exp(x) returns the base-2 (integer valued) exponents of
x, i.e., it is the R interface to MPFR C's mpfr_get_exp().
The result is integer iff .mpfr_erange_is_int()
is true, otherwise double. Note that the MPFR (4.0.1)
manual says about mpfr_get_exp(): The behavior for NaN,
infinity or zero is undefined.
.mpfr_erange_is_int() returns TRUE iff the
.mpfr_erange(c("Emin","Emax")) range lies inside the range of R's
integer limits, i.e., has absolute values not larger than
.Machine$integer.max ( = 2^{31} - 1).
.mpfr_erange_set() invisibly (see invisible())
returns TRUE iff the change was successful.
.mpfr_gmp_numbbits() returns the ‘GMP’ library “numb”
size, which is either 32 or 64 bit (as integer, i.e.,
64L or 32L). If it is not 64, you typically
cannot enlarge the exponential range of mpfr numbers via
.mpfr_erange(), see above.
.mpfrSizeof() may be more relevant (than .mpfr_gmp_numbbits()),
returning a named integer vector of length(.) == 3 with
the sizes in bytes of the three ‘MPFR’ library types named
c("mpfr_prec_t", "mpfr_exp_t", "mp_limb_t").
.mpfrVersion() returns a string, the version of the ‘MPFR’
library we are linking to.
.mpfr_formatinfo(x) returns conceptually a subset of
.mpfr2str()'s result, a list with three components
- exp
the base-2 exponents of x, identical to .mpfr2exp(x).
- finite
logical identical to is.finite(x).
- is.0
logical indicating if the corresponding
x[i] is zero; identical to mpfrIs0(x).
(Note that .mpfr2str(x, .., base)$exp is wrt base
and is not undefined but ...)
.mpfr_sign(x) only works for mpfr objects, then identical
to sign(x). Analogously, .mpfr_negative(x) is
-x in that case.
.getSign(x) is a low-level version of sign(x)
returning -1 or +1, but not 0.
Finally, ..bigq2mpfr(x, ..) and ..bigz2mpfr(x, ..) are fast
ways to coerce bigz and bigq number objects (created by
package gmp's functionality) to our "mpfr" class.
Note
mpfrXport() and mpfrImport() are experimental and
used to explore reported platform incompatibilities of
save()d and load()ed "mpfr"
objects between Windows and non-Windows platforms.
In other words, the format of the result of mpfrXport() and
hence the mxp argument to mpfrImport() are considered
internal, not part of the API and subject to change.
See Also
Start using mpfr(..), and compute with these numbers.
mpfrArray(x) is for numeric (“non-mpfr”)
x, whereas mpfr2array(x) is for "mpfr" classed
x, only.
Examples
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
## Ranges of (base 2) exponents of MPFR numbers:
.mpfr_erange() # the currently active range of possible base 2 exponents:
## A factory fresh setting fulfills
.mpfr_erange(c("Emin","Emax")) == c(-1,1) * (2^30 - 1)
## There are more 'kind's, the latter 4 showing how you could change the first two :
.mpfr_erange_kinds
.mpfr_erange(.mpfr_erange_kinds)
eLimits <- .mpfr_erange(c("min.emin", "max.emin", "min.emax", "max.emax"))
## Typically true in MPFR versions *iff* long is 64-bit, i.e. *not* on Windows
if(.Machine$sizeof.long == 8L) {
eLimits == c(-1,1, -1,1) * (2^62 - 1)
} else if(.Machine$sizeof.long == 4L) # on Windows
eLimits == c(-1,1, -1,1) * (2^30 - 1)
## Looking at internal representation [for power users only!]:
i8 <- mpfr(-2:5, 32)
x4 <- mpfr(c(NA, NaN, -Inf, Inf), 32)
stopifnot(exprs = {
identical(x4[1], x4[2])
is.na(x4[1] == x4[2]) # <- was *wrong* in Rmpfr <= 0.9-4
is.na(x4[1] != x4[2]) # (ditto)
identical(x4 < i8[1:4], c(NA,NA, TRUE,FALSE))
!is.finite(x4)
identical(is.infinite(x4), c(FALSE,FALSE, TRUE,TRUE))
})
## The output of the following depends on the GMP "numb" size
## (32 bit vs. 64 bit), *and* additionally
## on sizeof.long (mostly non-Windows <-> Windows, see above):
str( .mpfr2list(i8) )
str( .mpfr2list(x4, names = TRUE) )
dput( .mpfrSizeof() ) # on (64-bit) Linux, now typically all '8',
## as 64 bit = 8 bytes -- nowadays probably more relevant than
dput( .mpfr_gmp_numbbits() ) # typically 64
str(xp4 <- mpfrXport(x4, names = TRUE))
stopifnot(identical(x4, mpfrImport(mpfrXport(x4))),
identical(i8, mpfrImport(mpfrXport(i8))))
B6 <- mpfr2array(Bernoulli(1:6, 60), c(2,3),
dimnames = list(LETTERS[1:2], letters[1:3]))
## FIXME, need c(.), as dim(.) & dimnames(.) "get lost" in export/import:
stopifnot(identical(c(B6), mpfrImport(mpfrXport(B6))))
Rmpfr documentation built on Oct. 24, 2025, 3:01 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| mpfr-utils | R Documentation |
Rmpfr – Utilities for Precision Setting, etc
Description
This page documents utilities from package Rmpfr which are typically not called by the user, but may come handy in some situations.
Notably, the (base-2) maximal (and minimal) precision and the
“erange”, the range of possible (base-2) exponents of
mpfr-numbers can be queried and partly extended.
Usage
getPrec(x, base = 10, doNumeric = TRUE, is.mpfr = NA, bigq. = 128L)
.getPrec(x)
getD(x)
mpfr_default_prec(prec)
toNum(from, rnd.mode = c('N','D','U','Z','A'))
.mpfr2d(from)
.mpfr2i(from)
mpfr2array(x, dim, dimnames = NULL, check = FALSE)
.mpfr2list(x, names = FALSE)
mpfrXport(x, names = FALSE)
mpfrImport(mxp)
.mpfr_formatinfo(x)
.mpfr2exp(x)
.mpfr_erange(kind = c("Emin", "Emax"), names = TRUE)
.mpfr_erange_set(kind = c("Emin", "Emax"), value)
.mpfr_erange_kinds
.mpfr_erange_is_int()
.mpfr_maxPrec()
.mpfr_minPrec()
.mpfr_gmp_numbbits()
.mpfrSizeof()
.mpfrVersion()
## Really Internal and low level, no error checking (for when you know ..)
.mpfr (x, precBits)
.mpfr.(x, precBits, rnd.mode)
.getSign(x)
.mpfr_negative(x)
.mpfr_sign(x)
..bigq2mpfr(x, precB = NULL, rnd.mode = c("N", "D", "U", "Z", "A"))
..bigz2mpfr(x, precB = NULL, rnd.mode = c("N", "D", "U", "Z", "A"))
Arguments
x, from |
typically, an R object of class |
base |
(only when |
doNumeric |
logical indicating |
is.mpfr |
logical indicating if |
bigq. |
for |
prec, precB, precBits |
a positive integer, not larger than
|
rnd.mode |
a 1-letter string specifying how rounding
should happen at C-level conversion to MPFR, see details of
|
dim, dimnames |
for |
check |
logical indicating if the mpfrArray construction should happen with internal safety check. Previously, the implicit default used to be true. |
names |
(for |
mxp |
an |
kind |
a |
value |
|
Details
The .mpfr_erange* functions (and variable) allow to query and set
the allowed range of values for the base-2 exponents of
"mpfr" numbers.
See the examples below and GNU MPFR library documentation on the C functions
mpfr_get_emin(), mpfr_set_emin(.),
mpfr_get_emin_min(), and mpfr_get_emin_max(),
(and those four with ‘_emin’ replaced by ‘_emax’ above).
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().
.getPrec(x) is a simplified version of getPrec() which only
works for "mpfr" objects x.
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 much in package Rmpfr, where functions have
their own default precision where needed, and otherwise we'd rather not
be dependent of such a global setting.
mpfr_default_prec(prec) sets the current MPFR default
precision and returns the previous one; see above.
.mpfr_maxPrec() and (less interestingly) .mpfr_minPrec()
give the maximal and minimal base-2 precision allowed in the current
version of the MPFR library linked to by R package Rmpfr.
The maximal precision is typically 2^{63}, i.e.,
all.equal(.mpfr_maxPrec(), 2^63)
is typically true.
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() from gmp is preferred now.
.mpfr2d() is similar to but simpler than toNum(), whereas
.mpfr2i() is an analogue low level utility for
as.integer(<mpfr>).
mpfr2array() a slightly more flexible alternative to
dim(.) <- dd.
.mpfr2exp(x) returns the base-2 (integer valued) exponents of
x, i.e., it is the R interface to MPFR C's mpfr_get_exp().
The result is integer iff .mpfr_erange_is_int()
is true, otherwise double. Note that the MPFR (4.0.1)
manual says about mpfr_get_exp(): The behavior for NaN,
infinity or zero is undefined.
.mpfr_erange_is_int() returns TRUE iff the
.mpfr_erange(c("Emin","Emax")) range lies inside the range of R's
integer limits, i.e., has absolute values not larger than
.Machine$integer.max ( = 2^{31} - 1).
.mpfr_erange_set() invisibly (see invisible())
returns TRUE iff the change was successful.
.mpfr_gmp_numbbits() returns the ‘GMP’ library “numb”
size, which is either 32 or 64 bit (as integer, i.e.,
64L or 32L). If it is not 64, you typically
cannot enlarge the exponential range of mpfr numbers via
.mpfr_erange(), see above.
.mpfrSizeof() may be more relevant (than .mpfr_gmp_numbbits()),
returning a named integer vector of length(.) == 3 with
the sizes in bytes of the three ‘MPFR’ library types named
c("mpfr_prec_t", "mpfr_exp_t", "mp_limb_t").
.mpfrVersion() returns a string, the version of the ‘MPFR’
library we are linking to.
.mpfr_formatinfo(x) returns conceptually a subset of
.mpfr2str()'s result, a list with three components
- exp
the base-2 exponents of
x, identical to.mpfr2exp(x).- finite
logicalidentical tois.finite(x).- is.0
logicalindicating if the correspondingx[i]is zero; identical tompfrIs0(x).
(Note that .mpfr2str(x, .., base)$exp is wrt base
and is not undefined but ...)
.mpfr_sign(x) only works for mpfr objects, then identical
to sign(x). Analogously, .mpfr_negative(x) is
-x in that case.
.getSign(x) is a low-level version of sign(x)
returning -1 or +1, but not 0.
Finally, ..bigq2mpfr(x, ..) and ..bigz2mpfr(x, ..) are fast
ways to coerce bigz and bigq number objects (created by
package gmp's functionality) to our "mpfr" class.
Note
mpfrXport() and mpfrImport() are experimental and
used to explore reported platform incompatibilities of
save()d and load()ed "mpfr"
objects between Windows and non-Windows platforms.
In other words, the format of the result of mpfrXport() and
hence the mxp argument to mpfrImport() are considered
internal, not part of the API and subject to change.
See Also
Start using mpfr(..), and compute with these numbers.
mpfrArray(x) is for numeric (“non-mpfr”)
x, whereas mpfr2array(x) is for "mpfr" classed
x, only.
Examples
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
## Ranges of (base 2) exponents of MPFR numbers:
.mpfr_erange() # the currently active range of possible base 2 exponents:
## A factory fresh setting fulfills
.mpfr_erange(c("Emin","Emax")) == c(-1,1) * (2^30 - 1)
## There are more 'kind's, the latter 4 showing how you could change the first two :
.mpfr_erange_kinds
.mpfr_erange(.mpfr_erange_kinds)
eLimits <- .mpfr_erange(c("min.emin", "max.emin", "min.emax", "max.emax"))
## Typically true in MPFR versions *iff* long is 64-bit, i.e. *not* on Windows
if(.Machine$sizeof.long == 8L) {
eLimits == c(-1,1, -1,1) * (2^62 - 1)
} else if(.Machine$sizeof.long == 4L) # on Windows
eLimits == c(-1,1, -1,1) * (2^30 - 1)
## Looking at internal representation [for power users only!]:
i8 <- mpfr(-2:5, 32)
x4 <- mpfr(c(NA, NaN, -Inf, Inf), 32)
stopifnot(exprs = {
identical(x4[1], x4[2])
is.na(x4[1] == x4[2]) # <- was *wrong* in Rmpfr <= 0.9-4
is.na(x4[1] != x4[2]) # (ditto)
identical(x4 < i8[1:4], c(NA,NA, TRUE,FALSE))
!is.finite(x4)
identical(is.infinite(x4), c(FALSE,FALSE, TRUE,TRUE))
})
## The output of the following depends on the GMP "numb" size
## (32 bit vs. 64 bit), *and* additionally
## on sizeof.long (mostly non-Windows <-> Windows, see above):
str( .mpfr2list(i8) )
str( .mpfr2list(x4, names = TRUE) )
dput( .mpfrSizeof() ) # on (64-bit) Linux, now typically all '8',
## as 64 bit = 8 bytes -- nowadays probably more relevant than
dput( .mpfr_gmp_numbbits() ) # typically 64
str(xp4 <- mpfrXport(x4, names = TRUE))
stopifnot(identical(x4, mpfrImport(mpfrXport(x4))),
identical(i8, mpfrImport(mpfrXport(i8))))
B6 <- mpfr2array(Bernoulli(1:6, 60), c(2,3),
dimnames = list(LETTERS[1:2], letters[1:3]))
## FIXME, need c(.), as dim(.) & dimnames(.) "get lost" in export/import:
stopifnot(identical(c(B6), mpfrImport(mpfrXport(B6))))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.