News for R Package flint

Changes in version 0.1.2 (2025-10-10)

Compatibility

• Installation of flint version 0.1.1 failed under R versions 4.[3-4].z because the non-generic function asplit in base did not admit a formal argument drop. Compatibility is restored by conditional definition in .onLoad of the S4 generic function and S4 method with signature c(x = "flint").

Changes in version 0.1.1 (2025-10-08)

Description

• Enhances: Rmpfr, gmp as .initForeign defines methods for their classes.

Documentation

• There was a typo in ‘man/arb_hypgeom_bessel_j.Rd’, in the modified Bessel's equation, affecting only HTML and PDF output.

Methods

• S4 methods are defined for generic (or made-generic) functions aperm and asplit.

• S4 methods for anyDuplicated, duplicated, and unique are amended to handle arrays x. Accordingly they all gain an argument MARGIN with default value 1L.

• summary coerces to data frame and dispatches when its argument is a matrix, following summary.matrix.

• print gains an argument base, which it passes to format.

New Features

• R functions flintBits and flintBitsAccurate can be used to get the number of bits necessary for exact representation of an integer or floating type number and the number of bits of an interval midpoint whose accuracy is guaranteed given the interval radius. These are experimental and so only partially documented.

• R function .initForeign can be used to define coercions between classes in flint and analogous classes in external packages, currently Rmpfr or gmp.

Bug Fixes

• Calls to norm matching signature c(x = "flint", type = "missing") signaled an error due to dispatch ambiguity, for some reason not detected by the call to testInheritedMethods in ‘tests/ambiguity.R’.

• Calls to colSums and friends whose return value would have length zero allowed undefined behaviour (divide-by-zero in integer division).

• Calls to cbind and rbind could fill dimension names incorrectly when obtaining components from the call. Only the second component of the call (corresponding to the first actual argument) was “seen”.

• as.data.frame signaled an error when its argument was an array due to a “too late” assignment.

• Summary transferred attributes from its argument to its return value, in methods for classes ulong and slong.

• mtfrm passes digits.mag = 0L to format so that mag vectors are also formatted exactly.

Internals

• External pointers are cleared by their finalizers.

Changes in version 0.1.0 (2025-09-21)

Description

• Martin Maechler is a contributor.

Significant User-Visible Changes

• See section ‘Classes’ for backwards incompatible changes to the definition of virtual class flint.

• The class generator functions .ulong, .slong, ... are removed and replaced with pairs of class generator functions ulong, slong, ... and ulong.array, slong.array, ... with much nicer usage; see, e.g., help("ulong") for details.

• S4 methods for initialize, which were nonstandard by virtue of not calling callNextMethod in order to dispatch the default method, are removed in order to facilitate calls to new by expert users wanting to set slots directly (rather than indirectly through class generator functions) or wanting to instantiate class extensions with additional slots, e.g., new("ulongWithExtraSlot", ulong, extra = .). Users relying on the earlier behaviour of new should start using the documented class generator functions.

• R function flintIdentical is removed and replaced by an S4 method for made-generic function identical.

Classes

• Virtual class flint gains slots dim and dimnames, enabling representation of arrays. Methods for flint and subclasses must handle these slots exactly as default methods handle the so-named attributes of traditional vectors.

• Virtual class flint accepts NULL as a valid value for its names slot. NULL is used instead of character(0L) to indicate that an object is unnamed. Now character(0L) is valid only for objects of length zero.

• New classes OptionalInteger, OptionalList, and OptionalCharacter, defined as unions of NULL and integer, list, or character. They are used for slots dim, dimnames, and names of virtual class flint.

Methods

