Private namespace for libpqxx's internal use; do not access. More...

Namespaces
	gate

	pq
	Placeholders for libpq declarations.

Classes
class	callgate
	Base class for call gates. More...

class	connection_string_parser
	Parse a connection string into option keys and their values. More...

struct	disallowed_ambiguous_char_conversion
	Deliberately nonfunctional conversion traits for `char` types. More...

struct	float_string_traits
	String traits for builtin floating-point types. More...

struct	integer_string_traits
	String traits for builtin integer types. More...

struct	nonbinary_range_traits
	Base class for `string_traits` specialisations for nonbinary ranges. More...

struct	glyph_scanner
	Wrapper struct template for "find next glyph" functions. More...

struct	glyph_scanner< encoding_group::ascii_safe >
	ASCII, Latin-1, UTF-8, and the like. More...

struct	glyph_scanner< encoding_group::two_tier >
	Common encoding pattern: 1-byte ASCII, or 2-byte starting with high byte. More...

struct	glyph_scanner< encoding_group::gb18030 >
	GB18030 and its older subsets, including GBK. More...

struct	glyph_scanner< encoding_group::sjis >
	Shift-JIS family of encodings. More...

class	stream_query
	Stream query results from the database. Used by transaction_base::stream. More...

class	result_iter
	Iterator for looped unpacking of a result. More...

class	result_iteration
	Iterator for implementing pqxx::result::iter(). More...

class	sql_cursor
	Cursor with SQL positioning semantics. More...

struct	c_params
	Internal type: encode statement parameters. More...

class	stream_from_input_iterator
	Input iterator for stream_from. More...

class	stream_input_iteration
	Iteration over a stream_query. More...

class	stream_query_end_iterator
	The `end()` iterator for a `stream_query`. More...

class	stream_query_iterator
	Minimal iterator for stream_query. More...

struct	notice_waiters
	Various callbacks waiting for a notice to come in. More...

class	basic_robusttransaction
	Helper base class for the pqxx::robusttransaction class template. More...

struct	enum_traits
	Helper class for defining enum conversions. More...

class	basic_transaction
	Helper base class for the pqxx::transaction class template. More...

Typedefs
using	char_finder_func = std::size_t(std::string_view haystack, std::size_t start, sl)
	Function type: "find first occurrence of any of these ASCII characters.". More...

template<typename T >
using	composite_field_parser = void(*)(std::size_t &index, std::string_view input, std::size_t &pos, T &field, std::size_t last_field, sl loc)
	Pointer to an encoding-specific specialisation of parse_composite_field. More...

template<typename CALLABLE >
using	args_t = decltype(args_f(std::declval< CALLABLE >()))
	A callable's parameter types, as a tuple. More...

template<typename... TYPES>
using	strip_types_t = decltype(strip_types(std::declval< TYPES... >()))
	Take a tuple type and apply std::remove_cvref_t to its component types. More...

Functions
constexpr encoding_group	enc_group (std::string_view encoding_name, sl loc)
	Look up encoding group for an encoding by name. More...

char const *	name_encoding (int encoding_id) noexcept
	Return PostgreSQL's name for encoding enum value. More...

encoding_group	enc_group (int, sl)
	Convert libpq encoding enum value to its libpqxx group. More...

std::string	list_bytes (std::string_view data)
	Represent a short stretch of binary data (at most 3) for human readers. More...

void	throw_for_encoding_error (char const *encoding_name, std::string_view buffer, std::size_t start, std::size_t count, sl loc)
	Throw an error reporting that input text is not properly encoded. More...

void	throw_for_truncated_character (char const *encoding_name, std::string_view buffer, std::size_t start, sl loc)
	Throw an error reporting that the input is truncated in mid-character. More...

void	throw_null_conversion (std::string const &type, sl)
	Throw exception for attempt to convert SQL NULL to given type. More...

void	throw_null_conversion (std::string_view type, sl)
	Throw exception for attempt to convert SQL NULL to given type. More...

std::string	state_buffer_overrun (int have_bytes, int need_bytes)
	Summarize buffer overrun. More...

template<std::floating_point T>
std::string	to_string_float (T value, [[maybe_unused]] ctx c)
	Floating-point implementations for `pqxx::to_string()`. More...

template std::string	to_string_float (float, ctx)

template std::string	to_string_float (double, ctx)

template std::string	to_string_float (long double, ctx)

void	esc_bin (bytes_view binary_data, std::span< char > buffer) noexcept
	Hex-escape binary data into a buffer. More...

std::string	esc_bin (bytes_view binary_data)
	Hex-escape binary data into a std::string. More...

void	unesc_bin (std::string_view escaped_data, std::span< std::byte > buffer, sl loc)
	Reconstitute binary data from its escaped version. More...

pqxx::bytes	unesc_bin (std::string_view escaped_data, sl loc)
	Reconstitute binary data from its escaped version. More...

int	check_libpqxx_version (int apps_major, int apps_minor, int apps_patch, std::string_view apps_version)
	Check library binary version against application's expectations. More...

PQXX_COLD PQXX_LIBEXPORT void	skip_init_ssl (int skips) noexcept
	Control OpenSSL/crypto library initialisation. More...

template<encoding_group ENC>
constexpr PQXX_INLINE_COV std::size_t	scan_double_quoted_string (std::string_view input, std::size_t pos, sl loc)

template<encoding_group ENC>
constexpr PQXX_INLINE_COV std::string	parse_double_quoted_string (std::string_view input, std::size_t pos, sl loc)
	Un-quote and un-escape a double-quoted SQL string. More...

template<encoding_group ENC, char... STOP>
constexpr PQXX_INLINE_COV std::size_t	scan_unquoted_string (std::string_view input, std::size_t pos, sl loc)
	Find the end of an unquoted string in an array or composite-type value. More...

template<encoding_group ENC>
constexpr PQXX_INLINE_ONLY std::string_view	parse_unquoted_string (std::string_view input, std::size_t pos, sl)
	Parse an unquoted array entry or cfield of a composite-type field. More...

