class Poco::JSON::Object

Overview

Represents a JSON object. More…

#include <Object.h>

class Object
{
public:
    // typedefs

    typedef SharedPtr<Object> Ptr;
    typedef std::map<std::string, Dynamic::Var> ValueMap;
    typedef ValueMap::value_type ValueType;
    typedef ValueMap::iterator Iterator;
    typedef ValueMap::const_iterator ConstIterator;

    // construction

    Object(bool preserveInsertionOrder = false);
    Object(const Object& copy);

    // methods

    Iterator
    begin();

    ConstIterator
    begin() const;

    Iterator
    end();

    ConstIterator
    end() const;

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

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

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

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

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

    void
    getNames(std::vector<std::string>& names) const;

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

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

    bool
    isArray(ConstIterator& it) const;

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

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

    bool
    isObject(ConstIterator& it) const;

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

    std::size_t
    size() const;

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

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

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

    operator const Poco::DynamicStruct &() const;

    void
    clear();

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

Detailed Documentation

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"

Construction

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

Methods

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

Retrieves a property.

An empty value is returned when the property doesn’t exist.

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.

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

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.

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.

void
getNames(std::vector<std::string>& names) const

Returns all property names.

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

Returns true when the given property exists.

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

Returns true when the given property contains an array.

bool
isArray(ConstIterator& it) const

Returns true when the given property contains an array.

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

Returns true when the given property contains a null value.

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

Returns true when the given property contains an object.

bool
isObject(ConstIterator& it) const

Returns true when the given property contains an object.

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.

std::size_t
size() const

Returns the number of properties.

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

Sets a new value.

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.

void
remove(const std::string& key)

Removes the property with the given key.

operator const Poco::DynamicStruct &() const

Cast operator to Poco::DynamiStruct.

void
clear()

Clears the contents of the object.

Insertion order preservation property is left intact.

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

Utility function for creation of struct.