## `array`

A dynamically sized array of JSON values.

### Synopsis

Defined in header <boost/json/array.hpp>.

    class array;

### Types

Name | Description
--- | ---
`allocator_type` | Associated Allocator
`const_iterator` | A random access const iterator to an element.
`const_pointer` | A const pointer to an element.
`const_reference` | A const reference to an element.
`const_reverse_iterator` | A reverse random access const iterator to an element.
`difference_type` | The type used to represent signed integers.
`iterator` | A random access iterator to an element.
`pointer` | A pointer to an element.
`reference` | A reference to an element.
`reverse_iterator` | A reverse random access iterator to an element.
`size_type` | The type used to represent unsigned integers.
`value_type` | The type of each element.

### Member Functions

Name | Description
--- | ---
`array` [constructor] | Constructors.
`at` | Access an element, with bounds checking.
`back` | Access the last element.
`begin` | Return an iterator to the first element.
`capacity` | Return the number of elements that can be held in currently allocated memory.
`cbegin` | Return a const iterator to the first element.
`cend` | Return a const iterator past the last element.
`clear` | Clear the contents.
`crbegin` | Return a const reverse iterator to the first element of the reversed container.
`crend` | Return a const reverse iterator to the element following the last element of the reversed container.
`data` | Access the underlying array directly.
`emplace` | Insert a constructed element in-place.
`emplace_back` | Append a constructed element in-place.
`empty` | Check if the array has no elements.
`end` | Return a const iterator past the last element.
`erase` | Remove elements from the array.
`front` | Access the first element.
`get_allocator` | Return the associated allocator.
`if_contains` | Return a pointer to an element if it exists.
`insert` | Insert elements before the specified location.
`operator=` | Assignment operators.
`operator[]` | Access an element.
`pop_back` | Remove the last element.
`push_back` | Add an element to the end.
`rbegin` | Return a reverse iterator to the first element of the reversed container.
`rend` | Return a reverse iterator to the element following the last element of the reversed container.
`reserve` | Increase the capacity to at least a certain amount.
`resize` | Change the number of elements stored.
`shrink_to_fit` | Request the removal of unused capacity.
`size` | Return the number of elements in the array.
`storage` | Return the associated memory resource.
`swap` | Swap two arrays.
`try_at` | Access an element, with bounds checking.
`~array` [destructor] | Destructor.

### Static Member Functions

Name | Description
--- | ---
`max_size` | The maximum number of elements an array can hold.

### Friends

Name | Description
--- | ---
`operator!=` | Compare two arrays for inequality.
`operator<<` | Serialize to an output stream.
`operator==` | Compare two arrays for equality.
`swap` | Swap two arrays.

### Description

This is the type used to represent a JSON array as a modifiable container. The interface and performance characteristics are modeled after `std::vector<value>`.

Elements are stored contiguously, which means that they can be accessed not only through iterators, but also using offsets to regular pointers to elements. A pointer to an element of an `array` may be passed to any function that expects a pointer to `value`.

The storage of the array is handled automatically, being expanded and contracted as needed. Arrays usually occupy more space than array language constructs, because more memory is allocated to handle future growth. This way an array does not need to reallocate each time an element is inserted, but only when the additional memory is used up. The total amount of allocated memory can be queried using the `capacity` function. Extra memory can be relinquished by calling `shrink_to_fit`.

Reallocations are usually costly operations in terms of performance. The `reserve` function can be used to eliminate reallocations if the number of elements is known beforehand.

The complexity (efficiency) of common operations on arrays is as follows:

- Random access—​constant O(1).

- Insertion or removal of elements at the end - amortized constant O(1).

- Insertion or removal of elements—​linear in the distance to the end of the array O(n).

### Allocators

All elements stored in the container, and their children if any, will use the same memory resource that was used to construct the container.

### Thread Safety

Non-const member functions may not be called concurrently with any other member functions.

### Satisfies

ContiguousContainer, ReversibleContainer, and SequenceContainer.

Convenience header <boost/json.hpp>.

Edit this page