template<encoding_group ENC, typename T >
PQXX_INLINE_COV void	parse_composite_field (std::size_t &index, std::string_view input, std::size_t &pos, T &field, std::size_t last_field, sl loc)
	Parse a field of a composite-type value. More...

template<typename T >
constexpr PQXX_INLINE_COV composite_field_parser< T >	specialize_parse_composite_field (conversion_context const &c)
	Look up implementation of parse_composite_field for ENC. More...

template<typename T >
PQXX_INLINE_COV std::size_t	size_composite_field_buffer (T const &field)
	Conservatively estimate buffer size needed for a composite field. More...

template<typename T >
PQXX_INLINE_ONLY void	write_composite_field (std::span< char > buf, std::size_t &pos, T const &field, ctx c)

template<nonbinary_range TYPE>
PQXX_INLINE_COV std::size_t	array_into_buf (std::span< char > buf, TYPE const &value, std::size_t budget, ctx c)
	Write an SQL array representation into `buf`. More...

constexpr PQXX_PURE char	number_to_digit (int i) noexcept
	Convert a number in [0, 9] to its ASCII digit. More...

constexpr PQXX_PURE int	digit_to_number (char c) noexcept
	Compute numeric value of given textual digit (assuming that it is a digit). More...

template<typename HAVE , typename NEED >
PQXX_INLINE_COV std::string	state_buffer_overrun (HAVE have_bytes, NEED need_bytes)

template<std::floating_point T>
PQXX_LIBEXPORT std::string	to_string_float (T, ctx={})

template<typename T >
char *	generic_into_buf (char begin, char end, T const &value, ctx c={})
	Generic implementation for `into_buf()`, on top of `to_buf()`. More...

template<typename T >
std::size_t	generic_into_buf (std::span< char > buf, T const &value, ctx c={})
	Generic implementation for `into_buf()`, on top of `to_buf()`. More...

template<nonbinary_range TYPE>
std::size_t	array_into_buf (std::span< char > buf, TYPE const &value, std::size_t budget, ctx c={})
	Write an SQL array representation into `buf`. More...

PQXX_PURE constexpr PQXX_INLINE_ONLY unsigned char	get_byte (std::string_view buffer, std::size_t offset) noexcept
	Extract byte from buffer, return as unsigned char. More...

PQXX_PURE constexpr PQXX_INLINE_ONLY bool	between_inc (unsigned char value, unsigned bottom, unsigned top) noexcept
	Does value lie between bottom and top, inclusive? More...

template<encoding_group ENC, char... NEEDLE>
constexpr PQXX_INLINE_COV std::size_t	find_ascii_char (std::string_view haystack, std::size_t here, sl loc)
	Find any of the ASCII characters in `NEEDLE` in `haystack`. More...

template<char... NEEDLE>
PQXX_PURE PQXX_RETURNS_NONNULL constexpr PQXX_INLINE_COV char_finder_func *	get_char_finder (encoding_group enc, sl loc)
	Look up a character search function for an encoding group. More...

PQXX_LIBEXPORT result_size_type	obtain_stateless_cursor_size (sql_cursor &, sl)

PQXX_LIBEXPORT result	stateless_cursor_retrieve (sql_cursor &, result::difference_type size, result::difference_type begin_pos, result::difference_type end_pos, sl)

PQXX_LIBEXPORT void	wait_for (unsigned int microseconds)
	Wait. More...

PQXX_LIBEXPORT void	wait_fd (int fd, bool for_read, bool for_write, unsigned seconds=1, unsigned microseconds=0, sl=sl::current())
	Wait for a socket to be ready for reading/writing, or timeout. More...

constexpr PQXX_PURE pqxx::encoding_group	get_encoding_group (encoding_group const &enc, sl=sl::current()) noexcept
	Identity function for encoding_group, for regularity. More...

constexpr PQXX_PURE pqxx::encoding_group	get_encoding_group (ctx c, sl=sl::current()) noexcept
	Return client encoding from conversion_context. More...

PQXX_LIBEXPORT pqxx::encoding_group	get_encoding_group (connection const &, sl=sl::current())
	Return connection's current client encoding. More...

PQXX_LIBEXPORT pqxx::encoding_group	get_encoding_group (transaction_base const &, sl=sl::current())
	Return transaction's connection's current client encoding. More...

PQXX_LIBEXPORT void	clear_result (pq::PGresult const *) noexcept
	C++ wrapper for libpq's PQclear. More...

PQXX_LIBEXPORT PQXX_ZARGS std::string	demangle_type_name (char const[]) noexcept
	Attempt to demangle `std::type_info::name()` to something human-readable. More...

constexpr PQXX_ZARGS char const *	as_c_string (char const str[]) noexcept
	Get a raw C string pointer. More...

template<std::size_t N>
constexpr char const *	as_c_string (char(&str)[N]) noexcept
	Get a raw C string pointer. More...

template<std::size_t N>
constexpr char const *	as_c_string (char const (&str)[N]) noexcept
	Get a raw C string pointer. More...

constexpr char const *	as_c_string (std::string const &str) noexcept
	Get a raw C string pointer. More...

template<typename CHAR >
constexpr bool	is_digit (CHAR c) noexcept
	A safer and more generic replacement for `std::isdigit`. More...

std::string	describe_object (std::string_view class_name, std::string_view name)
	Describe an object for humans, based on class name and optional name. More...

void	check_unique_register (void const old_guest, std::string_view old_class, std::string_view old_name, void const new_guest, std::string_view new_class, std::string_view new_name)
	Check validity of registering a new "guest" in a "host.". More...

void	check_unique_unregister (void const old_guest, std::string_view old_class, std::string_view old_name, void const new_guest, std::string_view new_class, std::string_view new_name)
	Like check_unique_register, but for un-registering a guest. More...

constexpr PQXX_PURE std::size_t	size_esc_bin (std::size_t binary_bytes) noexcept
	Compute buffer size needed to escape binary data for use as a BYTEA. More...

constexpr PQXX_PURE std::size_t	size_unesc_bin (std::size_t escaped_bytes) noexcept
	Compute binary size from the size of its escaped version. More...

