field.hxx

Go to the documentation of this file.

/* Definitions for the pqxx::field class.
 *
 * pqxx::field refers to a field in a query result.
 *
 * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/field instead.
 *
 * 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_FIELD
#define PQXX_H_FIELD

#if !defined(PQXX_HEADER_PRE)
#  error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
#endif

#include <optional>

#include "pqxx/array.hxx"
#include "pqxx/composite.hxx"
#include "pqxx/result.hxx"
#include "pqxx/strconv.hxx"
#include "pqxx/types.hxx"

namespace pqxx
{

class PQXX_LIBEXPORT field
{
public:
  using size_type = field_size_type;


  [[nodiscard]] PQXX_PURE bool operator==(field const &) const noexcept;


  [[nodiscard]] PQXX_PURE bool operator!=(field const &rhs) const noexcept
  {
    return not operator==(rhs);
  }

  [[nodiscard]] PQXX_PURE char const *name() const &;

  [[nodiscard]] oid PQXX_PURE type() const;

  [[nodiscard]] PQXX_PURE oid table() const;

  PQXX_PURE constexpr row_size_type num() const noexcept { return col(); }

  [[nodiscard]] PQXX_PURE row_size_type table_column() const;


  [[nodiscard]] PQXX_PURE std::string_view view() const &
  {
    return std::string_view(c_str(), size());
  }


  [[nodiscard]] PQXX_PURE char const *c_str() const &;

  [[nodiscard]] PQXX_PURE bool is_null() const noexcept;

  [[nodiscard]] PQXX_PURE size_type size() const noexcept;


  template<typename T>
  auto to(T &obj) const ->
    typename std::enable_if_t<
      (not std::is_pointer<T>::value or std::is_same<T, char const *>::value),
      bool>
  {
    if (is_null())
    {
      return false;
    }
    else
    {
      auto const data{c_str()};
      from_string(data, obj);
      return true;
    }
  }


  template<typename... T> bool composite_to(T &...fields) const
  {
    if (is_null())
    {
      return false;
    }
    else
    {
      parse_composite(m_home.m_encoding, view(), fields...);
      return true;
    }
  }

  template<typename T> bool operator>>(T &obj) const { return to(obj); }


  template<typename T>
  auto to(T &obj, T const &default_value) const ->
    typename std::enable_if_t<
      (not std::is_pointer<T>::value or std::is_same<T, char const *>::value),
      bool>
  {
    bool const null{is_null()};
    if (null)
      obj = default_value;
    else
      obj = from_string<T>(this->view());
    return not null;
  }


  template<typename T> T as(T const &default_value) const
  {
    if (is_null())
      return default_value;
    else
      return from_string<T>(this->view());
  }


  template<typename T> T as() const
  {
    if (is_null())
    {
      if constexpr (not nullness<T>::has_null)
        internal::throw_null_conversion(name_type<T>());
      else
        return nullness<T>::null();
    }
    else
    {
      return from_string<T>(this->view());
    }
  }


  template<typename T, template<typename> class O = std::optional>
  constexpr O<T> get() const
  {
    return as<O<T>>();
  }

  template<typename ELEMENT, auto... ARGS>
  array<ELEMENT, ARGS...> as_sql_array() const
  {
    using array_type = array<ELEMENT, ARGS...>;

    // There's no such thing as a null SQL array.
    if (is_null())
      internal::throw_null_conversion(name_type<array_type>());
    else
      return array_type{this->view(), this->m_home.m_encoding};
  }


  [[deprecated(
    "Avoid pqxx::array_parser.  "
    "Instead, use as_sql_array() to convert to pqxx::array.")]]
  array_parser as_array() const & noexcept
  {
    return array_parser{c_str(), m_home.m_encoding};
  }


  [[deprecated(
    "Do not construct fields yourself.  Get them from the row.")]] field(row const &r, row_size_type c) noexcept;

  [[deprecated(
    "Do not construct fields yourself.  Get them from the "
    "row.")]] field() noexcept = default;


protected:
  constexpr result const &home() const noexcept { return m_home; }
  constexpr result::size_type idx() const noexcept { return m_row; }
  constexpr row_size_type col() const noexcept { return m_col; }

  // TODO: Create gates.
  friend class pqxx::result;
  friend class pqxx::row;
  field(
    result const &r, result_size_type row_num, row_size_type col_num) noexcept
          :
          m_col{col_num}, m_home{r}, m_row{row_num}
  {}

  row_size_type m_col;

private:
  result m_home;
  result::size_type m_row;
};


template<> inline bool field::to<std::string>(std::string &obj) const
{
  bool const null{is_null()};
  if (not null)
    obj = std::string{view()};
  return not null;
}


template<>
inline bool field::to<std::string>(
  std::string &obj, std::string const &default_value) const
{
  bool const null{is_null()};
  if (null)
    obj = default_value;
  else
    obj = std::string{view()};
  return not null;
}



template<> inline bool field::to<char const *>(char const *&obj) const
{
  bool const null{is_null()};
  if (not null)
    obj = c_str();
  return not null;
}


template<> inline bool field::to<std::string_view>(std::string_view &obj) const
{
  bool const null{is_null()};
  if (not null)
    obj = view();
  return not null;
}


template<>
inline bool field::to<std::string_view>(
  std::string_view &obj, std::string_view const &default_value) const
{
  bool const null{is_null()};
  if (null)
    obj = default_value;
  else
    obj = view();
  return not null;
}


template<> inline std::string_view field::as<std::string_view>() const
{
  if (is_null())
    PQXX_UNLIKELY
  internal::throw_null_conversion(name_type<std::string_view>());
  return view();
}


template<>
inline std::string_view
field::as<std::string_view>(std::string_view const &default_value) const
{
  return is_null() ? default_value : view();
}


template<> inline bool field::to<zview>(zview &obj) const
{
  bool const null{is_null()};
  if (not null)
    obj = zview{c_str(), size()};
  return not null;
}


template<>
inline bool field::to<zview>(zview &obj, zview const &default_value) const
{
  bool const null{is_null()};
  if (null)
    obj = default_value;
  else
    obj = zview{c_str(), size()};
  return not null;
}


template<> inline zview field::as<zview>() const
{
  if (is_null())
    PQXX_UNLIKELY
  internal::throw_null_conversion(name_type<zview>());
  return zview{c_str(), size()};
}


template<> inline zview field::as<zview>(zview const &default_value) const
{
  return is_null() ? default_value : zview{c_str(), size()};
}


template<typename CHAR = char, typename TRAITS = std::char_traits<CHAR>>
class field_streambuf : public std::basic_streambuf<CHAR, TRAITS>
{
public:
  using char_type = CHAR;
  using traits_type = TRAITS;
  using int_type = typename traits_type::int_type;
  using pos_type = typename traits_type::pos_type;
  using off_type = typename traits_type::off_type;
  using openmode = std::ios::openmode;
  using seekdir = std::ios::seekdir;

  explicit field_streambuf(field const &f) : m_field{f} { initialize(); }

protected:
  virtual int sync() override { return traits_type::eof(); }

  virtual pos_type seekoff(off_type, seekdir, openmode) override
  {
    return traits_type::eof();
  }
  virtual pos_type seekpos(pos_type, openmode) override
  {
    return traits_type::eof();
  }
  virtual int_type overflow(int_type) override { return traits_type::eof(); }
  virtual int_type underflow() override { return traits_type::eof(); }

private:
  field const &m_field;

  int_type initialize()
  {
    auto g{static_cast<char_type *>(const_cast<char *>(m_field.c_str()))};
    this->setg(g, g, g + std::size(m_field));
    return int_type(std::size(m_field));
  }
};



template<typename CHAR = char, typename TRAITS = std::char_traits<CHAR>>
class basic_fieldstream : public std::basic_istream<CHAR, TRAITS>
{
  using super = std::basic_istream<CHAR, TRAITS>;

public:
  using char_type = CHAR;
  using traits_type = TRAITS;
  using int_type = typename traits_type::int_type;
  using pos_type = typename traits_type::pos_type;
  using off_type = typename traits_type::off_type;

  [[deprecated("Use field::as<...>() or field::c_str().")]] basic_fieldstream(
    field const &f) :
          super{nullptr}, m_buf{f}
  {
    super::init(&m_buf);
  }

private:
  field_streambuf<CHAR, TRAITS> m_buf;
};


using fieldstream = basic_fieldstream<char>;



template<typename CHAR>
[[deprecated(
  "Do this by hand, probably with better error checking.")]] inline std::
  basic_ostream<CHAR> &
  operator<<(std::basic_ostream<CHAR> &s, field const &value)
{
  s.write(value.c_str(), std::streamsize(std::size(value)));
  return s;
}



template<typename T> inline T from_string(field const &value)
{
  if (value.is_null())
  {
    if constexpr (nullness<T>::has_null)
      return nullness<T>::null();
    else
      internal::throw_null_conversion(name_type<T>());
  }
  else
  {
    return from_string<T>(value.view());
  }
}



template<>
inline std::nullptr_t from_string<std::nullptr_t>(field const &value)
{
  if (not value.is_null())
    throw conversion_error{
      "Extracting non-null field into nullptr_t variable."};
  return nullptr;
}


template<> PQXX_LIBEXPORT std::string to_string(field const &value);
} // namespace pqxx
#endif