Classes
class	pqxx::binarystring
	Binary data corresponding to PostgreSQL's "BYTEA" binary-string type. More...

Functions
std::string	pqxx::connection::esc (char const text[]) const
	Escape string for use as SQL string literal on this connection.

std::string	pqxx::connection::esc (std::string_view text) const
	Escape string for use as SQL string literal on this connection. More...

std::string	pqxx::connection::esc_raw (unsigned char const bin[], std::size_t len) const
	Escape binary string for use as SQL string literal on this connection.

std::string	pqxx::connection::esc_raw (bytes_view) const
	Escape binary string for use as SQL string literal on this connection. More...

bytes	pqxx::connection::unesc_bin (std::string_view text) const
	Unescape binary data, e.g. from a `bytea` field. More...

std::string	pqxx::connection::quote_raw (bytes_view) const
	Escape and quote a string of binary data.

std::string	pqxx::connection::quote_name (std::string_view identifier) const
	Escape and quote an SQL identifier for use in a query.

std::string	pqxx::connection::quote_table (std::string_view name) const
	Escape and quote a table name. More...

std::string	pqxx::connection::quote_table (table_path) const
	Escape and quote a table path. More...

template<typename STRINGS >
std::string	pqxx::connection::quote_columns (STRINGS const &columns) const
	Quote and comma-separate a series of column names. More...

template<typename T >
std::string	pqxx::connection::quote (T const &t) const
	Represent object as SQL string, including quoting & escaping. More...

std::string	pqxx::connection::quote (binarystring const &) const

std::string	pqxx::connection::quote (bytes_view bytes) const
	Escape and quote binary data for use as a BYTEA value in SQL statement.

std::string	pqxx::connection::esc_like (std::string_view text, char escape_char= '\\') const
	Escape string for literal LIKE match. More...

std::string	pqxx::connection::esc (char const text[], std::size_t maxlen) const
	Escape string for use as SQL string literal on this connection. More...

std::string	pqxx::connection::unesc_raw (zview text) const
	Unescape binary data, e.g. from a `bytea` field. More...

std::string	pqxx::connection::unesc_raw (char const text[]) const
	Unescape binary data, e.g. from a `bytea` field. More...

std::string	pqxx::connection::quote_raw (unsigned char const bin[], std::size_t len) const
	Escape and quote a string of binary data.

template<typename... ARGS>
auto	pqxx::transaction_base::esc (ARGS &&...args) const
	Escape string for use as SQL string literal in this transaction. More...

template<typename... ARGS>
auto	pqxx::transaction_base::esc_raw (ARGS &&...args) const
	Escape binary data for use as SQL string literal in this transaction. More...

std::string	pqxx::transaction_base::unesc_raw (zview text) const
	Unescape binary data, e.g. from a `bytea` field. More...

bytes	pqxx::transaction_base::unesc_bin (zview text)
	Unescape binary data, e.g. from a `bytea` field. More...

std::string	pqxx::transaction_base::unesc_raw (char const *text) const
	Unescape binary data, e.g. from a `bytea` field. More...

bytes	pqxx::transaction_base::unesc_bin (char const text[])
	Unescape binary data, e.g. from a `bytea` field. More...

template<typename T >
std::string	pqxx::transaction_base::quote (T const &t) const
	Represent object as SQL string, including quoting & escaping. More...

std::string	pqxx::transaction_base::quote (binarystring const &t) const

std::string	pqxx::transaction_base::quote_raw (unsigned char const bin[], std::size_t len) const
	Binary-escape and quote a binary string for use as an SQL constant.

std::string	pqxx::transaction_base::quote_raw (zview bin) const
	Binary-escape and quote a binary string for use as an SQL constant.

std::string	pqxx::transaction_base::quote_name (std::string_view identifier) const
	Escape an SQL identifier for use in a query.

std::string	pqxx::transaction_base::esc_like (std::string_view bin, char escape_char= '\\') const
	Escape string for literal LIKE match.

