strconv.hxx

Go to the documentation of this file.

/* String conversion definitions.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/stringconv instead.
 *
 * Copyright (c) 2000-2026, Jeroen T. Vermeulen.
 *
 * 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.
 */
#ifndef PQXX_STRCONV_HXX
#define PQXX_STRCONV_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <algorithm>
#include <charconv>
#include <cstring>
#include <limits>
#include <ranges>
#include <sstream>
#include <stdexcept>
#include <typeinfo>
 
#include "pqxx/encoding_group.hxx"
#include "pqxx/except.hxx"
#include "pqxx/util.hxx"
#include "pqxx/zview.hxx"
 
 
namespace pqxx
{
 
 
// TODO: Drop `ENABLE` in 9.x.
 
template<typename TYPE, typename ENABLE = void> struct nullness final
{
  static bool has_null;
 
 
  static constexpr bool always_null = false;
 
  PQXX_PURE static bool is_null(TYPE const &value);
 
 
  [[nodiscard]] PQXX_PURE static TYPE null();
};
 
 
template<typename TYPE> struct no_null
{
 
  static constexpr bool has_null = false;
 
 
  static constexpr bool always_null = false;
 
 
  [[nodiscard]] PQXX_PURE static constexpr bool is_null(TYPE const &) noexcept
  {
    return false;
  }
};
 
 
 
template<typename TYPE, TYPE null_value> struct all_null
{
  static constexpr bool has_null = true;
 
  static constexpr bool always_null = true;
 
  [[nodiscard]] PQXX_PURE static constexpr bool is_null(TYPE const &) noexcept
  {
    return true;
  }
 
  [[nodiscard]] PQXX_PURE static constexpr TYPE null() { return null_value; }
};
 
 
 
struct conversion_context final
{
  // NOLINTBEGIN(misc-non-private-member-variables-in-classes)
 
 
  encoding_group enc = encoding_group::unknown;
 
 
  sl loc = sl::current();
 
  // NOLINTEND(misc-non-private-member-variables-in-classes)
 
  // NOLINTNEXTLINE(google-explicit-constructor,hicpp-explicit-conversions)
  constexpr conversion_context(sl lc = sl::current()) : loc{lc} {}
 
  explicit constexpr conversion_context(
    encoding_group e, sl l = sl::current()) :
          enc{e}, loc{l}
  {}
};
 
 
 
using ctx = conversion_context const &;
 
 
 
template<typename TYPE> struct string_traits final
{
 
  [[nodiscard]] static inline std::size_t
  size_buffer(TYPE const &value) noexcept;
 
 
  [[nodiscard]] static inline std::string_view
  to_buf(std::span<char> buf, TYPE const &value, ctx = {});
 
 
  [[nodiscard]] static inline TYPE
  from_string(std::string_view text, ctx = {});
 
  // TODO: Move is_unquoted_safe into the traits after all?
};
 
 
// C++26: Use "=delete" with reason.
 
template<typename TYPE> struct forbidden_conversion
{
  [[noreturn]] static std::string_view
  to_buf(std::span<char>, TYPE const &, ctx = {}) = delete;
  [[noreturn]] static TYPE from_string(std::string_view, ctx = {}) = delete;
  [[noreturn]] static std::size_t size_buffer(TYPE const &) noexcept = delete;
};
 
 
 
template<> struct string_traits<char> final : forbidden_conversion<char>
{};
 
 
 
template<>
struct string_traits<unsigned char> final : forbidden_conversion<unsigned char>
{};
 
 
 
template<>
struct string_traits<signed char> final : forbidden_conversion<signed char>
{};
 
 
 
template<>
struct string_traits<std::byte> final : forbidden_conversion<std::byte>
{};
 
 
template<enum_type ENUM> struct nullness<ENUM> final : no_null<ENUM>
{};
} // namespace pqxx
 
