libpqxx  7.9.0
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. More...
 
void reserve (std::size_t n) &
 Pre-allocate room for at least n parameters. More...
 
auto size () const noexcept
 Get the number of parameters currently in this params. More...
 
auto ssize () const
 Get the number of parameters (signed). More...
 
void append () &
 Append a null value. More...
 
void append (zview) &
 Append a non-null zview parameter. More...
 
void append (std::string const &) &
 Append a non-null string parameter. More...
 
void append (std::string &&) &
 Append a non-null string parameter. More...
 
void append (bytes_view) &
 Append a non-null binary parameter. More...
 
void append (bytes const &) &
 Append a non-null binary parameter. More...
 
void append (bytes &&) &
 Append a non-null binary parameter. More...
 
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. More...
 
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. More...
 
pqxx::internal::c_params make_c_params () const
 For internal use: Generate a params object for use in calls. More...
 

Detailed Description

Build a parameter list for a parameterised or prepared statement.

When calling a parameterised statement or a prepared statement, in some cases you can pass parameters into the statement directly in the invocation, as additional arguments to e.g. exec_prepared or exec_params. But not all functions accept that, plus, sometimes you want to build the lists at run time.

In those situations, you can create a params and append your parameters into that, one by one. Then you pass the params to the function that executes your SQL statement.

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. In the end all the embedded parameters show up in their natural order.

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 ( bytes &&  value) &

Append a non-null binary parameter.

◆ append() [4/12]

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

Append a non-null binary parameter.

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

◆ append() [5/12]

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

Append a non-null binary parameter.

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

◆ append() [6/12]

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

◆ append() [7/12]

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

◆ append() [8/12]

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

Append all parameters from value.

◆ 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(), pqxx::is_null(), 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::param_format(), and pqxx::internal::ssize().

Referenced by 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: