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, makeStruct, operator =, optValue, remove, set, setEscapeUnicode, size, stringify

Types

ConstIterator

typedef ValueMap::const_iterator ConstIterator;

Iterator

typedef ValueMap::iterator Iterator;

NameList

typedef std::vector < std::string > NameList;

Ptr

typedef SharedPtr < Object > Ptr;

ValueMap

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

ValueType

typedef ValueMap::value_type ValueType;

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

Destructor

~Object virtual

virtual ~Object();

Destroys the Object.

Member Functions

begin inline

Iterator begin();

Returns begin iterator for values.

begin

ConstIterator begin() const;

Returns const begin iterator for values.

clear

void clear();

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

Insertion order preservation property is left intact.

end inline

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 inline

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 inline

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 inline

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 inline

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

Returns true when the given property exists.

isArray inline

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 inline

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

Returns true when the given property contains a null value.

isObject inline

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

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

Utility function for creation of struct.

operator =

Object & operator = (
    const Object & other
);

optValue inline

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 inline

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.

setEscapeUnicode inline

void setEscapeUnicode(
    bool escape = true
);

Sets the flag for escaping unicode.

size inline

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.