namespace pqxx::internal
{
template<typename TYPE>
concept to_buf_7 =
  requires(zview out, char *begin, char *end, TYPE const &value) {
    out = string_traits<TYPE>::to_buf(begin, end, value);
  };
 
template<typename TYPE>
concept to_buf_8 = 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);
};
 
 
template<typename TYPE>
concept from_string_8 = requires(std::string_view text, ctx c) {
  TYPE{string_traits<TYPE>::from_string(text, c)};
  TYPE{string_traits<TYPE>::from_string(text)};
};
 
 
template<typename TYPE>
concept from_string_7 = requires(std::string_view text) {
  TYPE{string_traits<TYPE>::from_string(text)};
};
} // namespace pqxx::internal
 
 
namespace pqxx
{
 
template<typename... TYPE>
[[nodiscard]] inline constexpr std::size_t
size_buffer(TYPE const &...value) noexcept
{
  return (string_traits<std::remove_cvref_t<TYPE>>::size_buffer(value) + ...);
}
 
 
 
template<typename TYPE>
  requires(pqxx::internal::to_buf_7<TYPE> or pqxx::internal::to_buf_8<TYPE>)
consteval bool supports_to_buf_8()
{
  return requires { requires pqxx::internal::to_buf_8<TYPE>; };
}
 
 
 
template<typename TYPE>
[[nodiscard]] inline std::string_view
to_buf(std::span<char> buf, TYPE const &value, ctx c = {})
{
  using traits = string_traits<TYPE>;
  if constexpr (supports_to_buf_8<TYPE>())
  {
    return traits::to_buf(buf, value, c);
  }
  else
  {
    auto const begin{std::data(buf)}, end{begin + std::size(buf)};
    return traits::to_buf(begin, end, value);
  }
}
 
 
 
template<typename TYPE>
[[nodiscard]] inline std::size_t
into_buf(std::span<char> buf, TYPE const &value, ctx c = {})
{
  auto const data{std::data(buf)};
  std::string_view out{to_buf(buf, value, c)};
  auto const sz{std::size(out)};
 
  // Be careful to use a memory "move," not a "copy."  Source and destination
  // may overlap (or be identical).
  if (not std::empty(out)) [[likely]]
  {
    if (std::cmp_greater(std::size(out), std::size(buf)))
      throw conversion_overrun{
        std::format(
          "Buffer too small to convert {} value to string (needs a {}-byte "
          "buffer).",
          name_type<TYPE>(), std::size(out)),
        c.loc};
    std::memmove(data, std::data(out), sz);
  }
 
  return sz;
}
 
 
 
template<typename TYPE>
  requires(
    pqxx::internal::from_string_7<TYPE> or pqxx::internal::from_string_8<TYPE>)
consteval bool supports_from_string_8()
{
  return requires { requires pqxx::internal::from_string_8<TYPE>; };
}
 
 
 
template<typename TYPE>
[[nodiscard]] inline TYPE from_string(std::string_view text, ctx c = {})
{
  if constexpr (supports_from_string_8<TYPE>())
    return string_traits<TYPE>::from_string(text, c);
  else
    return string_traits<TYPE>::from_string(text);
}
 
// clang-tidy rule bug:
// NOLINTBEGIN(misc-unused-parameters)
 
 
template<>
[[nodiscard]] inline std::string_view from_string(std::string_view text, ctx)
{
  return text;
}
 
// NOLINTEND(misc-unused-parameters)
 
 
 
template<typename T>
inline void from_string(std::string_view text, T &value, ctx c = {})
{
  value = from_string<T>(text, c);
}
 
 
 
template<typename TYPE>
inline std::string to_string(TYPE const &value, ctx c = {});
} // namespace pqxx
 
 
namespace pqxx::internal
{
 
template<enum_type ENUM> struct enum_traits
{
  using impl_type = std::underlying_type_t<ENUM>;
 
  [[nodiscard]] static constexpr std::string_view
  to_buf(std::span<char> buf, ENUM const &value, ctx c = {})
  {
    return pqxx::to_buf(buf, to_underlying(value), c);
  }
 
  [[nodiscard]] static ENUM from_string(std::string_view text, ctx c = {})
  {
    return static_cast<ENUM>(pqxx::from_string<impl_type>(text, c));
  }
 
  [[nodiscard]] static constexpr std::size_t
  size_buffer(ENUM const &value) noexcept
  {
    return pqxx::size_buffer(to_underlying(value));
  }
 
private:
  // C++23: Replace with std::to_underlying.
  static constexpr impl_type to_underlying(ENUM const &value) noexcept
  {
    return static_cast<impl_type>(value);
  }
};
} // namespace pqxx::internal
 
 
 
