JSON C++ Object Wrapper

Wrapper around a C++ nlohmann::json object

This class is intended for advanced use cases in which users require detailed control of sampling algorithms and data structures. Minimal input validation and error checks are performed – users are responsible for providing the correct inputs. For tutorials on the "proper" usage of the stochtree's advanced workflow, we provide several vignettes at https://stochtree.ai/

Public fields

json_ptr: External pointer to a C++ nlohmann::json object
num_forests: Number of forests in the nlohmann::json object
forest_labels: Names of forest objects in the overall nlohmann::json object
num_rfx: Number of random effects terms in the nlohman::json object
rfx_container_labels: Names of rfx container objects in the overall nlohmann::json object
rfx_mapper_labels: Names of rfx label mapper objects in the overall nlohmann::json object
rfx_groupid_labels: Names of rfx group id objects in the overall nlohmann::json object

Methods

Method `new()`

Create a new CppJson object.

Usage

CppJson$new()

Returns

A new CppJson object.

Method `add_forest()`

Convert a forest container to json and add to the current CppJson object

Usage

CppJson$add_forest(forest_samples, forest_label = "")

Arguments

forest_samples: ForestSamples R class
forest_label: Key under the forests subfolder to store this container. Defaults to an auto-numbered forest_<n> label when empty.

Returns

None

Method `add_random_effects()`

Convert a random effects container to json and add to the current CppJson object

Usage

CppJson$add_random_effects(rfx_samples)

Arguments

rfx_samples: RandomEffectSamples R class

Returns

None

Method `add_scalar()`