• Many existing S4 methods are amended to handle changes in the definition of virtual class flint, in particular to handle arrays. Notably, S4 methods for [, [<-, [[, and [[<- are refactored completely to support array subscripts.

• S4 methods are defined for generic (or made-generic) functions %*%, backsolve, cbind2, chol, chol2inv, colMeans, colSums, det, determinant, diag, diag<-, dim, dim<-, dimnames, dimnames<-, drop, is.array, is.matrix, isSymmetric, norm, rbind2, rowMeans, rowSums, solve, t, and tcrossprod. It is not a coindicence that these are all more or less array-specific.

• S3 methods are defined for S3-turned-S4 generic functions. These methods call the S4 generic function so that S4 dispatch occurs if the S3 generic function is called.

• S4 methods are defined for generic functions $ and $<-, signaling an informative error.

• An S4 method is defined for made-generic function identical so that .xData slots are handled specially when two flint objects are compared.

New Features

• C library functions arb_hypgeom_bessel_j, acb_hypgeom_bessel_j, arb_hypgeom_bessel_y, acb_hypgeom_bessel_y, arb_hypgeom_bessel_i, acb_hypgeom_bessel_i, arb_hypgeom_bessel_k, and acb_hypgeom_bessel_k, which implement the Bessel and modified Bessel functions, are interfaced as R functions with identical names and prototypes. Requested by Martin Maechler.

• R function flintClass for getting the name of the direct nonvirtual subclass of virtual class flint from which the argument inherits, e.g., "ulong" if the class of the argument is "ulong" or "ulongExtension".

• R function asVector for coercion to basic vector classes and flint vector classes, optionally preserving attributes (at least dim, dimnames, names). It handles attributes more uniformly than as.vector and as, which may or may not drop attributes depending on the class of the argument and the target class.

• R functions cbind.flint and rbind.flint, similar in purpose to c.flint, enabling users to bypass the internal dispatch mechanism of cbind and rbind.

• It is now defined how flintLength and flintSize handle arguments not inheriting from virtual class flint.

• Mid and Mid<- are implemented for class acb, getting and setting the complex midpoint. Thanks to Martin Maechler for the suggestion and patch (GH#15).

• S4 methods for format gain argument digits.mag and use that instead of digits to format mag and mag components of arb and acb. The S4 method for print gains the same argument, passing it to format.

Bug Fixes

• Due to a copy-paste bug, Mid(x) <- value never worked for x of class arb and Imag(z) <- value never worked for z of class acf or acb. Thanks to Martin Maechler for the report and patch (GH#15).

Changes in version 0.0.5 (2025-05-27)

Installation

• ‘configure’ tests for ‘flint/flint.h’ from FLINT 3.1 more explicitly, and ‘src/noreturn.h’ uses the result of this test. Thanks to Brian Ripley for checks linking FLINT 3.2.

• ‘configure.ac’ calls macro AC_RUN_IFELSE instead of macro AC_COMPILE_IFELSE where the former was always intended.

Changes in version 0.0.4 (2025-03-23)

Documentation

• ‘man/flint-class.Rd’ contained a cut-paste error affecting section ‘Methods’, items [[ and [[<-.

New Features

• C library functions arb_hypgeom_gamma_lower, acb_hypgeom_gamma_lower, arb_hypgeom_gamma_upper, acb_hypgeom_gamma_upper, arb_hypgeom_beta_lower, and acb_hypgeom_beta_lower, which implement the incomplete gamma and beta functions, are interfaced as R functions with identical names and prototypes. Requested by Martin Maechler (GH#5).

• R functions arb_hypgeom_beta and acb_hypgeom_beta wrapping arb_hypgeom_gamma and acb_hypgeom_gamma are provided for completeness. FLINT provides no such entry points as of this writing.

Internals

• R function complex.runif facilitating complex-valued RNG in examples and tests.

Changes in version 0.0.3 (2025-02-23)

Installation

• Function R_flint_abort is declared with keyword macro FLINT_NORETURN conditionally, for compatibility with FLINT 3.0.

• ‘configure’ tests for function d_mul_2exp and ‘src/mag.c’ uses d_mul_2exp conditionally, for compatibility with FLINT 3.0.

• ‘configure’ works around broken ‘flint.pc’ installed by FLINT 3.0.

• ‘configure’ uses simpler prerequisite code when testing whether system header ‘flint/flint.h’ can be compiled.

• ‘src/noreturn.h’ is much refined, for compatibility with FLINT 3.0. The original version triggered clang -Wunknown-attributes.

• ‘src/revertnoreturn.h’ is included after the FLINT headers so that definitions in ‘src/noreturn.h’ do not infect headers included later.

Changes in version 0.0.2 (2025-02-20)

Installation

• An array declaration in ‘src/flint.h’ specified an incorrect (too small) array size, triggering gcc -Wlto-type-mismatch. Thanks to Brian Ripley for the report.

• ‘src/noreturn.h’ is included before the FLINT headers. FLINT 3.1 installs a broken ‘flint/flint.h’ whose use of keyword _Noreturn and keyword macro noreturn is not portable. Thanks to Brian Ripley for the report.

• ‘configure’ wrongly assumed that ‘Rinternals.h’ must be located in ‘'R RHOME'/include’. Thanks to Dirk Eddelbuettel for the report (GH#3).

• More pointers are zero-initialized to appease clang -Wsometimes-uninitialized.

Changes in version 0.0.1 (2025-02-17)

Description

• The package is titled “Fast Library for Number Theory”, matching FLINT.

• Mikael Jagan is the maintainer and sole author.

• Depends: R (>= 4.3) mainly for KaTeX support when rendering Rd to HTML and ‘⁠amsmath⁠’ support when rendering Rd to PDF.

• Depends: methods as flint defines S4 classes, generic functions, and methods.

• Imports: stats as flint provides S3 and S4 methods for quantile.

• SystemRequirements: flint (>= 3), mpfr (>= 3.1), gmp as flint links FLINT, GNU MPFR, and GNU MP. The version requirements are purely informational, as ‘configure’ and ‘configure.win’ scripts check that features used by the package are available.

Installation

• A ‘configure’ script is provided for installation under Unix. The script uses pkg-config where available to determine options for linking FLINT, GNU MPFR, and GNU MP. The user can set environment variables PKG_CONFIG and PKG_CONFIG_PATH to control how pkg-config is invoked and where it searches for ‘*.pc’ files. The script gives precedence to environment variables R_FLINT_CPPFLAGS, R_FLINT_CFLAGS, R_FLINT_LDFLAGS, and R_FLINT_LIBS: if any of these is set, then the script does not use pkg-config. In that case, R_FLINT_LIBS gets a default value -lflint -lmpfr -lgmp. The other R_FLINT_* are empty by default.

• A ‘configure.win’ script is provided for installation under Windows. Currently, it invokes ‘configure’, passing along positional parameters, and does nothing else.

Documentation

• S4 classes, generic functions, and methods are documented under help topics with keyword classes or methods. Interfaces to special mathematical functions are documented under help topics with keyword math. One can use help(package = "flint") or (for example) help.search(package = "flint", keyword = "math") to get a list of (non-internal) help topics.

Classes

• Virtual class flint with nonvirtual subclasses ulong, slong, fmpz, fmpq, mag, arf, acf, arb, and acb. Objects can be understood as vectors of length at most 2^32-1 or 2^64-1 (depending on the ABI) of the so-named C types. The implementation is based on external pointers.

• ulong and slong represent vectors of fixed precision unsigned and signed integers. The integer size is 32 or 64 bits (depending on the ABI).

• fmpz represents vectors of arbitrary precision signed integers.

• fmpq represents vectors of arbitrary precision rational numbers, always in “canonical” form with numerator and positive, coprime denominator

• mag represents vectors of fixed precision error bounds.

• arf and acf represent vectors of arbitrary precision floating-point real and complex numbers.

• arb and acb represent vectors of arbitrary precision floating-point real and complex numbers with error bounds. They support “ball arithmetic”.

Generic Functions

• S4 generic functions Num, Num<-, Den, and Den<- for getting and setting numerators and denominators of quotients.

• S4 generic functions Mid, Mid<-, Rad, and Rad<- for getting and setting midpoints and radii of balls in a metric space.

• S4 generic functions Real, Real<-, Imag, and Imag<- for getting and setting real and imaginary parts of complex numbers.

Methods

• S4 methods are defined for generic (or made-generic) functions [, [<-, [[, [[<-, Complex, Den, Den<-, Imag, Imag<-, Math, Math2, Mid, Mid<-, Num, Num<-, Ops, Rad, Rad<-, Real, Real<-, Summary, all.equal, anyDuplicated, anyNA, as.raw, as.logical, as.integer, as.numeric, as.complex, as.vector, as.matrix, as.array, as.data.frame, as.Date, as.POSIXct, as.POSIXlt, c, coerce, cut, duplicated, findInterval, format, initialize, is.finite, is.infinite, is.na, is.na<-, is.nan, is.unsorted, length, length<-, match, mean, mtfrm, names, names<-, print, quantile, rep, rep.int, rep_len, show, seq, sequence, summary, unique, and xtfrm.

• S3 methods are defined for S3-turned-S4 generic functions. These methods call the S4 generic function so that S4 dispatch occurs if the S3 generic function is called.

New Features

• Generator functions for each of the nonvirtual subclasses of virtual class flint.

• C library functions arb_const_pi, arb_const_log2, arb_const_log10, arb_const_e, arb_lambertw, acb_lambertw, arb_dirichlet_zeta, acb_dirichlet_zeta, arb_dirichlet_hurwitz, acb_dirichlet_hurwitz, acb_dirichlet_lerch_phi, arb_hypgeom_gamma, acb_hypgeom_gamma, arb_hypgeom_rgamma, acb_hypgeom_rgamma, arb_hypgeom_lgamma, acb_hypgeom_lgamma, acb_hypgeom_polygamma, arb_hypgeom_2f1, and acb_hypgeom_2f1 acb_polygamma, acb_dirichlet_zeta, acb_dirichlet_hurwitz, acb_dirichlet_lerch_phi, acb_hypgeom_gamma, acb_hypgeom_rgamma, acb_hypgeom_lgamma, and acb_hypgeom_2f1 are interfaced as R functions with identical names and “prototypes”. Arguments are coerced to the correct class and recycled internally.

• R function flintABI returning the size in bits of C type mp_limb_t, either 32 or 64. The value is determined at configure time.

• R function flintIdentical for testing whether two flint vectors have identical class, length, and “content”. This test is less strict than the test for pointer equality done by identical(x, y) when x and y are external pointers.

• R function flintLength for getting the length of a flint vector as a ulong vector or, optionally, as a traditional numeric vector subject to rounding error.

• R functions flintPrec and flintRnd for getting and setting the global default precision and rounding modes.

• R function flintSize for calculating the number of bytes used by a flint vector.

• R function flintTriple returning a character vector of length 3 of the form c(class, length, address), useful if details about a flint vector must be printed.

• R function flintVersion returning a list containing header and library versions for FLINT, GNU MPFR, and GNU MP. Header versions are determined at compile time. Library versions are determined at run time.

• R function c.flint, the workhorse of the S4 method for c. It is exported to enable users to bypass the internal dispatch mechanism of c, which dispatches on only the first positional argument.