Classes
struct	pqxx::nullness< TYPE, ENABLE >
	Traits describing a type's "null value," if any. More...

struct	pqxx::no_null< TYPE >
	Nullness traits describing a type which does not have a null value. More...

struct	pqxx::string_traits< TYPE >
	Traits class for use in string conversions. More...

struct	pqxx::nullness< ENUM, std::enable_if_t< std::is_enum_v< ENUM > > >
	Nullness: Enums do not have an inherent null value. More...

struct	pqxx::internal::enum_traits< ENUM >
	Helper class for defining enum conversions. More...

Typedefs
using	pqxx::internal::enum_traits< ENUM >::impl_type = std::underlying_type_t< ENUM >

using	pqxx::internal::enum_traits< ENUM >::impl_traits = string_traits< impl_type >

Functions
static bool	pqxx::nullness< TYPE, ENABLE >::is_null (TYPE const &value)
	Is `value` a null? More...

static TYPE	pqxx::nullness< TYPE, ENABLE >::null ()
	Return a null value. More...

static constexpr bool	pqxx::no_null< TYPE >::is_null (TYPE const &) noexcept

static zview	pqxx::string_traits< TYPE >::to_buf (char begin, char end, TYPE const &value)
	Return a `string_view` representing value, plus terminating zero. More...

static char *	pqxx::string_traits< TYPE >::into_buf (char begin, char end, TYPE const &value)
	Write value's string representation into buffer at `begin`. More...

static TYPE	pqxx::string_traits< TYPE >::from_string (std::string_view text)
	Parse a string representation of a `TYPE` value. More...

static size_t	pqxx::string_traits< TYPE >::size_buffer (TYPE const &value)
	Estimate how much buffer space is needed to represent value. More...

static constexpr zview	pqxx::internal::enum_traits< ENUM >::to_buf (char begin, char end, ENUM const &value)

static constexpr char *	pqxx::internal::enum_traits< ENUM >::into_buf (char begin, char end, ENUM const &value)

static ENUM	pqxx::internal::enum_traits< ENUM >::from_string (std::string_view text)

static size_t	pqxx::internal::enum_traits< ENUM >::size_buffer (ENUM const &value)

template<typename T >
T	pqxx::from_string (std::string_view text)
	Attempt to convert postgres-generated string to given built-in type. More...

template<typename T >
void	pqxx::from_string (std::string_view text, T &value)
	Attempt to convert postgres-generated string to given built-in object. More...

template<typename TYPE >
std::string	pqxx::to_string (TYPE const &value)
	Convert a value to a readable string that PostgreSQL will understand. More...

template<typename TYPE >
void	pqxx::into_string (TYPE const &value, std::string &out)
	Convert a value to a readable string that PostgreSQL will understand. More...

template<typename TYPE >
bool	pqxx::is_null (TYPE const &value)
	Is `value` null? More...

Variables
template<typename TYPE >
std::string const	pqxx::type_name {internal::demangle_type_name(typeid(TYPE).name())}
	A human-readable name for a type, used in error messages and such. More...

static bool	pqxx::nullness< TYPE, ENABLE >::has_null
	Does this type have a null value? More...

static constexpr bool	pqxx::no_null< TYPE >::has_null = false

template<typename T >
constexpr bool	pqxx::is_sql_array {false}
	Does this type translate to an SQL array? More...

template<typename T >
constexpr char	pqxx::array_separator {','}
	Element separator between SQL array elements of this type. More...

Detailed Description

The PostgreSQL server accepts and represents data in string form. It has its own formats for various data types. The string conversions define how various C++ types translate to and from their respective PostgreSQL text representations.

Each conversion is defined by a specialisations of string_traits. It gets complicated if you want top performance, but until you do, all you really need to care about when converting values between C++ in-memory representations such as int and the postgres string representations is the pqxx::to_string and pqxx::from_string functions.

If you need to convert a type which is not supported out of the box, you'll need to define your own specialisations for these templates, similar to the ones defined here and in pqxx/conversions.hxx. Any conversion code which "sees" your specialisation will now support your conversion. In particular, you'll be able to read result fields into a variable of the new type.

