# 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, getNames, getNullableValue, getObject, getValue, has, isArray, isNull, isObject, makeStruct, optValue, remove, set, size, stringify

## Types

### ConstIterator

typedef ValueMap::const_iterator ConstIterator;

### Iterator

typedef ValueMap::iterator Iterator;

### Ptr

typedef SharedPtr < Object > Ptr;

### ValueMap

typedef std::map < std::string, Dynamic::Var > ValueMap;

### ValueType

typedef ValueMap::value_type ValueType;

## Constructors

### Object

explicit Object(
bool preserveInsertionOrder = false
);

Creates an empty Object.

If preserveInsertionOrder, object will preserve the items insertion order. Otherwise, items will be sorted by keys.

### 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).

## Destructor

### ~Object

virtual ~Object();

Destroys the Object.

## Member Functions

### begin

Iterator begin();

### begin

ConstIterator begin() const;

### clear

void clear();

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

Insertion order preservation property is left intact.

### end

Iterator end();

### end

ConstIterator end() const;

### 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.

### getNames

void getNames(
std::vector < std::string > & names
) 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.

### makeStruct

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

Utility function for creation of struct.

### 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

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

Sets a new value.

### 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.