template<binary T>
void	esc_bin (T &&binary_data, std::span< char > buffer) noexcept
	Hex-escape binary data into a buffer. More...

template<typename RETURN , typename... ARGS>
std::tuple< ARGS... >	args_f (RETURN(&func)(ARGS...))
	Helper for determining a function's parameter types. More...

template<typename RETURN , typename... ARGS>
std::tuple< ARGS... >	args_f (std::function< RETURN(ARGS...)> const &)
	Helper for determining a `std::function`'s parameter types. More...

template<typename CLASS , typename RETURN , typename... ARGS>
std::tuple< ARGS... >	member_args_f (RETURN(CLASS::*)(ARGS...))
	Helper for determining a member function's parameter types. More...

template<typename CALLABLE >
auto	args_f (CALLABLE const &f) -> decltype(member_args_f(&CALLABLE::operator()))
	Helper for determining a callable type's parameter types. More...

template<typename... TYPES>
std::tuple< std::remove_cvref_t< TYPES >... >	strip_types (std::tuple< TYPES... > const &)
	Apply `std::remove_cvref_t` to each of a tuple type's component types. More...

constexpr PQXX_PURE char	unescape_char (char escaped) noexcept
	Return original byte for escaped character. More...

PQXX_COLD char const *	make_strerror_rs_result (int err_result, std::span< char > buffer)
	Helper for avoiding type trouble with `strerror_r()`/`strerror_s()`. More...

PQXX_COLD PQXX_ZARGS char const *	make_strerror_rs_result (char const *err_result, std::span< char >)
	Helper for avoiding type trouble with `strerror_r()`/`strerror_s()`. More...

PQXX_COLD char const *	error_string ([[maybe_unused]] int err_num, [[maybe_unused]] std::span< char > buffer)
	Get error string for a given `errno` value. More...

template<bool terminate>
std::size_t	copy_chars (std::string_view src, std::span< char > dst, std::size_t dst_offset, sl loc)
	Copy text from `src` into `buf` at offset `dst_offset`. More...

Variables
volatile int const	binary_major {version_major}
	Persistent copies of libpqxx version information. More...

volatile int const	binary_minor {version_minor}

volatile int const	binary_patch {version_patch}

std::string_view const	binary_version {version}
	Peristent copy of libpqxx version string. More...

template<typename CONT >
concept	containerlike = requires(CONT con) { CONT{con.begin(), con.end()}; }

template<typename CONT >
concept	nonbinary_container = nonbinary_range<CONT> and containerlike<CONT>

constexpr char	empty_composite_str [] {"()"}

constexpr std::size_t	one_ascii_char {1u}

template<typename ITERATOR >
constexpr auto const	iterator_identity

template<typename TYPE >
concept	to_buf_7
	Signature for string_traits<TYPE>::to_buf() in libpqxx 7. More...

template<typename TYPE >
concept	to_buf_8
	Signature for string_traits<TYPE>::to_buf() in libpqxx 8. More...

template<typename TYPE >
concept	from_string_8
	Signature for string_traits<TYPE>::from_string() in libpqxx 8. More...

template<typename TYPE >
concept	from_string_7
	Signature for string_traits<TYPE>::from_string() in libpqxx 7. More...

template<pqxx::isolation_level isolation, pqxx::write_policy rw>
const zview	begin_cmd
	The SQL command for starting a given type of transaction. More...

template<typename T >
concept	char_type
	Concept: one of the "char" types. More...

template<typename T >
concept	integer = std::integral<T> and not char_type<T>
	Concept: an integral number type. More...

Detailed Description

Private namespace for libpqxx's internal use; do not access.

Internal wrapper for SQL cursors. Supports higher-level cursor classes.

DO NOT INCLUDE THIS FILE DIRECTLY. Other headers include it for you.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

Common implementation for statement parameter lists.

These are used for both prepared statements and parameterized statements.

DO NOT INCLUDE THIS FILE DIRECTLY. Other headers include it for you.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

This namespace hides definitions internal to libpqxx. These are not supposed to be used by client programs, and they may change at any time without notice.

Conversely, if you find something in this namespace tremendously useful, by all means do lodge a request for its publication.

Warning: Here be dragons!

Class Documentation

◆ pqxx::internal::stream_query_end_iterator

class pqxx::internal::stream_query_end_iterator

The end() iterator for a stream_query.

Typedef Documentation

◆ args_t

template<typename CALLABLE >

using pqxx::internal::args_t = typedef decltype(args_f(std::declval<CALLABLE>()))

A callable's parameter types, as a tuple.

◆ char_finder_func

using pqxx::internal::char_finder_func = typedef std::size_t(std::string_view haystack, std::size_t start, sl)

Function type: "find first occurrence of any of these ASCII characters.".

This type of function takes a text buffer, and a location in that buffer; it returns the location of the first occurrence within that string, from the start position onwards, of any of a specific set of ASCII characters.

The start offset marks the beginning of the current glyph. So, if this glyph matches, the function will return start

If there is no match, returns the end of haystack.

◆ composite_field_parser

template<typename T >

using pqxx::internal::composite_field_parser = typedef void (*)( std::size_t &index, std::string_view input, std::size_t &pos, T &field, std::size_t last_field, sl loc)

Pointer to an encoding-specific specialisation of parse_composite_field.

◆ strip_types_t

template<typename... TYPES>

using pqxx::internal::strip_types_t = typedef decltype(strip_types(std::declval<TYPES...>()))

Take a tuple type and apply std::remove_cvref_t to its component types.

Function Documentation

◆ args_f() [1/3]

template<typename CALLABLE >

auto pqxx::internal::args_f ( CALLABLE const & f ) -> decltype(member_args_f(&CALLABLE::operator()))

Helper for determining a callable type's parameter types.

This specialisation should work for lambdas.

This function has no definition. It's not meant to be actually called. It's just there for pattern-matching in the compiler, so we can use its hypothetical return value.

◆ args_f() [2/3]

template<typename RETURN , typename... ARGS>

std::tuple<ARGS...> pqxx::internal::args_f ( RETURN(&)(ARGS...) func )