There is a macro to help you define conversions for individual enumeration types. The conversion will represent enumeration values as numeric strings.

Typedef Documentation

◆ impl_traits

template<typename ENUM >

using pqxx::internal::enum_traits< ENUM >::impl_traits = string_traits<impl_type>

◆ impl_type

template<typename ENUM >

using pqxx::internal::enum_traits< ENUM >::impl_type = std::underlying_type_t<ENUM>

Function Documentation

◆ from_string() [1/4]

template<typename TYPE >

bool pqxx::string_traits< TYPE >::from_string ( std::string_view text )

static

Parse a string representation of a TYPE value.

Throws conversion_error if value does not meet the expected format for a value of this type.

Referenced by pqxx::from_string().

◆ from_string() [2/4]

template<typename ENUM >

static ENUM pqxx::internal::enum_traits< ENUM >::from_string ( std::string_view text )

static

References pqxx::from_string().

◆ from_string() [3/4]

template<typename T >

T pqxx::from_string ( std::string_view text )

Attempt to convert postgres-generated string to given built-in type.

If the form of the value found in the string does not match the expected type, e.g. if a decimal point is found when converting to an integer type, the conversion fails. Overflows (e.g. converting "9999999999" to a 16-bit C++ type) are also treated as errors. If in some cases this behaviour should be inappropriate, convert to something bigger such as long int first and then truncate the resulting value.

Only the simplest possible conversions are supported. Fancy features like hexadecimal or octal, spurious signs, or exponent notation won't work. Whitespace is not stripped away. Only the kinds of strings that come out of PostgreSQL and out of to_string() can be converted.

References pqxx::string_traits< TYPE >::from_string().

Referenced by pqxx::internal::to_string_float().

◆ from_string() [4/4]

template<typename T >

void pqxx::from_string	(	std::string_view	text,
		T &	value
	)

Attempt to convert postgres-generated string to given built-in object.

This is like the single-argument form of the function, except instead of returning the value, it sets value.

You may find this more convenient in that it infers the type you want from the argument you pass. But there are disadvantages: it requires an assignment operator, and it may be less efficient.

References pqxx::into_string(), and pqxx::to_string().

Referenced by pqxx::internal::enum_traits< ENUM >::from_string().

◆ into_buf() [1/2]

template<typename TYPE >

static char* pqxx::string_traits< TYPE >::into_buf	(	char *	begin,
		char *	end,
		TYPE const &	value
	)

static

Write value's string representation into buffer at begin.

Assumes that value is non-null.

Writes value's string representation into the buffer, starting exactly at begin, and ensuring a trailing zero. Returns the address just beyond the trailing zero, so the caller could use it as the begin for another call to into_buf writing a next value.

◆ into_buf() [2/2]

template<typename ENUM >

static constexpr char* pqxx::internal::enum_traits< ENUM >::into_buf	(	char *	begin,
		char *	end,
		ENUM const &	value
	)

static

◆ into_string()

template<typename TYPE >

void pqxx::into_string	(	TYPE const &	value,
		std::string &	out
	)

Convert a value to a readable string that PostgreSQL will understand.

This variant of to_string can sometimes save a bit of time in loops, by re-using a std::string for multiple conversions.

Referenced by pqxx::from_string().

◆ is_null() [1/3]

template<typename TYPE , typename ENABLE = void>

static bool pqxx::nullness< TYPE, ENABLE >::is_null ( TYPE const & value )

static

Is value a null?

Referenced by pqxx::is_null().

◆ is_null() [2/3]

template<typename TYPE>

static constexpr bool pqxx::no_null< TYPE >::is_null ( TYPE const & )

staticnoexcept

◆ is_null() [3/3]

template<typename TYPE >

bool pqxx::is_null ( TYPE const & value )

Is value null?

References pqxx::ignore_unused(), and pqxx::nullness< TYPE, ENABLE >::is_null().

Referenced by pqxx::stream_from::complete(), pqxx::field::to< std::string >(), pqxx::field::num(), pqxx::internal::TypedCopyEscaper::operator()(), pqxx::connection::quote(), and pqxx::field::to().

◆ null()

template<typename TYPE , typename ENABLE = void>

