# json

<a id="json"></a>

# json

JSON value aliases, serialization helpers, and file utilities built on nlohmann/json.

## Classes

| Name | Description |
|------|-------------|
| [`Configuration`](https://auscaster.com/icey/docs/api-reference/icy-json-Configuration.md#configuration-5) | JSON configuration file |
| [`ISerializable`](https://auscaster.com/icey/docs/api-reference/icy-json-ISerializable.md#iserializable) | Abstract interface for JSON-serializable objects. |

## Typedefs

| Return | Name | Description |
|--------|------|-------------|
| `nlohmann::json` | [`Value`](#value)  | Primary JSON value type used throughout the library. |

---

<a id="value"></a>

### Value

```cpp
using Value = nlohmann::json
```

[Defined in src/json/include/icy/json/json.h:40](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L40)

Primary JSON value type used throughout the library.

## Functions

| Return | Name | Description |
|--------|------|-------------|
| `bool` | [`serialize`](#serialize) `inline` | Serializes `pObj` to a pretty-printed JSON string. |
| `bool` | [`deserialize`](#deserialize) `inline` | Deserializes `pObj` from a JSON string. |
| `void` | [`loadFile`](#loadfile) `inline` | Load a JSON file into a value. Throws on missing file or parse error. |
| `void` | [`saveFile`](#savefile-1) `inline` | Save a JSON value to a file. Throws on write error. |
| `void` | [`assertMember`](#assertmember) `inline` | Assert that a required member exists. Throws if missing. |
| `void` | [`countNestedKeys`](#countnestedkeys) `inline` | Count how many nested objects contain the given key. |
| `bool` | [`hasNestedKey`](#hasnestedkey) `inline` | Return true if any nested object contains the given key. |
| `bool` | [`findNestedObjectWithProperty`](#findnestedobjectwithproperty) `inline` | Find a nested object whose property matches the given key/value. |

---

<a id="serialize"></a>

### serialize

`inline`

```cpp
inline bool serialize(ISerializable * pObj, std::string & output)
```

[Defined in src/json/include/icy/json/iserializable.h:43](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/iserializable.h#L43)

Serializes `pObj` to a pretty-printed JSON string. 
#### Returns
true on success, false if `pObj` is null.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pObj` | [`ISerializable`](https://auscaster.com/icey/docs/api-reference/icy-json-ISerializable.md#iserializable) * | Object to serialize; must not be null. |
| `output` | `std::string &` | Receives the 4-space indented JSON string. |

---

<a id="deserialize"></a>

### deserialize

`inline`

```cpp
inline bool deserialize(ISerializable * pObj, std::string & input)
```

[Defined in src/json/include/icy/json/iserializable.h:59](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/iserializable.h#L59)

Deserializes `pObj` from a JSON string. 
#### Returns
true on success, false if `pObj` is null or parsing fails.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pObj` | [`ISerializable`](https://auscaster.com/icey/docs/api-reference/icy-json-ISerializable.md#iserializable) * | Object to populate; must not be null. |
| `input` | `std::string &` | JSON string to parse. |

---

<a id="loadfile"></a>

### loadFile

`inline`

```cpp
inline void loadFile(const std::string & path, json::Value & root)
```

[Defined in src/json/include/icy/json/json.h:44](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L44)

Load a JSON file into a value. Throws on missing file or parse error.

---

<a id="savefile-1"></a>

### saveFile

`inline`

```cpp
inline void saveFile(const std::string & path, const json::Value & root, int indent = 4)
```

[Defined in src/json/include/icy/json/json.h:56](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L56)

Save a JSON value to a file. Throws on write error.

---

<a id="assertmember"></a>

### assertMember

`inline`

```cpp
inline void assertMember(const json::Value & root, const std::string & name)
```

[Defined in src/json/include/icy/json/json.h:71](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L71)

Assert that a required member exists. Throws if missing.

---

<a id="countnestedkeys"></a>

### countNestedKeys

`inline`

```cpp
inline void countNestedKeys(const json::Value & root, const std::string & key, int & count)
```

[Defined in src/json/include/icy/json/json.h:79](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L79)

Count how many nested objects contain the given key.

---

<a id="hasnestedkey"></a>

### hasNestedKey

`inline`

```cpp
inline bool hasNestedKey(const json::Value & root, const std::string & key)
```

[Defined in src/json/include/icy/json/json.h:92](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L92)

Return true if any nested object contains the given key.

---

<a id="findnestedobjectwithproperty"></a>

### findNestedObjectWithProperty

`inline`

```cpp
inline bool findNestedObjectWithProperty(json::Value & root, json::Value *& result, std::string_view key, std::string_view value, bool partial = true, int index = 0)
```

[Defined in src/json/include/icy/json/json.h:113](https://github.com/auscaster/icey/blob/main/src/json/include/icy/json/json.h#L113)

Find a nested object whose property matches the given key/value.

Key or value may be empty for wildcard matching. If partial is true, substring matches are accepted for string values. The index parameter selects the Nth match (0 = first).

Returns true if found, with result pointing to the matching object.