# Poco::JSON

# class Object

Library: JSON
Package: JSON
Header: Poco/JSON/Object.h

## Description

Represents a JSON object. Object provides a representation based on shared pointers and optimized for performance. It is possible to convert Object to DynamicStruct. Conversion requires copying and therefore has performance penalty; the benefit is in improved syntax, eg:

    std::string json = "{ \"test\" : { \"property\" : \"value\" } }";
    Parser parser;
    Var result = parser.parse(json);

    // use pointers to avoid copying
    Object::Ptr object = result.extract<Object::Ptr>();
    Var test = object->get("test"); // holds { "property" : "value" }
    Object::Ptr subObject = test.extract<Object::Ptr>();
    test = subObject->get("property");
    std::string val = test.toString(); // val holds "value"

    // copy/convert to Poco::DynamicStruct
    Poco::DynamicStruct ds = *object;
    val = ds["test"]["property"]; // val holds "value"

## Member Summary

Member Functions: begin, clear, end, get, getArray, getEscapeUnicode, getNames, getNullableValue, getObject, getValue, has, isArray, isNull, isObject, makeOrderedStruct, makeStruct, operator =, optValue, remove, set, setEscapeUnicode, size, stringify

## Types Aliases

### ConstIterator

using ConstIterator = ValueMap::const_iterator;

### Iterator

using Iterator = ValueMap::iterator;

### NameList

using NameList = std::vector < std::string >;

### Ptr

using Ptr = SharedPtr < Object >;

### ValueMap

using ValueMap = std::map < std::string, Dynamic::Var >;

### ValueType

using ValueType = ValueMap::value_type;

## Constructors

### Object

explicit Object(
int options = 0
);

Creates an empty Object.

If JSON_PRESERVE_KEY_ORDER is specified, the object will preserve the items insertion order. Otherwise, items will be sorted by keys.

If JSON_ESCAPE_UNICODE is specified, when the object is stringified, all unicode characters will be escaped in the resulting string.

### Object

Object(
const Object & copy
);

Creates an Object by copying another one.

Struct is not copied to keep the operation as efficient as possible (when needed, it will be generated upon request).

### Object

Object(
Object && other
) noexcept;

Move constructor

## Destructor

### ~Object

~Object();

Destroys the Object.

## Member Functions

### begin

Iterator begin();

Returns begin iterator for values.

### begin

ConstIterator begin() const;

Returns const begin iterator for values.

### clear

void clear();

Cast operator to Poco::OrderedDynamiStruct. Cast operator to Poco::DynamiStruct. Clears the contents of the object.

Insertion order preservation property is left intact.

### end

Iterator end();

Returns end iterator for values.

### end

ConstIterator end() const;

Returns const end iterator for values.

### get

Dynamic::Var get(
const std::string & key
) const;

Retrieves a property. An empty value is returned when the property doesn't exist.

### getArray

Array::Ptr getArray(
const std::string & key
) const;

Returns a SharedPtr to an array when the property is an array. An empty SharedPtr is returned when the element doesn't exist or is not an array.

### getEscapeUnicode

bool getEscapeUnicode() const;

Returns the flag for escaping unicode.

### getNames

void getNames(
NameList & names
) const;

Fills the supplied vector with all property names.

### getNames

NameList getNames() const;

Returns all property names.

### getNullableValue

template < typename T > Poco::Nullable < T > getNullableValue(
const std::string & key
) const;

Retrieves the property with the given name and will try to convert the value to the given template type.

The convert<T> method of Var is called which can also throw exceptions for invalid values. Note: This will not work for an array or an object.

### getObject

Object::Ptr getObject(
const std::string & key
) const;

Returns a SharedPtr to an object when the property is an object. An empty SharedPtr is returned when the property doesn't exist or is not an object

### getValue

template < typename T > T getValue(
const std::string & key
) const;

Retrieves the property with the given name and will try to convert the value to the given template type. The convert<T>() method of Var is called which can also throw exceptions for invalid values. Note: This will not work for an array or an object.

### has

bool has(
const std::string & key
) const;

Returns true when the given property exists.

### isArray

bool isArray(
const std::string & key
) const;

Returns true when the given property contains an array.

### isArray

bool isArray(
ConstIterator & it
) const;

Returns true when the given property contains an array.

### isNull

bool isNull(
const std::string & key
) const;

Returns true when the given property contains a null value.

### isObject

bool isObject(
const std::string & key
) const;

Returns true when the given property contains an object.

### isObject

bool isObject(
ConstIterator & it
) const;

Returns true when the given property contains an object.

### makeOrderedStruct

static Poco::OrderedDynamicStruct makeOrderedStruct(
const Object::Ptr & obj
);

Utility function for creation of ordered struct.

### makeStruct

static Poco::DynamicStruct makeStruct(
const Object::Ptr & obj
);

Utility function for creation of struct.

### operator =

Object & operator = (
const Object & other
);

### operator =

Object & operator = (
Object && other
) noexcept;

### optValue

template < typename T > T optValue(
const std::string & key,
const T & def
) const;

Returns the value of a property when the property exists and can be converted to the given type. Otherwise def will be returned.

### remove

void remove(
const std::string & key
);

Removes the property with the given key.

### set

Object & set(
const std::string & key,
const Dynamic::Var & value
);

Sets a new value.

### setEscapeUnicode

void setEscapeUnicode(
bool escape = true
);

Sets the flag for escaping unicode.

### size

std::size_t size() const;

Returns the number of properties.

### stringify

void stringify(
std::ostream & out,
unsigned int indent = 0,
int step = - 1
) const;

Prints the object to out stream.

When indent is 0, the object will be printed on a single line without indentation.