Helper for determining a function's parameter types.

This function has no definition. It's not meant to be actually called. It's just there for pattern-matching in the compiler, so we can use its hypothetical return value.

◆ args_f() [3/3]

template<typename RETURN , typename... ARGS>

std::tuple<ARGS...> pqxx::internal::args_f ( std::function< RETURN(ARGS...)> const & )

Helper for determining a std::function's parameter types.

This function has no definition. It's not meant to be actually called. It's just there for pattern-matching in the compiler, so we can use its hypothetical return value.

◆ array_into_buf() [1/2]

template<nonbinary_range TYPE>

PQXX_INLINE_COV std::size_t pqxx::internal::array_into_buf	(	std::span< char >	buf,
		TYPE const &	value,
		std::size_t	budget,
		ctx	c
	)

inline

Write an SQL array representation into buf.

Returns: The number of bytes used, from the beginning of buf. There is no terminating zero.

◆ array_into_buf() [2/2]

template<nonbinary_range TYPE>

std::size_t pqxx::internal::array_into_buf	(	std::span< char >	buf,
		TYPE const &	value,
		std::size_t	budget,
		ctx	c
	)

inline

Write an SQL array representation into buf.

Returns: The number of bytes used, from the beginning of buf. There is no terminating zero.

◆ as_c_string() [1/4]

template<std::size_t N>

constexpr char const* pqxx::internal::as_c_string ( char const (&) str[N] )

inlineconstexprnoexcept

Get a raw C string pointer.

◆ as_c_string() [2/4]

constexpr PQXX_ZARGS char const* pqxx::internal::as_c_string ( char const str[] )

inlineconstexprnoexcept

Get a raw C string pointer.

◆ as_c_string() [3/4]

template<std::size_t N>

constexpr char const* pqxx::internal::as_c_string ( char(&) str[N] )

inlineconstexprnoexcept

Get a raw C string pointer.

◆ as_c_string() [4/4]

constexpr char const* pqxx::internal::as_c_string ( std::string const & str )

inlineconstexprnoexcept

Get a raw C string pointer.

◆ between_inc()

PQXX_PURE constexpr PQXX_INLINE_ONLY bool pqxx::internal::between_inc	(	unsigned char	value,
		unsigned	bottom,
		unsigned	top
	)

inlineconstexprnoexcept

Does value lie between bottom and top, inclusive?

Don't generate out-of-line copies; they complicate profiling.

◆ check_libpqxx_version()

PQXX_NOINLINE PQXX_LIBEXPORT int pqxx::internal::check_libpqxx_version	(	int	apps_major,
		int	apps_minor,
		int	apps_patch,
		std::string_view	apps_version
	)

Check library binary version against application's expectations.

Helps detect version mismatches between libpqxx headers and the libpqxx library binary.

Sometimes users run into trouble linking their code against libpqxx because they build their own libpqxx, but the system also has a different version installed; or, they install a dynamically linked application with a mismatched libpqxx binary.

This function's definition is in the libpqxx binary, so it knows the version as it stood when the libpqxx binary was compiled. The calling binary contains a call to this function (inlined from check_version()), passing the version numbers as they applied when the application was compiled. That's why they're called "the app's" version components.

◆ check_unique_register()

void pqxx::internal::check_unique_register	(	void const *	old_guest,
		std::string_view	old_class,
		std::string_view	old_name,
		void const *	new_guest,
		std::string_view	new_class,
		std::string_view	new_name
	)

Check validity of registering a new "guest" in a "host.".

The host might be e.g. a connection, and the guest a transaction. The host can only have one guest at a time, so it is an error to register a new guest while the host already has a guest.

If the new registration is an error, this function throws a descriptive exception.

Pass the old guest (if any) and the new guest (if any), for both, a type name (at least if the guest is not null), and optionally an object name (but which may be omitted if the caller did not assign one).

◆ check_unique_unregister()

void pqxx::internal::check_unique_unregister	(	void const *	old_guest,
		std::string_view	old_class,
		std::string_view	old_name,
		void const *	new_guest,
		std::string_view	new_class,
		std::string_view	new_name
	)

Like check_unique_register, but for un-registering a guest.

Pass the guest which was registered, as well as the guest which is being unregistered, so that the function can check that they are the same one.

◆ clear_result()

void pqxx::internal::clear_result ( pq::PGresult const * data )

noexcept

C++ wrapper for libpq's PQclear.

◆ copy_chars()

template<bool terminate>

std::size_t pqxx::internal::copy_chars	(	std::string_view	src,
		std::span< char >	dst,
		std::size_t	dst_offset,
		sl	loc
	)

inline

Copy text from src into buf at offset dst_offset.

This is a wrapper for std::string_view::copy() with a few changes.

First, it checks for overruns and throws pqxx::conversion_overrun if needed. (To that end, the destination is a std::span, not a raw pointer.)

Second, it takes an offset into the destination buffer, i.e. you can tell it where in the destination buffer the copy should write, but there's no parameter to influence which part of src you want to copy. You always copy the whole thing.

Third, it returns not the number of bytes it copied, but rather, the offset into dst that's right behind the last copied byte.

If terminate is true, also writes a terminating zero.

◆ demangle_type_name()

std::string pqxx::internal::demangle_type_name ( char const raw[] )

noexcept

Attempt to demangle std::type_info::name() to something human-readable.

Even though this function is noexcept, it is technically possible for the construction of the return value to fail. I've never heard of this ever happening, but if it does, there is no way to catch the exception anyway because it happens before main().

So, if construction of the return value fails, there is no choice but to terminate.

Implementation of types-related helpers.

See COPYING for copyright license. If you did not receive a file called COPYING with this source code, please notify the distributor of this mistake, or contact the author.

◆ describe_object()

std::string pqxx::internal::describe_object	(	std::string_view	class_name,
		std::string_view	name
	)

Describe an object for humans, based on class name and optional name.

Interprets an empty name as "no name given."

◆ digit_to_number()

constexpr PQXX_PURE int pqxx::internal::digit_to_number ( char c )

inlineconstexprnoexcept

