Package {fastgeojson}

Fast Serialization of R Objects to JSON and GeoJSON

Description

as_json() serializes R objects to JSON, and sf objects to GeoJSON, in parallel and with lossless numbers. The encoders are implemented in Rust via extendr.

It takes the arguments of jsonlite::toJSON(), in the same order, and follows jsonlite's output conventions: jsonlite's own test suite runs against it. Two defaults differ: numbers are written losslessly (digits = Inf, where toJSON() rounds to 4 decimal places) and sf objects become GeoJSON (sf = "geojson", where toJSON() writes a record array).

Usage

as_json(
  x,
  dataframe = c("rows", "columns", "values"),
  matrix = c("rowmajor", "columnmajor"),
  Date = c("ISO8601", "epoch"),
  POSIXt = c("string", "ISO8601", "epoch", "mongo"),
  factor = c("string", "integer"),
  complex = c("string", "list"),
  raw = c("base64", "hex", "mongo", "int", "js"),
  null = c("list", "null"),
  na = c("null", "string"),
  auto_unbox = FALSE,
  digits = Inf,
  pretty = FALSE,
  force = FALSE,
  ...
)

Arguments

Details

Coming from jsonlite. Code that calls toJSON() with named arguments can call as_json() with the same ones; pass digits = 4 (and sf = "dataframe" for sf input) to reproduce toJSON()'s defaults. Unknown arguments are accepted through ..., as toJSON() does.

Encoding strategy. as_json() inspects x and dispatches to the appropriate Rust encoder:

• Simple features (sf): a GeoJSON FeatureCollection.

• Data frames: row- or column-oriented, processed in parallel in row chunks for large inputs.

• Atomic vectors and lists: JSON arrays and objects, recursively.

Type mapping.

• Numeric: JSON numbers, exact by default; see digits. NA, NaN, Inf and -Inf follow the na argument.

• Logical: true / false.

• Character: JSON strings. latin1- and native-encoded inputs are translated to UTF-8; bytes that are not valid UTF-8 pass through unchanged, as toJSON() passes them, and a "bytes"-marked string raises the error toJSON() raises.

• Factor: labels, or integer codes when factor = "integer".

• Date / POSIXt: controlled by Date and POSIXt.

• complex / raw: controlled by complex and raw.

Threads. See fastgeojson_threads() to control parallelism.

Value

A length-one character vector of class "json", or c("geojson", "json") for sf input – unless as_bytes = TRUE, which returns an unclassed raw vector holding the same bytes.

See Also

fastgeojson_threads() to control parallelism.

Examples

as_json(list(a = 1, b = "foo", c = NA))
as_json(list(val = 5), auto_unbox = TRUE)

df <- data.frame(x = c(1.5, 2.5), y = c("a", "b"))
as_json(df)
as_json(df, dataframe = "columns")

# Straight out to a file, without interning the result as an R string.
f <- tempfile()
con <- file(f, "wb")
writeBin(as_json(df, as_bytes = TRUE), con)
close(con)
unlink(f)

if (requireNamespace("sf", quietly = TRUE)) {
  nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
  geo <- as_json(nc[1:2, ])
}

Get or set the number of worker threads

Description

Controls how many threads the Rust backend uses for parallel serialization.

Normal use gets the whole machine. The count is resolved in this order: an explicit value set here; then FASTGEOJSON_NUM_THREADS, RAYON_NUM_THREADS, OMP_NUM_THREADS or OMP_THREAD_LIMIT; then two if ⁠R CMD check⁠ is detected (CRAN's policy caps checking at two cores, since the check farm is shared – it places no limit on ordinary use); then the number of available cores.

Usage

fastgeojson_threads(n = NULL)

Arguments

Value

An integer scalar, the number of worker threads in use after the call. Returned invisibly when n is supplied; visibly when it is not.

Examples

fastgeojson_threads()
old <- fastgeojson_threads(2)
fastgeojson_threads(0)