libpqxx  7.7.0
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 #include <ios>
17 #include <memory>
18 #include <stdexcept>
19 
20 #include "pqxx/except.hxx"
21 #include "pqxx/types.hxx"
22 #include "pqxx/util.hxx"
23 #include "pqxx/zview.hxx"
24 
25 #include "pqxx/internal/encodings.hxx"
26 
27 
28 namespace pqxx::internal
29 {
30 PQXX_LIBEXPORT void clear_result(pq::PGresult const *);
31 }
32 
33 
34 namespace pqxx::internal::gate
35 {
36 class result_connection;
37 class result_creation;
38 class result_pipeline;
39 class result_row;
40 class result_sql_cursor;
41 } // namespace pqxx::internal::gate
42 
43 
44 namespace pqxx
45 {
47 
67 class PQXX_LIBEXPORT result
68 {
69 public:
72  using reference = row;
73  using const_iterator = const_result_iterator;
76  using const_reverse_iterator = const_reverse_result_iterator;
78 
79  result() noexcept :
80  m_data(make_data_pointer()),
81  m_query(),
82  m_encoding(internal::encoding_group::MONOBYTE)
83  {}
84 
85  result(result const &rhs) noexcept = default;
86 
88 
91  result &operator=(result const &rhs) noexcept = default;
92 
101  [[nodiscard]] bool operator==(result const &) const noexcept;
104  [[nodiscard]] bool operator!=(result const &rhs) const noexcept
105  {
106  return not operator==(rhs);
107  }
109 
111 
117  template<typename... TYPE> auto iter() const;
118 
119  [[nodiscard]] const_reverse_iterator rbegin() const;
120  [[nodiscard]] const_reverse_iterator crbegin() const;
121  [[nodiscard]] const_reverse_iterator rend() const;
122  [[nodiscard]] const_reverse_iterator crend() const;
123 
124  [[nodiscard]] const_iterator begin() const noexcept;
125  [[nodiscard]] const_iterator cbegin() const noexcept;
126  [[nodiscard]] inline const_iterator end() const noexcept;
127  [[nodiscard]] inline const_iterator cend() const noexcept;
128 
129  [[nodiscard]] reference front() const noexcept;
130  [[nodiscard]] reference back() const noexcept;
131 
132  [[nodiscard]] PQXX_PURE size_type size() const noexcept;
133  [[nodiscard]] PQXX_PURE bool empty() const noexcept;
134  [[nodiscard]] size_type capacity() const noexcept { return size(); }
135 
137 
141  void swap(result &) noexcept;
142 
144 
148  [[nodiscard]] row operator[](size_type i) const noexcept;
149 
150 #if defined(PQXX_HAVE_MULTIDIMENSIONAL_SUBSCRIPT)
151  // TODO: If C++23 will let us, also accept string for the column.
152  [[nodiscard]] field
153  operator[](size_type row_num, row_size_type col_num) const noexcept;
154 #endif
155 
157  row at(size_type) const;
158 
160  field at(size_type, row_size_type) const;
161 
163 
170  void clear() noexcept
171  {
172  m_data.reset();
173  m_query = nullptr;
174  }
175 
180  [[nodiscard]] PQXX_PURE row_size_type columns() const noexcept;
182 
184  [[nodiscard]] row_size_type column_number(zview name) const;
185 
187  [[nodiscard]] char const *column_name(row_size_type number) const &;
188 
190  [[nodiscard]] oid column_type(row_size_type col_num) const;
191 
193  [[nodiscard]] oid column_type(zview col_name) const
194  {
195  return column_type(column_number(col_name));
196  }
197 
199  [[nodiscard]] oid column_table(row_size_type col_num) const;
200 
202  [[nodiscard]] oid column_table(zview col_name) const
203  {
204  return column_table(column_number(col_name));
205  }
206 
208  [[nodiscard]] row_size_type table_column(row_size_type col_num) const;
209 
211  [[nodiscard]] row_size_type table_column(zview col_name) const
212  {
213  return table_column(column_number(col_name));
214  }
216 
218  [[nodiscard]] PQXX_PURE std::string const &query() const &noexcept;
219 
221 
224  [[nodiscard]] PQXX_PURE oid inserted_oid() const;
225 
227 
230  [[nodiscard]] PQXX_PURE size_type affected_rows() const;
231 
232 
233 private:
234  using data_pointer = std::shared_ptr<internal::pq::PGresult const>;
235 
237  data_pointer m_data;
238 
240  static data_pointer
241  make_data_pointer(internal::pq::PGresult const *res = nullptr)
242  {
243  return {res, internal::clear_result};
244  }
245 
246  friend class pqxx::internal::gate::result_pipeline;
247  PQXX_PURE std::shared_ptr<std::string const> query_ptr() const noexcept
248  {
249  return m_query;
250  }
251 
253  std::shared_ptr<std::string const> m_query;
254 
255  internal::encoding_group m_encoding;
256 
257  static std::string const s_empty_string;
258 
259  friend class pqxx::field;
260  PQXX_PURE char const *get_value(size_type row, row_size_type col) const;
261  PQXX_PURE bool get_is_null(size_type row, row_size_type col) const;
262  PQXX_PURE
263  field_size_type get_length(size_type, row_size_type) const noexcept;
264 
265  friend class pqxx::internal::gate::result_creation;
266  result(
267  internal::pq::PGresult *rhs, std::shared_ptr<std::string> query,
268  internal::encoding_group enc);
269 
270  PQXX_PRIVATE void check_status(std::string_view desc = ""sv) const;
271 
272  friend class pqxx::internal::gate::result_connection;
273  friend class pqxx::internal::gate::result_row;
274  bool operator!() const noexcept { return m_data.get() == nullptr; }
275  operator bool() const noexcept { return m_data.get() != nullptr; }
276 
277  [[noreturn]] PQXX_PRIVATE void
278  throw_sql_error(std::string const &Err, std::string const &Query) const;
279  PQXX_PRIVATE PQXX_PURE int errorposition() const;
280  PQXX_PRIVATE std::string status_error() const;
281 
282  friend class pqxx::internal::gate::result_sql_cursor;
283  PQXX_PURE char const *cmd_status() const noexcept;
284 };
285 } // namespace pqxx
286 #endif
int row_size_type
Number of fields in a row of database data.
Definition: types.hxx:30
const_result_iterator const_iterator
Definition: result.hxx:73
oid column_table(zview col_name) const
What table did this column come from?
Definition: result.hxx:202
Reference to a field in a result set.
Definition: field.hxx:30
Result set containing data returned by a query or command.
Definition: result.hxx:67
Definition: connection.hxx:94
row_size_type table_column(zview col_name) const
What column in its table did this column come from?
Definition: result.hxx:211
result_difference_type difference_type
Definition: result.hxx:71
void clear_result(pq::PGresult const *)
C++ wrapper for libpq&#39;s PQclear.
Definition: result.cxx:37
const_reverse_result_iterator const_reverse_iterator
Definition: result.hxx:76
result_size_type size_type
Definition: result.hxx:70
oid column_type(zview col_name) const
Return column&#39;s type, as an OID from the system catalogue.
Definition: result.hxx:193
int result_difference_type
Difference between result sizes.
Definition: types.hxx:27
row_size_type col() const noexcept
Definition: field.hxx:255
int result_size_type
Number of rows in a result set.
Definition: types.hxx:24
void clear() noexcept
Let go of the result&#39;s data.
Definition: result.hxx:170
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
size_type capacity() const noexcept
Definition: result.hxx:134
std::size_t field_size_type
Number of bytes in a field of database data.
Definition: types.hxx:36
Internal items for libpqxx&#39; own use. Do not use these yourself.
Definition: composite.hxx:79
result() noexcept
Definition: result.hxx:79
const_reverse_iterator reverse_iterator
Definition: result.hxx:77
bool operator!=(result const &rhs) const noexcept
Compare two results for inequality.
Definition: result.hxx:104
const_iterator pointer
Definition: result.hxx:74
const_iterator iterator
Definition: result.hxx:75
Reference to one row in a result.
Definition: row.hxx:42
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:22