class Poco::JSON::Array

Overview

Represents a JSON array. More…

#include <Array.h>

class Array
{
public:
    // typedefs

    typedef std::vector<Dynamic::Var> ValueVec;
    typedef std::vector<Dynamic::Var>::iterator Iterator;
    typedef std::vector<Dynamic::Var>::const_iterator ConstIterator;
    typedef SharedPtr<Array> Ptr;

    // construction

    Array();
    Array(const Array& copy);

    // methods

    ValueVec::const_iterator
    begin() const;

    ValueVec::const_iterator
    end() const;

    Dynamic::Var
    get(unsigned int index) const;

    Array::Ptr
    getArray(unsigned int index) const;

    template <typename T>
    T
    getElement(unsigned int index) const;

    SharedPtr<Object>
    getObject(unsigned int index) const;

    std::size_t
    size() const;

    bool
    isArray(unsigned int index) const;

    bool
    isArray(const Dynamic::Var& value) const;

    bool
    isArray(ConstIterator& value) const;

    bool
    isNull(unsigned int index) const;

    bool
    isObject(unsigned int index) const;

    bool
    isObject(const Dynamic::Var& value) const;

    bool
    isObject(ConstIterator& value) const;

    template <typename T>
    T
    optElement(
        unsigned int index,
        const T& def
        ) const;

    void
    add(const Dynamic::Var& value);

    void
    set(
        unsigned int index,
        const Dynamic::Var& value
        );

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

    void
    remove(unsigned int index);

    operator const Poco::Dynamic::Array &() const;

    void
    clear();

    static
    Poco::Dynamic::Array
    makeArray(const JSON::Array::Ptr& arr);
};

Detailed Documentation

Represents a JSON array.

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

// use pointers to avoid copying
using namespace Poco::JSON;
std::string json = "[ {\"test\" : 0}, { \"test1\" : [1, 2, 3], \"test2\" : 4 } ]";
Parser parser;
Var result = parser.parse(json);
Array::Ptr arr = result.extract<Array::Ptr>();
Object::Ptr object = arr->getObject(0); // object == {\"test\" : 0}
int i = object->getElement<int>("test"); // i == 0;
Object::Ptr subObject = *arr->getObject(1); // subObject == {\"test\" : 0}
Array subArr::Ptr = subObject->getArray("test1"); // subArr == [1, 2, 3]
i = result = subArr->get(0); // i == 1;

// copy/convert to Poco::Dynamic::Array
Poco::Dynamic::Array da = *arr;
i = da[0]["test"];     // i == 0
i = da[1]["test1"][1]; // i == 2
i = da[1]["test2"];    // i == 4

Construction

Array()

Creates an empty Array.

Array(const Array& copy)

Creates an Array by copying another one.

Methods

ValueVec::const_iterator
begin() const

Returns the begin iterator for values.

ValueVec::const_iterator
end() const

Returns the end iterator for values.

Dynamic::Var
get(unsigned int index) const

Retrieves the element at the given index.

Will return an empty value when the element doesn’t exist.

Array::Ptr
getArray(unsigned int index) const

Retrieves an array.

When the element is not an Array or doesn’t exist, an empty SharedPtr is returned.

template <typename T>
T
getElement(unsigned int index) const

Retrieves an element and tries to convert it to the template type.

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

SharedPtr<Object>
getObject(unsigned int index) const

Retrieves an object.

When the element is not an object or doesn’t exist, an empty SharedPtr is returned.

std::size_t
size() const

Returns the size of the array.

bool
isArray(unsigned int index) const

Returns true when the element is an array.

bool
isArray(const Dynamic::Var& value) const

Returns true when the element is an array.

bool
isArray(ConstIterator& value) const

Returns true when the element is an array.

bool
isNull(unsigned int index) const

Returns true when the element is null or when the element doesn’t exist.

bool
isObject(unsigned int index) const

Returns true when the element is an object.

bool
isObject(const Dynamic::Var& value) const

Returns true when the element is an object.

bool
isObject(ConstIterator& value) const

Returns true when the element is an object.

template <typename T>
T
optElement(
    unsigned int index,
    const T& def
    ) const

Returns the element at the given index.

When the element is null, doesn’t exist or can’t be converted to the given type, the default value will be returned

void
add(const Dynamic::Var& value)

Add the given value to the array.

void
set(
    unsigned int index,
    const Dynamic::Var& value
    )

Update the element on the given index to specified value.

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

Prints the array to out.

When indent has zero value, the array will be printed without newline breaks and spaces between elements.

void
remove(unsigned int index)

Removes the element on the given index.

void
clear()

Clears the contents of the array.

static
Poco::Dynamic::Array
makeArray(const JSON::Array::Ptr& arr)

Utility function for creation of array.