util.hxx

Go to the documentation of this file.

/* Various utility definitions for libpqxx.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/util 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_UTIL_HXX
#define PQXX_UTIL_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <cassert>
#include <cctype>
#include <cerrno>
#include <cmath>
#include <cstring>
#include <format>
#include <functional>
#include <iterator>
#include <limits>
#include <memory>
#include <stdexcept>
#include <string>
#include <string_view>
#include <type_traits>
#include <typeinfo>
#include <utility>
#include <vector>
 
#include "pqxx/except.hxx"
#include "pqxx/types.hxx"
#include "pqxx/version.hxx"
 
 
namespace pqxx
{} // namespace pqxx
 
 
// C++23: Retire wrapper.
// PQXX_UNREACHABLE: equivalent to `std::unreachable()` if available.
#if defined(__cpp_lib_unreachable) && __cpp_lib_unreachable
#  define PQXX_UNREACHABLE std::unreachable()
#else
#  define PQXX_UNREACHABLE [[unlikely]] while (false)
#endif
 
 
 
namespace pqxx::internal
{} // namespace pqxx::internal
 
 
namespace pqxx
{
using namespace std::literals;
 
 
 
template<typename TO, typename FROM>
inline TO
check_cast(FROM value, std::string_view description, sl loc = sl::current())
  requires(
    std::is_arithmetic_v<FROM> and std::is_arithmetic_v<TO> and
    (std::is_integral_v<FROM> == std::is_integral_v<TO>))
{
  // The rest of this code won't quite work for bool, but bool is trivially
  // convertible to other arithmetic types as far as I can see.
  if constexpr (std::is_same_v<FROM, bool>)
    return static_cast<TO>(value);
 
  using to_limits = std::numeric_limits<TO>;
 
  if constexpr (std::is_integral_v<FROM>)
  {
    // Integral value.  These are simple, but only thanks to the standard
    // library's safe comparison functions.
    if (std::cmp_less(value, to_limits::lowest()))
      throw range_error{
        std::format(
          "Underflow casting {} from {} to {}: {}", value, name_type<FROM>(),
          name_type<TO>(), description),
        loc};
    if (std::cmp_greater(value, (to_limits::max)()))
      throw range_error{
        std::format(
          "Overflow casting {} from {} to {}: {}", value, name_type<FROM>(),
          name_type<TO>(), description),
        loc};
  }
  else if (std::isinf(value))
  {
    // Floating-point infinities.  These will always exceed TO's upper or lower
    // limit, but that's fine; they will translate directly to a TO infinity.
  }
  else
  {
    // NaN, or a regular floating-point value.  A NaN will never be less than
    // or greater than any value, such as TO's upper/lower bounds.
    if (value < to_limits::lowest())
      throw range_error{
        std::format(
          "Underflow casting {} from {} to {}: {}", value, name_type<FROM>(),
          name_type<TO>(), description),
        loc};
    if (value > (to_limits::max)())
      throw range_error{
        std::format(
          "Overflow casting {} from {} to {}: {}", value, name_type<FROM>(),
          name_type<TO>(), description),
        loc};
  }
 
  return static_cast<TO>(value);
}
 
 
// TODO: No longer useful as of PostgreSQL 17: libpq is always thread-safe.
 
struct PQXX_LIBEXPORT thread_safety_model final
{
  std::string description;
 
  bool safe_libpq = false;
 
 
  bool safe_kerberos = false;
};
 
 
[[nodiscard]] PQXX_LIBEXPORT thread_safety_model describe_thread_safety();
 
 
 
struct byte_char_traits final : std::char_traits<char>
{
  using char_type = std::byte;
 
  static void assign(std::byte &a, const std::byte &b) noexcept { a = b; }
  static bool eq(std::byte a, std::byte b) { return a == b; }
  static bool lt(std::byte a, std::byte b) { return a < b; }
 
  static int compare(const std::byte *a, const std::byte *b, std::size_t size)
  {
    return std::memcmp(a, b, size);
  }
 
  /* This would be nonsense: we can't determine the length of a random sequence
   * of bytes.  There is no terminating zero like there is for C strings.
   *
   * But `std::char_traits` requires us to provide this function, so we
   * declare it without defining it.
   */
  static size_t length(const std::byte *data);
 
  PQXX_RETURNS_NONNULL static const std::byte *
  find(const std::byte *data, std::size_t size, const std::byte &value)
  {
    return static_cast<const std::byte *>(
      std::memchr(data, static_cast<int>(value), size));
  }
 
  PQXX_RETURNS_NONNULL static std::byte *
  move(std::byte *dest, const std::byte *src, std::size_t size)
  {
    return static_cast<std::byte *>(std::memmove(dest, src, size));
  }
 
  PQXX_RETURNS_NONNULL static std::byte *
  copy(std::byte *dest, const std::byte *src, std::size_t size)
  {
    return static_cast<std::byte *>(std::memcpy(dest, src, size));
  }
 
  PQXX_RETURNS_NONNULL static std::byte *
  assign(std::byte *dest, std::size_t size, std::byte value)
  {
    return static_cast<std::byte *>(
      std::memset(dest, static_cast<int>(value), size));
  }
 
  static int_type not_eof(int_type value);
 
  static std::byte to_char_type(int_type value) { return std::byte(value); }
 
  static int_type to_int_type(std::byte value) { return int_type(value); }
 
  static bool eq_int_type(int_type a, int_type b) { return a == b; }
 
  static int_type eof();
};
 
