SSBtools (version 1.8.6)

convert_integer64: Convert integer64 data to base R numeric, integer, or character types

Description

Converts integer64 data (from the bit64 package) in a data.frame, list, or vector to base R numeric, integer, or character types.

Usage

convert_integer64(
  df,
  to_integer = "if_fits",
  precision_loss = "character",
  always_character = FALSE
)

Value

The same type of object as the input (data.frame, list, or vector), with all integer64 values converted to base R integer, numeric, or character depending on settings.

Arguments

df

A data.frame, list, or vector to process.

to_integer

Character string controlling how conversion to integer is handled. The rule is applied variable by variable. Must be one of:

• "never" — always convert to numeric, never to integer

• "if_fits" — convert to integer if all values fit within 32-bit range (default)

• "if_summable" — convert to integer if the sum of absolute values fits within 32-bit range

• "always" — always convert to integer, with potential coercion warnings

• "always_quiet" — always convert to integer, suppressing coercion warnings

precision_loss

Character string controlling what happens when 64-bit integers cannot be represented exactly as 64-bit floating-point numbers. Must be one of:

• "character" — convert to character if the value cannot be represented exactly (default)

• "warn" — convert to numeric and allow warnings about precision loss

• "quiet" — convert to numeric but suppress such warnings

always_character

Logical. If TRUE, all integer64 values are converted directly to character, overriding both to_integer and precision_loss. Default is FALSE.

Details

Variables with class integer64 often appear when reading data from Arrow files, for example using arrow::read_parquet(). Arrow supports 64-bit integer values, while the R language (and thus all R packages, including the tidyverse) only supports 32-bit integers and 64-bit floating-point numbers. These 64-bit integers therefore need conversion when loaded into R.

When the input is a data.frame or list, conversion is performed variable by variable, and only those with class integer64 are modified.

Depending on settings, integer64 data are converted to base R integer, numeric (double), or character.

Note that a simpler helper that always converts directly to numeric, without any checks or dependency tests, can be defined as:

              convert_integer64_to_numeric <- function(df) {
                df[] <- lapply(df, function(x) {
                  if (inherits(x, "integer64")) as.numeric(x) else x
                })
                df
              }

See Also

bit64::as.integer64()

Examples

if (requireNamespace("bit64", quietly = TRUE)) {
  x  <- bit64::seq.integer64(2025, 10^9, 3 * 10^8)
  print(x)
  
  print(convert_integer64(x*4, "always_quiet"))
  
  df <- data.frame(a = 11:14, b = x, c = 2 * x, d = 3 * x, e = x * x, f = c(22, 23, 24, 25))
  print(df)

  df1 <- convert_integer64(df, "never")
  df2 <- convert_integer64(df, "if_fits")
  df3 <- convert_integer64(df, "if_summable")
  df4 <- convert_integer64(df, "always_quiet")

  print(sapply(df,  class))
  print(sapply(df1, class))
  print(sapply(df2, class))
  print(sapply(df3, class))
  print(sapply(df4, class))
  
  print(df2)
  print(df4)
  
  cat("# Examples showing that integer64 is problematic:\n")
      y <- bit64::seq.integer64(1, 3)
      print(y)
      print(0.5 * y)
      print(y * 0.5)
      matrix(y, 1, 3)   
}