libpqxx
7.9.0
|
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. More... | |
constexpr std::size_t | dimensions () noexcept |
How many dimensions does this array have? More... | |
std::array< std::size_t, DIMENSIONS > const & | sizes () noexcept |
Return the sizes of this array in each of its dimensions. More... | |
template<typename... INDEX> | |
ELEMENT const & | at (INDEX... index) const |
template<typename... INDEX> | |
ELEMENT const & | operator[] (INDEX... index) const |
Access element (without bounds check). More... | |
constexpr auto | cbegin () const noexcept |
Begin iteration of individual elements. More... | |
constexpr auto | cend () const noexcept |
Return end point of iteration. More... | |
constexpr auto | crbegin () const noexcept |
Begin reverse iteration. More... | |
constexpr auto | crend () const noexcept |
Return end point of reverse iteration. More... | |
constexpr std::size_t | size () const noexcept |
Number of elements in the array. More... | |
constexpr auto | ssize () const noexcept |
Number of elements in the array (as a signed number). More... | |
constexpr auto | front () const noexcept |
Refer to the first element, if any. More... | |
constexpr auto | back () const noexcept |
Refer to the last element, if any. More... | |
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]
.
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.
pqxx::unexpected_null | if the array contains a null value, and the ELEMENT type does not support null values. |
ELEMENT const& pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::at | ( | INDEX... | index | ) | const |
|
constexprnoexcept |
Refer to the last element, if any.
If the array is empty, dereferencing this results in undefined behaviour.
|
constexprnoexcept |
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.
|
constexprnoexcept |
Return end point of iteration.
|
constexprnoexcept |
Begin reverse iteration.
|
constexprnoexcept |
Return end point of reverse iteration.
|
constexprnoexcept |
How many dimensions does this array have?
This value is known at compile time.
|
constexprnoexcept |
Refer to the first element, if any.
If the array is empty, dereferencing this results in undefined behaviour.
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.
|
constexprnoexcept |
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().
|
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.
|
constexprnoexcept |
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().