Add a scalar to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_scalar(field_name, field_value, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_value: Numeric value of the field to be added to json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_integer()`

Add a scalar to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_integer(field_name, field_value, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_value: Integer value of the field to be added to json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_boolean()`

Add a boolean value to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_boolean(field_name, field_value, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_value: Numeric value of the field to be added to json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_string()`

Add a string value to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_string(field_name, field_value, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_value: Numeric value of the field to be added to json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_vector()`

Add a vector to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_vector(field_name, field_vector, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_vector: Vector to be stored in json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_integer_vector()`

Add an integer vector to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_integer_vector(field_name, field_vector, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_vector: Vector to be stored in json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_string_vector()`

Add an array to the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$add_string_vector(field_name, field_vector, subfolder_name = NULL)

Arguments

field_name: The name of the field to be added to json
field_vector: Character vector to be stored in json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which to place the value

Returns

None

Method `add_list()`

Add a list of vectors (as an object map of arrays) to the json object under the name "field_name"

Usage

CppJson$add_list(field_name, field_list)

Arguments

field_name: The name of the field to be added to json
field_list: List to be stored in json

Returns

None

Method `add_string_list()`

Add a list of vectors (as an object map of arrays) to the json object under the name "field_name"

Usage

CppJson$add_string_list(field_name, field_list)

Arguments

field_name: The name of the field to be added to json
field_list: List to be stored in json

Returns

None

Method `get_scalar()`

Retrieve a scalar value from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_scalar(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `get_integer()`

Retrieve a integer value from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_integer(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `get_boolean()`

Retrieve a boolean value from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_boolean(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `get_string()`

Retrieve a string value from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_string(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `contains()`

Whether the json object contains a field "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$contains(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to check for
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

Logical, TRUE if the field is present

Method `get_scalar_or_default()`

Retrieve a scalar value, returning default if the field is absent. Used to "augment" older JSON within a schema version (see RFC 0005).

Usage

CppJson$get_scalar_or_default(field_name, default, subfolder_name = NULL)

Arguments

field_name: The name of the field
default: Value returned if the field is absent
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

The stored value, or default if absent

Method `get_integer_or_default()`

Retrieve an integer value, returning default if the field is absent.

Usage

CppJson$get_integer_or_default(field_name, default, subfolder_name = NULL)

Arguments

field_name: The name of the field
default: Value returned if the field is absent
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

The stored value, or default if absent

Method `get_boolean_or_default()`

Retrieve a boolean value, returning default if the field is absent.

Usage

CppJson$get_boolean_or_default(field_name, default, subfolder_name = NULL)

Arguments

field_name: The name of the field
default: Value returned if the field is absent
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

The stored value, or default if absent

Method `get_string_or_default()`

Retrieve a string value, returning default if the field is absent.

Usage

CppJson$get_string_or_default(field_name, default, subfolder_name = NULL)

Arguments

field_name: The name of the field
default: Value returned if the field is absent
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

The stored value, or default if absent

Method `rename_field()`

Rename a field "old_name" to "new_name" (with optional subfolder). No-op if "old_name" is absent. Used by JSON schema migrations (RFC 0005).

Usage

CppJson$rename_field(old_name, new_name, subfolder_name = NULL)

Arguments

old_name: Current field name
new_name: New field name
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

None

Method `erase_field()`

Erase a field "field_name" (with optional subfolder). No-op if absent.

Usage

CppJson$erase_field(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to erase
subfolder_name: (Optional) Name of the subfolder / hierarchy

Returns

None

Method `get_vector()`

Retrieve a vector from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_vector(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `get_integer_vector()`

Retrieve an integer vector from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_integer_vector(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `get_string_vector()`

Retrieve a character vector from the json object under the name "field_name" (with optional subfolder "subfolder_name")

Usage

CppJson$get_string_vector(field_name, subfolder_name = NULL)

Arguments

field_name: The name of the field to be accessed from json
subfolder_name: (Optional) Name of the subfolder / hierarchy under which the field is stored

Returns

None

Method `get_numeric_list()`

Reconstruct a list of numeric vectors from the json object stored under "field_name"

Usage

CppJson$get_numeric_list(field_name, key_names)

Arguments

field_name: The name of the field to be added to json
key_names: Vector of names of list elements (each of which is a vector)

Returns

None

Method `get_string_list()`

Reconstruct a list of string vectors from the json object stored under "field_name"

Usage

CppJson$get_string_list(field_name, key_names)

Arguments

field_name: The name of the field to be added to json
key_names: Vector of names of list elements (each of which is a vector)

Returns

None

Method `return_json_string()`

Convert a JSON object to in-memory string

Usage

CppJson$return_json_string()

Returns

JSON string

Method `save_file()`

Save a json object to file

Usage

CppJson$save_file(filename)

Arguments

filename: String of filepath, must end in ".json"

Returns

None

Method `load_from_file()`

Load a json object from file

Usage

CppJson$load_from_file(filename)

Arguments

filename: String of filepath, must end in ".json"

Returns

None

Method `load_from_string()`

Load a json object from string

Usage

CppJson$load_from_string(json_string)

Arguments

json_string: JSON string dump

Returns

None

Public fields

Methods

Public methods

Method new()

Usage

Returns

Method add_forest()

Usage

Arguments

Returns

Method add_random_effects()

Usage

Arguments

Returns

Method add_scalar()

Usage

Arguments

Returns

Method add_integer()

Usage

Arguments

Returns

Method add_boolean()

Usage

Arguments

Returns

Method add_string()

Usage

Arguments

Returns

Method add_vector()

Usage

Arguments

Returns

Method add_integer_vector()

Usage

Arguments

Returns

Method add_string_vector()

Usage

Arguments

Returns

Method add_list()

Usage

Arguments

Returns

Method add_string_list()

Usage

Arguments

Returns

Method get_scalar()

Usage

Arguments

Returns

Method get_integer()

Usage

Arguments

Returns

Method get_boolean()

Usage

Arguments

Returns

Method get_string()

Usage

Arguments

Returns

Method contains()

Usage

Arguments

Returns

Method get_scalar_or_default()

Usage

Arguments

Returns

Method get_integer_or_default()

Usage

Arguments

Returns

Method get_boolean_or_default()

Method `new()`

Method `add_forest()`

Method `add_random_effects()`

Method `add_scalar()`

Method `add_integer()`

Method `add_boolean()`

Method `add_string()`

Method `add_vector()`

Method `add_integer_vector()`

Method `add_string_vector()`

Method `add_list()`

Method `add_string_list()`

Method `get_scalar()`

Method `get_integer()`

Method `get_boolean()`

Method `get_string()`

Method `contains()`

Method `get_scalar_or_default()`

Method `get_integer_or_default()`

Method `get_boolean_or_default()`

Method `get_string_or_default()`

Method `rename_field()`

Method `erase_field()`

Method `get_vector()`

Method `get_integer_vector()`

Method `get_string_vector()`

Method `get_numeric_list()`

Method `get_string_list()`

Method `return_json_string()`

Method `save_file()`

Method `load_from_file()`

Method `load_from_string()`