ulong-class: Fixed Precision Unsigned and Signed Integers

Description

Classes ulong and slong extend virtual class flint. They represent vectors of fixed precision unsigned and signed integers, respectively. The integer size is 32 or 64 bits, depending on the ABI; see flintABI. There is no representation for R's missing value NA_integer_.

Usage

## Class generator functions
ulong(x = 0L, length = 0L, names = NULL)
slong(x = 0L, length = 0L, names = NULL)
ulong.array(x = 0L, dim = length(x), dimnames = NULL)
slong.array(x = 0L, dim = length(x), dimnames = NULL)
## Limits
ULONG_MAX
SLONG_MIN
SLONG_MAX

Value

A ulong or slong vector, possibly an array; see

‘Details’.

Arguments

x: an atomic or flint vector containing data for conversion to ulong or slong.
length: a numeric vector of length one giving the length of the return value. If that exceeds the length of x, then x is recycled. Non-integer values are rounded in the direction of zero.
names: the names slot of the return value, either NULL or a character vector of equal length. Non-character names are coerced to character.
dim: the dim slot of the return value, an integer vector of nonzero length. If the product exceeds the length of x, then x is recycled. Non-integer numeric dim are coerced to integer.
dimnames: the dimnames slot of the return value, either NULL or a list of length equal to the length of dim. The components are either NULL or character vectors of length given by dim. Non-character vector components of dimnames are coerced to character.

Conversion

Real numbers and real parts of complex numbers are rounded in the direction of 0. Imaginary parts of complex numbers are discarded.

Character strings are converted using function mpz_set_str from the GNU MP library with argument base set to 0; see https://gmplib.org/manual/Assigning-Integers.

An error is signaled if elements of x are not in the range of the C type, in particular if elements of x are NaN, -Inf, or Inf. The range is \((-1, 2^{n})\) for ulong and \((-2^{n-1}-1, 2^{n-1})\) for slong, where \(n\) is the value of flintABI().

Slots

.xData, dim, dimnames, names: inherited from virtual class flint.

Methods

