How a5R stores cell IDs without strings

The problem

An A5 cell ID is a 64-bit unsigned integer (u64). R has no native u64 type — its integers are 32-bit signed (-2^31 to 2^31 - 1), and its doubles are 64-bit floating point. A double can only represent integers exactly up to 2^53, while a u64 can go up to 2^64 - 1.

The obvious workaround is to store cell IDs as hex strings ("0800000000000006"). This works, but every trip across the R–Rust boundary requires hex parsing and formatting — O(n) string allocation that dominates the cost of lightweight operations like a5_get_resolution() or a5_cell_to_parent().

The solution: eight raw-byte fields

A u64 is exactly 8 bytes. We store each byte of the little-endian representation as a separate raw vector field in a vctrs record type:

cell_id (u64):  0x0800000000000006

little-endian bytes:
  b1 = 0x06, b2 = 0x00, b3 = 0x00, b4 = 0x00,
  b5 = 0x00, b6 = 0x00, b7 = 0x00, b8 = 0x08

This is lossless — the eight bytes are the exact same bits as the original u64, just stored across eight contiguous raw vectors. No precision loss, no special-case handling. On the Rust side, reconstructing the u64 from the eight byte slices is a single u64::from_le_bytes() call. This also avoids pointers, so there is no need to think about serialization when saving an a5_cell object to disk.

R-side: a vctrs record type

On the R side, a5_cell is a vctrs record (vctrs::new_rcrd()) with eight fields (b1 through b8):

library(a5R)
cell <- a5_lonlat_to_cell(-3.19, 55.95, resolution = 10)
vctrs::field(cell, "b1")
#> [1] 00
vctrs::field(cell, "b8")
#> [1] 63

Each field is a plain raw vector — a contiguous block of memory with no per-element overhead. Subsetting, combining, and NA propagation are all handled automatically by vctrs.

Hex strings are only produced on demand:

# Display calls format(), which converts to hex for readability
cell
#> <a5_cell[1]>
#> [1] 6344be8000000000

# Explicit conversion
a5_u64_to_hex(cell)
#> [1] "6344be8000000000"

# Round-trip from hex
a5_cell("0800000000000006")
#> <a5_cell[1]>
#> [1] 0800000000000006

Why this matters

Compare memory for one million cells:

set.seed(42)
cells <- a5_lonlat_to_cell(
  runif(1e6, -180, 180),
  runif(1e6, -80, 80),
  resolution = 10
)

# rcrd: eight contiguous raw vectors (8 × 1 byte × 1M ≈ 7.6 MB)
format(object.size(cells), units = "MB")
#> [1] "7.6 Mb"

# equivalent hex strings would be ~81 MB
# (16 chars + 56-byte SEXP header per string)
hex <- a5_u64_to_hex(cells)
format(object.size(hex), units = "MB")
#> [1] "81 Mb"

NA handling

A5 cell IDs use 60 “quintants” (values 0–59) in their top 6 bits. Quintant 63 (binary 111111) is invalid in the A5 system, so we use 0xFC00000000000000 as a sentinel value for NA. In little-endian, the last byte (b8) is 0xFC, making NA detection a fast single-byte check.

On the Rust side, the sentinel is detected and mapped to None. Standard R idioms work as expected:

cells_with_na <- a5_cell(c("0800000000000006", NA))
is.na(cells_with_na)
#> [1] FALSE  TRUE

Summary