Value - Documentation

new Value(valueopt, parseopt, sort_namesopt)

Description:

Implements a minimal C/C++ JSON data structure with weak-syntax reader/writer.
- Such a value is either
  - an atomic string
    - including string parsable as numeric or boolean value, or
  - a record, i.e., a recursive construct of,
    - an unordered set of value accessed by label, while
    - an array is a record {\tt { 0: a 1: b ...}} indexed by consecutive non negative integer.
- Value functions
  - Element access:
    - value.isMember(name) allows to check if a value is defined,
    - value.at(name) allows to access a value as a record,
      - the at()` is virtual, i.e, can be overloaded allowing to define non-memorized dynamic calculated values.
    - value.get(name, default_typed_value) allows to access an atomic value.
  - Modifiers:
    - value.set(name, value) allows to write a value,
    - value.erase(name) allows to erase a value,
    - value.clear() allows to empty the value.
  - Capacity and property:
    - value.isEmpty() allows to check if the value is empty,
    - value.isRecord() allows to check if the value is a record,
    - value.isArray() allows to check if the value is an array,
    - value.getNames() returns all the record field names, allowing to iterate on the fields,
    - value.size() returns the number of records,
    - value.length() returns the length of the value as an array, allowing to iterate on the array elements.
  - Other operations:
    - value.asString() returns this value as a string,
    - value.equal(another_value) checks if two values are equal,
    - value.sortNames() allows to sort the record field names in alphabetic order,
    - value.sort(before) allows to sort an array,
- Note: The Value is equipped with a equal and less operators and a hash function in order to be used in containers such as std::unordered_map<wjson::Value, T> or std::map<wjson::Value, T>; however in the latter case the order is simply the lexical order of the string representation which is likely semantically biased. A correct semantic order depends on the data type as defined in the symboling package.
- Note: JSON is a read-only reference, i.e. an alias of const wjson::Value& for readability convenience.

Parameters:

Name	Type	Attributes	Default	Description
`value`	string \| bool \| int \| uint \| double \| float \| JSON	<optional>		The initial value.
`parse`	bool	<optional>	`false`	For a string value, if true parses the string, else only copy it.
`sort_names`	bool	<optional>	`false`	For a parsed string value, if true sorts the names in alphabetic order, as performed by sortNames().

Members

(static) EMPTY :Value

Description:

The wjson::Value::EMPTY is a generic read-only empty value.

The wjson::Value::EMPTY is a generic read-only empty value.

Type:

Value

Methods

asString(prettyopt, strictopt, fastopt) → {string}

Description:

Returns the data structure as a string.
- This allows to check if two data structures are equal for the modified semantic:
  - Two literal values are equal if and only the literal string value asString() are equal, see equals().
  - Two data structures are equal if and only each item are inserted in the same order and equal.

Parameters:

Name	Type	Attributes	Default	Description
`pretty`	bool	<optional>	`false`	If true properly format in 2D, else returns a minimal raw format.
`strict`	bool	<optional>	`false`	If true strict JSON syntax, else produces a weak JSON syntax.
`fast`	bool	<optional>	`false`	If fast serializes the data as fast as possible (quoting all words without any lexical analysis).

Returns:

The value as a string.

Type: string

isEmpty() → {bool}

Description:

Returns true if this structure is empty, i.e., without any field not literal value.
- As a literal, the empty value casts to the empty string "", the boolean false value, the integral number 0, or the floating point number NAN.
- An empty record corresponds to parsing {} and an empty array to parsing [].
- The clear() methods allows to clear all value content.

Returns:

The check result.

Type: bool

isRecord() → {bool}

Description:

Returns true if this structure is a non empty record, false otherwise.
- A value is a record as soon as a field as been defined using the subscript [] operator.
- By contract an array corresponds to a record with numerical keys. It is thus a record.
- An object is atomic if and only if it is not a record.

Returns:

The check result.

Type: bool

isArray() → {bool}

Description:

Returns true if this structure is an array, false otherwise.

Returns:

Returns true if it is a record with only consecutive non negative integral numerical keys of syntax (0|[1-9][0-9]*).

Type: bool

isMember(name) → {bool}

Description:

Returns true if this structure has the given field defined, false otherwise.

Parameters:

Name	Type	Description
`name`	string \| uint	The field key name or numerical index.

Returns:

Returns true of defined.

Type: bool

length() → {uint}

Description:

Returns the number of numerically indexed fields.

The size of the record, i.e., the number of fields is returned by size().

// Given a Value array the indexed field iterator writes:
for(unsigned int i = 0; i < value.length(); i++) {
  const Value& field_value = value.at(i);
  Value& field_value = value[i];
../..

Returns:

The numerical indexed field count.

Type: uint

getNames() → {Array.<string>}

Description:

Returns the field names in the insertion order.

// Given a Value record the structure field names iterator writes:
for(auto it = value.getNames().cbegin(); it != value.getNames().cend(); ++it) {
  std::string field_name = *it;
  const Value& field_value = value.at(field_name);
  Value& field_value = value[field_name];
../..

Returns:

A std::vector<std::string> with the field key names or index in insertion order.

Type: Array.<string>

size() → {uint}

Description:

Returns the number of fields with either literal or numerical index.
- If the record is an array, its length, i.e., the number of fields with numerical indexes is returned by length().
- This is a simple shortcut for ``getNames().size()`.

