libpqxx  7.1.2
result.hxx
1 /* Definitions for the pqxx::result class and support classes.
2  *
3  * pqxx::result represents the set of result rows from a database query.
4  *
5  * DO NOT INCLUDE THIS FILE DIRECTLY; include pqxx/result instead.
6  *
7  * Copyright (c) 2000-2020, Jeroen T. Vermeulen.
8  *
9  * See COPYING for copyright license. If you did not receive a file called
10  * COPYING with this source code, please notify the distributor of this
11  * mistake, or contact the author.
12  */
13 #ifndef PQXX_H_RESULT
14 #define PQXX_H_RESULT
15 
16 #include "pqxx/compiler-public.hxx"
17 #include "pqxx/internal/compiler-internal-pre.hxx"
18 
19 #include <ios>
20 #include <memory>
21 #include <stdexcept>
22 
23 #include "pqxx/except.hxx"
24 #include "pqxx/types.hxx"
25 #include "pqxx/util.hxx"
26 #include "pqxx/zview.hxx"
27 
28 #include "pqxx/internal/encodings.hxx"
29 
30 
31 namespace pqxx::internal
32 {
33 PQXX_LIBEXPORT void clear_result(pq::PGresult const *);
34 }
35 
36 
37 namespace pqxx::internal::gate
38 {
39 class result_connection;
40 class result_creation;
41 class result_pipeline;
42 class result_row;
43 class result_sql_cursor;
44 } // namespace pqxx::internal::gate
45 
46 
47 namespace pqxx
48 {
50 
70 class PQXX_LIBEXPORT result
71 {
72 public:
75  using reference = row;
81 
82  result() noexcept :
83  m_data(make_data_pointer()),
84  m_query(),
85  m_encoding(internal::encoding_group::MONOBYTE)
86  {}
87  result(result const &rhs) noexcept = default;
88 
89  result &operator=(result const &rhs) noexcept = default;
90 
95  [[nodiscard]] bool operator==(result const &) const noexcept;
96  [[nodiscard]] bool operator!=(result const &rhs) const noexcept
97  {
98  return not operator==(rhs);
99  }
101 
103 
109  template<typename... TYPE> auto iter() const;
110 
111  [[nodiscard]] const_reverse_iterator rbegin() const;
112  [[nodiscard]] const_reverse_iterator crbegin() const;
113  [[nodiscard]] const_reverse_iterator rend() const;
114  [[nodiscard]] const_reverse_iterator crend() const;
115 
116  [[nodiscard]] const_iterator begin() const noexcept;
117  [[nodiscard]] const_iterator cbegin() const noexcept;
118  [[nodiscard]] inline const_iterator end() const noexcept;
119  [[nodiscard]] inline const_iterator cend() const noexcept;
120 
121  [[nodiscard]] reference front() const noexcept;
122  [[nodiscard]] reference back() const noexcept;
123 
124  [[nodiscard]] PQXX_PURE size_type size() const noexcept;
125  [[nodiscard]] PQXX_PURE bool empty() const noexcept;
126  [[nodiscard]] size_type capacity() const noexcept { return size(); }
127 
128  void swap(result &) noexcept;
129 
130  [[nodiscard]] row operator[](size_type i) const noexcept;
131  row at(size_type) const;
132 
133  void clear() noexcept
134  {
135  m_data.reset();
136  m_query = nullptr;
137  }
138 
143  [[nodiscard]] PQXX_PURE row_size_type columns() const noexcept;
145 
147  row_size_type column_number(char const col_name[]) const;
148 
150  row_size_type column_number(std::string const &name) const
151  {
152  return column_number(name.c_str());
153  }
154 
157  {
158  return column_number(name.c_str());
159  }
160 
162  [[nodiscard]] char const *column_name(row_size_type number) const;
163 
165  [[nodiscard]] oid column_type(row_size_type col_num) const;
166 
168  template<typename STRING>[[nodiscard]] oid column_type(STRING col_name) const
169  {
170  return column_type(column_number(col_name));
171  }
172 
174  [[nodiscard]] oid column_table(row_size_type col_num) const;
175 
177  template<typename STRING>
178  [[nodiscard]] oid column_table(STRING col_name) const
179  {
180  return column_table(column_number(col_name));
181  }
182 
184  [[nodiscard]] row_size_type table_column(row_size_type col_num) const;
185 
187  template<typename STRING>
188  [[nodiscard]] row_size_type table_column(STRING col_name) const
189  {
190  return table_column(column_number(col_name));
191  }
193 
195  [[nodiscard]] PQXX_PURE std::string const &query() const noexcept;
196 
198 
201  [[nodiscard]] PQXX_PURE oid inserted_oid() const;
202 
205 
208  [[nodiscard]] PQXX_PURE size_type affected_rows() const;
209 
210 
211 private:
212  using data_pointer = std::shared_ptr<internal::pq::PGresult const>;
213 
215  data_pointer m_data;
216 
218  static data_pointer
219  make_data_pointer(internal::pq::PGresult const *res = nullptr)
220  {
221  return data_pointer{res, internal::clear_result};
222  }
223 
224  friend class pqxx::internal::gate::result_pipeline;
225  PQXX_PURE std::shared_ptr<std::string> query_ptr() const noexcept
226  {
227  return m_query;
228  }
229 
231  std::shared_ptr<std::string> m_query;
232 
233  internal::encoding_group m_encoding;
234 
235  static std::string const s_empty_string;
236 
237  friend class pqxx::field;
238  PQXX_PURE char const *get_value(size_type row, row_size_type col) const;
239  PQXX_PURE bool get_is_null(size_type row, row_size_type col) const;
240  PQXX_PURE
241  field_size_type get_length(size_type, row_size_type) const noexcept;
242 
243  friend class pqxx::internal::gate::result_creation;
244  result(
245  internal::pq::PGresult *rhs, std::shared_ptr<std::string> query,
246  internal::encoding_group enc);
247 
248  PQXX_PRIVATE void check_status() const;
249 
250  friend class pqxx::internal::gate::result_connection;
251  friend class pqxx::internal::gate::result_row;
252  bool operator!() const noexcept { return m_data.get() == nullptr; }
253  operator bool() const noexcept { return m_data.get() != nullptr; }
254 
255  [[noreturn]] PQXX_PRIVATE void
256  ThrowSQLError(std::string const &Err, std::string const &Query) const;
257  PQXX_PRIVATE PQXX_PURE int errorposition() const;
258  PQXX_PRIVATE std::string StatusError() const;
259 
260  friend class pqxx::internal::gate::result_sql_cursor;
261  PQXX_PURE char const *cmd_status() const noexcept;
262 };
263 } // namespace pqxx
264 
265 #include "pqxx/internal/compiler-internal-post.hxx"
266 #endif
pqxx::result::empty
PQXX_PURE bool empty() const noexcept
Definition: result.cxx:106
pqxx::result::column_number
row_size_type column_number(zview name) const
Number of given column (throws exception if it doesn't exist).
Definition: result.hxx:156
pqxx::result::table_column
row_size_type table_column(STRING col_name) const
What column in its table did this column come from?
Definition: result.hxx:188
pqxx::result_size_type
int result_size_type
Number of rows in a result set.
Definition: types.hxx:18
pqxx::result::swap
void swap(result &) noexcept
Definition: result.cxx:124
pqxx::result::rend
const_reverse_iterator rend() const
Definition: result.cxx:74
pqxx::result::column_name
char const * column_name(row_size_type number) const
Name of column with this number (throws exception if it doesn't exist)
Definition: result.cxx:432
pqxx::result::column_type
oid column_type(STRING col_name) const
Return column's type, as an OID from the system catalogue.
Definition: result.hxx:168
pqxx::internal::clear_result
void clear_result(pq::PGresult const *)
C++ wrapper for libpq's PQclear.
Definition: result.cxx:35
pqxx
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
pqxx::internal::gate
Definition: connection.hxx:67
pqxx::to_string
std::string to_string(field const &value)
Convert a field to a string.
Definition: result.cxx:498
pqxx::result::column_table
oid column_table(STRING col_name) const
What table did this column come from?
Definition: result.hxx:178
pqxx::result::column_table
oid column_table(row_size_type col_num) const
What table did this column come from?
Definition: result.cxx:378
pqxx::PQXX_DECLARE_ENUM_CONVERSION
PQXX_DECLARE_ENUM_CONVERSION(pqxx::internal::encoding_group)
pqxx::result::operator!=
bool operator!=(result const &rhs) const noexcept
Definition: result.hxx:96
pqxx::const_reverse_result_iterator::operator--
const_reverse_result_iterator & operator--()
Definition: result_iterator.hxx:243
pqxx::result::begin
const_iterator begin() const noexcept
Definition: result.cxx:86
pqxx::result::result
result(result const &rhs) noexcept=default
pqxx::internal
Private namespace for libpqxx's internal use; do not access.
Definition: connection.hxx:61
pqxx::const_reverse_result_iterator
Reverse iterator for result. Use as result::const_reverse_iterator.
Definition: result_iterator.hxx:176
pqxx::field::col
row_size_type col() const noexcept
Definition: field.hxx:215
pqxx::result::inserted_oid
PQXX_PURE oid inserted_oid() const
If command was INSERT of 1 row, return oid of inserted row.
Definition: result.cxx:317
pqxx::result::difference_type
result_difference_type difference_type
Definition: result.hxx:74
pqxx::zview::c_str
constexpr char const * c_str() const noexcept
Either a null pointer, or a zero-terminated text buffer.
Definition: zview.hxx:53
pqxx::result::operator==
bool operator==(result const &) const noexcept
Definition: result.cxx:48
pqxx::zview
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:33
pqxx::result
Result set containing data returned by a query or command.
Definition: result.hxx:71
pqxx::result_difference_type
int result_difference_type
Difference between result sizes.
Definition: types.hxx:21
pqxx::result::columns
PQXX_PURE row_size_type columns() const noexcept
Number of columns in result.
Definition: result.cxx:447
pqxx::field::size
size_type size() const noexcept
Return number of bytes taken up by the field's value.
Definition: field.cxx:72
pqxx::field::size_type
field_size_type size_type
Definition: field.hxx:35
pqxx::range_error
Something is out of range, similar to std::out_of_range.
Definition: except.hxx:194
pqxx::field_size_type
std::size_t field_size_type
Number of bytes in a field of database data.
Definition: types.hxx:30
pqxx::result::size
PQXX_PURE size_type size() const noexcept
Definition: result.cxx:98
pqxx::const_reverse_result_iterator::operator++
const_reverse_result_iterator & operator++()
Definition: result_iterator.hxx:237
pqxx::result::back
reference back() const noexcept
Definition: result.cxx:118
pqxx::row
Reference to one row in a result.
Definition: row.hxx:44
pqxx::result::size_type
result_size_type size_type
Definition: result.hxx:73
pqxx::result::operator[]
row operator[](size_type i) const noexcept
Definition: result.cxx:131
pqxx::const_reverse_result_iterator::base
PQXX_PURE const_result_iterator base() const noexcept
Definition: result.cxx:473
pqxx::result::column_number
row_size_type column_number(char const col_name[]) const
Number of given column (throws exception if it doesn't exist).
Definition: result.cxx:366
pqxx::result::rbegin
const_reverse_iterator rbegin() const
Definition: result.cxx:62
pqxx::row::size_type
row_size_type size_type
Definition: row.hxx:46
pqxx::result::affected_rows
PQXX_PURE size_type affected_rows() const
Definition: result.cxx:326
pqxx::result::at
row at(size_type) const
Definition: result.cxx:137
pqxx::result::operator=
result & operator=(result const &rhs) noexcept=default
pqxx::const_result_iterator::operator--
const_result_iterator & operator--()
Definition: result_iterator.hxx:103
pqxx::result::front
reference front() const noexcept
Definition: result.cxx:112
pqxx::result::result
result() noexcept
Definition: result.hxx:82
pqxx::argument_error
Invalid argument passed to libpqxx, similar to std::invalid_argument.
Definition: except.hxx:173
pqxx::result::cbegin
const_iterator cbegin() const noexcept
Definition: result.cxx:92
pqxx::row_size_type
int row_size_type
Number of fields in a row of database data.
Definition: types.hxx:24
pqxx::field
Reference to a field in a result set.
Definition: field.hxx:33
pqxx::field::c_str
char const * c_str() const
Read as plain C string.
Definition: field.cxx:60
pqxx::const_result_iterator::operator++
const_result_iterator & operator++()
Definition: result_iterator.hxx:97
pqxx::const_result_iterator
Iterator for rows in a result. Use as result::const_iterator.
Definition: result_iterator.hxx:36
pqxx::oid_none
constexpr oid oid_none
The "null" oid.
Definition: util.hxx:187
pqxx::result::iter
auto iter() const
Iterate rows, reading them directly into a tuple of "TYPE...".
pqxx::usage_error
Error in usage of libpqxx library, similar to std::logic_error.
Definition: except.hxx:166
pqxx::result::query
PQXX_PURE std::string const & query() const noexcept
Query that produced this result, if available (empty string otherwise)
Definition: result.cxx:311
pqxx::result::clear
void clear() noexcept
Definition: result.hxx:133
pqxx::result::column_type
oid column_type(row_size_type col_num) const
Return column's type, as an OID from the system catalogue.
Definition: result.cxx:355
pqxx::result::crend
const_reverse_iterator crend() const
Definition: result.cxx:80
pqxx::result::crbegin
const_reverse_iterator crbegin() const
Definition: result.cxx:68
pqxx::result::table_column
row_size_type table_column(row_size_type col_num) const
What column in its table did this column come from?
Definition: result.cxx:394