doc updates for CRAN submission

coolbutuseless · Jan 13, 2024 · c944375 · c944375
1 parent 675e9d2
commit c944375
Show file tree

Hide file tree

Showing 18 changed files with 636 additions and 297 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: yyjsonr
 Type: Package
-Title: A Fast JSON Parser and Generator 
+Title: Fast JSON Parser and Generator 
 Version: 0.1.13
 Authors@R: c(
     person("Mike", "Cheng", role = c("aut", "cre", 'cph'), 
@@ -11,7 +11,7 @@ Maintainer: Mike Cheng <[email protected]>
 Description: A fast JSON parser, generator and validator which converts JSON 
     data to/from R objects.  The standard R data types are supported 
     (e.g. logical, numeric, integer) with configurable handling of NULL and NA 
-    values. Data frames, atomic vectors and  lists are all supported as data 
+    values. Data frames, atomic vectors and lists are all supported as data 
     containers translated to/from JSON.
     This implementation is a wrapper around the 'yyjson' C library.  
 License: MIT + file LICENSE

diff --git a/R/json-opts.R b/R/json-opts.R
@@ -166,8 +166,8 @@ yyjson_write_flag <- list(
 #'        'integer64' type is a \emph{signed} integer type, and a warning will
 #'        be issued if JSON contains an \emph{unsigned} integer which cannot
 #'        be stored in this type.
-#' @param missing_list_elem how to handle missing elements in list columns in 
-#'        data.frames. Options, 'na', or 'null.  Default: 'null'
+#' @param df_missing_list_elem R value to use when elements are missing in list 
+#'        columns in data.frames. Default: NULL
 #' @param obj_of_arrs_to_df logical. Should a named list of equal-length
 #'        vectors be promoted to a data.frame?  Default: TRUE.  If FALSE, then
 #'        result will be left as a list.
@@ -201,27 +201,28 @@ yyjson_write_flag <- list(
 #' opts_read_json()
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 opts_read_json <- function(
-    int64                 = c('string', 'bit64'),
-    missing_list_elem     = c('null', 'na'),
+    promote_num_to_string = FALSE,
+    df_missing_list_elem  = NULL,
     obj_of_arrs_to_df     = TRUE,
     arr_of_objs_to_df     = TRUE,
-    length1_array_asis   = FALSE,
     str_specials          = c('string', 'special'),
     num_specials          = c('special', 'string'),
-    promote_num_to_string = FALSE,
+    int64                 = c('string', 'bit64'),
+    length1_array_asis    = FALSE,
     yyjson_read_flag      = 0L
 ) {
 
   structure(
     list(
-      int64               = match.arg(int64),
-      missing_list_elem   = match.arg(missing_list_elem),
-      obj_of_arrs_to_df   = isTRUE(obj_of_arrs_to_df),
-      arr_of_objs_to_df   = isTRUE(arr_of_objs_to_df),
-      length1_array_asis = isTRUE(length1_array_asis),
-      str_specials        = match.arg(str_specials),
-      num_specials        = match.arg(num_specials),
-      yyjson_read_flag    = as.integer(yyjson_read_flag)
+      promote_num_to_string = isTRUE(promote_num_to_string),
+      df_missing_list_elem  = df_missing_list_elem,
+      obj_of_arrs_to_df     = isTRUE(obj_of_arrs_to_df),
+      arr_of_objs_to_df     = isTRUE(arr_of_objs_to_df),
+      length1_array_asis    = isTRUE(length1_array_asis),
+      str_specials          = match.arg(str_specials),
+      num_specials          = match.arg(num_specials),
+      int64                 = match.arg(int64),
+      yyjson_read_flag      = as.integer(yyjson_read_flag)
     ),
     class = "opts_read_json"
   )
@@ -268,10 +269,10 @@ opts_read_json <- function(
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 opts_write_json <- function( 
     digits            = -1,
+    pretty            = FALSE,
+    auto_unbox        = FALSE,
     dataframe         = c("rows", "columns"),
     factor            = c("string", "integer"),
-    auto_unbox        = FALSE,
-    pretty            = FALSE,
     name_repair       = c('none', 'minimal'),
     num_specials      = c('null', 'string'),
     str_specials      = c('null', 'string'),

diff --git a/R/json.R b/R/json.R
@@ -84,11 +84,9 @@ read_json_file <- function(filename, opts = list(), ...) {
 #'
 #'
 #' @examples
-#' \dontrun{
 #' if (interactive()) {
 #'   read_json_conn(url("https://api.github.com/users/hadley/repos"))
 #' }
-#' }
 #' 
 #' 
 #' @family JSON Parsers
@@ -109,7 +107,7 @@ read_json_conn <- function(conn, opts = list(), ...) {
 #' @param ... Other named options can be used to override any options in \code{opts}.
 #'        The valid named options are identical to arguments to [opts_write_json()]
 #' 
-#' @return Character string
+#' @return Single string containing JSON
 #' 
 #' @family JSON Serializer
 #' @export
@@ -132,7 +130,7 @@ write_json_str <- function(x, opts = list(), ...) {
 #' @inheritParams write_json_str
 #' @param filename filename
 #' 
-#' @return NULL
+#' @return None
 #' @family JSON Serializer
 #' @export
 #' 

diff --git a/README.Rmd b/README.Rmd
@@ -41,33 +41,30 @@ if (FALSE) {
 
 In most cases it is around 2x to 10x faster than `{jsonlite}` at both reading and writing JSON.
 
-It is a wrapper for the [`yyjson`](https://github.com/ibireme/yyjson) C library.
-
-
-### The `yyjson` C library
-
-This package includes the [`yyjson`](https://github.com/ibireme/yyjson) C
-library (version `YYJSON_VERSION_HEX = 0x000700`).  
-
+It is a wrapper for the [`yyjson`](https://github.com/ibireme/yyjson) C library (v0.8.0).
 `yysjon` is MIT licensed - see `LICENSE-yyjson.txt` in this package for more details.
 
 ### What's in the box
 
-|         |          | string              | file                 | raw             | conn             | options              |
-|---------|----------|---------------------|----------------------|-----------------|------------------|----------------------|
-| json    | read     | read_json_str()     | read_json_file()     | read_json_raw() | read_json_conn() | opts_read_json()     |
-|         | write    | write_json_str()    | write_json_file()    |                 |                  | opts_write_json()    |
-|         | validate | validate_json_str() | validate_json_file() |                 |                  |                      |
+This package contains specialised functions for each type of operation (read/write/validate) and the 
+storage location of the JSON (string/file/raw vector/connection).
 
+The matrix of available operations and storage is shown below:
 
+|          | string              | file                 | raw             | conn             | options              |
+|----------|---------------------|----------------------|-----------------|------------------|----------------------|
+| read     | read_json_str()     | read_json_file()     | read_json_raw() | read_json_conn() | opts_read_json()     |
+| write    | write_json_str()    | write_json_file()    |                 |                  | opts_write_json()    |
+| validate | validate_json_str() | validate_json_file() |                 |                  |                      |
 
-### Comparison to other JSON packages
+
+
+### Comparison to other packages with read/write JSON
 
 |              | Write JSON| Read JSON | 
 |--------------|-----------|-----------|
 | yyjsonr      | Fast!     | Fast!     | 
 | jsonlite     | Yes       | Yes       | 
-| RcppSimdJson |           | Fast!     | 
 | jsonify      | Yes       | Yes       | 
 
 
@@ -99,49 +96,6 @@ read_json_str(str)
 ```
 
 
-Parsing differences compared to `{jsonlite}`
-=============================================================================
-
-
-3-d arrays are parsed as multiple 2-d matrices and combined
------------------------------------------------------------------------------
-
-In `{yyjsonr}` the order in which elements in an array are serialized to 
-JSON correspond to an array of row-major matrices in human-readable order.
-
-`{jsonlite}` does things differently. 
-
-The array formats are internally
-consistent within each package, but not cross-compatible between them i.e.
-you cannot serialize an array in `{yyjsonr}` and re-create it exactly 
-using `{jsonlite}`.
-
-
-```{r}
-# A simple 3D array 
-mat <- array(1:12, dim = c(2,3,2))
-mat
-```
-
-
-```{r}
-# jsonlite's serialization of matrices is internally consistent and re-parses
-# to the initial matrix.
-str <- jsonlite::toJSON(mat, pretty = TRUE)
-cat(str)
-jsonlite::fromJSON(str)
-```
-
-
-```{r}
-# yyjsonr's serialization of matrices is internally consistent and re-parses
-# to the initial matrix.
-# But note that it is *different* to what jsonlite does.
-str <- yyjsonr::write_json_str(mat, pretty = TRUE)
-cat(str)
-yyjsonr::read_json_str(str)
-```
-
 
 ## Future
 
@@ -155,7 +109,7 @@ yyjsonr::read_json_str(str)
 ## Limitations
 
 * Some datatypes not currently supported. Please file an issue on GitHub if
-  these types are critical for yoy:
+  these types are critical for you.  Providing test cases also appreciated!:
     * Complex numbers
     * POSIXlt
     * Matrices of POSIXct / Date

diff --git a/README.md b/README.md
@@ -18,32 +18,30 @@ In most cases it is around 2x to 10x faster than `{jsonlite}` at both
 reading and writing JSON.
 
 It is a wrapper for the [`yyjson`](https://github.com/ibireme/yyjson) C
-library.
+library (v0.8.0). `yysjon` is MIT licensed - see `LICENSE-yyjson.txt` in
+this package for more details.
 
-### The `yyjson` C library
-
-This package includes the [`yyjson`](https://github.com/ibireme/yyjson)
-C library (version `YYJSON_VERSION_HEX = 0x000700`).
+### What’s in the box
 
-`yysjon` is MIT licensed - see `LICENSE-yyjson.txt` in this package for
-more details.
+This package contains specialised functions for each type of operation
+(read/write/validate) and the storage location of the JSON
+(string/file/raw vector/connection).
 
-### What’s in the box
+The matrix of available operations and storage is shown below:
 
-|      |          | string              | file                 | raw             | conn             | options           |
-|------|----------|---------------------|----------------------|-----------------|------------------|-------------------|
-| json | read     | read_json_str()     | read_json_file()     | read_json_raw() | read_json_conn() | opts_read_json()  |
-|      | write    | write_json_str()    | write_json_file()    |                 |                  | opts_write_json() |
-|      | validate | validate_json_str() | validate_json_file() |                 |                  |                   |
+|          | string              | file                 | raw             | conn             | options           |
+|----------|---------------------|----------------------|-----------------|------------------|-------------------|
+| read     | read_json_str()     | read_json_file()     | read_json_raw() | read_json_conn() | opts_read_json()  |
+| write    | write_json_str()    | write_json_file()    |                 |                  | opts_write_json() |
+| validate | validate_json_str() | validate_json_file() |                 |                  |                   |
 
-### Comparison to other JSON packages
+### Comparison to other packages with read/write JSON
 
-|              | Write JSON | Read JSON |
-|--------------|------------|-----------|
-| yyjsonr      | Fast!      | Fast!     |
-| jsonlite     | Yes        | Yes       |
-| RcppSimdJson |            | Fast!     |
-| jsonify      | Yes        | Yes       |
+|          | Write JSON | Read JSON |
+|----------|------------|-----------|
+| yyjsonr  | Fast!      | Fast!     |
+| jsonlite | Yes        | Yes       |
+| jsonify  | Yes        | Yes       |
 
 <img src="man/figures/benchmark-summary.png">
 
@@ -217,9 +215,9 @@ yyjsonr::read_json_str(str)
     sake of my sanity.
   - See the `geojson` branch of this repository
 
-## Limitiations
+## Limitations
 
-- Some datatypes not currently supported. Please file an issue on github
+- Some datatypes not currently supported. Please file an issue on GitHub
   if these types are critical for yoy:
   - Complex numbers
   - POSIXlt