Compute numeric value of given textual digit (assuming that it is a digit).

The digit must be a base-10 digit.

◆ enc_group() [1/2]

PQXX_PURE PQXX_LIBEXPORT encoding_group pqxx::internal::enc_group	(	int	libpq_enc_id,
		sl	loc
	)

Convert libpq encoding enum value to its libpqxx group.

◆ enc_group() [2/2]

constexpr encoding_group pqxx::internal::enc_group	(	std::string_view	encoding_name,
		sl	loc
	)

constexpr

Look up encoding group for an encoding by name.

Exceptions

argument_error if the encoding name is not an accepted one.

◆ error_string()

PQXX_COLD char const* pqxx::internal::error_string	(	[[maybe_unused] ] int	err_num,
		[[maybe_unused] ] std::span< char >	buffer
	)

inline

Get error string for a given errno value.

◆ esc_bin() [1/3]

PQXX_LIBEXPORT std::string pqxx::internal::esc_bin ( bytes_view binary_data )

Hex-escape binary data into a std::string.

◆ esc_bin() [2/3]

PQXX_LIBEXPORT void pqxx::internal::esc_bin	(	bytes_view	binary_data,
		std::span< char >	buffer
	)

noexcept

Hex-escape binary data into a buffer.

The buffer must have room for size_esc_bin(std::size(binary_data)) bytes, and the function will write exactly that number of bytes into the buffer. This includes a trailing zero.

◆ esc_bin() [3/3]

template<binary T>

void pqxx::internal::esc_bin	(	T &&	binary_data,
		std::span< char >	buffer
	)

inlinenoexcept

Hex-escape binary data into a buffer.

The buffer must have room for size_esc_bin(std::size(binary_data)) bytes, and the function will write exactly that number of bytes into the buffer. This includes a trailing zero.

◆ find_ascii_char()

template<encoding_group ENC, char... NEEDLE>

constexpr PQXX_INLINE_COV std::size_t pqxx::internal::find_ascii_char	(	std::string_view	haystack,
		std::size_t	here,
		sl	loc
	)

inlineconstexpr

Find any of the ASCII characters in NEEDLE in haystack.

Scans through haystack until it finds a single-byte character that matches any of the values in NEEDLE.

Returns the offset of the character it finds, or the end of the haystack otherwise.

◆ generic_into_buf() [1/2]

template<typename T >

char* pqxx::internal::generic_into_buf	(	char *	begin,
		char *	end,
		T const &	value,
		ctx	c = `{}`
	)

inline

Generic implementation for into_buf(), on top of to_buf().

◆ generic_into_buf() [2/2]

template<typename T >

std::size_t pqxx::internal::generic_into_buf	(	std::span< char >	buf,
		T const &	value,
		ctx	c = `{}`
	)

inline

Generic implementation for into_buf(), on top of to_buf().

◆ get_byte()

PQXX_PURE constexpr PQXX_INLINE_ONLY unsigned char pqxx::internal::get_byte	(	std::string_view	buffer,
		std::size_t	offset
	)

inlineconstexprnoexcept

Extract byte from buffer, return as unsigned char.

Don't generate out-of-line copies; they complicate profiling.

◆ get_char_finder()

template<char... NEEDLE>

PQXX_PURE PQXX_RETURNS_NONNULL constexpr PQXX_INLINE_COV char_finder_func* pqxx::internal::get_char_finder	(	encoding_group	enc,
		sl	loc
	)

inlineconstexpr

Look up a character search function for an encoding group.

We only define a few individual instantiations of this function, as needed.

Returns a pointer to a function which looks for the first instance of any of the ASCII characters in NEEDLE. Returns its offset, or the end of the haystack if it found none.

@warn All of the characters in NEEDLE need to be ASCII characters, and they cannot be letters. This is needed because it enables a more efficient implementation of UHC support.

◆ get_encoding_group() [1/4]

pqxx::encoding_group pqxx::internal::get_encoding_group	(	pqxx::connection const &	cx,
		sl	loc = `sl::current()`
	)

Return connection's current client encoding.

◆ get_encoding_group() [2/4]

constexpr PQXX_PURE pqxx::encoding_group pqxx::internal::get_encoding_group	(	ctx	c,
		sl	= `sl::current()`
	)

inlineconstexprnoexcept

Return client encoding from conversion_context.

Also accepts a source_location argument, but ignores it in favour of the one embedded in the conversion_context.

◆ get_encoding_group() [3/4]

constexpr PQXX_PURE pqxx::encoding_group pqxx::internal::get_encoding_group	(	encoding_group const &	enc,
		sl	= `sl::current()`
	)

inlineconstexprnoexcept

Identity function for encoding_group, for regularity.

◆ get_encoding_group() [4/4]

pqxx::encoding_group pqxx::internal::get_encoding_group	(	pqxx::transaction_base const &	tx,
		sl	loc = `sl::current()`
	)

Return transaction's connection's current client encoding.

◆ is_digit()

template<typename CHAR >

constexpr bool pqxx::internal::is_digit ( CHAR c )

inlineconstexprnoexcept

A safer and more generic replacement for std::isdigit.

Turns out std::isdigit isn't as easy to use as it sounds. It takes an int, but requires it to be nonnegative. Which means it's an outright liability on systems where char is signed.

◆ list_bytes()

std::string pqxx::internal::list_bytes ( std::string_view data )

Represent a short stretch of binary data (at most 3) for human readers.

◆ make_strerror_rs_result() [1/2]

PQXX_COLD PQXX_ZARGS char const* pqxx::internal::make_strerror_rs_result	(	char const *	err_result,
		std::span< char >
	)

inline

Helper for avoiding type trouble with strerror_r()/strerror_s().

Extracts the error string from a GNU-style strerror_r() outcome.

There's another overload for th strerror_s() and POSIX-style strerror_r() case.

◆ make_strerror_rs_result() [2/2]

PQXX_COLD char const* pqxx::internal::make_strerror_rs_result	(	int	err_result,
		std::span< char >	buffer
	)

inline

Helper for avoiding type trouble with strerror_r()/strerror_s().

