Configuration Options for Serializing to JSON

In yyjsonr: Fast 'JSON', 'NDJSON' and 'GeoJSON' Parser and Generator

knitr::opts_chunk$set(
  collapse = FALSE,
  comment = "#>"
)

suppressPackageStartupMessages({
  library(yyjsonr)
})

Overview

This vignette:

• introduces the opts argument for writing JSON with the write_json_X() family of functions.
• outlines the creation of default options with opts_write_json()
• provides extended examples of how these options control writing JSON

The opts argument - Specifying options when reading JSON

All write_json_x() functions have an opts argument. opts takes a named list of options used to configure the way yyjsonr writes JSON from R objects.

The default argument for opts is an empty list, which internally sets the default options for writing.

The default options for writing JSON can also be viewed by running opts_write_json().

The following three function calls are all equivalent ways of calling write_json_str() using the default options:

write_json_str(iris)
write_json_str(iris, opts = list())
write_json_str(iris, opts = opts_write_json())

Setting arguments to override the default options

Setting a single option (and keeping all other options at their default value) can be done in a number of ways.

The following three function calls are all equivalent:

write_json_str(iris, opts = list(str_specials = 'string'))
write_json_str(iris, opts = opts_write_json(str_specials = 'string'))
write_json_str(iris, str_specials = 'string')

Option digits - Number of decimal places for numeric values

The digits option controls the number of decimal places output for numeric values. The default value of digits = -1 indicates that the internal yyjson C library formatting should be used.

robj <- c(1, 1.23, 3.141592654)
write_json_str(robj)
write_json_str(robj, digits = 2)
write_json_str(robj, digits = 0)

Option pretty - Use whitespace to make the JSON pretty

The pretty option is a logical value indicating whether or not whitespace should be used to make the resulting JSON more readable.

robj <- head(iris, 2)
write_json_str(robj) |> cat()
write_json_str(robj, pretty = TRUE) |> cat()

Option auto_unbox - Handling for R vectors of length 1

The auto_unbox option is a logical value indicating whether single values should be written as JSON scalars or JSON arrays (with length 1).

When auto_unbox = FALSE (the default), single values are always written as a JSON array i.e. within [] brackets.

When auto_unbox = TRUE, single values are written as bare JSON scalar values

robj <- list(1, c(1, 2), NA)
write_json_str(robj) |> cat()
write_json_str(robj, auto_unbox = TRUE) |> cat()

Option dataframe - Orientation of data.frame output

The dataframe option controls the orientation of the data output to JSON:

• dataframe = "rows" (the default) writes the data one-row-at-a-time as a JSON [] array containing a JSON {} object for each row.
• dataframe = "cols" writes the data one-column-at-a-time as a JSON {} object containing JSON [] arrays.

robj <- head(iris, 3)
write_json_str(robj, pretty = TRUE) |> cat()
write_json_str(robj, pretty = TRUE, dataframe = "cols") |> cat()

Option factor - factor representation

The factor option indicates whether factors should be output as string (the default) or integer values.

set.seed(1)

robj <- sample(iris$Species, 10)
write_json_str(robj) |> cat()
write_json_str(robj, factor = 'integer') |> cat()

Option name_repair - Dealing with missing names in lists

When writing R lists which are only partially named, name_repair controls the names which are generated for the JSON output.

• name_repair = "none" (the default) means that no names are created, and an empty string will be used as the key.
• name_repair = "minimal" will generate default names for each unnamed list item based upon its position in the list.

robj <- list(a = 1, b = 2, 67)
write_json_str(robj, pretty = TRUE) |> cat()
write_json_str(robj, pretty = TRUE, name_repair = 'minimal') |> cat()

Option num_specials - Writing numeric NA, NaN and Inf

JSON only has a single null value as a representation of missing-ness or special-ness of a value. That is, it has no natural representations to distinguish the special R numeric values like NA, NaN and Inf.

The num_specials option configures handling of these values in the JSON output:

• num_specials = "null" (the default) will write special numeric values as JSON null values.
• num_specials = "string" will write string representations of these values.

robj <- c(1.23, NA_real_, NaN, Inf, -Inf)
write_json_str(robj) |> cat()
write_json_str(robj, num_specials = 'string') |> cat()

Option str_specials - Writing character NA

JSON only has a single null value as a representation of missing-ness or special-ness of a value. That is, it has no specific representation of NA_character_.

The str_specials option configures handling of NA_character_ values in the JSON output:

• str_specials = "null" (the default) will write NA_character_ as JSON null.
• str_specials = "string" will write NA_character_ as "NA".

robj <- c("hello", NA_character_)
write_json_str(robj) |> cat()
write_json_str(robj, str_specials = 'string') |> cat()

Option yyjson_write_flag - internal YYJSON C library options

The yyjson C library supports a number of internal options for writing JSON.

These options are considered advanced, and the user is referred to the yyjson documentation for further explanation on what they control.

Warning: some of these advanced options do not make sense for interfacing with R, or otherwise conflict with how this package converts R objects to JSON.

# A reference list of all the possible YYJSON options
yyjsonr::yyjson_write_flag

write_json_str(
  c('hello / there', '#RStats'),
  opts = opts_write_json(yyjson_write_flag = c(
    yyjson_write_flag$YYJSON_WRITE_ESCAPE_SLASHES
  ))
) |> cat()

yyjsonr documentation built on May 29, 2024, 3:01 a.m.