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

#include <params.hxx>

Public Member Functions
	params ()=default

template<typename First , typename... Args>
	params (First &&first, 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...

constexpr auto	size () const noexcept
	Get the number of parameters currently in this `params`. More...

constexpr auto	ssize () const
	Get the number of parameters (signed). More...

void	append (sl=sl::current()) &
	Append a null value. More...

void	append (zview, sl=sl::current()) &
	Append a non-null zview parameter. More...

void	append (std::string const &, sl=sl::current()) &
	Append a non-null string parameter. More...

void	append (std::string &&, sl=sl::current()) &
	Append a non-null string parameter. More...

void	append (bytes_view, sl=sl::current()) &
	Append a non-null binary parameter. More...

template<binary DATA>
void	append (DATA const &data, sl loc=sl::current()) &
	Append a non-null binary parameter. More...

void	append (bytes &&, sl=sl::current()) &
	Append a non-null binary parameter. More...

void	append (params const &value, sl=sl::current()) &
	Append all parameters in `value`. More...

void	append (params &&value, sl=sl::current()) &
	Append all parameters in `value`. More...

template<typename TYPE >
void	append ([[maybe_unused]] TYPE const &value, sl loc=sl::current()) &

template<std::ranges::range RANGE>
void	append_multi (RANGE const &range, sl loc=sl::current()) &
	Append all elements of `range` as parameters. More...

pqxx::internal::c_params	make_c_params (sl loc) 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 many cases you can pass parameters into the statement in the form of a pqxx::params object.

Constructor & Destructor Documentation

◆ params() [1/2]

pqxx::params::params ( )

default

◆ params() [2/2]

template<typename First , typename... Args>

pqxx::params::params	(	First &&	first,
		Args &&...	args
	)

inline

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

Note: As a first parameter, we recommend passing an encoding_group, or a connection, or a transaction_base (or a more specific transaction type derived from it), or a conversion_context. The params will use this to obtain the client encoding. (It will not be passed as a parameter; it's just there as a source of the encoding information). In most cases you won't need this, but there are exceptions where a complex object can't be passed otherwise. To keep things clear, we recommend passing it in the general case so that you never run into exceptions about encoding being unknown.

Member Function Documentation

◆ append() [1/10]

template<typename TYPE >

void pqxx::params::append	(	[[maybe_unused] ] TYPE const &	value,
		sl	loc = `sl::current()`
	)		&

inline

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

◆ append() [2/10]

void pqxx::params::append	(	bytes &&	value,
		sl	= `sl::current()`
	)		&

Append a non-null binary parameter.

◆ append() [3/10]

void pqxx::params::append	(	bytes_view	value,
		sl	= `sl::current()`
	)		&

Append a non-null binary parameter.

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

◆ append() [4/10]

template<binary DATA>

void pqxx::params::append	(	DATA const &	data,
		sl	loc = `sl::current()`
	)		&

inline

Append a non-null binary parameter.

The data object must stay in place and unchanged, for as long as the params remains active.

◆ append() [5/10]

void pqxx::params::append	(	params &&	value,
		sl	= `sl::current()`
	)		&

Append all parameters in value.

◆ append() [6/10]

void pqxx::params::append	(	params const &	value,
		sl	= `sl::current()`
	)		&

Append all parameters in value.

◆ append() [7/10]

void pqxx::params::append ( sl = sl::current() ) &

Append a null value.

◆ append() [8/10]

void pqxx::params::append	(	std::string &&	value,
		sl	= `sl::current()`
	)		&

Append a non-null string parameter.

◆ append() [9/10]

void pqxx::params::append	(	std::string const &	value,
		sl	= `sl::current()`
	)		&

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() [10/10]

void pqxx::params::append	(	zview	value,
		sl	= `sl::current()`
	)		&

Append a non-null zview parameter.

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

◆ append_multi()

template<std::ranges::range RANGE>

void pqxx::params::append_multi	(	RANGE const &	range,
		sl	loc = `sl::current()`
	)		&

inline

Append all elements of range as parameters.

◆ make_c_params()

pqxx::internal::c_params pqxx::params::make_c_params ( sl loc ) 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.

◆ 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()

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

inlineconstexprnoexcept

Get the number of parameters currently in this params.

◆ ssize()

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

inlineconstexpr

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.

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

include/pqxx/params.hxx
src/params.cxx

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ params() [1/2]

◆ params() [2/2]

Member Function Documentation

◆ append() [1/10]

◆ append() [2/10]

◆ append() [3/10]

◆ append() [4/10]

◆ append() [5/10]

◆ append() [6/10]

◆ append() [7/10]

◆ append() [8/10]

◆ append() [9/10]

◆ append() [10/10]

◆ append_multi()

◆ make_c_params()

◆ reserve()

◆ size()

◆ ssize()