!: signature(x = "ulong"):
signature(x = "slong"):
equivalent to (but faster than) x == 0L.
%*%, crossprod, tcrossprod: signature(x = "ulong", y = "ulong"):
signature(x = "slong", y = "slong"):
signature(x = "ulong", y = "ANY"):
signature(x = "slong", y = "ANY"):
signature(x = "ANY", y = "ulong"):
signature(x = "ANY", y = "slong"):
matrix products. The “other” operand must be atomic or inherit from virtual class flint. crossprod and tcrossprod behave as if y = x when y is missing or NULL. Operands are promoted as necessary and must be conformable (have compatible dimensions). Non-array operands of length k are handled as 1-by-k or k-by-1 matrices depending on the call.
+: signature(e1 = "ulong", e2 = "missing"):
signature(e1 = "slong", e2 = "missing"):
returns a copy of the argument.
-: signature(e1 = "ulong", e2 = "missing"):
signature(e1 = "slong", e2 = "missing"):
returns the negation of the argument.
Complex: signature(z = "ulong"):
signature(z = "slong"):
mathematical functions of one argument; see S4groupGeneric. Member functions requiring promotion to a floating-point type may not be implemented.
Math: signature(x = "ulong"):
signature(x = "slong"):
mathematical functions of one argument; see S4groupGeneric. Member functions requiring promotion to a floating-point type may not be implemented.
Math2: signature(x = "ulong"):
signature(x = "slong"):
decimal rounding according to a second argument digits; see S4groupGeneric. There are just two member member functions: round, signif.
Ops: signature(e1 = "ulong", e2 = "ulong"):
signature(e1 = "slong", e2 = "slong"):
signature(e1 = "ulong", e2 = "ANY"):
signature(e1 = "slong", e2 = "ANY"):
signature(e1 = "ANY", e2 = "ulong"):
signature(e1 = "ANY", e2 = "slong"):
binary arithmetic, comparison, and logical operators; see S4groupGeneric. The “other” operand must be atomic or inherit from virtual class flint. Operands are promoted as necessary. Array operands must be conformable (have identical dimensions). Non-array operands are recycled.
Summary: signature(x = "ulong"):
signature(x = "slong"):
univariate summary statistics; see S4groupGeneric. The return value is a logical vector of length 1 (any, all) or a ulong, slong, or fmpz vector of length 1 or 2 (sum, prod, min, max, range).
anyNA: signature(x = "ulong"):
signature(x = "slong"):
returns FALSE, as ulong and slong have no representation for NaN.
as.vector: signature(x = "ulong"):
signature(x = "slong"):
returns as.vector(y, mode), where y is a double vector containing the result of converting each element of x to the range of double, rounding if the value is not exactly representable in double precision. The rounding mode is to the nearest representable number in the direction of zero. Coercion to types "character", "symbol" (synonym "name"), "pairlist", "list", and "expression", which are not “number-like”, is handled specially. See also asVector.
backsolve: signature(r = "ulong", x = "ulong"):
signature(r = "slong", x = "slong"):
signature(r = "ulong", x = "ANY"):
signature(r = "slong", x = "ANY"):
signature(r = "ANY", x = "ulong"):
signature(r = "ANY", x = "slong"):
solution of the triangular system op2(op1(r)) %*% y = x, where op1=ifelse(upper.tri, triu, tril) and op2=ifelse(transpose, t, identity) and upper.tri and transpose are optional logical arguments with default values TRUE and FALSE, respectively. The “other” operand must be atomic or inherit from virtual class flint. If x is missing, then the return value is the inverse of op2(op1(r)), as if x were the identity matrix. Operands are promoted as necessary and must be conformable (have compatible dimensions). Non-array x are handled as length(x)-by-1 matrices. If r and (if not missing) x are both formally rational, then the solution is exact and the return value is an fmpq matrix.
chol: signature(x = "ulong"):
signature(x = "slong"):
coerces x to class arf and dispatches.
chol2inv: signature(x = "ulong"):
signature(x = "slong"):
returns the inverse of the positive definite matrix whose upper triangular Cholesky factor is the upper triangular part of x. The return value is the exact inverse, being computed as tcrossprod(backsolve(x)).
coerce: signature(from = "ANY", to = "ulong"):
signature(from = "ANY", to = "slong"):
returns the value of ulong(from) or slong(from).
colSums: signature(x = "ulong"):
signature(x = "slong"):
returns a ulong or (in case of overflow) fmpz vector or array containing the column sums of x, defined as sums over dimensions 1:dims.
colMeans: signature(x = "ulong"):
signature(x = "slong"):
returns an fmpq vector or array containing the column means of x, defined as means over dimensions 1:dims.
det, determinant, diff, diffinv: signature(x = "ulong"):
signature(x = "slong"):
coerces x to class fmpz and dispatches.
format: signature(x = "ulong"):
signature(x = "slong"):
returns a character vector suitable for printing. Optional arguments control the output; see format-methods.
is.finite: signature(x = "ulong"):
signature(x = "slong"):
returns a logical vector whose elements are all TRUE, as ulong and slong have no representation for NaN, -Inf, and Inf.
is.infinite, is.na, is.nan: signature(x = "ulong"):
signature(x = "slong"):
returns a logical vector whose elements are all FALSE, as ulong and slong have no representation for NaN, -Inf, and Inf.
is.unsorted: signature(x = "ulong"):
signature(x = "slong"):
returns a logical indicating if x is not sorted in nondecreasing order (increasing order if optional argument strictly is set to TRUE).
mean: signature(x = "ulong"):
signature(x = "slong"):
returns the arithmetic mean. An error is signaled if the argument length is 0, because the return type is fmpq which cannot represent the result of division by 0.
rowSums: signature(x = "ulong"):
signature(x = "slong"):
returns a ulong or (in case of overflow) fmpz vector or array containing the row sums of x, defined as sums over dimensions (dims+1):length(dim(x)).
rowMeans: signature(x = "ulong"):
signature(x = "slong"):
returns an fmpq vector or array containing the row means of x, defined as means over dimensions (dims+1):length(dim(x)).
solve: signature(a = "ulong", b = "ulong"):
signature(a = "slong", b = "slong"):
signature(a = "ulong", b = "ANY"):
signature(a = "slong", b = "ANY"):
signature(a = "ANY", b = "ulong"):
signature(a = "ANY", b = "slong"):
solution of the general system a %*% x = b. The “other” operand must be atomic or inherit from virtual class flint. If b is missing, then the return value is the inverse of a, as if b were the identity matrix. Operands are promoted as necessary and must be conformable (have compatible dimensions). Non-array b are handled as length(b)-by-1 matrices. If a and (if not missing) b are both formally rational, then the solution is exact and the return value is an fmpq matrix.

