libpqxx
7.6.0
|
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 |
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 . More... | |
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... | |
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 > | |
bool | pqxx::is_null (TYPE const &value) noexcept |
Is value null? More... | |
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... | |
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 bool | pqxx::nullness< TYPE, ENABLE >::always_null |
Is this type always null? More... | |
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... | |
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. More... | |
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.
using pqxx::internal::enum_traits< ENUM >::impl_traits = string_traits<impl_type> |
using pqxx::internal::enum_traits< ENUM >::impl_type = std::underlying_type_t<ENUM> |
|
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().
|
static |
References pqxx::from_string().
TYPE pqxx::from_string | ( | std::string_view | text | ) |
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.
References pqxx::string_traits< TYPE >::from_string().
Referenced by pqxx::internal::to_string_float().
std::string_view pqxx::from_string | ( | std::string_view | text | ) |
"Convert" a std::string_view to a std::string_view.
Just returns its input.
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::to_string().
Referenced by pqxx::internal::enum_traits< ENUM >::from_string().
|
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.
Referenced by pqxx::placeholders< COUNTER >::next().
|
static |
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::to_buf().
|
static |
Is value
a null?
|
staticnoexcept |
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.
|
noexcept |
Is value
null?
Referenced by pqxx::params::append(), pqxx::field::as(), pqxx::field::composite_to(), pqxx::field::as< std::string_view >(), pqxx::field::to< std::string >(), pqxx::field::to< std::string_view >(), pqxx::field::num(), pqxx::connection::quote(), pqxx::field::to(), and pqxx::stream_to::write_values().
|
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::from_string().
constexpr format pqxx::param_format | ( | TYPE const & | ) |
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.
References pqxx::binary, and pqxx::text.
Referenced by pqxx::params::make_c_params().
|
staticnoexcept |
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.
|
staticnoexcept |
References pqxx::size_buffer().
|
noexcept |
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.
Referenced by pqxx::string_traits< binarystring >::into_buf(), pqxx::separated_list(), pqxx::internal::enum_traits< ENUM >::size_buffer(), pqxx::internal::to_string_float(), and pqxx::stream_to::write_values().
|
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.
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. |
|
static |
References pqxx::to_buf().
std::vector<std::string_view> pqxx::to_buf | ( | char * | here, |
char const * | end, | ||
TYPE... | value | ||
) |
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.
References pqxx::into_string().
Referenced by pqxx::internal::state_buffer_overrun(), pqxx::internal::enum_traits< ENUM >::to_buf(), pqxx::internal::to_string_float(), pqxx::blob::write(), and pqxx::stream_to::write_values().
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.
Referenced by pqxx::largeobject_streambuf< CHAR, TRAITS >::overflow().
|
static |
Is this type always null?
|
static |
Are all values of this type null?
There are a few special C++ types which are always null - mainly std::nullptr_t
.
constexpr char pqxx::array_separator {','} |
Element separator between SQL array elements of this type.
|
static |
Does this type have a null value?
|
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."
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.
constexpr bool pqxx::is_unquoted_safe {false} |
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
.