Skip to content

Commit

Permalink
docs: add information about json_string
Browse files Browse the repository at this point in the history
  • Loading branch information
esynr3z committed May 29, 2024
1 parent 058530c commit 4452d25
Showing 1 changed file with 54 additions and 4 deletions.
58 changes: 54 additions & 4 deletions docs/modules/ROOT/pages/user.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -130,10 +130,10 @@ NOTE: SystemVerilog associative array is used to implement JSON object. As a con
| `new(values_t values)` | Create an instance from an associative array.
| `json_object from(values_t values)` | Static method to create an instance from an associative array. Alternative to standard constructor.
| `json_value get(string key)` | Get a value at the provided key.
| `set(string key, json_value value)` | Set the given value for the provided key.
| `void set(string key, json_value value)` | Set the given value for the provided key.
| `values_t get_values()` | Get all internal values as associative array.
| `keys_t get_keys()` | Get all keys for internal values as queue.
| `flush()` | Remove all stored values.
| `void flush()` | Remove all stored values.
| `size()`, `exists()`, `delete()`, `first()`, `last()`, `next()`, `prev()` | Thin wrappers over the standard associative array methods which also mimic their signature and return values.
|===

Expand All @@ -151,18 +151,68 @@ so you can expect that this class will operate according to behavior of an origi
| `new(values_t values)` | Create an instance from a queue.
| `json_array from(values_t values)` | Static method to create an instance from a queue. Alternative to standard constructor.
| `json_value get(int index)` | Get a value at the provided index.
| `set(int index, json_value value)` | Set the given value for the provided index.
| `void set(int index, json_value value)` | Set the given value for the provided index.
| `values_t get_values()` | Get all internal values as queue.
| `flush()` | Remove all stored values.
| `void flush()` | Remove all stored values.
| `size()`, `insert()`, `delete()`, `push_front()`, `push_back()`, `pop_front()`, `pop_back()` | Thin wrappers over the standard queue methods which also mimic their signature and return values.
|===

=== String

`{class-json-string}` wrapper class represens standard JSON string value type using SV string.

IMPORTANT: `\b` and `\u` escape sequences are not supported.

.json_string methods outline
[cols="1,1"]
|===
| `new(string value)` | Create an instance from a string.
| `json_string from(string value)` | Static method to create an instance from a string. Alternative to standard constructor.
| `string get()` | Get internal string value.
| `void set(string value)` | Set internal string value.
|===

==== Extension: Enum

`{class-json-enum}#(ENUM_T)` wrapper class, that inherits from `{class-json-string}` and represens SV `enum` value as standard JSON string.
The class is parametrized with type `ENUM_T` to work with any enumeration.

Purpose of this class is to facilitate using SV enum with JSON decoder/encoder. For example, JSON values tree can be created with `{class-json-enum}` instances and then they can be seamlessly converted to strings during encoding. And vice versa for decoding.

.json_enum#(ENUM_T) methods outline
[cols="1,1"]
|===
| `new(ENUM_T value)` | Create an instance from an `enum`.
| `json_enum#(ENUM_T) from(ENUM_T value)` | Static method to create an instance from an `enum`. Alternative to standard constructor.
| json_result#(json_enum#(ENUM_T)) from_string(string value) | Static method to create an instance from a `string`. Alternative to standard constructor. This option is failable, because only specific string (enumeration variants) can be used to create valid `json_enum`.
| `string get()` | Get internal enum value as a string.
| `void set(string value)` | Set internal enum value from a string. This function may fail due to wrong value is provided, and this fail is unrecoverable (fatal).
| `ENUM_T get_enum()` | Get internal enum value.
| `void set_enum(ENUM_T value)` | Set internal enum value.
|===

==== Extension: Bit Vector

`{class-json-bits}#(BITS_T)` wrapper class, that inherits from `{class-json-string}` and represens SV bit vector value (e.g. `bit[511:0]`) as standard JSON string.
The class is parametrized with type `BITS_T` to work with any bit vector - any width, signed or unsigned. Packed structures can be used as well.

Purpose of this class is to facilitate using SV bit vectors of arbitrary size with JSON decoder/encoder.
As a result, any number, that cannot be represented as JSON number using `longint` or `real`, can be represented as a string.

There is an internal property `preferred_radix`, that can take values: `json_bits::RADIX_DEC`, `json_bits::RADIX_BIN` or `json_bits::RADIX_HEX`. This property can be changed any time and affects how bit vector is converted to the string - what base is used.

.json_bits#(BITS_T) methods outline
[cols="1,1"]
|===
| `new(BITS_T value, radix_e preferred_radix=RADIX_DEC)` | Create an instance from a bit vector.
| `json_bits#(BITS_T) from(BITS_T value, radix_e preferred_radix=RADIX_DEC)` | Static method to create an instance from a bit vector. Alternative to standard constructor.
| `json_result#(json_bits#(BITS_T)) from_string(string value)` | Static method to create an instance from a `string`. Alternative to standard constructor. This option is failable, because only specific string can be used to create valid `json_bits`. It should contain only numbers "0"-"9", letters "a"-"f". Prefix "0x" is allowed for hexadecimal values and "0b" for binary ones. Radix is discovered automatically and saved into `preferred_radix`.
| `string get()` | Get internal bit vector value as a string.
| `void set(string value)` | Set internal bit vector value from a string. This function may fail due to wrong value is provided, and this fail is unrecoverable (fatal).
| `BITS_T get_bits()` | Get internal bit vector value.
| `set_bits(BITS_T value)` | Set internal bit vector value.
|===

=== Number

==== Integer Number
Expand Down

0 comments on commit 4452d25

Please sign in to comment.