// Supress warnings from potentially using a deprecated generic
// std::char_traits.
// Necessary for libc++ 18.
#include "pqxx/internal/ignore-deprecated-pre.hxx"
 
using bytes = std::vector<std::byte>;
 
#include "pqxx/internal/ignore-deprecated-post.hxx"
 
 
 
template<potential_binary TYPE> inline bytes_view binary_cast(TYPE const &data)
{
  using item_t = value_type<TYPE>;
  return std::as_bytes(
    std::span<item_t const>{std::data(data), std::size(data)});
}
 
 
 
template<char_sized CHAR, typename SIZE>
bytes_view binary_cast(CHAR const *data, SIZE size)
{
  return binary_cast(std::span<CHAR>{data, check_cast<std::size_t>(size)});
}
 
 
constexpr oid oid_none{0};
 
 
 
template<typename... T>
[[maybe_unused, deprecated("Use [[maybe_unused]], std::ignore, etc.")]]
inline constexpr void ignore_unused(T &&...) noexcept
{}
 
 
// clang-tidy rule bug:
// NOLINTBEGIN(
//    cppcoreguidelines-pro-bounds-array-to-pointer-decay,
//    hicpp-no-array-decay
// )
 
 
template<typename HAYSTACK, typename NEEDLE>
inline bool str_contains(HAYSTACK const &haystack, NEEDLE const &needle)
  requires(
    std::same_as<HAYSTACK, std::string> or
    std::same_as<HAYSTACK, std::string_view>)
{
  // C++23: Replace with `haystack.contains(needle)`.  Retire wrapper.
  return haystack.find(needle) != HAYSTACK::npos;
}
// NOLINTEND(
//    cppcoreguidelines-pro-bounds-array-to-pointer-decay,
//    hicpp-no-array-decay
// )
 
 
 
