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
28namespace pqxx::internal
29{
30PQXX_LIBEXPORT void clear_result(pq::PGresult const *);
31}
32
33
35{
36class result_connection;
37class result_creation;
38class result_pipeline;
39class result_row;
40class result_sql_cursor;
41} // namespace pqxx::internal::gate
42
43
44namespace pqxx
45{
47
67class PQXX_LIBEXPORT result
68{
69public:
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
102 [[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
181 [[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
233private:
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
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:23
int row_size_type
Number of fields in a row of database data.
Definition: types.hxx:30
std::size_t field_size_type
Number of bytes in a field of database data.
Definition: types.hxx:36
int result_difference_type
Difference between result sizes.
Definition: types.hxx:27
int result_size_type
Number of rows in a result set.
Definition: types.hxx:24
Internal items for libpqxx' own use. Do not use these yourself.
Definition: composite.hxx:80
void clear_result(pq::PGresult const *)
C++ wrapper for libpq's PQclear.
Definition: result.cxx:37
Definition: connection.hxx:95
Reference to a field in a result set.
Definition: field.hxx:31
Result set containing data returned by a query or command.
Definition: result.hxx:68
const_reverse_result_iterator const_reverse_iterator
Definition: result.hxx:76
row_size_type table_column(zview col_name) const
What column in its table did this column come from?
Definition: result.hxx:211
result() noexcept
Definition: result.hxx:79
result_size_type size_type
Definition: result.hxx:70
bool operator!=(result const &rhs) const noexcept
Compare two results for inequality.
Definition: result.hxx:104
const_iterator pointer
Definition: result.hxx:74
void clear() noexcept
Let go of the result's data.
Definition: result.hxx:170
const_iterator iterator
Definition: result.hxx:75
result_difference_type difference_type
Definition: result.hxx:71
const_reverse_iterator reverse_iterator
Definition: result.hxx:77
oid column_table(zview col_name) const
What table did this column come from?
Definition: result.hxx:202
result & operator=(result const &rhs) noexcept=default
Assign one result to another.
const_result_iterator const_iterator
Definition: result.hxx:73
result(result const &rhs) noexcept=default
auto iter() const
Iterate rows, reading them directly into a tuple of "TYPE...".
Reference to one row in a result.
Definition: row.hxx:43
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:38