Poco::JSON

class Array

File Information

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

Description

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

Member Summary

Member Functions: add, begin, clear, empty, end, get, getArray, getElement, getEscapeUnicode, getLowercaseHex, getObject, isArray, isNull, isObject, makeArray, operator =, optElement, remove, set, setEscapeUnicode, setLowercaseHex, size, stringify

Types Aliases

ConstIterator

using ConstIterator = std::vector < Dynamic::Var >::const_iterator;

Iterator

using Iterator = std::vector < Dynamic::Var >::iterator;

Ptr

using Ptr = SharedPtr < Array >;

ValueVec

using ValueVec = std::vector < Dynamic::Var >;

Constructors

Array

Array(
    int options = 0
);

Creates an empty Array.

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

Array

Array(
    const Array & copy
);

Creates an Array by copying another one.

Array

Array(
    Array && other
) noexcept;

Move constructor

Destructor

~Array

~Array();

Destroys the Array.

Member Functions

add inline

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

Add the given value to the array

begin inline

ValueVec::const_iterator begin() const;

Returns the begin iterator for values.

clear

void clear();

Clears the contents of the array.

empty inline

bool empty() const;

Returns true if the array is empty, false otherwise.

end inline

ValueVec::const_iterator end() const;

Returns the end iterator for values.

get

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.

getArray

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.

getElement inline

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.

getEscapeUnicode inline

bool getEscapeUnicode() const;

Returns the flag for escaping unicode.

getLowercaseHex inline

bool getLowercaseHex() const;

Returns the flag for using lowercase hex numbers

getObject

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.

isArray inline

bool isArray(
    unsigned int index
) const;

Returns true when the element is an array.

isArray

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

Returns true when the element is an array.

isArray

bool isArray(
    ConstIterator & value
) const;

Returns true when the element is an array.

isNull

bool isNull(
    unsigned int index
) const;

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

isObject

bool isObject(
    unsigned int index
) const;

Returns true when the element is an object.

isObject

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

Returns true when the element is an object.

isObject

bool isObject(
    ConstIterator & value
) const;

Returns true when the element is an object.

makeArray static

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

Conversion operator to Dynamic::Array. Utility function for creation of array.

operator =

Array & operator = (
    const Array & other
);

Assignment operator.

operator =

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

Move assignment operator.

optElement inline

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

remove inline

void remove(
    unsigned int index
);

Removes the element on the given index.

set inline

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

Update the element on the given index to specified value

setEscapeUnicode inline

void setEscapeUnicode(
    bool escape = true
);

Sets the flag for escaping unicode.

setLowercaseHex inline

void setLowercaseHex(
    bool lowercaseHex
);

Sets the flag for using lowercase hex numbers

size inline

std::size_t size() const;

Returns the size of the array.

stringify

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.