Detailed Description

Class Documentation

class pqxx::binarystring

Binary data corresponding to PostgreSQL's "BYTEA" binary-string type.

Deprecated:: Use bytes and bytes_view for binary data. In C++20 or better, any contiguous_range of std::byte will do.

This class represents a binary string as stored in a field of type bytea.

Internally a binarystring is zero-terminated, but it may also contain null bytes, they're just like any other byte value. So don't assume that it's safe to treat the contents as a C-style string.

The binarystring retains its value even if the result it was obtained from is destroyed, but it cannot be copied or assigned.

To include a binarystring value in an SQL query, escape and quote it using the transaction's quote_raw function.

Warning: This class is implemented as a reference-counting smart pointer. Copying, swapping, and destroying binarystring objects that refer to the same underlying data block is not thread-safe. If you wish to pass binarystrings around between threads, make sure that each of these operations is protected against concurrency with similar operations on the same object, or other objects pointing to the same data block.

Public Types
using	char_type = unsigned char

using	value_type = char_type

using	size_type = std::size_t

using	difference_type = long

using	const_reference = value_type const &

using	const_pointer = value_type const *

using	const_iterator = const_pointer

using	const_reverse_iterator = std::reverse_iterator< const_iterator >

Public Member Functions
	binarystring (binarystring const &)=default

	binarystring (field const &)
	Read and unescape bytea field. More...

	binarystring (std::string_view)
	Copy binary data from std::string_view on binary data. More...

	binarystring (void const *, std::size_t)
	Copy binary data of given length straight out of memory.

	binarystring (std::shared_ptr< value_type > ptr, size_type size)
	Efficiently wrap a buffer of binary data in a `binarystring`.

size_type	size () const noexcept
	Size of converted string in bytes.

size_type	length () const noexcept
	Size of converted string in bytes.

bool	empty () const noexcept

const_iterator	begin () const noexcept

const_iterator	cbegin () const noexcept

const_iterator	end () const noexcept

const_iterator	cend () const noexcept

const_reference	front () const noexcept

const_reference	back () const noexcept

const_reverse_iterator	rbegin () const

const_reverse_iterator	crbegin () const

const_reverse_iterator	rend () const

const_reverse_iterator	crend () const

value_type const *	data () const noexcept
	Unescaped field contents.

const_reference	operator[] (size_type i) const noexcept

PQXX_PURE bool	operator== (binarystring const &) const noexcept

bool	operator!= (binarystring const &rhs) const noexcept

binarystring &	operator= (binarystring const &)

const_reference	at (size_type) const
	Index contained string, checking for valid index.

void	swap (binarystring &)
	Swap contents with other binarystring.

char const *	get () const noexcept
	Raw character buffer (no terminating zero is added). More...

std::string_view	view () const noexcept
	Read contents as a std::string_view.

std::string	str () const
	Read as regular C++ string (may include null characters). More...

std::byte const *	bytes () const
	Access data as a pointer to `std::byte`.

pqxx::bytes_view	bytes_view () const
	Read data as a `bytes_view`.

Constructor & Destructor Documentation

pqxx::binarystring::binarystring ( field const & F )

explicit

Read and unescape bytea field.

The field will be zero-terminated, even if the original bytea field isn't.

Parameters

F	the field to read; must be a bytea field

pqxx::binarystring::binarystring ( std::string_view s )

explicit

Copy binary data from std::string_view on binary data.

This is inefficient in that it copies the data to a buffer allocated on the heap.

Member Function Documentation

char const* pqxx::binarystring::get ( ) const

inlinenoexcept

Raw character buffer (no terminating zero is added).

Warning: No terminating zero is added! If the binary data did not end in a null character, you will not find one here.

std::string pqxx::binarystring::str ( ) const

Read as regular C++ string (may include null characters).

This creates and returns a new string object. Don't call this repeatedly; retrieve your string once and keep it in a local variable. Also, do not expect to be able to compare the string's address to that of an earlier invocation.

