|
libpqxx
The C++ client library for PostgreSQL
|
|
libpqxx
The C++ client library for PostgreSQL
|
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::forbidden_conversion< TYPE > |
| String traits for a forbidden type conversion. More... | |
| struct | pqxx::string_traits< char > |
You cannot convert a char to/from SQL. More... | |
| struct | pqxx::string_traits< unsigned char > |
You cannot convert an unsigned char to/from SQL. More... | |
| struct | pqxx::string_traits< signed char > |
You cannot convert a signed char to/from SQL. More... | |
| struct | pqxx::string_traits< std::byte > |
You cannot convert a std::byte to/from SQL. 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? | |
| static TYPE | pqxx::nullness< TYPE, ENABLE >::null () |
| Return a null value. More... | |
| static constexpr bool | pqxx::no_null< TYPE >::is_null (TYPE const &) noexcept |
| Does a given value correspond to an SQL null value? More... | |
| 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. | |
| static TYPE | pqxx::string_traits< TYPE >::from_string (std::string_view text) |
Parse a string representation of a TYPE value. More... | |
| static std::size_t | pqxx::string_traits< TYPE >::size_buffer (TYPE const &value) noexcept |
| Estimate how much buffer space is needed to represent value. More... | |
| template<typename TYPE > | |
| void | pqxx::oops_forbidden_conversion () noexcept |
| Nonexistent function to indicate a disallowed type conversion. More... | |
| static zview | pqxx::forbidden_conversion< TYPE >::to_buf (char *, char *, TYPE const &) |
| static char * | pqxx::forbidden_conversion< TYPE >::into_buf (char *, char *, TYPE const &) |
| static TYPE | pqxx::forbidden_conversion< TYPE >::from_string (std::string_view) |
| static std::size_t | pqxx::forbidden_conversion< TYPE >::size_buffer (TYPE const &) noexcept |
| 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 std::size_t | pqxx::internal::enum_traits< ENUM >::size_buffer (ENUM const &value) noexcept |
| template<typename TYPE > | |
| TYPE | pqxx::from_string (std::string_view text) |
| Parse a value in postgres' text format as a TYPE. More... | |
| template<> | |
| std::string_view | pqxx::from_string (std::string_view text) |
| "Convert" a std::string_view to a std::string_view. 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> | |
| std::vector< std::string_view > | pqxx::to_buf (char *here, char const *end, TYPE...value) |
| Convert multiple values to strings inside a single buffer. 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 > | |
| constexpr bool | pqxx::is_null (TYPE const &value) noexcept |
Is value null? | |
| template<typename... TYPE> | |
| std::size_t | pqxx::size_buffer (TYPE const &...value) noexcept |
| Estimate how much buffer space is needed to represent values as a string. More... | |
| template<typename TYPE > | |
| constexpr format | pqxx::param_format (TYPE const &) |
| What's the preferred format for passing non-null parameters of this type? More... | |
| template<typename TYPE > | |
| zview | pqxx::generic_to_buf (char *begin, char *end, TYPE const &value) |
Implement string_traits<TYPE>::to_buf by calling into_buf. 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? | |
| static bool | pqxx::nullness< TYPE, ENABLE >::always_null |
| Is this type always null? | |
| static constexpr bool | pqxx::no_null< TYPE >::has_null = false |
Does TYPE have a "built-in null value"? More... | |
| static constexpr bool | pqxx::no_null< TYPE >::always_null = false |
| Are all values of this type null? More... | |
| static constexpr bool | pqxx::string_traits< TYPE >::converts_to_string {false} |
Is conversion from TYPE to strings supported? More... | |
| static constexpr bool | pqxx::string_traits< TYPE >::converts_from_string {false} |
Is conversion from string_view to TYPE supported? More... | |
| static constexpr bool | pqxx::forbidden_conversion< TYPE >::converts_to_string {false} |
| static constexpr bool | pqxx::forbidden_conversion< TYPE >::converts_from_string {false} |
| static constexpr bool | pqxx::internal::enum_traits< ENUM >::converts_to_string {true} |
| static constexpr bool | pqxx::internal::enum_traits< ENUM >::converts_from_string {true} |
| template<typename TYPE > | |
| constexpr bool | pqxx::is_sql_array {false} |
| Does this type translate to an SQL array? More... | |
| template<typename TYPE > | |
| constexpr bool | pqxx::is_unquoted_safe {false} |
| Can we use this type in arrays and composite types without quoting them? More... | |
| template<typename T > | |
| constexpr char | pqxx::array_separator {','} |
| Element separator between SQL array elements of this type. | |
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.
| struct pqxx::nullness |
Traits describing a type's "null value," if any.
Some C++ types have a special value or state which correspond directly to SQL's NULL.
The nullness traits describe whether it exists, and whether a particular value is null.
Static Public Member Functions | |
| static bool | is_null (TYPE const &value) |
Is value a null? | |
| static TYPE | null () |
| Return a null value. More... | |
Static Public Attributes | |
| static bool | has_null |
| Does this type have a null value? | |
| static bool | always_null |
| Is this type always null? | |
| struct pqxx::no_null |
Nullness traits describing a type which does not have a null value.
Static Public Member Functions | |
| static constexpr bool | is_null (TYPE const &) noexcept |
| Does a given value correspond to an SQL null value? More... | |
Static Public Attributes | |
| static constexpr bool | has_null = false |
Does TYPE have a "built-in null value"? More... | |
| static constexpr bool | always_null = false |
| Are all values of this type null? More... | |
| struct pqxx::string_traits |
Traits class for use in string conversions.
Specialize this template for a type for which you wish to add to_string and from_string support.
String conversions are not meant to work for nulls. Check for null before converting a value of TYPE to a string, or vice versa, and handle them separately.
Static Public Member Functions | |
| static zview | to_buf (char *begin, char *end, TYPE const &value) |
Return a string_view representing value, plus terminating zero. More... | |
| static char * | into_buf (char *begin, char *end, TYPE const &value) |
Write value's string representation into buffer at begin. | |
| static TYPE | from_string (std::string_view text) |
Parse a string representation of a TYPE value. More... | |
| static std::size_t | size_buffer (TYPE const &value) noexcept |
| Estimate how much buffer space is needed to represent value. More... | |
Static Public Attributes | |
| static constexpr bool | converts_to_string {false} |
Is conversion from TYPE to strings supported? More... | |
| static constexpr bool | converts_from_string {false} |
Is conversion from string_view to TYPE supported? More... | |
| struct pqxx::forbidden_conversion |
String traits for a forbidden type conversion.
If you have a C++ type for which you explicitly wish to forbid SQL conversion, you can derive a pqxx::string_traits specialisation for that type from this struct. Any attempt to convert the type will then fail to build, and produce an error mentioning oops_forbidden_conversion.
Static Public Member Functions | |
| static zview | to_buf (char *, char *, TYPE const &) |
| static char * | into_buf (char *, char *, TYPE const &) |
| static TYPE | from_string (std::string_view) |
| static std::size_t | size_buffer (TYPE const &) noexcept |
Static Public Attributes | |
| static constexpr bool | converts_to_string {false} |
| static constexpr bool | converts_from_string {false} |
| struct pqxx::string_traits< char > |
You cannot convert a char to/from SQL.
Converting this type may seem simple enough, but it's ambiguous: Did you mean the char value as a small integer? If so, did you mean it to be signed or unsigned? (The C++ Standard allows the system to implement char as either a signed type or an unsigned type.) Or were you thinking of a single-character string (and if so, using what encoding)? Or perhaps it's just a raw byte value?
If you meant it as an integer, use an appropriate integral type such as int or short or unsigned int etc.
If you wanted a single-character string, use std::string_view (or a similar type such as std::string).
Or if you had a raw byte in mind, try pqxx::bytes_view instead.
Inheritance diagram for pqxx::string_traits< char >:Additional Inherited Members | |
| Static Public Member Functions inherited from pqxx::forbidden_conversion< char > | |
| static zview | to_buf (char *, char *, char const &) |
| static char * | into_buf (char *, char *, char const &) |
| static char | from_string (std::string_view) |
| static std::size_t | size_buffer (char const &) noexcept |
| Static Public Attributes inherited from pqxx::forbidden_conversion< char > | |
| static constexpr bool | converts_to_string |
| static constexpr bool | converts_from_string |
| struct pqxx::string_traits< unsigned char > |
You cannot convert an unsigned char to/from SQL.
Converting this type may seem simple enough, but it's ambiguous: Did you mean the char value as a small integer? Or were you thinking of a single-character string (and if so, using what encoding)? Or perhaps it's just a raw byte value?
If you meant it as an integer, use an appropriate integral type such as int or short or unsigned int etc.
If you wanted a single-character string, use std::string_view (or a similar type such as std::string).
Or if you had a raw byte in mind, try pqxx::bytes_view instead.
Inheritance diagram for pqxx::string_traits< unsigned char >:Additional Inherited Members | |
| Static Public Member Functions inherited from pqxx::forbidden_conversion< unsigned char > | |
| static zview | to_buf (char *, char *, unsigned char const &) |
| static char * | into_buf (char *, char *, unsigned char const &) |
| static unsigned char | from_string (std::string_view) |
| static std::size_t | size_buffer (unsigned char const &) noexcept |
| Static Public Attributes inherited from pqxx::forbidden_conversion< unsigned char > | |
| static constexpr bool | converts_to_string |
| static constexpr bool | converts_from_string |
| struct pqxx::string_traits< signed char > |
You cannot convert a signed char to/from SQL.
Converting this type may seem simple enough, but it's ambiguous: Did you mean the value as a small integer? Or were you thinking of a single-character string (and if so, in what encoding)? Or perhaps it's just a raw byte value?
If you meant it as an integer, use an appropriate integral type such as int or short etc.
If you wanted a single-character string, use std::string_view (or a similar type such as std::string).
Or if you had a raw byte in mind, try pqxx::bytes_view instead.
Inheritance diagram for pqxx::string_traits< signed char >:Additional Inherited Members | |
| Static Public Member Functions inherited from pqxx::forbidden_conversion< signed char > | |
| static zview | to_buf (char *, char *, signed char const &) |
| static char * | into_buf (char *, char *, signed char const &) |
| static signed char | from_string (std::string_view) |
| static std::size_t | size_buffer (signed char const &) noexcept |
| Static Public Attributes inherited from pqxx::forbidden_conversion< signed char > | |
| static constexpr bool | converts_to_string |
| static constexpr bool | converts_from_string |
| struct pqxx::string_traits< std::byte > |
You cannot convert a std::byte to/from SQL.
To convert a raw byte value, use a bytes_view.
For example, to convert a byte b from C++ to SQL, convert the value pqxx::bytes_view{&b, 1} instead.
Inheritance diagram for pqxx::string_traits< std::byte >:Additional Inherited Members | |
| Static Public Member Functions inherited from pqxx::forbidden_conversion< std::byte > | |
| static zview | to_buf (char *, char *, std::byte const &) |
| static char * | into_buf (char *, char *, std::byte const &) |
| static std::byte | from_string (std::string_view) |
| static std::size_t | size_buffer (std::byte const &) noexcept |
| Static Public Attributes inherited from pqxx::forbidden_conversion< std::byte > | |
| static constexpr bool | converts_to_string |
| static constexpr bool | converts_from_string |
| struct pqxx::nullness< ENUM, std::enable_if_t< std::is_enum_v< ENUM > > > |
Nullness: Enums do not have an inherent null value.
Inheritance diagram for pqxx::nullness< ENUM, std::enable_if_t< std::is_enum_v< ENUM > > >:Additional Inherited Members | |
| Static Public Member Functions inherited from pqxx::no_null< ENUM > | |
| static constexpr bool | is_null (ENUM const &) noexcept |
| Does a given value correspond to an SQL null value? More... | |
| Static Public Attributes inherited from pqxx::no_null< ENUM > | |
| static constexpr bool | has_null |
Does TYPE have a "built-in null value"? More... | |
| static constexpr bool | always_null |
| Are all values of this type null? More... | |
| struct pqxx::internal::enum_traits |
Helper class for defining enum conversions.
The conversion will convert enum values to numeric strings, and vice versa.
To define a string conversion for an enum type, derive a string_traits specialisation for the enum from this struct.
There's usually an easier way though: the PQXX_DECLARE_ENUM_CONVERSION macro. Use enum_traits manually only if you need to customise your traits type in more detail.
Public Types | |
| using | impl_type = std::underlying_type_t< ENUM > |
| using | impl_traits = string_traits< impl_type > |
Static Public Member Functions | |
| static constexpr zview | to_buf (char *begin, char *end, ENUM const &value) |
| static constexpr char * | into_buf (char *begin, char *end, ENUM const &value) |
| static ENUM | from_string (std::string_view text) |
| static std::size_t | size_buffer (ENUM const &value) noexcept |
Static Public Attributes | |
| static constexpr bool | converts_to_string {true} |
| static constexpr bool | converts_from_string {true} |
|
inlinestatic |
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.
|
inline |
Parse a value in postgres' text format as a 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.
|
inline |
"Convert" a std::string_view to a std::string_view.
Just returns its input.
|
inline |
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.
|
inline |
Implement string_traits<TYPE>::to_buf by calling into_buf.
When you specialise string_traits for a new type, most of the time its to_buf implementation has no special optimisation tricks and just writes its text into the buffer it receives from the caller, starting at the beginning.
In that common situation, you can implement to_buf as just a call to generic_to_buf. It will call into_buf and return the right result for to_buf.
|
inline |
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.
|
inlinestaticnoexcept |
Does a given value correspond to an SQL null value?
Most C++ types, such as int or std::string, have no inherent null value. But some types such as C-style string pointers do have a natural equivalent to an SQL 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.
|
noexcept |
Nonexistent function to indicate a disallowed type conversion.
There is no implementation for this function, so any reference to it will fail to link. The error message will mention the function name and its template argument, as a deliberate message to an application developer that their code is attempting to use a deliberately unsupported conversion.
There are some C++ types that you may want to convert to or from SQL values, but which libpqxx deliberately does not support. Take char for example: we define no conversions for that type because it is not inherently clear whether whether the corresponding SQL type should be a single-character string, a small integer, a raw byte value, etc. The intention could differ from one call site to the next.
If an application attempts to convert these types, we try to make sure that the compiler will issue an error involving this function name, and mention the type, as a hint as to the reason.
|
inline |
What's the preferred format for passing non-null parameters of this type?
This affects how we pass parameters of TYPE when calling parameterised statements or prepared statements.
Generally we pass parameters in text format, but binary strings are the exception. We also pass nulls in binary format, so this function need not handle null values.
|
inlinestaticnoexcept |
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.
|
inlinenoexcept |
Estimate how much buffer space is needed to represent values as a string.
The estimate may be a little pessimistic, if it saves time. It also includes room for a terminating zero after each value.
|
inlinestatic |
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.
| 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. |
|
inline |
Convert multiple values to strings inside a single buffer.
There must be enough room for all values, or this will throw conversion_overrun. You can obtain a conservative estimate of the buffer space required by calling size_buffer() on the values.
The std::string_view results may point into the buffer, so don't assume that they will remain valid after you destruct or move the buffer.
|
inline |
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.
|
static |
Are all values of this type null?
There are a few special C++ types which are always null - mainly std::nullptr_t.
|
static |
Is conversion from string_view to TYPE supported?
When defining your own conversions, specialise this as true to indicate that your string traits support from_string.
|
static |
Is conversion from TYPE to strings supported?
When defining your own conversions, specialise this as true to indicate that your string traits support the conversions to strings.
|
static |
Does TYPE have a "built-in null value"?
For example, a pointer can equal nullptr, which makes a very natural representation of an SQL null value. For such types, the code sometimes needs to make special allowances.
for most types, such as int or std::string, there is no built-in null. If you want to represent an SQL null value for such a type, you would have to wrap it in something that does have a null value. For example, you could use std::optional<int> for "either an @c int or a
null value."
|
inline |
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.
|
inline |
Can we use this type in arrays and composite types without quoting them?
Define this as true only if values of TYPE can never contain any special characters that might need escaping or confuse the parsing of array or composite * types, such as commas, quotes, parentheses, braces, newlines, and so on.
When converting a value of such a type to a string in an array or a field in a composite type, we do not need to add quotes, nor escape any special characters.
This is just an optimisation, so it defaults to false to err on the side of slow correctness.
| 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.
1.8.10 
