R: Convert an R object to a string in Javascript Object Notation
toJSON
R Documentation
Convert an R object to a string in Javascript Object Notation
Description
This function and its methods convert an R object into a string
that represents the object in Javascript Object Notation (JSON).
The different methods try to map R's vectors to JSON arrays and
associative arrays. There is ambiguity here as an R vector of length 1
can be a JSON scalar or an array with one element. When there are
names on the R vector, the descision is clearer.
We have introduced the emptyNamedList variable to identify
an empty list that has an empty names character vector and so
maps to an associative array in JSON, albeit an empty one.
Objects of class AsIs in R, i.e. that are enclosed in a call to
I() are treated as containers even if they are of length 1.
This allows callers to indicate the desired representation of an R "scalar"
as an array of length 1 in JSON
additional arguments controlling the formatting of the
JSON.
container
a logical value indicating whether to treat the
object as a vector/container or a scalar and so represent it as an
array or primitive in JavaScript.
collapse
a string that is used as the separator when combining the individual lines of the
generated JSON content
.level
an integer value. This is not a parameter the caller is supposed to supply. It is a
value that is passed in recursive calls to identify the top-level and sub-level serialization to JSON
and so help to identify when a scalar needs to be in a container and when it is legitimate to
output a scalar value directly.
.withNames
a logical value. If we are dealing with a named
vector/list, we typically generate a JSON associative
array/dictionary. If there are no names, we create a simple array.
This argument allows us to explicitly control whether we use a
dictionary or to ignore the names and use an array.
.na
a value to use when we encounter an NA value in the R
objects. This allows the caller to convert these to whatever makes
sense to them. For example, we might specify this as "null"
and then the NA values will appear as null in the JSON
output. One can also specify an unusual numeric value, e.g. -9999999
to indicate a missing value!
.escapeEscapes
a logical value that controls how
new line and tab characters are serialized. If this is TRUE,
we preserve them symbolically by escaping the .
Otherwise, we replace them with their literal value.
pretty
a logical value that controls if extra processing is done
on the result to make it indented for easier human-readability.
At present, this reparses the generated JSON content and
re-formats it (using libjson). This means that there
can be three copies of the data in memory simultaneously -
the original data, the JSON text and the pretty-printed
version of the JSON text. For large objects, this can
require a lot of memory.
asIs
a logical value that, if TRUE causes
R vectors of length 1 to be represented as arrays in JSON,
but if FALSE to be represented as scalars, where appropriate
(i.e. not the top level of the JSON content). This avoids having
to explicitly mark sub-elements in an R object as being of class
AsIs.
.inf
how to represent infinity in JSON. This should be a string.