libpqxx 7.8.1
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-2023, 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
33namespace pqxx::internal
34{
35PQXX_LIBEXPORT void clear_result(pq::PGresult const *) noexcept;
36} // namespace pqxx::internal
37
38
40{
41class result_connection;
42class result_creation;
43class result_pipeline;
44class result_row;
45class result_sql_cursor;
46} // namespace pqxx::internal::gate
47
48
49namespace pqxx
50{
52
72class PQXX_LIBEXPORT result
73{
74public:
77 using reference = row;
78 using const_iterator = const_result_iterator;
81 using const_reverse_iterator = const_reverse_result_iterator;
83
84 result() noexcept :
85 m_data{make_data_pointer()},
86 m_query{},
87 m_encoding{internal::encoding_group::MONOBYTE}
88 {}
89
90 result(result const &rhs) noexcept = default;
91 result(result &&rhs) noexcept = default;
92
94
97 result &operator=(result const &rhs) noexcept = default;
98
100 result &operator=(result &&rhs) noexcept = default;
101
111 [[nodiscard]] bool operator==(result const &) const noexcept;
113 [[nodiscard]] bool operator!=(result const &rhs) const noexcept
114 {
115 return not operator==(rhs);
116 }
118
120
126 template<typename... TYPE> auto iter() const;
127
128 [[nodiscard]] const_reverse_iterator rbegin() const;
129 [[nodiscard]] const_reverse_iterator crbegin() const;
130 [[nodiscard]] const_reverse_iterator rend() const;
131 [[nodiscard]] const_reverse_iterator crend() const;
132
133 [[nodiscard]] const_iterator begin() const noexcept;
134 [[nodiscard]] const_iterator cbegin() const noexcept;
135 [[nodiscard]] inline const_iterator end() const noexcept;
136 [[nodiscard]] inline const_iterator cend() const noexcept;
137
138 [[nodiscard]] reference front() const noexcept;
139 [[nodiscard]] reference back() const noexcept;
140
141 [[nodiscard]] PQXX_PURE size_type size() const noexcept;
142 [[nodiscard]] PQXX_PURE bool empty() const noexcept;
143 [[nodiscard]] size_type capacity() const noexcept { return size(); }
144
146
150 void swap(result &) noexcept;
151
153
157 [[nodiscard]] row operator[](size_type i) const noexcept;
158
159#if pqxx_have_multidim
160 [[nodiscard]] field
161 operator[](size_type row_num, row_size_type col_num) const noexcept;
162#endif // pqxx_have_multidim
163
165 row at(size_type) const;
166
168 field at(size_type, row_size_type) const;
169
171
178 void clear() noexcept
179 {
180 m_data.reset();
181 m_query = nullptr;
182 }
183
189 [[nodiscard]] PQXX_PURE row_size_type columns() const noexcept;
190
192 [[nodiscard]] row_size_type column_number(zview name) const;
193
195 [[nodiscard]] char const *column_name(row_size_type number) const &;
196
198 [[nodiscard]] oid column_type(row_size_type col_num) const;
199
201 [[nodiscard]] oid column_type(zview col_name) const
202 {
203 return column_type(column_number(col_name));
204 }
205
207 [[nodiscard]] oid column_table(row_size_type col_num) const;
208
210 [[nodiscard]] oid column_table(zview col_name) const
211 {
212 return column_table(column_number(col_name));
213 }
214
216 [[nodiscard]] row_size_type table_column(row_size_type col_num) const;
217
219 [[nodiscard]] row_size_type table_column(zview col_name) const
220 {
221 return table_column(column_number(col_name));
222 }
224
226 [[nodiscard]] PQXX_PURE std::string const &query() const &noexcept;
227
229
232 [[nodiscard]] PQXX_PURE oid inserted_oid() const;
233
235
238 [[nodiscard]] PQXX_PURE size_type affected_rows() const;
239
240 // C++20: Concept like std::invocable, but without specifying param types.
242
276 template<typename CALLABLE> inline void for_each(CALLABLE &&func) const;
277
278private:
279 using data_pointer = std::shared_ptr<internal::pq::PGresult const>;
280
282 data_pointer m_data;
283
285 static data_pointer
286 make_data_pointer(internal::pq::PGresult const *res = nullptr) noexcept
287 {
288 return {res, internal::clear_result};
289 }
290
291 friend class pqxx::internal::gate::result_pipeline;
292 PQXX_PURE std::shared_ptr<std::string const> query_ptr() const noexcept
293 {
294 return m_query;
295 }
296
298 std::shared_ptr<std::string const> m_query;
299
300 internal::encoding_group m_encoding;
301
302 static std::string const s_empty_string;
303
304 friend class pqxx::field;
305 PQXX_PURE char const *
306 get_value(size_type row, row_size_type col) const noexcept;
307 PQXX_PURE bool get_is_null(size_type row, row_size_type col) const noexcept;
308 PQXX_PURE
309 field_size_type get_length(size_type, row_size_type) const noexcept;
310
311 friend class pqxx::internal::gate::result_creation;
312 result(
313 internal::pq::PGresult *rhs, std::shared_ptr<std::string> query,
314 internal::encoding_group enc);
315
316 PQXX_PRIVATE void check_status(std::string_view desc = ""sv) const;
317
318 friend class pqxx::internal::gate::result_connection;
319 friend class pqxx::internal::gate::result_row;
320 bool operator!() const noexcept { return m_data.get() == nullptr; }
321 operator bool() const noexcept { return m_data.get() != nullptr; }
322
323 [[noreturn]] PQXX_PRIVATE PQXX_COLD void
324 throw_sql_error(std::string const &Err, std::string const &Query) const;
325 PQXX_PRIVATE PQXX_PURE int errorposition() const;
326 PQXX_PRIVATE std::string status_error() const;
327
328 friend class pqxx::internal::gate::result_sql_cursor;
329 PQXX_PURE char const *cmd_status() const noexcept;
330};
331} // namespace pqxx
332#endif
The home of all libpqxx classes, functions, templates, etc.
Definition array.hxx:33
int row_size_type
Number of fields in a row of database data.
Definition types.hxx:34
std::size_t field_size_type
Number of bytes in a field of database data.
Definition types.hxx:40
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
Internal items for libpqxx' own use. Do not use these yourself.
Definition composite.hxx:84
void clear_result(pq::PGresult const *) noexcept
C++ wrapper for libpq's PQclear.
Definition result.cxx:42
Definition connection.hxx:112
Reference to a field in a result set.
Definition field.hxx:35
Result set containing data returned by a query or command.
Definition result.hxx:73
const_reverse_result_iterator const_reverse_iterator
Definition result.hxx:81
result(result &&rhs) noexcept=default
row_size_type table_column(zview col_name) const
What column in its table did this column come from?
Definition result.hxx:219
result() noexcept
Definition result.hxx:84
result & operator=(result &&rhs) noexcept=default
Assign one result to another, invaliding the old one.
result_size_type size_type
Definition result.hxx:75
bool operator!=(result const &rhs) const noexcept
Compare two results for inequality.
Definition result.hxx:113
const_iterator pointer
Definition result.hxx:79
void clear() noexcept
Let go of the result's data.
Definition result.hxx:178
const_iterator iterator
Definition result.hxx:80
result_difference_type difference_type
Definition result.hxx:76
const_reverse_iterator reverse_iterator
Definition result.hxx:82
oid column_table(zview col_name) const
What table did this column come from?
Definition result.hxx:210
result & operator=(result const &rhs) noexcept=default
Assign one result to another.
const_result_iterator const_iterator
Definition result.hxx:78
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:47
Marker-type wrapper: zero-terminated std::string_view.
Definition zview.hxx:38