static TYPE pqxx::nullness< TYPE, ENABLE >::null ( )

static

Return a null value.

Don't use this in generic code to compare a value and see whether it is null. Some types may have multiple null values which do not compare as equal, or may define a null value which is not equal to anything including itself, like in SQL.

Referenced by pqxx::field::as(), and pqxx::stream_from::operator>>().

◆ size_buffer() [1/2]

template<typename TYPE >

static size_t pqxx::string_traits< TYPE >::size_buffer ( TYPE const & value )

static

Estimate how much buffer space is needed to represent value.

The estimate may be a little pessimistic, if it saves time.

The estimate includes the terminating zero.

◆ size_buffer() [2/2]

template<typename ENUM >

static size_t pqxx::internal::enum_traits< ENUM >::size_buffer ( ENUM const & value )

static

◆ to_buf() [1/2]

template<typename TYPE >

static zview pqxx::string_traits< TYPE >::to_buf	(	char *	begin,
		char *	end,
		TYPE const &	value
	)

static

Return a string_view representing value, plus terminating zero.

Produces a string_view containing the PostgreSQL string representation for value.

Uses the space from begin to end as a buffer, if needed. The returned string may lie somewhere in that buffer, or it may be a compile-time constant, or it may be null if value was a null value. Even if the string is stored in the buffer, its begin() may or may not be the same as begin.

The string_view is guaranteed to be valid as long as the buffer from begin to end remains accessible and unmodified.

Exceptions

pqxx::conversion_overrun if the provided buffer space may not be enough. For maximum performance, this is a conservative estimate. It may complain about a buffer which is actually large enough for your value, if an exact check gets too expensive.

◆ to_buf() [2/2]

template<typename ENUM >

static constexpr zview pqxx::internal::enum_traits< ENUM >::to_buf	(	char *	begin,
		char *	end,
		ENUM const &	value
	)

static

◆ to_string()

template<typename TYPE >

std::string pqxx::to_string ( TYPE const & value )

Convert a value to a readable string that PostgreSQL will understand.

The conversion does no special formatting, and ignores any locale settings. The resulting string will be human-readable and in a format suitable for use in SQL queries. It won't have niceties such as "thousands separators" though.

Variable Documentation

◆ array_separator

template<typename T >

constexpr char pqxx::array_separator {','}

Element separator between SQL array elements of this type.

◆ has_null [1/2]

template<typename TYPE , typename ENABLE = void>

bool pqxx::nullness< TYPE, ENABLE >::has_null

static

Does this type have a null value?

◆ has_null [2/2]

template<typename TYPE>

constexpr bool pqxx::no_null< TYPE >::has_null = false

static

◆ is_sql_array

template<typename T >

constexpr bool pqxx::is_sql_array {false}

Does this type translate to an SQL array?

Specialisations may override this to be true for container types.

This may not always be a black-and-white choice. For instance, a std::string is a container, but normally it translates to an SQL string, not an SQL array.

◆ type_name

template<typename TYPE >

std::string const pqxx::type_name {internal::demangle_type_name(typeid(TYPE).name())}

A human-readable name for a type, used in error messages and such.

Actually this may not always be very user-friendly. It uses std::type_info::name(). On gcc-like compilers we try to demangle its output. Visual Studio produces human-friendly names out of the box.

This variable is not inline. Inlining it gives rise to "memory leak" warnings from asan, the address sanitizer, possibly from use of std::type_info::name.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ impl_traits

◆ impl_type

Function Documentation

◆ from_string() [1/4]

◆ from_string() [2/4]

◆ from_string() [3/4]

◆ from_string() [4/4]

◆ into_buf() [1/2]

◆ into_buf() [2/2]

◆ into_string()

◆ is_null() [1/3]

◆ is_null() [2/3]

◆ is_null() [3/3]

◆ null()

◆ size_buffer() [1/2]

◆ size_buffer() [2/2]

◆ to_buf() [1/2]

◆ to_buf() [2/2]

◆ to_string()

Variable Documentation

◆ array_separator

◆ has_null [1/2]

◆ has_null [2/2]

◆ is_sql_array

◆ type_name