String conversion

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

Classes
struct	pqxx::string_traits< T >
	Traits class for use in string conversions. More...
struct	pqxx::enum_traits< ENUM >
	Helper class for defining enum conversions. More...
struct	pqxx::string_traits< const char * >
	String traits for C-style string ("pointer to const char") More...
struct	pqxx::string_traits< char * >
	String traits for non-const C-style string ("pointer to char") More...
struct	pqxx::string_traits< char[N]>
	String traits for C-style string constant ("array of char") More...
struct	pqxx::string_traits< std::string >
struct	pqxx::string_traits< const std::string >
struct	pqxx::string_traits< std::stringstream >

Macros
#define	PQXX_DECLARE_STRING_TRAITS_SPECIALIZATION(T)
#define	PQXX_DECLARE_ENUM_CONVERSION(ENUM)
	Macro: Define a string conversion for an enum type. More...

Functions
template<typename T >
void	pqxx::from_string (const char Str[], T &Obj)
	Attempt to convert postgres-generated string to given built-in type. More...
template<typename T >
void	pqxx::from_string (const char Str[], T &Obj, size_t)
	Conversion with known string length (for strings that may contain nuls) More...
template<>
void	pqxx::from_string< std::string > (const char Str[], std::string &Obj, size_t len)
template<typename T >
void	pqxx::from_string (const std::string &Str, T &Obj)
template<typename T >
void	pqxx::from_string (const std::stringstream &Str, T &Obj)
template<>
void	pqxx::from_string (const std::string &Str, std::string &Obj)
template<typename T >
std::string	pqxx::to_string (const T &Obj)
	Convert built-in type to a readable string that PostgreSQL will understand. 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 specialisation of the string_traits template. This template implements some basic functions to support the conversion, ideally in both directions.

If you need to convert a type which is not supported out of the box, define your own string_traits specialisation for that type, similar to the ones defined here. 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.

Macro Definition Documentation

PQXX_DECLARE_ENUM_CONVERSION

#define PQXX_DECLARE_ENUM_CONVERSION

(

ENUM

)

Value:

template<> \
struct PQXX_LIBEXPORT string_traits<ENUM> : pqxx::enum_traits<ENUM> \
{ \
  static constexpr const char *name() noexcept { return #ENUM; } \
  [[noreturn]] static ENUM null() \
        { internal::throw_null_conversion(name()); } \
}

Macro: Define a string conversion for an enum type.

This specialises the pqxx::string_traits template, so use it in the pqxx namespace.

For example:

 #include <iostream>
 #include <pqxx/strconv>
 enum X { xa, xb };
 namespace pqxx { PQXX_DECLARE_ENUM_CONVERSION(x); }
 int main() { std::cout << to_string(xa) << std::endl; }

PQXX_DECLARE_STRING_TRAITS_SPECIALIZATION

#define PQXX_DECLARE_STRING_TRAITS_SPECIALIZATION

(

T

)

Value:

template<> struct PQXX_LIBEXPORT string_traits<T>                       \
{                                                                       \
  static constexpr const char *name() noexcept { return #T; }           \
  static constexpr bool has_null() noexcept { return false; }           \
  static bool is_null(T) { return false; }                              \
  [[noreturn]] static T null()                                          \
    { internal::throw_null_conversion(name()); }                        \
  static void from_string(const char Str[], T &Obj);                    \
  static std::string to_string(T Obj);                                  \
};

Helper: declare a typical string_traits specialisation.

It'd be great to do this without a preprocessor macro. The problem is that we want to represent the parameter type's name to programmers. There's probably a better way in newer C++ versions, but I don't think there is one in C++11.

Function Documentation

from_string() [1/5]

template<typename T >

void pqxx::from_string	(	const char	Str[],
		T &	Obj
	)

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. No fancy features such as hexadecimal or octal, spurious signs, or exponent notation will work. No whitespace is stripped away. Only the kinds of strings that come out of PostgreSQL and out of to_string() can be converted.

References pqxx::from_string().

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

from_string() [2/5]

template<typename T >

void pqxx::from_string	(	const char	Str[],
		T &	Obj,
		size_t
	)

Conversion with known string length (for strings that may contain nuls)

This is only used for strings, where embedded nul bytes should not determine the end of the string.

For all other types, this just uses the regular, nul-terminated version of from_string().

References pqxx::from_string().

from_string() [3/5]

template<typename T >

void pqxx::from_string	(	const std::string &	Str,
		T &	Obj
	)

References pqxx::from_string().

from_string() [4/5]

template<typename T >

void pqxx::from_string	(	const std::stringstream &	Str,
		T &	Obj
	)

References pqxx::from_string().

from_string() [5/5]

template<>

void pqxx::from_string	(	const std::string &	Str,
		std::string &	Obj
	)

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

from_string< std::string >()

template<>

void pqxx::from_string< std::string >	(	const char	Str[],
		std::string &	Obj,
		size_t	len
	)

to_string()

template<typename T >

std::string pqxx::to_string

(

const T &

Obj

)

Convert built-in type to a readable string that PostgreSQL will understand.

No special formatting is done, and any locale settings are ignored. The resulting string will be human-readable and in a format suitable for use in SQL queries.

Referenced by pqxx::internal::throw_null_conversion(), and pqxx::enum_traits< ENUM >::to_string().