Extracts the error string from a strerror_s() or a POSIX-style streror_r() outcome.

The problem is with strerror_r(), really. There's a GNU version which returns the error string as a char *; and there's a POSIX version which writes the error string into buffer and returns a status code.

Not all compilers will let us handle that with a "if constexpr" on the return type. In particular, clang 17 on a Mac complains. it insists on even the non-applicable branch returning the right type. So, instead of having an if constexpr with an else, we overload functions for the two alternatives.

◆ member_args_f()

template<typename CLASS , typename RETURN , typename... ARGS>

std::tuple< ARGS... > pqxx::internal::member_args_f ( RETURN(CLASS::*)(ARGS...) )

Helper for determining a member function's parameter types.

Helper for determining a const member function's parameter types.

This function has no definition. It's not meant to be actually called. It's just there for pattern-matching in the compiler, so we can use its hypothetical return value.

◆ name_encoding()

PQXX_PURE char const * pqxx::internal::name_encoding ( int encoding_id )

noexcept

Return PostgreSQL's name for encoding enum value.

◆ number_to_digit()

constexpr PQXX_PURE char pqxx::internal::number_to_digit ( int i )

inlineconstexprnoexcept

Convert a number in [0, 9] to its ASCII digit.

◆ obtain_stateless_cursor_size()

pqxx::result::size_type pqxx::internal::obtain_stateless_cursor_size	(	sql_cursor &	cur,
		sl	loc
	)

◆ parse_composite_field()

template<encoding_group ENC, typename T >

PQXX_INLINE_COV void pqxx::internal::parse_composite_field	(	std::size_t &	index,
		std::string_view	input,
		std::size_t &	pos,
		T &	field,
		std::size_t	last_field,
		sl	loc
	)

inline

Parse a field of a composite-type value.

T is the C++ type of the field we're parsing, and index is its zero-based number.

Strip off the leading parenthesis or bracket yourself before parsing. However, this function will parse the lcosing parenthesis or bracket.

After a successful parse, pos will point at std::end(text).

For the purposes of parsing, ranges and arrays count as compositve values, so this function supports parsing those. If you specifically need a closing parenthesis, check afterwards that text did not end in a bracket instead.

Parameters

index	Index of the current field, zero-based. It will increment for the next field.
input	Full input text for the entire composite-type value.
pos	Starting position (in `input`) of the field that we're parsing. After parsing, this will point at the beginning of the next field if there is one, or one position past the last character otherwise.
field	Destination for the parsed value.
scan	Glyph scanning function for the relevant encoding type.
last_field	Number of the last field in the value (zero-based). When parsing the last field, this will equal `index`.

◆ parse_double_quoted_string()

template<encoding_group ENC>

constexpr PQXX_INLINE_COV std::string pqxx::internal::parse_double_quoted_string	(	std::string_view	input,
		std::size_t	pos,
		sl	loc
	)

inlineconstexpr

Un-quote and un-escape a double-quoted SQL string.

Parameters

input Text. The double-quoted string must start at offset pos, and must end at the end of input. So, truncate input before calling if necessary.

◆ parse_unquoted_string()

template<encoding_group ENC>

constexpr PQXX_INLINE_ONLY std::string_view pqxx::internal::parse_unquoted_string	(	std::string_view	input,
		std::size_t	pos,
		sl
	)

inlineconstexpr

Parse an unquoted array entry or cfield of a composite-type field.

Parameters

input	A view on the text, truncated at the end of the string. So, the end of `input` must coincide with the end of the string. Truncate before calling if necessary.
pos	The string's starting offset within `input`.

◆ scan_double_quoted_string()

template<encoding_group ENC>

constexpr PQXX_INLINE_COV std::size_t pqxx::internal::scan_double_quoted_string	(	std::string_view	input,
		std::size_t	pos,
		sl	loc
	)

inlineconstexpr

input[pos] must be the opening double quote.

The backend double-quotes strings in composites or arrays, when needed. Special characters are escaped using backslashes.

Returns the offset of the first position after the closing quote.

◆ scan_unquoted_string()

template<encoding_group ENC, char... STOP>

constexpr PQXX_INLINE_COV std::size_t pqxx::internal::scan_unquoted_string	(	std::string_view	input,
		std::size_t	pos,
		sl	loc
	)

inlineconstexpr

Find the end of an unquoted string in an array or composite-type value.

Stops when it gets to the end of the input; or when it sees any of the characters in STOP which has not been escaped.

For array values, STOP is an array element separator (typically comma, or semicolon), or a closing brace. For a value of a composite type, STOP is a comma or a closing parenthesis.

◆ size_composite_field_buffer()

template<typename T >

PQXX_INLINE_COV std::size_t pqxx::internal::size_composite_field_buffer ( T const & field )

inline

Conservatively estimate buffer size needed for a composite field.

◆ size_esc_bin()

constexpr PQXX_PURE std::size_t pqxx::internal::size_esc_bin ( std::size_t binary_bytes )

inlineconstexprnoexcept

Compute buffer size needed to escape binary data for use as a BYTEA.

This uses the hex-escaping format. The return value includes room for the "\x" prefix.

◆ size_unesc_bin()

constexpr PQXX_PURE std::size_t pqxx::internal::size_unesc_bin ( std::size_t escaped_bytes )

inlineconstexprnoexcept

Compute binary size from the size of its escaped version.

Do not include a terminating zero in escaped_bytes.

◆ skip_init_ssl()

void pqxx::internal::skip_init_ssl ( int skips )

noexcept

Control OpenSSL/crypto library initialisation.

This is an internal helper. Unless you're working on libpqxx itself, use pqxx::skip_init_ssl instead.

Parameters

flags a bitmask of 1 << flag for each of the skip_init flags.

Ignores the skip_init::nothing flag.

◆ specialize_parse_composite_field()

template<typename T >

constexpr PQXX_INLINE_COV composite_field_parser<T> pqxx::internal::specialize_parse_composite_field ( conversion_context const & c )

inlineconstexpr

Look up implementation of parse_composite_field for ENC.

◆ state_buffer_overrun() [1/2]

template<typename HAVE , typename NEED >

