|
| | array (std::string_view data, connection const &cx, sl loc=sl::current()) |
| | Parse an SQL array, read as text from a pqxx::result or stream. More...
|
| |
| | array (std::string_view data, encoding_group enc, sl loc=sl::current()) |
| |
| PQXX_PURE std::array< std::size_t, DIMENSIONS > const & | sizes () const noexcept |
| | Return the sizes of this array in each of its dimensions. More...
|
| |
| template<std::integral... INDEX> |
| ELEMENT const & | at (INDEX... index) const |
| |
| template<std::integral... INDEX> |
| PQXX_PURE ELEMENT const & | operator[] (INDEX... index) const |
| | Access element (without bounds check). More...
|
| |
|
There is no "nice" way to iterate over a multi-dimensional array as yet. Instead, you can iterate over all the elements as if it were a simple, flat, one-dimensional array.
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.
|
| constexpr PQXX_PURE auto | cbegin () const noexcept |
| | Begin iteration of individual elements. More...
|
| |
| constexpr PQXX_PURE auto | cend () const noexcept |
| | Return end point of iteration. More...
|
| |
| constexpr PQXX_PURE auto | begin () const noexcept |
| | Begin iteration of individual elements. More...
|
| |
| constexpr PQXX_PURE auto | end () const noexcept |
| | Return endpoint of iteration. More...
|
| |
| constexpr PQXX_PURE auto | crbegin () const noexcept |
| | Begin reverse iteration. More...
|
| |
| constexpr PQXX_PURE auto | crend () const noexcept |
| | Return end point of reverse iteration. More...
|
| |
| constexpr PQXX_PURE auto | rbegin () const noexcept |
| |
| constexpr PQXX_PURE auto | rend () 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 const & | front () const noexcept |
| | Refer to the first element, if any. More...
|
| |
| constexpr auto const & | back () const noexcept |
| | Refer to the last element, if any. More...
|
| |
template<not_borrowed 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].
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
Parse an SQL array, read as text from a pqxx::result or stream.
Uses cx 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. |
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
| constexpr auto const& pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::back |
( |
| ) |
const |
|
inlineconstexprnoexcept |
Refer to the last element, if any.
If the array is empty, dereferencing this results in undefined behaviour.
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
| constexpr auto const& pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::front |
( |
| ) |
const |
|
inlineconstexprnoexcept |
Refer to the first element, if any.
If the array is empty, dereferencing this results in undefined behaviour.
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
template<std::integral... INDEX>
| PQXX_PURE ELEMENT const& pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::operator[] |
( |
INDEX... |
index | ) |
const |
|
inline |
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.
- Warning
- This function is marked as "pure." This means that if it fails, depending on your compiler, the exception may occur in a different place than you expected. The compiler may even find scenarios where it can avoid calling this operator, meaning that the exception does not happen at all. If you need more deterministic exception behaviour, use at().
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
| constexpr std::size_t pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::size |
( |
| ) |
const |
|
inlineconstexprnoexcept |
Number of elements in the array.
This includes all elements, in all dimensions. Therefore it is the product of all values in sizes().
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
| PQXX_PURE std::array<std::size_t, DIMENSIONS> const& pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::sizes |
( |
| ) |
const |
|
inlinenoexcept |
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.
template<not_borrowed ELEMENT, std::size_t DIMENSIONS = 1u, char SEPARATOR = array_separator<ELEMENT>>
| constexpr auto pqxx::array< ELEMENT, DIMENSIONS, SEPARATOR >::ssize |
( |
| ) |
const |
|
inlineconstexprnoexcept |
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.
1.9.1