#define PQXX_DECLARE_ENUM_CONVERSION(ENUM)                                    \
  template<>                                                                  \
  [[maybe_unused, deprecated("Use name_type() instead of type_name.")]]       \
  constexpr inline std::string_view type_name<ENUM>{#ENUM};                   \
  template<> inline constexpr std::string_view name_type<ENUM>() noexcept     \
  {                                                                           \
    return #ENUM;                                                             \
  }                                                                           \
  template<>                                                                  \
  struct string_traits<ENUM> final : pqxx::internal::enum_traits<ENUM>        \
  {}
 
 
namespace pqxx
{
 
template<typename... TYPE>
[[nodiscard, deprecated("Pass span and string_view.")]]
inline std::vector<std::string_view>
to_buf(char *begin, char const *end, TYPE... value)
{
  assert(begin <= end);
 
  // We can't construct the span as {begin, end} because end points to const.
  // Works fine on gcc 13, but clang 18 vomits huge cryptic errors.
 
  // clang-tidy rule bug:
  // NOLINTNEXTLINE(misc-const-correctness)
  std::span<char> buf{
    begin, check_cast<std::size_t>(
             end - begin, "string_view too large.", sl::current())};
  std::size_t here{0u};
  return {[&here, buf](auto v) {
    auto start{here};
    here += pqxx::into_buf(buf.subspan(start), v);
    assert(start < here);
    assert(here <= std::size(buf));
    // C++26: Use buf.at().
    assert(buf[here - 1] == '\0');
    // Exclude the trailing zero out of the string_view.
    auto len{here - start - 1};
    return std::string_view{std::data(buf) + start, len};
  }(value)...};
}
 
 
 
template<typename... TYPE>
inline std::vector<std::string_view>
to_buf_multi(ctx c, std::span<char> buf, TYPE... value)
{
  // TODO: Would it be worth merging consecutive identical strings?
  std::size_t here{0u};
  return {[&here, buf, &c](auto v) {
    auto start{here};
    here += pqxx::into_buf(buf.subspan(start), v, c);
    assert(start < here);
    assert(here <= std::size(buf));
    // C++26: Use buf.at().
    auto const len{here - start};
    return std::string_view{std::data(buf) + start, len};
  }(value)...};
}
 
 
 
template<typename... TYPE>
inline std::vector<std::string_view>
to_buf_multi(std::span<char> buf, TYPE... value)
{
  // TODO: Would it be worth merging consecutive identical strings?
  std::size_t here{0u};
  conversion_context c{};
  return {[&here, buf, &c](auto v) {
    auto start{here};
    here += pqxx::into_buf(buf.subspan(start), v, c);
    assert(start < here);
    assert(here <= std::size(buf));
    // C++26: Use buf.at().
    auto const len{here - start};
    return std::string_view{std::data(buf) + start, len};
  }(value)...};
}
 
 
 
template<typename TYPE>
inline void into_string(TYPE const &value, std::string &out);
 
 
 
template<typename TYPE> [[nodiscard]] inline constexpr bool has_null() noexcept
{
  using base_type = std::remove_cvref_t<TYPE>;
  return nullness<base_type>::has_null;
}
 
 
 
template<typename TYPE>
[[nodiscard]] inline constexpr bool always_null() noexcept
{
  using base_type = std::remove_cvref_t<TYPE>;
  return nullness<base_type>::always_null;
}
 
 
template<typename TYPE>
[[nodiscard]] inline constexpr bool is_null(TYPE const &value) noexcept
{
  using base_type = std::remove_cvref_t<TYPE>;
  if constexpr (always_null<TYPE>())
    return true;
  else
    return nullness<base_type>::is_null(value);
}
 
 
 
template<typename TYPE>
[[nodiscard]] inline constexpr TYPE make_null()
  requires(pqxx::has_null<TYPE>())
{
  using base_type = std::remove_cvref_t<TYPE>;
  return nullness<base_type>::null();
}
 
 
 
template<typename TYPE> inline constexpr bool is_sql_array{false};
 
 
 
template<typename TYPE> inline constexpr bool is_unquoted_safe{false};
 
 
template<typename T> inline constexpr char array_separator{','};
 
 
 
template<typename TYPE> inline constexpr format param_format(TYPE const &)
{
  return format::text;
}
} // namespace pqxx
 
 
#include "pqxx/internal/conversions.hxx"
#endif