Returns:

The numerical indexed field count.

Type: uint

get(nameopt, default_value) → {string|bool|int|double|double|float|char|Value}

Description:

Returns the literal value of a given field of this structure.

 wjson::Value value("{ number: 3.1416, no: FaLsE }", true);
 double v1 = value.get("number", NAN); // Returns 3.1416 up to the machine precision, since the value is parsable as a double.
 double v2 = value.get("no", NAN); // Returns the default value NAN, since the value is not parsable as a double.
 float v3 = value.get("number", 0.0f); // Returns 3.1416 up to the machine precision, since the value is parsable as a float.
 float v4 = value.get("no", 0.0f); // Returns 0.0, since the value is not parsable as a float.
 int v5 = value.get("number", 0); // Returns 3 since the value is numerically parsable and rounds to the integer value 3.
 bool v6 = value.get("no", true); // Returns false since the value parses as a boolean.
 bool v7 = value.get("number", true); // Returns the default value true since the value is not parsable as a boolean.

Parameters:

Name Type Attributes Description

Name	Type	Attributes	Description
`name`	string \| uint	<optional>	The field key name or numerical index. If the field is omitted, returns the literal value of this value.
`default_value`	string \| bool \| int \| uint \| double \| float \| char \| Value		A default value, defining also the field type.

name

string | uint

The field key name or numerical index.

If the field is omitted, returns the literal value of this value.

default_value

A default value, defining also the field type.

Returns:

The value with the type corresponding to the default value.

If the field is undefined, unparsable or out of range, the default value is returned.
A numeric value is parsed as a double and rounded if returned as an integer.
If the type is bool the string is converted to lower-case and valid if equal to "true" or "false".
If the type is char the first char of the string value is considered.

Type: string | bool | int | double | double | float | char | Value

at(name) → {Value}

Description:

Returns a given field of this structure.

  Value value = jsonValue.at(name_or_index); // Allows to get a read-only version of a field value.
  Value value = jsonValue[name_or_index];    // Allows to get a field value, and create if not yet defined.

This method is virtual, it thus can be overloaded to define non-memorized dynamic calculated values.

Parameters:

Name	Type	Description
`name`	string \| uint	The field key name or numerical index.

Returns:

The field value as a read-only structured value. If undefined, returns an empty data structure.

Type: Value

set(name, value) → {Value}

Description:

Sets a given field of this structure.

Setting a value:

  jsonValue.set(name_or_index, value);          // Allows to set a non-empty field value.
  jsonValue[name_or_index] = value;             // Allows to set a non-empty or empty field value.