template<typename SL>
concept c_source_location = requires(SL const loc) {
  { loc.file_name() } -> std::convertible_to<char const *>;
  { loc.function_name() } -> std::convertible_to<char const *>;
  { loc.line() } -> std::convertible_to<std::uint_least32_t>;
  { loc.column() } -> std::convertible_to<std::uint_least32_t>;
};
 
 
template<c_source_location LOC>
PQXX_PURE inline std::string source_loc(LOC const &loc)
{
  char const *const file{loc.file_name()};
  assert(file != nullptr);
 
  char const *const func{loc.function_name()};
  unsigned const line{loc.line()}, column{loc.column()};
 
  // (The standard says this can't be null, but let's be conservative.)
  bool const have_func{func != nullptr and *func != '\0'}, have_line{line > 0},
    have_column{column > 0};
 
  if (have_func and have_line and have_column)
  {
    return std::format("{}:{}:{}: ({})", file, line, column, func);
  }
  else if (have_func and have_line)
  {
    return std::format("{}:{}: ({})", file, line, func);
  }
  else if (have_line and have_column)
  {
    return std::format("{}:{}:{}:", file, line, column);
  }
  else if (have_func)
  {
    // (In this case we don't care whether we have a column.)
    return std::format("{}: ({})", file, func);
  }
  else if (have_line)
  {
    return std::format("{}:{}:", file, line);
  }
  else
  {
    return std::format("{}:", file);
  }
}
} // namespace pqxx
 
 
namespace pqxx::internal
{
using namespace std::literals;
 
 
 
PQXX_NOINLINE PQXX_LIBEXPORT int check_libpqxx_version(
  int apps_major, int apps_minor, int apps_patch,
  std::string_view apps_version);
 
 
PQXX_ZARGS inline constexpr char const *as_c_string(char const str[]) noexcept
{
  return str;
}
template<std::size_t N>
inline constexpr char const *as_c_string(char (&str)[N]) noexcept
{
  return str;
}
template<std::size_t N>
inline constexpr char const *as_c_string(char const (&str)[N]) noexcept
{
  return str;
}
inline constexpr char const *as_c_string(std::string const &str) noexcept
{
  return str.c_str();
}
 
 
// LCOV_EXCL_START
 
template<typename CHAR> inline constexpr bool is_digit(CHAR c) noexcept
{
  return (c >= '0') and (c <= '9');
}
 
 
#if !defined(NDEBUG)
static_assert(is_digit('0'));
static_assert(is_digit('1'));
static_assert(is_digit('9'));
static_assert(not is_digit('a'));
static_assert(not is_digit('f'));
static_assert(not is_digit('z'));
static_assert(not is_digit(' '));
#endif
// LCOV_EXCL_STOP
 
 
 
[[nodiscard]] std::string
describe_object(std::string_view class_name, std::string_view name);
 
 
 
void check_unique_register(
  void const *old_guest, std::string_view old_class, std::string_view old_name,
  void const *new_guest, std::string_view new_class,
  std::string_view new_name);
 
 
 
void check_unique_unregister(
  void const *old_guest, std::string_view old_class, std::string_view old_name,
  void const *new_guest, std::string_view new_class,
  std::string_view new_name);
 
 
 
PQXX_PURE inline constexpr std::size_t
size_esc_bin(std::size_t binary_bytes) noexcept
{
  assert(std::cmp_less(
    binary_bytes, (std::numeric_limits<std::size_t>::max)() / 2u));
  return 2 + (2 * binary_bytes) + 1;
}
 
 
 
PQXX_PURE inline constexpr std::size_t
size_unesc_bin(std::size_t escaped_bytes) noexcept
{
  if (escaped_bytes < 2u) [[unlikely]]
    return 0;
  else
    return (escaped_bytes - 2) / 2;
}
 
 
 
PQXX_LIBEXPORT void
esc_bin(bytes_view binary_data, std::span<char> buffer) noexcept;
 
 
 
template<binary T>
inline void esc_bin(T &&binary_data, std::span<char> buffer) noexcept
{
  esc_bin(binary_cast(binary_data), buffer);
}
 
 
PQXX_LIBEXPORT std::string esc_bin(bytes_view binary_data);
 
 
PQXX_LIBEXPORT void
unesc_bin(std::string_view escaped_data, std::span<std::byte> buffer, sl loc);
 
 
PQXX_LIBEXPORT bytes unesc_bin(std::string_view escaped_data, sl loc);
 
 
 
template<typename RETURN, typename... ARGS>
std::tuple<ARGS...> args_f(RETURN (&func)(ARGS...));
 
 
 
template<typename RETURN, typename... ARGS>
std::tuple<ARGS...> args_f(std::function<RETURN(ARGS...)> const &);
 
 
 
template<typename CLASS, typename RETURN, typename... ARGS>
std::tuple<ARGS...> member_args_f(RETURN (CLASS::*)(ARGS...));
 
 
 
template<typename CLASS, typename RETURN, typename... ARGS>
std::tuple<ARGS...> member_args_f(RETURN (CLASS::*)(ARGS...) const);
 
 
 
template<typename CALLABLE>
auto args_f(CALLABLE const &f)
  -> decltype(member_args_f(&CALLABLE::operator()));
 
 
template<typename CALLABLE>
using args_t = decltype(args_f(std::declval<CALLABLE>()));
 
 
 
template<typename... TYPES>
std::tuple<std::remove_cvref_t<TYPES>...>
strip_types(std::tuple<TYPES...> const &);
 
 
template<typename... TYPES>
using strip_types_t = decltype(strip_types(std::declval<TYPES...>()));
 
 
// LCOV_EXCL_START
PQXX_PURE inline constexpr char unescape_char(char escaped) noexcept
{
  switch (escaped)
  {
  case 'b': // Backspace.
    [[unlikely]] return '\b';
  case 'f': // Form feed
    [[unlikely]] return '\f';
  case 'n': // Line feed.
    return '\n';
  case 'r': // Carriage return.
    return '\r';
  case 't': // Horizontal tab.
    return '\t';
  case 'v': // Vertical tab.
    return '\v';
  default: break;
  }
  // Regular character ("self-escaped").
  return escaped;
}
 
 
#if !defined(NDEBUG)
static_assert(unescape_char('a') == 'a');
static_assert(unescape_char('b') == '\b');
static_assert(unescape_char('f') == '\f');
static_assert(unescape_char('n') == '\n');
static_assert(unescape_char('r') == '\r');
static_assert(unescape_char('t') == '\t');
static_assert(unescape_char('v') == '\v');
static_assert(unescape_char('z') == 'z');
#endif
// LCOV_EXCL_STOP
 
 
 
[[maybe_unused]] PQXX_COLD inline char const *
make_strerror_rs_result(int err_result, std::span<char> buffer)
{
  if (err_result == 0)
    return std::data(buffer);
  else
    return "Unknown error; could not retrieve error string.";
}
 
 
 
[[maybe_unused]] PQXX_COLD PQXX_ZARGS inline char const *
make_strerror_rs_result(char const *err_result, std::span<char>)
{
  return err_result;
}
 
 
[[nodiscard]] PQXX_COLD inline char const *error_string(
  [[maybe_unused]] int err_num, [[maybe_unused]] std::span<char> buffer)
{
  // Not entirely clear whether strerror_s will be in std or global namespace.
  // NOLINTNEXTLINE(google-build-using-namespace)
  using namespace std;
 
#if defined(PQXX_HAVE_STERROR_S) || defined(PQXX_HAVE_STRERROR_R)
#  if defined(PQXX_HAVE_STRERROR_S)
  auto const err_result{
    strerror_s(std::data(buffer), std::size(buffer), err_num)};
#  else
  auto const err_result{
    strerror_r(err_num, std::data(buffer), std::size(buffer))};
#  endif
  return make_strerror_rs_result(err_result, buffer);
#else
  // Fallback case, hopefully for no actual platforms out there.
  return "(No error information available.)";
#endif
}
 
 
 
template<bool terminate>
inline std::size_t copy_chars(
  std::string_view src, std::span<char> dst, std::size_t dst_offset, sl loc)
{
  auto const sz{std::size(src)};
  if (std::cmp_greater(
        dst_offset + sz + std::size_t(terminate), std::size(dst)))
    throw conversion_overrun{
      std::format(
        "Text copy exceeded buffer space: tried to copy {} bytes '{}' into a "
        "buffer of {} bytes, at offset {}.",
        sz, src, std::size(dst), dst_offset),
      loc};
  auto at{dst_offset + src.copy(std::data(dst) + dst_offset, sz)};
  if constexpr (terminate)
    dst[at++] = '\0';
  return at;
}
} // namespace pqxx::internal
 
 
namespace pqxx::internal::pq
{
PQXX_LIBEXPORT void pqfreemem(void const *) noexcept;
} // namespace pqxx::internal::pq
#endif