PQXX_INLINE_COV std::string pqxx::internal::state_buffer_overrun	(	HAVE	have_bytes,
		NEED	need_bytes
	)

inline

◆ state_buffer_overrun() [2/2]

PQXX_LIBEXPORT std::string pqxx::internal::state_buffer_overrun	(	int	have_bytes,
		int	need_bytes
	)

Summarize buffer overrun.

Don't worry about the exact parameter types: the sizes will be reasonably small, and nonnegative.

◆ stateless_cursor_retrieve()

pqxx::result pqxx::internal::stateless_cursor_retrieve	(	sql_cursor &	cur,
		result::difference_type	size,
		result::difference_type	begin_pos,
		result::difference_type	end_pos,
		sl	loc
	)

◆ strip_types()

template<typename... TYPES>

std::tuple<std::remove_cvref_t<TYPES>...> pqxx::internal::strip_types ( std::tuple< TYPES... > const & )

Apply std::remove_cvref_t to each of a tuple type's component types.

This function has no definition. It is not meant to be called, only to be used to deduce the right types.

◆ throw_for_encoding_error()

PQXX_COLD PQXX_LIBEXPORT PQXX_ZARGS void pqxx::internal::throw_for_encoding_error	(	char const *	encoding_name,
		std::string_view	buffer,
		std::size_t	start,
		std::size_t	count,
		sl	loc
	)

Throw an error reporting that input text is not properly encoded.

Parameters

encoding_name	Either a name for the expected encoding, or a placeholder for it.
buffer	The full input text.
start	The starting offset for the incorrect character.
count	The number of bytes in the incorrect character. Must not exceed the size of the buffer.

◆ throw_for_truncated_character()

PQXX_COLD PQXX_LIBEXPORT PQXX_ZARGS void pqxx::internal::throw_for_truncated_character	(	char const *	encoding_name,
		std::string_view	buffer,
		std::size_t	start,
		sl	loc
	)

Throw an error reporting that the input is truncated in mid-character.

This happens when a multibyte character is supposed to span more bytes than there are left in the buffer.

Parameters

encoding_name	Either a name for the expected encoding, or a placeholder for it.
buffer	The full input text.
start	The starting offset for the incorrect character.

◆ throw_null_conversion() [1/2]

PQXX_COLD PQXX_LIBEXPORT void pqxx::internal::throw_null_conversion	(	std::string const &	type,
		sl	loc
	)

Throw exception for attempt to convert SQL NULL to given type.

◆ throw_null_conversion() [2/2]

PQXX_COLD PQXX_LIBEXPORT void pqxx::internal::throw_null_conversion	(	std::string_view	type,
		sl	loc
	)

Throw exception for attempt to convert SQL NULL to given type.

◆ to_string_float() [1/5]

template std::string pqxx::internal::to_string_float	(	double	,
		ctx
	)

◆ to_string_float() [2/5]

template std::string pqxx::internal::to_string_float	(	float	,
		ctx
	)

◆ to_string_float() [3/5]

template std::string pqxx::internal::to_string_float	(	long double	,
		ctx
	)

◆ to_string_float() [4/5]

template<std::floating_point T>

std::string pqxx::internal::to_string_float	(	T	value,
		[[maybe_unused] ] ctx	c
	)

Floating-point implementations for pqxx::to_string().

◆ to_string_float() [5/5]

template<std::floating_point T>

PQXX_LIBEXPORT std::string pqxx::internal::to_string_float	(	T	,
		ctx	= `{}`
	)

◆ unesc_bin() [1/2]

PQXX_LIBEXPORT bytes pqxx::internal::unesc_bin	(	std::string_view	escaped_data,
		sl	loc
	)

Reconstitute binary data from its escaped version.

◆ unesc_bin() [2/2]

PQXX_LIBEXPORT void pqxx::internal::unesc_bin	(	std::string_view	escaped_data,
		std::span< std::byte >	buffer,
		sl	loc
	)

Reconstitute binary data from its escaped version.

◆ unescape_char()

constexpr PQXX_PURE char pqxx::internal::unescape_char ( char escaped )

inlineconstexprnoexcept

Return original byte for escaped character.

◆ wait_fd()

PQXX_LIBEXPORT void pqxx::internal::wait_fd	(	int	fd,
		bool	for_read,
		bool	for_write,
		unsigned	seconds = `1`,
		unsigned	microseconds = `0`,
		sl	= `sl::current()`
	)

Wait for a socket to be ready for reading/writing, or timeout.

All waits are finite. It is not guaranteed that this will wait for the full time specified, e.g. because the process receives a signal. The calling code MUST be prepared to handle an occasional premature return.

Why does this not wait forever? Mainly so that you do not forget to handle premature returns, and write subtly buggy code that appears to work fine in testing!

Okay, but why don't you _handle signals and continue to wait?_ Because how the application handles signals is the application's business. It's not up to libpqxx to mess with that. Perhaps you want to return early after some particular signal. Perhaps you don't for some other signal.

But what if I need to minimise wakeups to save power or CPU time? It probably won't make much of a difference whether it's just libpqxx waking up or your own code waking up as well. What you can do is pass a longer wait time, so it happens less often.

Increasing wait times can help, but there are diminishing returns. It will reduce this particular overhead in your application, until some other source of overhead becomes more significant. At that point... stop increasing the wait time and go fix that other thing!

◆ wait_for()

void pqxx::internal::wait_for ( unsigned int microseconds )

Wait.

This is normally std::this_thread::sleep_for(). But MinGW's thread header doesn't work, so we must be careful about including it.

◆ write_composite_field()

template<typename T >

PQXX_INLINE_ONLY void pqxx::internal::write_composite_field	(	std::span< char >	buf,
		std::size_t &	pos,
		T const &	field,
		ctx	c
	)

inline

Variable Documentation

◆ begin_cmd

template<pqxx::isolation_level isolation, pqxx::write_policy rw>

const zview pqxx::internal::begin_cmd

extern

The SQL command for starting a given type of transaction.

◆ binary_major

volatile int const pqxx::internal::binary_major {version_major}

