pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR > Class Template Referencefinal

An SQL array received from the database. More...

`#include <array.hxx>`

## Public Member Functions

| array (std::string_view data, connection const &conn)
| Parse an SQL array, read as text from a pqxx::result or stream.
constexpr std::size_t | dimensions () noexcept
| How many dimensions does this array have?
std::array< std::size_t, DIMENSIONS > const & | sizes () noexcept
| Return the sizes of this array in each of its dimensions.
template<typename... INDEX>
ELEMENT const & | at (INDEX... index) const
template<typename... INDEX>
ELEMENT const & | operator[] (INDEX... index) const
| Access element (without bounds check).
constexpr auto | cbegin () const noexcept
| Begin iteration of individual elements.
constexpr auto | cend () const noexcept
| Return end point of iteration.
constexpr auto | crbegin () const noexcept
| Begin reverse iteration.
constexpr auto | crend () const noexcept
| Return end point of reverse iteration.
constexpr std::size_t | size () const noexcept
| Number of elements in the array.
constexpr auto | ssize () const noexcept
| Number of elements in the array (as a signed number).
constexpr auto | front () const noexcept
| Refer to the first element, if any.
constexpr auto | back () const noexcept
| Refer to the last element, if any.

## Detailed Description

template<typename ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
class pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >

An SQL array received from the database.

Parses an SQL array from its text format, making it available as a container of C++-side values.

The array can have one or more dimensions. You must specify the number of dimensions at compile time. In each dimension, the array has a size which the `array` constructor determines at run time based on the SQL array's textual representation. The sizes of a given SQL array are consistent: if your array has two dimensions, for example, then it will have one "horizontal" size which determines the number of elements in each row; and it will have one "vertical" size which determines the number of rows.

Physical memory storage is "row-major." This means that the last of the dimensions represents a row. So in memory, element `a[m][n]` comes right before `a[m][n+1]`.

## Constructor & Destructor Documentation

## array()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::array | ( | std::string_view | data,
|  | connection const & | conn
| ) |  |

Parse an SQL array, read as text from a pqxx::result or stream.

Uses `conn` only during construction, to find out the text encoding in which it should interpret `data`.

Once the `array` constructor completes, destroying or moving the `connection` will not affect the `array` object in any way.

Exceptions

  pqxx::unexpected_null | if the array contains a null value, and the `ELEMENT` type does not support null values.

## Member Function Documentation

## at()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
template<typename... INDEX>

ELEMENT const & pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::at | ( | INDEX... | index | ) | const

## back()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::back | ( |  | ) | const

constexpr noexcept

Refer to the last element, if any.

If the array is empty, dereferencing this results in undefined behaviour.

## cbegin()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::cbegin | ( |  | ) | const

constexpr noexcept

Begin iteration of individual elements.

If this is a multi-dimensional array, iteration proceeds in row-major order. So for example, a two-dimensional array `a` would start at `a[0, 0]`, then `a[0, 1]`, and so on. Once it reaches the end of that first row, it moves on to element `a[1, 0]`, and continues from there.

## cend()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::cend | ( |  | ) | const

constexpr noexcept

Return end point of iteration.

## crbegin()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::crbegin | ( |  | ) | const

constexpr noexcept

Begin reverse iteration.

## crend()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::crend | ( |  | ) | const

constexpr noexcept

Return end point of reverse iteration.

## dimensions()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr std::size_t pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::dimensions | ( |  | ) |

constexpr noexcept

How many dimensions does this array have?

This value is known at compile time.

## front()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::front | ( |  | ) | const

constexpr noexcept

Refer to the first element, if any.

If the array is empty, dereferencing this results in undefined behaviour.

## operator[]()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
template<typename... INDEX>

ELEMENT const & pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::operator[] | ( | INDEX... | index | ) | const

Access element (without bounds check).

Return element at given index. Blindly assumes that the index lies within the bounds of the array. This is likely to be slightly faster than `at()`.

Multi-dimensional indexing using `operator[]` only works in C++23 or better. In older versions of C++ it will work only with single-dimensional arrays.

## size()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr std::size_t pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::size | ( |  | ) | const

constexpr noexcept

Number of elements in the array.

This includes all elements, in all dimensions. Therefore it is the product of all values in `sizes()`.

Referenced by pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::ssize().

## sizes()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

std::array< std::size_t, DIMENSIONS > const & pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::sizes | ( |  | ) |

noexcept

Return the sizes of this array in each of its dimensions.

The last of the sizes is the number of elements in a single row. The size before that is the number of rows of elements, and so on. The first is the "outer" size.

## ssize()

template<typename ELEMENT , std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>

constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::ssize | ( |  | ) | const

constexpr noexcept

Number of elements in the array (as a signed number).

This includes all elements, in all dimensions. Therefore it is the product of all values in `sizes()`.

In principle, the size could get so large that it had no signed equivalent. If that can ever happen, this is your own problem and behaviour is undefined.

In practice however, I don't think `ssize()` could ever overflow. You'd need an array where each element takes up just one byte, such as Booleans, filling up more than half your address space. But the input string for that array would need at least two bytes per value: one for the value, one for the separating comma between elements. So even then you wouldn't have enough address space to create the array, even if your system allowed you to use your full address space.

References pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::size().

The documentation for this class was generated from the following file:

- array.hxx