1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fromJSON.R, R/toJSON.R
\name{toJSON, fromJSON}
\alias{toJSON, fromJSON}
\alias{fromJSON}
\alias{toJSON}
\alias{jsonlite}
\title{Convert \R{} objects to/from JSON}
\usage{
fromJSON(txt, simplifyVector = TRUE,
simplifyDataFrame = simplifyVector, simplifyMatrix = simplifyVector,
flatten = FALSE, ...)
toJSON(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"), null = c("list", "null"),
na = c("null", "string"), auto_unbox = FALSE, digits = 4,
pretty = FALSE, force = FALSE, ...)
}
\arguments{
\item{txt}{a JSON string, URL or file}
\item{simplifyVector}{coerce JSON arrays containing only primitives into an atomic vector}
\item{simplifyDataFrame}{coerce JSON arrays containing only records (JSON objects) into a data frame}
\item{simplifyMatrix}{coerce JSON arrays containing vectors of equal mode and dimension into matrix or array}
\item{flatten}{automatically \code{\link{flatten}} nested data frames into a single non-nested data frame}
\item{...}{arguments passed on to class specific \code{print} methods}
\item{x}{the object to be encoded}
\item{dataframe}{how to encode data.frame objects: must be one of 'rows', 'columns' or 'values'}
\item{matrix}{how to encode matrices and higher dimensional arrays: must be one of 'rowmajor' or 'columnmajor'.}
\item{Date}{how to encode Date objects: must be one of 'ISO8601' or 'epoch'}
\item{POSIXt}{how to encode POSIXt (datetime) objects: must be one of 'string', 'ISO8601', 'epoch' or 'mongo'}
\item{factor}{how to encode factor objects: must be one of 'string' or 'integer'}
\item{complex}{how to encode complex numbers: must be one of 'string' or 'list'}
\item{raw}{how to encode raw objects: must be one of 'base64', 'hex' or 'mongo'}
\item{null}{how to encode NULL values within a list: must be one of 'null' or 'list'}
\item{na}{how to print NA values: must be one of 'null' or 'string'. Defaults are class specific}
\item{auto_unbox}{automatically \code{\link{unbox}} all atomic vectors of length 1. It is usually safer to avoid this and instead use the \code{\link{unbox}} function to unbox individual elements.
An exception is that objects of class \code{AsIs} (i.e. wrapped in \code{I()}) are not automatically unboxed. This is a way to mark single values as length-1 arrays.}
\item{digits}{max number of decimal digits to print for numeric values. Use \code{I()} to specify significant digits. Use \code{NA} for max precision.}
\item{pretty}{adds indentation whitespace to JSON output. Can be TRUE/FALSE or a number specifying the number of spaces to indent. See \code{\link{prettify}}}
\item{force}{unclass/skip objects of classes with no defined JSON mapping}
}
\description{
These functions are used to convert between JSON data and \R{} objects. The \code{\link{toJSON}} and \code{\link{fromJSON}}
functions use a class based mapping, which follows conventions outlined in this paper: \url{https://arxiv.org/abs/1403.2805} (also available as vignette).
}
\details{
The \code{\link{toJSON}} and \code{\link{fromJSON}} functions are drop-in replacements for the identically named functions
in packages \code{rjson} and \code{RJSONIO}. Our implementation uses an alternative, somewhat more consistent mapping
between \R{} objects and JSON strings.
The \code{\link{serializeJSON}} and \code{\link{unserializeJSON}} functions in this package use an
alternative system to convert between \R{} objects and JSON, which supports more classes but is much more verbose.
A JSON string is always unicode, using \code{UTF-8} by default, hence there is usually no need to escape any characters.
However, the JSON format does support escaping of unicode characters, which are encoded using a backslash followed by
a lower case \code{"u"} and 4 hex characters, for example: \code{"Z\\u00FCrich"}. The \code{fromJSON} function
will parse such escape sequences but it is usually preferable to encode unicode characters in JSON using native
\code{UTF-8} rather than escape sequences.
}
\examples{
# Stringify some data
jsoncars <- toJSON(mtcars, pretty=TRUE)
cat(jsoncars)
# Parse it back
fromJSON(jsoncars)
# Parse escaped unicode
fromJSON('{"city" : "Z\\\\u00FCrich"}')
# Decimal vs significant digits
toJSON(pi, digits=3)
toJSON(pi, digits=I(3))
\dontrun{
#retrieve data frame
data1 <- fromJSON("https://api.github.com/users/hadley/orgs")
names(data1)
data1$login
# Nested data frames:
data2 <- fromJSON("https://api.github.com/users/hadley/repos")
names(data2)
names(data2$owner)
data2$owner$login
# Flatten the data into a regular non-nested dataframe
names(flatten(data2))
# Flatten directly (more efficient):
data3 <- fromJSON("https://api.github.com/users/hadley/repos", flatten = TRUE)
identical(data3, flatten(data2))
}
}
\references{
Jeroen Ooms (2014). The \code{jsonlite} Package: A Practical and Consistent Mapping Between JSON Data and \R{} Objects. \emph{arXiv:1403.2805}. \url{https://arxiv.org/abs/1403.2805}
}
|