Unsetting a value:
- Note the semantic difference between the set() method and the [] operator

  jsonValue.erase(name_or_index);               // Allows to unset a field value.
  jsonValue.set(name_or_index, EMPTY);          // Allows to unset a field value.
  jsonValue[name_or_index] = EMPTY;             // Allows to explicitly set a field to the EMPTY value.

Appending a value to an array:

  jsonValue[jsonValue.length()] = value;        // Allows to append a field value to the jsonValue array.
  jsonValue.add(value);                         // Allows to append a field value to the jsonValue array.

while the add() method allows also to insert/delete value in an array. A construct of the following form allows to set a field value on a temporary clone of a read-only value, thus not modifying the value.

  Value& otherValue = jsonValue.clone().set(name_or_index, value);

Parameters:

Name	Type	Description
`name`	string \| uint	The field key name or numerical index.
`value`	Value	The field value. The value is copied.

Returns:

A reference to this value, allowing to chain set methods:

 value.set(name_or_index, value).set(another_name_or_index, another_value);

Type: Value

add(index, value) → {Value}

Description:

Adds, inserts or deletes a value in this data structure viewed as a list.

Setting a value:

  jsonValue.add(index, value);          // Allows to insert a value at this index, shifting all sub-sequence values to the right.
  jsonValue.add(index, EMPTY);          // Allows to delete a value at this index, shifting all sub-sequence values to the left.
  jsonValue.add(value);                 // Allows to append a value

A construct of the following form allows to set a field value on a temporary clone of a read-only value, thus not modifying the value.

  Value& otherValue = jsonValue.clone().add(name_or_index, value);

Parameters:

Name	Type	Description
`index`	uint	The numerical index.
`value`	Value	The field value. The value is copied.

Returns:

A reference to this value, allowing to chain set methods:

 value.add(value).set(another_name_or_index, another_value);

Type: Value

copy(value) → {Value}

Description:

Copies all fields of a record or array.

Parameters:

Name	Type	Description
`value`	Value	The record or array field value. The value is copied.

Returns:

A reference to this value, allowing to chain set methods.

Type: Value

erase(nameopt)

Description:

Erases a given field.
- When erased the corresponding value is an empty data structure.

Parameters:

Name	Type	Attributes	Description
`name`	string \| uint	<optional>	The field key name or numerical index.

rename(old_name, new_name) → {bool}

Description:

Renames a given field without changing the field order.

Parameters:

Name	Type	Description
`old_name`	string	The old field key name.
`new_name`	string	The new field key name.

Returns:

True if the old name has been found, false otherwise.

Type: bool

clear(preserveTypeopt)

Description:

Erases all fields and literal content of this value.

Parameters:

Name	Type	Attributes	Default	Description
`preserveType`	bool	<optional>	`false`	If true a record becomes an empty record `{}` and an array an empty array `[]`. Otherwise the object becomes atomic.

sort(before)

Description:

Sorts the numerically indexed values according to the comparison function.

Only applies on numerically indexed values: Key order, and named value are not affected.

struct Before {
  // Sorts in numerical order considering values as unsigned int
  static bool before(JSON lhs, JSON rhs) {
    return lhs.get(0u) < rhs.get(0u);
  }
};
jsonValue.sort(Before::before);

Parameters:

Name Type Description

Name	Type	Description
`before`	function	A `static bool before(JSON lhs, JSON rhs)` which returns `true` if the first argument is less than (i.e., is ordered before) the second.

before

function

A static bool before(JSON lhs, JSON rhs)

which returns true if the first argument is less than (i.e., is ordered before) the second.

sortNames()

Description:

Sorts the names and indexes in alphabetic order.
- This allows two values with the same field's value to be syntactically equal.
- Numerical indexes are sorted in numerical order and non numerical indexes in alphabetic orders, and sorted after the numerical indexes.
- This applies recursively on sub-values.

equals(value)

Description:

Returns true if this date equals the given value.
- Two literal values are equal if and only the literal string value are equal, see equals().
- Also available using the == or != operator syntax.

Parameters:

Name	Type	Description
`value`		The value to compare with.

Returns:

True if both values are equal.