Details

The class generator functions have four distinct usages:

ulong()
ulong(length=)
ulong(x)
ulong(x, length=)
slong()
slong(length=)
slong(x)
slong(x, length=)

The first usage generates an empty vector. The second usage generates a zero vector of the indicated length. The third usage converts x, preserving dimensions, dimension names, and names. The fourth usage converts x, recycling its elements to the indicated length and discarding its dimensions, dimension names, and names. Attempts to recycle x of length zero to nonzero length are an error.

Usage of ulong.array and slong.array is modelled after array.

ULONG_MAX is a ulong vector of length 1 storing the greatest integer representable by ulong, namely \(2^{n}-1\), where \(n\) is the value of flintABI(). SLONG_MIN and SLONG_MAX are slong vectors of length 1 storing the least and greatest integers representable by slong, namely \(-2^{n-1}\) and \(2^{n-1}-1\).

References

The FLINT documentation of the underlying C types: https://flintlib.org/doc/flint.html

Examples

Run this code

showClass("ulong")
showClass("slong")
showMethods(classes = c("ulong", "slong"))

(zu <- ulong(length = 12L))
stopifnot(flintSize(zu) * 8L == length(zu) * flintABI())

## Conversion of data not representable in target type/class depends on
## existence of NA value
as.integer(SLONG_MIN)
try(ulong(-1L))
try(slong(NA_integer_))

## Overflow in +, -, *, %/% promotes to arbitrary precision
ulong(0L) - ulong(1L)
ULONG_MAX + ulong(1L)

## Mixture of unsigned and signed promotes to signed arbitrary precision
## ("raw" is unsigned, "logical" and "integer" are signed)
c(ulong(1L), as.raw(0L))
c(ulong(1L), FALSE)
c(ulong(1L), 0L)
c(ulong(1L), slong(0L))

## Quotients are formally rational
SLONG_MAX/seq_len(8L)
mean(slong(c(1L, 1L, 2L)))
summary(slong(c(1L, 1L, 2L, 3L, 5L, 8L, 13L, 21L)))

## Floored integer division
p <- slong(-127L)
q <- c(-(3L:1L), 1L:3L)
stopifnot(identical(p %/% q * q + p %% q, rep(p, 6L)))

## A sequence
d <- 3L
(s <- seq.int(from = SLONG_MIN + 1L, by = SLONG_MAX, length.out = d))
stopifnot(identical(s, c(-SLONG_MAX, 0L, SLONG_MAX)),
          identical(s %/% SLONG_MAX, slong(-1L:1L)),
          identical(s  /  SLONG_MAX, fmpq(-1L:1L)))

## An array
(Xs <- diag(s, d))
(Iu <- cbind(ulong(1L:d), ulong(1L:d)))
stopifnot(identical(Xs, s * slong.array(rep(c(1L, 0L), c(1L, d)), c(d, d))),
          identical(Xs[Iu], s), identical(diag(Xs), s))

Run the code above in your browser using DataLab