libpqxx  7.7.4
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-2022, 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 #if !defined(PQXX_HEADER_PRE)
17 # error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
18 #endif
19 
20 #include <functional>
21 #include <ios>
22 #include <memory>
23 #include <stdexcept>
24 
25 #include "pqxx/except.hxx"
26 #include "pqxx/types.hxx"
27 #include "pqxx/util.hxx"
28 #include "pqxx/zview.hxx"
29 
30 #include "pqxx/internal/encodings.hxx"
31 
32 
33 namespace pqxx::internal
34 {
35 // TODO: Make noexcept (but breaks ABI).
36 PQXX_LIBEXPORT void clear_result(pq::PGresult const *);
37 } // namespace pqxx::internal
38 
39 
40 namespace pqxx::internal::gate
41 {
42 class result_connection;
43 class result_creation;
44 class result_pipeline;
45 class result_row;
46 class result_sql_cursor;
47 } // namespace pqxx::internal::gate
48 
49 
50 namespace pqxx
51 {
53 
73 class PQXX_LIBEXPORT result
74 {
75 public:
78  using reference = row;
79  using const_iterator = const_result_iterator;
82  using const_reverse_iterator = const_reverse_result_iterator;
84 
85  result() noexcept :
86  m_data{make_data_pointer()},
87  m_query{},
88  m_encoding{internal::encoding_group::MONOBYTE}
89  {}
90 
91  result(result const &rhs) noexcept = default;
92  result(result &&rhs) noexcept = default;
93 
95 
98  result &operator=(result const &rhs) noexcept = default;
99 
101  result &operator=(result &&rhs) noexcept = default;
102 
111  [[nodiscard]] bool operator==(result const &) const noexcept;
114  [[nodiscard]] bool operator!=(result const &rhs) const noexcept
115  {
116  return not operator==(rhs);
117  }
119 
121 
127  template<typename... TYPE> auto iter() const;
128 
129  [[nodiscard]] const_reverse_iterator rbegin() const;
130  [[nodiscard]] const_reverse_iterator crbegin() const;
131  [[nodiscard]] const_reverse_iterator rend() const;
132  [[nodiscard]] const_reverse_iterator crend() const;
133 
134  [[nodiscard]] const_iterator begin() const noexcept;
135  [[nodiscard]] const_iterator cbegin() const noexcept;
136  [[nodiscard]] inline const_iterator end() const noexcept;
137  [[nodiscard]] inline const_iterator cend() const noexcept;
138 
139  [[nodiscard]] reference front() const noexcept;
140  [[nodiscard]] reference back() const noexcept;
141 
142  [[nodiscard]] PQXX_PURE size_type size() const noexcept;
143  [[nodiscard]] PQXX_PURE bool empty() const noexcept;
144  [[nodiscard]] size_type capacity() const noexcept { return size(); }
145 
147 
151  void swap(result &) noexcept;
152 
154 
158  [[nodiscard]] row operator[](size_type i) const noexcept;
159 
160 #if defined(PQXX_HAVE_MULTIDIMENSIONAL_SUBSCRIPT)
161  // TODO: If C++23 will let us, also accept string for the column.
162  [[nodiscard]] field
163  operator[](size_type row_num, row_size_type col_num) const noexcept;
164 #endif
165 
167  row at(size_type) const;
168 
170  field at(size_type, row_size_type) const;
171 
173 
180  void clear() noexcept
181  {
182  m_data.reset();
183  m_query = nullptr;
184  }
185 
190  [[nodiscard]] PQXX_PURE row_size_type columns() const noexcept;
192 
194  [[nodiscard]] row_size_type column_number(zview name) const;
195 
197  [[nodiscard]] char const *column_name(row_size_type number) const &;
198 
200  [[nodiscard]] oid column_type(row_size_type col_num) const;
201 
203  [[nodiscard]] oid column_type(zview col_name) const
204  {
205  return column_type(column_number(col_name));
206  }
207 
209  [[nodiscard]] oid column_table(row_size_type col_num) const;
210 
212  [[nodiscard]] oid column_table(zview col_name) const
213  {
214  return column_table(column_number(col_name));
215  }
216 
218  [[nodiscard]] row_size_type table_column(row_size_type col_num) const;
219 
221  [[nodiscard]] row_size_type table_column(zview col_name) const
222  {
223  return table_column(column_number(col_name));
224  }
226 
228  [[nodiscard]] PQXX_PURE std::string const &query() const &noexcept;
229 
231 
234  [[nodiscard]] PQXX_PURE oid inserted_oid() const;
235 
237 
240  [[nodiscard]] PQXX_PURE size_type affected_rows() const;
241 
242  // C++20: Concept like std::invocable, but without specifying param types.
244 
278  template<typename CALLABLE> inline void for_each(CALLABLE &&func) const;
279 
280 private:
281  using data_pointer = std::shared_ptr<internal::pq::PGresult const>;
282 
284  data_pointer m_data;
285 
287  static data_pointer
288  make_data_pointer(internal::pq::PGresult const *res = nullptr) noexcept
289  {
290  return {res, internal::clear_result};
291  }
292 
293  friend class pqxx::internal::gate::result_pipeline;
294  PQXX_PURE std::shared_ptr<std::string const> query_ptr() const noexcept
295  {
296  return m_query;
297  }
298 
300  std::shared_ptr<std::string const> m_query;
301 
302  internal::encoding_group m_encoding;
303 
304  static std::string const s_empty_string;
305 
306  friend class pqxx::field;
307  // TODO: noexcept. Breaks ABI.
308  PQXX_PURE char const *get_value(size_type row, row_size_type col) const;
309  // TODO: noexcept. Breaks ABI.
310  PQXX_PURE bool get_is_null(size_type row, row_size_type col) const;
311  PQXX_PURE
312  field_size_type get_length(size_type, row_size_type) const noexcept;
313 
314  friend class pqxx::internal::gate::result_creation;
315  result(
316  internal::pq::PGresult *rhs, std::shared_ptr<std::string> query,
317  internal::encoding_group enc);
318 
319  PQXX_PRIVATE void check_status(std::string_view desc = ""sv) const;
320 
321  friend class pqxx::internal::gate::result_connection;
322  friend class pqxx::internal::gate::result_row;
323  bool operator!() const noexcept
324  {
325  return m_data.get() == nullptr;
326  }
327  operator bool() const noexcept
328  {
329  return m_data.get() != nullptr;
330  }
331 
332  [[noreturn]] PQXX_PRIVATE void
333  throw_sql_error(std::string const &Err, std::string const &Query) const;
334  PQXX_PRIVATE PQXX_PURE int errorposition() const;
335  PQXX_PRIVATE std::string status_error() const;
336 
337  friend class pqxx::internal::gate::result_sql_cursor;
338  PQXX_PURE char const *cmd_status() const noexcept;
339 };
340 } // namespace pqxx
341 #endif
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:26
Reference to one row in a result.
Definition: row.hxx:46
void clear_result(pq::PGresult const *)
C++ wrapper for libpq&#39;s PQclear.
Definition: result.cxx:42
row_size_type table_column(zview col_name) const
What column in its table did this column come from?
Definition: result.hxx:221
const_result_iterator const_iterator
Definition: result.hxx:79
Reference to a field in a result set.
Definition: field.hxx:34
std::size_t field_size_type
Number of bytes in a field of database data.
Definition: types.hxx:40
int row_size_type
Number of fields in a row of database data.
Definition: types.hxx:34
size_type capacity() const noexcept
Definition: result.hxx:144
result() noexcept
Definition: result.hxx:85
result_difference_type difference_type
Definition: result.hxx:77
Definition: connection.hxx:98
bool operator!=(result const &rhs) const noexcept
Compare two results for inequality.
Definition: result.hxx:114
const_reverse_result_iterator const_reverse_iterator
Definition: result.hxx:82
result_size_type size_type
Definition: result.hxx:76
oid column_type(zview col_name) const
Return column&#39;s type, as an OID from the system catalogue.
Definition: result.hxx:203
const_iterator iterator
Definition: result.hxx:81
constexpr row_size_type col() const noexcept
Definition: field.hxx:265
Result set containing data returned by a query or command.
Definition: result.hxx:73
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
Internal items for libpqxx&#39; own use. Do not use these yourself.
Definition: composite.hxx:82
void clear() noexcept
Let go of the result&#39;s data.
Definition: result.hxx:180
oid column_table(zview col_name) const
What table did this column come from?
Definition: result.hxx:212
const_reverse_iterator reverse_iterator
Definition: result.hxx:83
int result_difference_type
Difference between result sizes.
Definition: types.hxx:31
int result_size_type
Number of rows in a result set.
Definition: types.hxx:28
const_iterator pointer
Definition: result.hxx:80