stream_to.hxx

Go to the documentation of this file.

/* Definition of the pqxx::stream_to class.
 *
 * pqxx::stream_to enables optimized batch updates to a database table.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/stream_to.hxx 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_STREAM_TO_HXX
#define PQXX_STREAM_TO_HXX
 
#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif
 
#include "pqxx/separated_list.hxx"
#include "pqxx/transaction_base.hxx"
 
 
namespace pqxx
{
 
class PQXX_LIBEXPORT stream_to final : transaction_focus
{
public:
 
  static stream_to table(
    transaction_base &tx, table_path path,
    std::initializer_list<std::string_view> columns = {})
  {
    auto const &cx{tx.conn()};
    return raw_table(tx, cx.quote_table(path), cx.quote_columns(columns));
  }
 
 
  template<pqxx::char_strings COLUMNS>
  static stream_to
  table(transaction_base &tx, table_path path, COLUMNS const &columns)
  {
    auto const &cx{tx.conn()};
    return stream_to::raw_table(
      tx, cx.quote_table(path), tx.conn().quote_columns(columns));
  }
 
 
  template<pqxx::char_strings COLUMNS>
  static stream_to
  table(transaction_base &tx, std::string_view path, COLUMNS const &columns)
  {
    return stream_to::raw_table(tx, path, tx.conn().quote_columns(columns));
  }
 
 
  static stream_to raw_table(
    transaction_base &tx, std::string_view path, std::string_view columns = "",
    sl loc = sl::current())
  {
    return {tx, path, columns, loc};
  }
 
  stream_to(stream_to const &) = delete;
 
  // Some false positives from clang-tidy checks in this constructor.  The
  // initial base-class move moves only the embedded base-class object, not the
  // individual member variables that fall outside the base class.
  // Also there's one deliberate invalidation step of the moved-from object,
  // which is also being flagged as a potential use-after-move.
 
  // NOLINTBEGIN(bugprone-use-after-move,hicpp-invalid-access-moved)
  stream_to(stream_to &&other) :
          // (This first step only moves the transaction_focus base-class
          // object.)
          transaction_focus{std::move(other)},
          m_buffer{std::move(other.m_buffer)},
          m_field_buf{std::move(other.m_field_buf)},
          m_finder{other.m_finder},
          m_created_loc{other.m_created_loc},
          m_finished{other.m_finished}
  {
    other.m_finished = true;
  }
  // NOLINTEND(bugprone-use-after-move,hicpp-invalid-access-moved)
 
  ~stream_to() noexcept;
 
  stream_to &operator=(stream_to const &) = delete;
  stream_to &operator=(stream_to &&) = delete;
 
  // NOLINTBEGIN(google-explicit-constructor,hicpp-explicit-conversions)
  [[nodiscard]] constexpr operator bool() const noexcept
  {
    return not m_finished;
  }
  // NOLINTEND(google-explicit-constructor,hicpp-explicit-conversions)
 
  [[nodiscard]] constexpr bool operator!() const noexcept
  {
    return m_finished;
  }
 
 
  void complete(sl loc = sl::current());
 
 
  template<typename Row> stream_to &operator<<(Row const &row)
  {
    write_row(row, m_created_loc);
    return *this;
  }
 
 
  stream_to &operator<<(stream_from &);
 
 
  template<typename Row> void write_row(Row const &row, sl loc = sl::current())
  {
    fill_buffer(
      row, conversion_context{trans().conn().get_encoding_group(loc), loc});
    write_buffer(loc);
  }
 
 
  template<typename... Ts> void write_values(Ts const &...fields)
  {
    fill_buffer(fields...);
    write_buffer(m_created_loc);
  }
 
private:
  stream_to(
    transaction_base &tx, std::string_view path, std::string_view columns, sl);
 
  std::string m_buffer;
 
  std::string m_field_buf;
 
  internal::char_finder_func *m_finder;
 
  sl m_created_loc;
 
  bool m_finished = false;
 
  void write_raw_line(std::string_view, sl);
 
 
  void write_buffer(sl);
 
  static constexpr std::string_view null_field{"\\N\t"};
 
  template<typename T>
  static constexpr std::size_t estimate_buffer(T const &)
    requires(pqxx::always_null<T>())
  {
    return std::size(null_field);
  }
 
 
  template<typename T>
  static constexpr std::size_t estimate_buffer(T const &field)
    requires(not pqxx::always_null<T>())
  {
    return is_null(field) ? std::size(null_field) : size_buffer(field);
  }
 
  void escape_field_to_buffer(std::string_view data, sl loc);
 
 
  template<typename Field>
  void append_to_buffer(Field const &f, ctx c)
    requires(not pqxx::always_null<Field>())
  {
    // We append each field, terminated by a tab.  That will leave us with
    // one tab too many, assuming we write any fields at all; we remove that
    // at the end.
    if (is_null(f))
    {
      // Easy.  Append null and tab in one go.
      m_buffer.append(null_field);
    }
    else
    {
      // Convert f into m_buffer.
      auto const budget{estimate_buffer(f)};
 
      // We're not using is_unquoted_safe for this, because in this context,
      // a tab counts as a special character that needs escaping.
      if constexpr (std::is_arithmetic_v<Field>)
      {
        // Specially optimised for "safe" types, which never need any
        // escaping.  Convert straight into m_buffer.
 
        auto const offset{std::size(m_buffer)};
        // Also include room to append the tab.
        auto const total{offset + budget + 1};
        m_buffer.resize(total);
        auto const data{m_buffer.data()};
        std::size_t const end{
          offset + into_buf({data + offset, data + total}, f, c)};
        assert((end + 1) < std::size(m_buffer));
        m_buffer[end] = '\t';
        // Shrink to fit.  Keep the tab though.
        m_buffer.resize(end + 1);
      }
      else if constexpr (
        std::is_same_v<Field, std::string> or
        std::is_same_v<Field, std::string_view> or
        std::is_same_v<Field, zview>)
      {
        // This string may need escaping.
        m_field_buf.resize(budget);
        escape_field_to_buffer(f, c.loc);
      }
      else if constexpr (
        std::is_same_v<Field, std::optional<std::string>> or
        std::is_same_v<Field, std::optional<std::string_view>> or
        std::is_same_v<Field, std::optional<zview>>)
      {
        // Optional string.  It's not null (we checked for that above), so...
        // Treat like a string.
        m_field_buf.resize(budget);
        // No need to check whether f has a value; if it didn't, the is_null(f)
        // check at the top would have evaluated as true.
        // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
        escape_field_to_buffer(f.value(), c.loc);
      }
      // TODO: Support deleter template argument on unique_ptr.
      else if constexpr (
        std::is_same_v<Field, std::unique_ptr<std::string>> or
        std::is_same_v<Field, std::unique_ptr<std::string_view>> or
        std::is_same_v<Field, std::unique_ptr<zview>> or
        std::is_same_v<Field, std::shared_ptr<std::string>> or
        std::is_same_v<Field, std::shared_ptr<std::string_view>> or
        std::is_same_v<Field, std::shared_ptr<zview>>)
      {
        // TODO: Generalise this.
        // Effectively also an optional string.  It's not null (we checked
        // for that above).
        m_field_buf.resize(budget);
        escape_field_to_buffer(*f, c.loc);
      }
      else
      {
        // This field needs to be converted to a string, and after that,
        // escaped as well.
        m_field_buf.resize(budget);
        escape_field_to_buffer(to_buf(m_field_buf, f, c), c.loc);
      }
    }
  }
 
 
  template<typename Field>
  void append_to_buffer(Field const &, ctx)
    requires(pqxx::always_null<Field>())
  {
    m_buffer.append(null_field);
  }
 
  template<typename Container>
  void fill_buffer(Container const &cont, ctx c)
    requires(not std::is_same_v<
             std::remove_cv_t<typename Container::value_type>, char>)
  {
    // To avoid unnecessary allocations and deallocations, we run through c
    // twice: once to determine how much buffer space we may need, and once to
    // actually write it into the buffer.
    std::size_t budget{0};
    for (auto const &f : cont) budget += estimate_buffer(f);
    m_buffer.reserve(budget);
    for (auto const &f : cont) append_to_buffer(f, c);
  }
 
  template<typename Tuple, std::size_t... indexes>
  static std::size_t
  budget_tuple(Tuple const &t, std::index_sequence<indexes...>)
  {
    return (estimate_buffer(std::get<indexes>(t)) + ...);
  }
 
  template<typename Tuple, std::size_t... indexes>
  void append_tuple(Tuple const &t, std::index_sequence<indexes...>, ctx c)
  {
    (append_to_buffer(std::get<indexes>(t), c), ...);
  }
 
  template<typename... Elts>
  void fill_buffer(std::tuple<Elts...> const &t, ctx c)
  {
    using indexes = std::make_index_sequence<sizeof...(Elts)>;
 
    m_buffer.reserve(budget_tuple(t, indexes{}));
    append_tuple(t, indexes{}, c);
  }
 
  template<typename... Ts> void fill_buffer(const Ts &...fields)
  {
    conversion_context const c{
      trans().conn().get_encoding_group(m_created_loc), m_created_loc};
    (..., append_to_buffer(fields, c));
  }
 
  static constexpr std::string_view s_classname{"stream_to"};
};
} // namespace pqxx
#endif