# Poco::JSON

# class Array

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

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

Add the given value to the array

### begin

ValueVec::const_iterator begin() const;

Returns the begin iterator for values.

### clear

void clear();

Clears the contents of the array.

### empty

bool empty() const;

Returns true if the array is empty, false otherwise.

### end

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

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

bool getEscapeUnicode() const;

Returns the flag for escaping unicode.

### getLowercaseHex

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

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

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

void remove(
unsigned int index
);

Removes the element on the given index.

### set

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

Update the element on the given index to specified value

### setEscapeUnicode

void setEscapeUnicode(
bool escape = true
);

Sets the flag for escaping unicode.

### setLowercaseHex

void setLowercaseHex(
bool lowercaseHex
);

Sets the flag for using lowercase hex numbers

### size

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.