libpqxx  7.3.1
String-escaping functions

Classes

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

Functions

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::esc (char const text[]) const
 Escape string for use as SQL string literal on this connection. More...
 
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. More...
 
std::string pqxx::connection::esc_raw (std::basic_string_view< std::byte >) const
 Escape binary 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 table field or notification payload. More...
 
std::string pqxx::connection::unesc_raw (char const text[]) const
 Unescape binary data, e.g. from a table field or notification payload. More...
 
std::string pqxx::connection::quote_raw (unsigned char const bin[], std::size_t len) const
 Escape and quote a string of binary data. More...
 
std::string pqxx::connection::quote_raw (std::basic_string_view< std::byte >) const
 Escape and quote a string of binary data. More...
 
std::string pqxx::connection::quote_name (std::string_view identifier) const
 Escape and quote an SQL identifier for use in a query. 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 (std::basic_string_view< std::byte > bytes) const
 Escape and quote binary data for use as a BYTEA value in SQL statement. More...
 
std::string pqxx::connection::esc_like (std::string_view text, char escape_char='\\') const
 Escape string for literal LIKE match. More...
 
std::string pqxx::transaction_base::esc (char const text[]) const
 Escape string for use as SQL string literal in this transaction. More...
 
std::string pqxx::transaction_base::esc (char const text[], std::size_t maxlen) const
 Escape string for use as SQL string literal in this transaction. More...
 
std::string pqxx::transaction_base::esc (std::string_view text) const
 Escape string for use as SQL string literal in this transaction. More...
 
std::string pqxx::transaction_base::esc_raw (unsigned char const data[], std::size_t len) const
 Escape binary data for use as SQL string literal in this transaction. More...
 
std::string pqxx::transaction_base::esc_raw (zview) 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 table field or notification payload. More...
 
std::string pqxx::transaction_base::unesc_raw (char const *text) const
 Unescape binary data, e.g. from a table field or notification payload. 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_raw (unsigned char const bin[], std::size_t len) const
 Binary-escape and quote a binary string for use as an SQL constant. More...
 
std::string pqxx::transaction_base::quote_raw (zview bin) const
 Binary-escape and quote a binary string for use as an SQL constant. More...
 
std::string pqxx::transaction_base::quote_name (std::string_view identifier) const
 Escape an SQL identifier for use in a query. More...
 
std::string pqxx::transaction_base::esc_like (std::string_view bin, char escape_char='\\') const
 Escape string for literal LIKE match. More...
 

Detailed Description

Function Documentation

◆ esc() [1/6]

std::string pqxx::transaction_base::esc ( char const  text[]) const

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

◆ esc() [2/6]

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

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

◆ esc() [3/6]

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

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

◆ esc() [4/6]

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

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!

◆ esc() [5/6]

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

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

◆ esc() [6/6]

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

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

Warning
If the string contains a zero byte, escaping stops there even if it's not at the end of the string!

◆ esc_like() [1/2]

std::string pqxx::transaction_base::esc_like ( std::string_view  bin,
char  escape_char = '\\' 
) const

Escape string for literal LIKE match.

◆ esc_like() [2/2]

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:

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.

References pqxx::check_cast(), pqxx::internal::enc_group(), and pqxx::connection::encoding_id().

◆ esc_raw() [1/4]

std::string pqxx::transaction_base::esc_raw ( unsigned char const  data[],
std::size_t  len 
) const

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, they 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.

◆ esc_raw() [2/4]

std::string pqxx::transaction_base::esc_raw ( zview  bin) const

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

References pqxx::zview::c_str(), pqxx::transaction_base::conn(), and pqxx::connection::esc_raw().

◆ esc_raw() [3/4]

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.

Deprecated:
Use std::basic_string_view<std::byte> instead.

References pqxx::internal::esc_bin().

Referenced by pqxx::transaction_base::esc_raw(), and pqxx::connection::quote_raw().

◆ esc_raw() [4/4]

std::string pqxx::connection::esc_raw ( std::basic_string_view< std::byte >  bin) const

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

References pqxx::internal::esc_bin().

◆ quote() [1/4]

template<typename T >
std::string pqxx::transaction_base::quote ( T const &  t) const

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls.

◆ quote() [2/4]

template<typename T >
std::string pqxx::connection::quote ( T const &  t) const

Represent object as SQL string, including quoting & escaping.

Nulls are recognized and represented as SQL nulls. They get no quotes.

References pqxx::internal::as_c_string(), pqxx::check_version(), pqxx::connection::connection(), pqxx::is_null(), pqxx::to_string(), pqxx::internal::wait_read(), and pqxx::internal::wait_write().

◆ quote() [3/4]

std::string pqxx::connection::quote ( binarystring const &  b) const
Deprecated:
Use basic_string or basic_string_view of std::byte.

References pqxx::binarystring::data(), and pqxx::connection::quote_raw().

◆ quote() [4/4]

std::string pqxx::connection::quote ( std::basic_string_view< std::byte >  bytes) const

Escape and quote binary data for use as a BYTEA value in SQL statement.

References pqxx::connection::quote_raw().

◆ quote_name() [1/2]

std::string pqxx::transaction_base::quote_name ( std::string_view  identifier) const

Escape an SQL identifier for use in a query.

Referenced by pqxx::stream_from::stream_from().

◆ quote_name() [2/2]

std::string pqxx::connection::quote_name ( std::string_view  identifier) const

Escape and quote an SQL identifier for use in a query.

Referenced by pqxx::connection::trace(), and pqxx::connection::unprepare().

◆ quote_raw() [1/4]

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.

◆ quote_raw() [2/4]

std::string pqxx::transaction_base::quote_raw ( zview  bin) const

Binary-escape and quote a binary string for use as an SQL constant.

References pqxx::zview::c_str(), pqxx::transaction_base::conn(), and pqxx::connection::quote_raw().

◆ quote_raw() [3/4]

std::string pqxx::connection::quote_raw ( unsigned char const  bin[],
std::size_t  len 
) const

Escape and quote a string of binary data.

Deprecated:
Use std::basic_string_view<std::byte> instead.

References pqxx::connection::esc_raw().

Referenced by pqxx::connection::quote(), and pqxx::transaction_base::quote_raw().

◆ quote_raw() [4/4]

std::string pqxx::connection::quote_raw ( std::basic_string_view< std::byte >  bytes) const

Escape and quote a string of binary data.

References pqxx::connection::esc_raw().

◆ unesc_raw() [1/4]

std::string pqxx::transaction_base::unesc_raw ( zview  text) const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

◆ unesc_raw() [2/4]

std::string pqxx::transaction_base::unesc_raw ( char const *  text) const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

◆ unesc_raw() [3/4]

std::string pqxx::connection::unesc_raw ( zview  text) const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

References pqxx::zview::c_str(), and pqxx::internal::wait_read().

◆ unesc_raw() [4/4]

std::string pqxx::connection::unesc_raw ( char const  text[]) const

Unescape binary data, e.g. from a table field or notification payload.

Takes a binary string as escaped by PostgreSQL, and returns a restored copy of the original binary data.

References pqxx::internal::unesc_bin().