Function Documentation

template<typename... ARGS>

auto pqxx::transaction_base::esc ( ARGS &&... args ) const

inline

Escape string for use as SQL string literal in this transaction.

Use these when writing SQL queries that incorporate C++ values as SQL constants.

The functions you see here are just convenience shortcuts to the same functions on the connection object.

std::string pqxx::connection::esc ( std::string_view text ) const

Escape string for use as SQL string literal on this connection.

Warning: This is meant for text strings only. It cannot contain bytes whose value is zero ("nul bytes").

std::string pqxx::connection::esc	(	char const	text[],
		std::size_t	maxlen
	)		const

inline

Escape string for use as SQL string literal on this connection.

Warning: This accepts a length, and it does not require a terminating zero byte. But if there is a zero byte, escaping stops there even if it's not at the end of the string!

std::string pqxx::connection::esc_like	(	std::string_view	text,
		char	escape_char = `'\\'`
	)		const

Escape string for literal LIKE match.

Use this when part of an SQL "LIKE" pattern should match only as a literal string, not as a pattern, even if it contains "%" or "_" characters that would normally act as wildcards.

The string does not get string-escaped or quoted. You do that later.

For instance, let's say you have a string name entered by the user, and you're searching a file column for items that match name followed by a dot and three letters. Even if name contains wildcard characters "%" or "_", you only want those to match literally, so "_" only matches "_" and "%" only matches a single "%".

You do that by "like-escaping" name, appending the wildcard pattern ".___", and finally, escaping and quoting the result for inclusion in your query:

```cxx tx.exec( "SELECT file FROM item WHERE file LIKE " + tx.quote(tx.esc_like(name) + ".___"));
```

The SQL "LIKE" operator also lets you choose your own escape character. This is supported, but must be a single-byte character.

template<typename... ARGS>

auto pqxx::transaction_base::esc_raw ( ARGS &&... args ) const

inline

Escape binary data for use as SQL string literal in this transaction.

Raw, binary data is treated differently from regular strings. Binary strings are never interpreted as text, so they may safely include byte values or byte sequences that don't happen to represent valid characters in the character encoding being used.

The binary string does not stop at the first zero byte, as is the case with textual strings. Instead, it may contain zero bytes anywhere. If it happens to contain bytes that look like quote characters, or other things that can disrupt their use in SQL queries, they will be replaced with special escape sequences.

std::string pqxx::connection::esc_raw ( bytes_view bin ) const

Escape binary string for use as SQL string literal on this connection.

You can also just use esc with a binary string.

template<typename T >

std::string pqxx::transaction_base::quote ( T const & t ) const

inline

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

template<typename T >

std::string pqxx::connection::quote ( T const & t ) const

inline

Represent object as SQL string, including quoting & escaping.

Recognises nulls and represents them as SQL nulls. They get no quotes.

template<typename STRINGS >

std::string pqxx::connection::quote_columns ( STRINGS const & columns ) const

inline

Quote and comma-separate a series of column names.

Use this to save a bit of work in cases where you repeatedly need to pass the same list of column names, e.g. with stream_to and stream_from. Some functions that need to quote the columns list internally, will have a "raw" alternative which let you do the quoting yourself. It's a bit of extra work, but it can in rare cases let you eliminate some duplicate work in quoting them repeatedly.

std::string pqxx::connection::quote_table ( std::string_view name ) const

Escape and quote a table name.

When passing just a table name, this is just another name for quote_name.

std::string pqxx::connection::quote_table ( table_path path ) const

Escape and quote a table path.

A table path consists of a table name, optionally prefixed by a schema name; and if both are given, they are in turn optionally prefixed by a database name.

Each portion of the path (database name, schema name, table name) will be quoted separately, and they will be joined together by dots. So for example, myschema.mytable will become "myschema"."mytable".

bytes pqxx::transaction_base::unesc_bin ( zview text )

inline

Unescape binary data, e.g. from a bytea field.