pqxx::params Class Reference

Build a parameter list for a parameterised or prepared statement. More...

`#include <params.hxx>`

## Public Member Functions

| params ()=default
template<typename... Args>
constexpr | params (Args &&...args)
| Pre-populate a `params` with `args`. Feel free to add more later.
void | reserve (std::size_t n) &
| Pre-allocate room for at least `n` parameters.
auto | size () const noexcept
| Get the number of parameters currently in this `params`.
auto | ssize () const
| Get the number of parameters (signed).
void | append () &
| Append a null value.
void | append (zview) &
| Append a non-null zview parameter.
void | append (std::string const &) &
| Append a non-null string parameter.
void | append (std::string &&) &
| Append a non-null string parameter.
void | append (std::basic_string_view< std::byte >) &
| Append a non-null binary parameter.
void | append (std::basic_string< std::byte > const &) &
| Append a non-null binary parameter.
void | append (std::basic_string< std::byte > &&) &
| Append a non-null binary parameter.
void | append (binarystring const &value) &
template<typename IT , typename ACCESSOR >
void | append (pqxx::internal::dynamic_params< IT, ACCESSOR > const &value) &
| Append all parameters from value.
void | append (params const &value) &
void | append (params &&value) &
template<typename TYPE >
void | append (TYPE const &value) &
template<PQXX_RANGE_ARG RANGE>
void | append_multi (RANGE const &range) &
| Append all elements of `range` as parameters.
pqxx::internal::c_params | make_c_params () const
| For internal use: Generate a `params` object for use in calls.

## Detailed Description

Build a parameter list for a parameterised or prepared statement.

When calling a parameterised statement or a prepared statement, you can pass parameters into the statement directly in the invocation, as additional arguments to `exec_prepared` or `exec_params`. But in complex cases, sometimes that's just not convenient.

In those situations, you can create a `params` and append your parameters into that, one by one. Then you pass the `params` to `exec_prepared` or `exec_params`.

Combinations also work: if you have a `params` containing a string parameter, and you call `exec_params` with an `int` argument followed by your `params`, you'll be passing the `int` as the first parameter and the string as the second. You can even insert a `params` in a `params`, or pass two `params` objects to a statement.

## Constructor & Destructor Documentation

## params() [1/2]

pqxx::params::params | ( |  | ) |

default

## params() [2/2]

template<typename... Args>

constexpr pqxx::params::params | ( | Args &&... | args | ) |

constexpr

Pre-populate a `params` with `args`. Feel free to add more later.

## Member Function Documentation

## append() [1/12]

void pqxx::params::append | ( |  | ) | &

Append a null value.

## append() [2/12]

void PQXX_COLD pqxx::params::append | ( | binarystring const & | value | ) | &

Deprecated:
  Append binarystring parameter.

The binarystring must stay valid for as long as the `params` remains active.

## append() [3/12]

void pqxx::params::append | ( | params && | value | ) | &

## append() [4/12]

void pqxx::params::append | ( | params const & | value | ) | &

## append() [5/12]

template<typename IT , typename ACCESSOR >

void pqxx::params::append | ( | pqxx::internal::dynamic_params< IT, ACCESSOR > const & | value | ) | &

Append all parameters from value.

## append() [6/12]

void pqxx::params::append | ( | std::basic_string< std::byte > && | value | ) | &

Append a non-null binary parameter.

## append() [7/12]

void pqxx::params::append | ( | std::basic_string< std::byte > const & | value | ) | &

Append a non-null binary parameter.

Copies the underlying data into internal storage. For best efficiency, use the `std::basic_string_view<std::byte>` variant if you can, or `std::move()`.

## append() [8/12]

void pqxx::params::append | ( | std::basic_string_view< std::byte > | value | ) | &

Append a non-null binary parameter.

The underlying data must stay valid for as long as the `params` remains active.

## append() [9/12]

void pqxx::params::append | ( | std::string && | value | ) | &

Append a non-null string parameter.

## append() [10/12]

void pqxx::params::append | ( | std::string const & | value | ) | &

Append a non-null string parameter.

Copies the underlying data into internal storage. For best efficiency, use the zview variant if you can, or `std::move()`

## append() [11/12]

template<typename TYPE >

void pqxx::params::append | ( | TYPE const & | value | ) | &

Append a non-null parameter, converting it to its string representation.

References pqxx::ignore_unused(), and pqxx::to_string().

## append() [12/12]

void pqxx::params::append | ( | zview | value | ) | &

Append a non-null zview parameter.

The underlying data must stay valid for as long as the `params` remains active.

## append_multi()

template<PQXX_RANGE_ARG RANGE>

void pqxx::params::append_multi | ( | RANGE const & | range | ) | &

Append all elements of `range` as parameters.

## make_c_params()

pqxx::internal::c_params pqxx::params::make_c_params | ( |  | ) | const

For internal use: Generate a `params` object for use in calls.

The params object encapsulates the pointers which we will need to pass to libpq when calling a parameterised or prepared statement.

The pointers in the params will refer to storage owned by either the params object, or the caller. This is not a problem because a `c_params` object is guaranteed to live only while the call is going on. As soon as we climb back out of that call tree, we're done with that data.

References pqxx::internal::ssize().

Referenced by pqxx::transaction_base::exec_params(), and pqxx::transaction_base::exec_prepared().

## reserve()

void pqxx::params::reserve | ( | std::size_t | n | ) | &

Pre-allocate room for at least `n` parameters.

This is not needed, but it may improve efficiency.

Reserve space if you're going to add parameters individually, and you've got some idea of how many there are going to be. It may save some memory re-allocations.

## size()

auto pqxx::params::size | ( |  | ) | const

noexcept

Get the number of parameters currently in this `params`.

## ssize()

auto pqxx::params::ssize | ( |  | ) | const

Get the number of parameters (signed).

Unlike `size()`, this is not yet `noexcept`. That's because C++17's `std::vector` does not have a `ssize()` member function. These member functions are `noexcept`, but `std::size()` and `std::ssize()` are not.

References pqxx::internal::ssize().

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

- params.hxx
- params.cxx