Class JsonObject

Represents a basic JSON object.

Inheritance
object
JsonValue
JsonObject
JsonApiDocument
JsonApiErrorObject
JsonApiLinkObject
JsonApiLinksObject
JsonApiRelationshipObject
JsonApiRelationshipsObject
JsonApiResourceIdentifierObject
JsonApiVersionObject
Implements
Inherited Members
Namespace: Subsembly.Json
Assembly: Subsembly.Json.dll
Syntax
public class JsonObject : JsonValue, ICloneable
Remarks

It is possible, and recommended, to derive more specialized JSON object classes for particular usages. In order to parse JSON data in a derived JsonObject instance, the method ParseJson(string) shall be used.

If a specialized JSON object may contain nested JSON objects, then the method OnCreateChildObject(string) shall be overridden in order to create a specialized JsonObject instance, based on the field name.

By overriding OnCreateChildObject(string) and OnCreateChildArray(string), a complete specialized object tree can be created by parsing the JSON.

Constructors

JsonObject()

Declaration
public JsonObject()

JsonObject(IDictionary<string, JsonValue>)

Declaration
public JsonObject(IDictionary<string, JsonValue> aValue)
Parameters
Type Name Description
IDictionary<string, JsonValue> aValue

Methods

GetBool(string)

Declaration
public bool GetBool(string sName)
Parameters
Type Name Description
string sName
Returns
Type Description
bool
Exceptions
Type Condition
ArgumentNullException

The parameter sName was null.

GetDateIfNotEmpty(string)

Declaration
public DateTime GetDateIfNotEmpty(string sName)
Parameters
Type Name Description
string sName
Returns
Type Description
DateTime

If the property does not exist, or if the property contains a Null or an Undefined value, then DateTime.MinValue is returned. If the property contains a Number, then it is interpreted as a tick value. Otherwise an attempt is made to parse it as an ISO date string.
Exceptions
Type Condition
ArgumentNullException

The parameter sName was null.
JsonTypeException

The property did contain a JSON value that cannot be meaningfully converted to a DateTime. For example Boolean, Object, or Array.

GetIfNotEmpty(string)

Convenience for conditionally getting a string property.

Declaration
public string GetIfNotEmpty(string sName)
Parameters
Type Name Description
string sName

Name of property to get. Must not be null.
Returns
Type Description
string

If the named property exists, then its string value will be returned. If the property does not exist, or if the property contains a Null or an Undefined value, then null is returned.
Exceptions
Type Condition
ArgumentNullException

The parameter sName was null.

GetIfNotNaN<T>(string, T)

Declaration
public T GetIfNotNaN<T>(string sName, T nDefaultValue = default)
Parameters
Type Name Description
string sName
T nDefaultValue
Returns
Type Description
T
Type Parameters
Name Description
T
Remarks

Assumes int as underlying type of T, if T is an enum type.

Exceptions
Type Condition
ArgumentNullException

The parameter sName was null.

GetOwnPropertyNames()

Declaration
public ICollection<string> GetOwnPropertyNames()
Returns
Type Description
ICollection<string>

GetUuidIfNotEmpty(string)

Declaration
public Guid GetUuidIfNotEmpty(string sName)
Parameters
Type Name Description
string sName
Returns
Type Description
Guid

HasOwnProperty(string)

Declaration
public bool HasOwnProperty(string sName)
Parameters
Type Name Description
string sName
Returns
Type Description
bool

OnAfterParseObject()

This is called by the JSON parser after this object was fully parsed. It can be used as a hook to validate the data, or to prepare a cache.

Declaration
protected virtual void OnAfterParseObject()
Remarks

The default implementation does nothing.

OnCreateChildArray(string)

This is called whenever the JSON parser needs a child array object for this object.

Declaration
protected virtual JsonArray OnCreateChildArray(string sFieldName)
Parameters
Type Name Description
string sFieldName

The name of the field for which a child array object is needed.
Returns
Type Description
JsonArray
Remarks

An override can use this as an opportunity to returned a more specific object, derived from JsonArray. Such a derived object could provide additional convenient properties for accessing the fields of it.

The default implementation just returns a new JsonArray.

OnCreateChildObject(string)

This is called whenever the JSON parser needs a child object for this object.

Declaration
protected virtual JsonObject OnCreateChildObject(string sFieldName)
Parameters
Type Name Description
string sFieldName

The name of the field for which a child object is needed.
Returns
Type Description
JsonObject
Remarks

An override can use this as an opportunity to returned a more specific object, derived from JsonObject. Such a derived object could provide additional convenient properties for accessing the fields of it.

The default implementation just returns a new JsonObject.

Parse(byte[])

Creates a new, base JsonObject and fills it with the JSON data from vbJson. To parse and load data in an instance derived from JsonObject, use ParseJson(byte[]) instead.

Declaration
public static JsonObject Parse(byte[] vbJson)
Parameters
Type Name Description
byte[] vbJson

The JSON to be parsed. If this is is null, then this method returns null.
Returns
Type Description
JsonObject

Parse(string)

Creates a new, base JsonObject and fills it with the JSON data from sJson. To parse and load data in an instance derived from JsonObject, use ParseJson(string) instead.

Declaration
public static JsonObject Parse(string sJson)
Parameters
Type Name Description
string sJson

The JSON to be parsed. If this is is null or an empty string, then this method returns null.
Returns
Type Description
JsonObject
See Also

ParseJson(byte[])

Parse the given vbJson data, adding all its properties to this object.

Declaration
public void ParseJson(byte[] vbJson)
Parameters
Type Name Description
byte[] vbJson

The JSON to be parsed. If this is is null, then this method does nothing.
See Also

ParseJson(string)

Parse the given sJson string, adding all its properties to this object.

Declaration
public void ParseJson(string sJson)
Parameters
Type Name Description
string sJson

The JSON to be parsed. If this is is null or an empty string, then this method does nothing.
Remarks

This JsonObject will receive all the parsed values. The values will be added to this object. Existing values with the same field name are replaced.

See Also

SetIfNotEmpty(string, JsonValue)

Convenience for conditionally setting an object property.

Declaration
public void SetIfNotEmpty(string sName, JsonValue aValue)
Parameters
Type Name Description
string sName

Name of property to set. Must not be null.
JsonValue aValue

Value to set for the named property. If this is null or an instance of type Null, or an instance of type Undefined, or a null or empty String, then the property will not be set.
Exceptions
Type Condition
ArgumentNullException

The parameter sName was null.

SetUuidIfNotEmpty(string, Guid)

Declaration
public void SetUuidIfNotEmpty(string sName, Guid tGuid)
Parameters
Type Name Description
string sName

Name of property to set. Must not be null.
Guid tGuid

The UUID to set. If this is Guid.Empty, then nothing will be set. Otherwise the value is set as a string according to RFC 4122, e.g. "f81d4fae-7dec-11d0-a765-00a0c91e6bf6" using lower case.

Implements