Persistent copies of libpqxx version information.

These are not efficient. They are stored here for one reason only: to ensure that the libpqxx library binary contains its own version inforamtion, even if the application code that calls libpqxx is compiled against a different version. (We allow some slight differences.) That way we can compare the binary version against the version that was in the headers.

The volatile is probably overkill. I just want this to have linkage as far as compilation is concerned.

◆ binary_minor

volatile int const pqxx::internal::binary_minor {version_minor}

◆ binary_patch

volatile int const pqxx::internal::binary_patch {version_patch}

◆ binary_version

std::string_view const pqxx::internal::binary_version {version}

Peristent copy of libpqxx version string.

I'd like to make this volatile, but there are just too many complications along the way. Which is probably for the best.

Let's just hope that this declaration is enough to prevent the compiler from optimising this away completely. (I wouldn't particularly mind if the linker did so though.)

◆ char_type

template<typename T >

concept pqxx::internal::char_type

Initial value:

= std::same_as<std::remove_cv_t<T>, char> or
                    std::same_as<std::remove_cv_t<T>, signed char> or
                    std::same_as<std::remove_cv_t<T>, unsigned char>

Concept: one of the "char" types.

◆ containerlike

template<typename CONT >

concept pqxx::internal::containerlike = requires(CONT con) { CONT{con.begin(), con.end()}; }

◆ empty_composite_str

constexpr char pqxx::internal::empty_composite_str[] {"()"}

constexpr

◆ from_string_7

template<typename TYPE >

concept pqxx::internal::from_string_7

Initial value:

= requires(std::string_view text) {
  TYPE{string_traits<TYPE>::from_string(text)};
}

Signature for string_traits<TYPE>::from_string() in libpqxx 7.

This is actually identical to the new format, except the latter accepts an optional conversion_context argument.

◆ from_string_8

template<typename TYPE >

concept pqxx::internal::from_string_8

Initial value:

= requires(std::string_view text, ctx c) {
  TYPE{string_traits<TYPE>::from_string(text, c)};
  TYPE{string_traits<TYPE>::from_string(text)};
}

Signature for string_traits<TYPE>::from_string() in libpqxx 8.

◆ integer

template<typename T >

concept pqxx::internal::integer = std::integral<T> and not char_type<T>

Concept: an integral number type.

Unlike std::integral, this does not include the char types.

◆ iterator_identity

template<typename ITERATOR >

constexpr auto const pqxx::internal::iterator_identity

inlineconstexpr

Initial value:

{

[](decltype(*std::declval<ITERATOR>()) x) { return x; }}

◆ nonbinary_container

template<typename CONT >

concept pqxx::internal::nonbinary_container = nonbinary_range<CONT> and containerlike<CONT>

◆ one_ascii_char

constexpr std::size_t pqxx::internal::one_ascii_char {1u}

constexpr

◆ to_buf_7

template<typename TYPE >

concept pqxx::internal::to_buf_7

Initial value:

=
  requires(zview out, char *begin, char *end, TYPE const &value) {
    out = string_traits<TYPE>::to_buf(begin, end, value);
  }

Signature for string_traits<TYPE>::to_buf() in libpqxx 7.

◆ to_buf_8

template<typename TYPE >

concept pqxx::internal::to_buf_8

Initial value:

= requires(
  std::string_view out, std::span<char> buf, TYPE const &value, ctx c) {
  out = string_traits<TYPE>::to_buf(buf, value, c);
  out = string_traits<TYPE>::to_buf(buf, value);
}

Signature for string_traits<TYPE>::to_buf() in libpqxx 8.

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Class Documentation

◆ pqxx::internal::stream_query_end_iterator

Typedef Documentation

◆ args_t

◆ char_finder_func

◆ composite_field_parser

◆ strip_types_t

Function Documentation

◆ args_f() [1/3]

◆ args_f() [2/3]

◆ args_f() [3/3]

◆ array_into_buf() [1/2]

◆ array_into_buf() [2/2]

◆ as_c_string() [1/4]

◆ as_c_string() [2/4]

◆ as_c_string() [3/4]

◆ as_c_string() [4/4]

◆ between_inc()

◆ check_libpqxx_version()

◆ check_unique_register()

◆ check_unique_unregister()

◆ clear_result()

◆ copy_chars()

◆ demangle_type_name()

◆ describe_object()

◆ digit_to_number()

◆ enc_group() [1/2]

◆ enc_group() [2/2]

◆ error_string()

◆ esc_bin() [1/3]

◆ esc_bin() [2/3]

◆ esc_bin() [3/3]

◆ find_ascii_char()

◆ generic_into_buf() [1/2]

◆ generic_into_buf() [2/2]

◆ get_byte()

◆ get_char_finder()

◆ get_encoding_group() [1/4]

◆ get_encoding_group() [2/4]

◆ get_encoding_group() [3/4]

◆ get_encoding_group() [4/4]

◆ is_digit()

◆ list_bytes()

◆ make_strerror_rs_result() [1/2]

◆ make_strerror_rs_result() [2/2]

◆ member_args_f()

◆ name_encoding()

◆ number_to_digit()

◆ obtain_stateless_cursor_size()

◆ parse_composite_field()

◆ parse_double_quoted_string()

◆ parse_unquoted_string()

◆ scan_double_quoted_string()

◆ scan_unquoted_string()

◆ size_composite_field_buffer()

◆ size_esc_bin()

◆ size_unesc_bin()

◆ skip_init_ssl()

◆ specialize_parse_composite_field()

◆ state_buffer_overrun() [1/2]

◆ state_buffer_overrun() [2/2]

◆ stateless_cursor_retrieve()

◆ strip_types()

◆ throw_for_encoding_error()

◆ throw_for_truncated_character()

◆ throw_null_conversion() [1/2]

◆ throw_null_conversion() [2/2]

◆ to_string_float() [1/5]

◆ to_string_float() [2/5]

◆ to_string_float() [3/5]

◆ to_string_float() [4/5]

◆ to_string_float() [5/5]

◆ unesc_bin() [1/2]

◆ unesc_bin() [2/2]