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-2025, 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_H_PARAMS
#define PQXX_H_PARAMS
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include <array>
#include <variant>
 
#include "pqxx/internal/concat.hxx"
#include "pqxx/internal/statement_parameters.hxx"
#include "pqxx/types.hxx"
 
 
namespace pqxx
{

class PQXX_LIBEXPORT params
{
public:
  params() = default;

  template<typename... Args> constexpr params(Args &&...args)
  {
    reserve(sizeof...(args));
    append_pack(std::forward<Args>(args)...);
  }


  void reserve(std::size_t n) &;
 
  // C++20: constexpr.
  [[nodiscard]] auto size() const noexcept { return m_params.size(); }
 
  // C++20: Use the vector's ssize() directly and go noexcept+constexpr.

  [[nodiscard]] auto ssize() const { return pqxx::internal::ssize(m_params); }

  void append() &;


  void append(zview) &;


  void append(std::string const &) &;

  void append(std::string &&) &;


  void append(bytes_view) &;


  void append(bytes const &) &;
 
#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_RANGES)

  template<binary DATA> void append(DATA const &data) &
  {
    append(bytes_view{std::data(data), std::size(data)});
  }
#endif // PQXX_HAVE_CONCEPTS

  void append(bytes &&) &;


  void append(binarystring const &value) &;

  template<typename IT, typename ACCESSOR>
  void append(pqxx::internal::dynamic_params<IT, ACCESSOR> const &value) &
  {
    for (auto &param : value) append(value.access(param));
  }
 
  void append(params const &value) &;
 
  void append(params &&value) &;

  template<typename TYPE> void append(TYPE const &value) &
  {
    // TODO: Pool storage for multiple string conversions in one buffer?
    if constexpr (nullness<strip_t<TYPE>>::always_null)
    {
      ignore_unused(value);
      m_params.emplace_back();
    }
    else if (is_null(value))
    {
      m_params.emplace_back();
    }
    else
    {
      m_params.emplace_back(entry{to_string(value)});
    }
  }

  template<PQXX_RANGE_ARG RANGE> void append_multi(RANGE const &range) &
  {
#if defined(PQXX_HAVE_CONCEPTS) && defined(PQXX_HAVE_RANGES)
    if constexpr (std::ranges::sized_range<RANGE>)
      reserve(std::size(*this) + std::size(range));
#endif
    for (auto &value : range) append(value);
  }


  pqxx::internal::c_params make_c_params() const;
 
private:
  template<typename Arg, typename... More>
  void append_pack(Arg &&arg, More &&...args)
  {
    this->append(std::forward<Arg>(arg));
    // Recurse for remaining args.
    append_pack(std::forward<More>(args)...);
  }

  constexpr void append_pack() 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;
 
  static constexpr std::string_view s_overflow{
    "Statement parameter length overflow."sv};
};
 


template<typename COUNTER = unsigned int> class placeholders
{
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));
  }


  constexpr zview view() const & noexcept
  {
    return zview{std::data(m_buf), m_len};
  }


  std::string get() const { return std::string(std::data(m_buf), m_len); }

  void next() &
  {
    if (m_current >= max_params)
      throw range_error{pqxx::internal::concat(
        "Too many parameters in one statement: limit is ", max_params, ".")};
    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)};
      char *const end{string_traits<COUNTER>::into_buf(
        data + 1, data + std::size(m_buf), m_current)};
      // (Subtract because we don't include the trailing zero.)
      m_len = check_cast<COUNTER>(end - data, "placeholders counter") - 1;
    }
    else
    {
      PQXX_LIKELY
      // Shortcut for the common case: just increment that last digit.
      ++m_buf[m_len - 1];
    }
  }

  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
 

namespace pqxx::prepare
{
template<typename IT>
[[deprecated("Use the params class instead.")]] constexpr inline auto
make_dynamic_params(IT begin, IT end)
{
  return pqxx::internal::dynamic_params(begin, end);
}
 

template<typename C>
[[deprecated("Use the params class instead.")]] constexpr inline auto
make_dynamic_params(C const &container)
{
  using IT = typename C::const_iterator;
#include "pqxx/internal/ignore-deprecated-pre.hxx"
  return pqxx::internal::dynamic_params<IT>{container};
#include "pqxx/internal/ignore-deprecated-post.hxx"
}
 

template<typename C, typename ACCESSOR>
[[deprecated("Use the params class instead.")]] constexpr inline auto
make_dynamic_params(C &container, ACCESSOR accessor)
{
  using IT = decltype(std::begin(container));
#include "pqxx/internal/ignore-deprecated-pre.hxx"
  return pqxx::internal::dynamic_params<IT, ACCESSOR>{container, accessor};
#include "pqxx/internal/ignore-deprecated-post.hxx"
}
} // namespace pqxx::prepare
#endif