params.hxx

Go to the documentation of this file.

/* Helpers for prepared statements and parameterised statements.
 *
 * See @ref connection and @ref transaction_base for more.
 *
 * 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_PARAMS_HXX
#define PQXX_PARAMS_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <array>
#include <format>
 
#include "pqxx/internal/statement_parameters.hxx"
#include "pqxx/types.hxx"
 
 
namespace pqxx::internal
{
PQXX_PURE [[nodiscard]] inline constexpr pqxx::encoding_group
get_encoding_group(encoding_group const &enc, sl = sl::current()) noexcept
{
  return enc;
}
 
 
 
PQXX_PURE [[nodiscard]] inline constexpr pqxx::encoding_group
get_encoding_group(ctx c, sl = sl::current()) noexcept
{
  return c.enc;
}
 
 
[[nodiscard]] PQXX_LIBEXPORT pqxx::encoding_group
get_encoding_group(connection const &, sl = sl::current());
 
 
[[nodiscard]] PQXX_LIBEXPORT pqxx::encoding_group
get_encoding_group(transaction_base const &, sl = sl::current());
} // namespace pqxx::internal
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT params final
{
public:
  params() = default;
 
  // NOLINTBEGIN(google-explicit-constructor,hicpp-explicit-conversions)
 
 
  template<typename First, typename... Args>
  params(First &&first, Args &&...args)
  {
    sl loc;
    if constexpr (std::is_same_v<std::remove_cvref<First>, conversion_context>)
      loc = first.loc;
    else
      loc = sl::current();
 
    if constexpr (requires(encoding_group eg) {
                    eg = pqxx::internal::get_encoding_group(first);
                  })
    {
      // First argument is a source of an encoding group, not a parameter.
      m_enc = pqxx::internal::get_encoding_group(first);
      append_pack(loc, std::forward<Args>(args)...);
    }
    else
    {
      // The first argument is just a regular parameter.  Append it first.
      append_pack(
        loc, std::forward<First>(first), std::forward<Args>(args)...);
    }
  }
 
  // NOLINTEND(google-explicit-constructor,hicpp-explicit-conversions)
 
 
  void reserve(std::size_t n) &;
 
  [[nodiscard]] constexpr auto size() const noexcept
  {
    return m_params.size();
  }
 
 
  [[nodiscard]] constexpr auto ssize() const { return std::ssize(m_params); }
 
  void append(sl = sl::current()) &;
 
 
  void append(zview, sl = sl::current()) &;
 
 
  void append(std::string const &, sl = sl::current()) &;
 
  void append(std::string &&, sl = sl::current()) &;
 
 
  void append(bytes_view, sl = sl::current()) &;
 
 
  template<binary DATA> void append(DATA const &data, sl loc = sl::current()) &
  {
    append(binary_cast(data), loc);
  }
 
  void append(bytes &&, sl = sl::current()) &;
 
  void append(params const &value, sl = sl::current()) &;
 
  void append(params &&value, sl = sl::current()) &;
 
  template<typename TYPE>
  void append([[maybe_unused]] TYPE const &value, sl loc = sl::current()) &
  {
    // TODO: Pool storage for multiple string conversions in one buffer?
    if constexpr (pqxx::always_null<TYPE>())
    {
      m_params.emplace_back();
    }
    else if (is_null(value))
    {
      m_params.emplace_back();
    }
    else
    {
      // TODO: Block-allocate storage for parameters.
      m_params.emplace_back(
        entry{to_string(value, conversion_context{m_enc, loc})});
    }
  }
 
  template<std::ranges::range RANGE>
  void append_multi(RANGE const &range, sl loc = sl::current()) &
  {
    if constexpr (std::ranges::sized_range<RANGE>)
      reserve(std::size(*this) + std::size(range));
    for (auto &value : range) append(value, loc);
  }
 
 
  [[nodiscard]] pqxx::internal::c_params make_c_params(sl loc) const;
 
private:
  template<typename... Args> void append_pack(sl loc, Args &&...args)
  {
    reserve(size() + sizeof...(args));
    ((this->append(std::forward<Args>(args), loc)), ...);
  }
 
 
  void append_pack(sl) const noexcept {}
 
  // The way we store a parameter depends on whether it's binary or text
  // (most types are text), and whether we're responsible for storing the
  // contents.
  using entry =
    std::variant<std::nullptr_t, zview, std::string, bytes_view, bytes>;
  std::vector<entry> m_params;
 
  encoding_group m_enc{encoding_group::unknown};
 
  static constexpr std::string_view s_overflow{
    "Statement parameter length overflow."sv};
};
 
 
 
template<typename COUNTER = unsigned int> class placeholders final
{
public:
  static inline constexpr unsigned int max_params{
    (std::numeric_limits<COUNTER>::max)()};
 
  placeholders()
  {
    static constexpr auto initial{"$1\0"sv};
    initial.copy(std::data(m_buf), std::size(initial));
  }
 
 
  [[nodiscard]] constexpr zview view() const & noexcept
  {
    return zview{std::data(m_buf), m_len};
  }
 
 
  [[nodiscard]] std::string get() const
  {
    return std::string(std::data(m_buf), m_len);
  }
 
  void next(sl loc = sl::current()) &
  {
    conversion_context const c{{}, loc};
    if (m_current >= max_params)
      throw range_error{
        std::format(
          "Too many parameters in one statement: limit is {}.", max_params),
        loc};
    PQXX_ASSUME(m_current > 0);
    ++m_current;
    if (m_current % 10 == 0)
    {
      // Carry the 1.  Don't get too clever for this relatively rare
      // case, just rewrite the entire number.  Leave the $ in place
      // though.
      char *const data{std::data(m_buf)};
 
      auto const written{pqxx::into_buf<COUNTER>(
        {data + 1, data + std::size(m_buf) - 1}, m_current, c)};
      std::size_t const end{1 + written};
      assert(end < std::size(m_buf));
      data[end] = '\0';
      m_len = check_cast<COUNTER>(end, "placeholders counter", loc);
    }
    else [[likely]]
    {
      // Shortcut for the common case: just increment that last digit.
      ++m_buf.at(m_len - 1);
    }
  }
 
  [[nodiscard]] COUNTER count() const noexcept { return m_current; }
 
private:
  COUNTER m_current = 1;
 
  COUNTER m_len = 2;
 
 
  std::array<char, std::numeric_limits<COUNTER>::digits10 + 3> m_buf;
};
} // namespace pqxx
#endif