libpqxx 7.9.0
row.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-2024, 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_ROW
14#define PQXX_H_ROW
15
16#if !defined(PQXX_HEADER_PRE)
17# error "Include libpqxx headers as <pqxx/header>, not <pqxx/header.hxx>."
18#endif
19
20#include "pqxx/except.hxx"
21#include "pqxx/field.hxx"
22#include "pqxx/result.hxx"
23
24#include "pqxx/internal/concat.hxx"
25
26namespace pqxx::internal
27{
28template<typename... T> class result_iter;
29} // namespace pqxx::internal
30
31
32namespace pqxx
33{
35
47{
48public:
49 // TODO: Some of these types conflict: class is both iterator and container.
50 // TODO: Set iterator nested types using std::iterator_traits.
59
63 row &operator=(row const &) noexcept = default;
64 row &operator=(row &&) noexcept = default;
65
70 [[nodiscard]] PQXX_PURE bool operator==(row const &) const noexcept;
71 [[nodiscard]] bool operator!=(row const &rhs) const noexcept
72 {
73 return not operator==(rhs);
74 }
76
77 [[nodiscard]] const_iterator begin() const noexcept;
78 [[nodiscard]] const_iterator cbegin() const noexcept;
79 [[nodiscard]] const_iterator end() const noexcept;
80 [[nodiscard]] const_iterator cend() const noexcept;
81
86 [[nodiscard]] reference front() const noexcept;
87 [[nodiscard]] reference back() const noexcept;
88
93
94 [[nodiscard]] reference operator[](size_type) const noexcept;
98 [[nodiscard]] reference operator[](zview col_name) const;
99
100 reference at(size_type) const;
104 reference at(zview col_name) const;
105
107 {
108 return m_end - m_begin;
109 }
110
113 {
114 return m_index;
115 }
116
122 [[nodiscard]] size_type column_number(zview col_name) const;
123
125 [[nodiscard]] oid column_type(size_type) const;
126
129 {
130 return column_type(column_number(col_name));
131 }
132
134 [[nodiscard]] oid column_table(size_type col_num) const;
135
138 {
139 return column_table(column_number(col_name));
140 }
141
143
150 [[nodiscard]] size_type table_column(size_type) const;
151
154 {
155 return table_column(column_number(col_name));
156 }
158
160 {
161 return rownumber();
162 }
163
165
173 template<typename Tuple> void to(Tuple &t) const
174 {
175 check_size(std::tuple_size_v<Tuple>);
176 convert(t);
177 }
178
180
188 template<typename... TYPE> std::tuple<TYPE...> as() const
189 {
190 check_size(sizeof...(TYPE));
191 using seq = std::make_index_sequence<sizeof...(TYPE)>;
192 return get_tuple<std::tuple<TYPE...>>(seq{});
193 }
194
195 [[deprecated("Swap iterators, not rows.")]] void swap(row &) noexcept;
196
208 [[deprecated("Row slicing is going away. File a bug if you need it.")]] row
209 slice(size_type sbegin, size_type send) const;
210
212 [[nodiscard, deprecated("Row slicing is going away.")]] PQXX_PURE bool
213 empty() const noexcept;
214
219
221 void check_size(size_type expected) const
222 {
223 if (size() != expected)
224 throw usage_error{internal::concat(
225 "Tried to extract ", expected, " field(s) from a row of ", size(),
226 ".")};
227 }
228
230
233 template<typename TUPLE> TUPLE as_tuple() const
234 {
235 using seq = std::make_index_sequence<std::tuple_size_v<TUPLE>>;
236 return get_tuple<TUPLE>(seq{});
237 }
238
239 template<typename... T> friend class pqxx::internal::result_iter;
241 template<typename Tuple> void convert(Tuple &t) const
242 {
243 extract_fields(t, std::make_index_sequence<std::tuple_size_v<Tuple>>{});
244 }
245
246 friend class field;
247
250
252
256 result::size_type m_index = 0;
257
258 // TODO: Remove m_begin and (if possible) m_end when we remove slice().
260 size_type m_begin = 0;
262 size_type m_end = 0;
263
264private:
265 template<typename Tuple, std::size_t... indexes>
266 void extract_fields(Tuple &t, std::index_sequence<indexes...>) const
267 {
269 }
270
271 template<typename Tuple, std::size_t index>
272 void extract_value(Tuple &t) const;
273
275 template<typename TUPLE, std::size_t... indexes>
276 auto get_tuple(std::index_sequence<indexes...>) const
277 {
278 return std::make_tuple(get_field<TUPLE, indexes>()...);
279 }
280
282 template<typename TUPLE, std::size_t index> auto get_field() const
283 {
284 return (*this)[index].as<std::tuple_element_t<index, TUPLE>>();
285 }
286};
287
288
291{
292public:
293 using iterator_category = std::random_access_iterator_tag;
294 using value_type = field const;
295 using pointer = field const *;
299
300#include "pqxx/internal/ignore-deprecated-pre.hxx"
302#include "pqxx/internal/ignore-deprecated-post.hxx"
304 field{t.m_result, t.m_index, c}
305 {}
307 const_row_iterator(const_row_iterator const &) noexcept = default;
309
314 [[nodiscard]] constexpr pointer operator->() const noexcept { return this; }
315 [[nodiscard]] reference operator*() const noexcept { return {*this}; }
317
322 const_row_iterator &operator=(const_row_iterator const &) noexcept = default;
324
325 const_row_iterator operator++(int) & noexcept;
327 {
328 ++m_col;
329 return *this;
330 }
331 const_row_iterator operator--(int) & noexcept;
333 {
334 --m_col;
335 return *this;
336 }
337
339 {
340 m_col = size_type(difference_type(m_col) + i);
341 return *this;
342 }
344 {
345 m_col = size_type(difference_type(m_col) - i);
346 return *this;
347 }
349
354 [[nodiscard]] constexpr bool
355 operator==(const_row_iterator const &i) const noexcept
356 {
357 return col() == i.col();
358 }
359 [[nodiscard]] constexpr bool
360 operator!=(const_row_iterator const &i) const noexcept
361 {
362 return col() != i.col();
363 }
364 [[nodiscard]] constexpr bool
365 operator<(const_row_iterator const &i) const noexcept
366 {
367 return col() < i.col();
368 }
369 [[nodiscard]] constexpr bool
370 operator<=(const_row_iterator const &i) const noexcept
371 {
372 return col() <= i.col();
373 }
374 [[nodiscard]] constexpr bool
375 operator>(const_row_iterator const &i) const noexcept
376 {
377 return col() > i.col();
378 }
379 [[nodiscard]] constexpr bool
380 operator>=(const_row_iterator const &i) const noexcept
381 {
382 return col() >= i.col();
383 }
385
391 operator+(difference_type) const noexcept;
392
393 friend const_row_iterator
394 operator+(difference_type, const_row_iterator const &) noexcept;
395
397 operator-(difference_type) const noexcept;
398 [[nodiscard]] inline difference_type
399 operator-(const_row_iterator const &) const noexcept;
401};
402
403
406{
407public:
415
418 default;
420
423 {
424 super::operator--();
425 }
426
427 [[nodiscard]] PQXX_PURE iterator_type base() const noexcept;
428
433 using iterator_type::operator->;
434 using iterator_type::operator*;
436
441 const_reverse_row_iterator &
443 {
444 iterator_type::operator=(r);
445 return *this;
446 }
448 {
449 iterator_type::operator--();
450 return *this;
451 }
452 const_reverse_row_iterator operator++(int) & noexcept;
454 {
455 iterator_type::operator++();
456 return *this;
457 }
458 const_reverse_row_iterator operator--(int) &;
460 {
461 iterator_type::operator-=(i);
462 return *this;
463 }
465 {
466 iterator_type::operator+=(i);
467 return *this;
468 }
470
477 {
478 return const_reverse_row_iterator{base() - i};
479 }
482 {
483 return const_reverse_row_iterator{base() + i};
484 }
485 [[nodiscard]] difference_type
487 {
488 return rhs.const_row_iterator::operator-(*this);
489 }
491
496 [[nodiscard]] bool
498 {
499 return iterator_type::operator==(rhs);
500 }
501 [[nodiscard]] bool
503 {
504 return !operator==(rhs);
505 }
506
507 [[nodiscard]] constexpr bool
508 operator<(const_reverse_row_iterator const &rhs) const noexcept
509 {
510 return iterator_type::operator>(rhs);
511 }
512 [[nodiscard]] constexpr bool
513 operator<=(const_reverse_row_iterator const &rhs) const noexcept
514 {
515 return iterator_type::operator>=(rhs);
516 }
517 [[nodiscard]] constexpr bool
519 {
520 return iterator_type::operator<(rhs);
521 }
522 [[nodiscard]] constexpr bool
524 {
525 return iterator_type::operator<=(rhs);
526 }
528};
529
530
531const_row_iterator
533{
534 // TODO:: More direct route to home().columns()?
535 return {
536 row{home(), idx(), home().columns()},
537 size_type(difference_type(col()) + o)};
538}
539
542{
543 return i + o;
544}
545
548{
549 // TODO:: More direct route to home().columns()?
550 return {
551 row{home(), idx(), home().columns()},
552 size_type(difference_type(col()) - o)};
553}
554
557{
558 return difference_type(num() - i.num());
559}
560
561
562template<typename Tuple, std::size_t index>
563inline void row::extract_value(Tuple &t) const
564{
566 field const f{m_result, m_index, index};
567 std::get<index>(t) = from_string<field_type>(f);
568}
569} // namespace pqxx
570#endif
The home of all libpqxx classes, functions, templates, etc.
Definition array.hxx:33
int result_size_type
Number of rows in a result set.
Definition types.hxx:28
constexpr char array_separator
Element separator between SQL array elements of this type.
Definition strconv.hxx:557
const_row_iterator operator+(const_row_iterator::difference_type o, const_row_iterator const &i) noexcept
Definition row.hxx:540
int row_size_type
Number of fields in a row of database data.
Definition types.hxx:34
int row_difference_type
Difference between row sizes.
Definition types.hxx:37
Internal items for libpqxx' own use. Do not use these yourself.
Definition composite.hxx:84
Error in usage of libpqxx library, similar to std::logic_error.
Definition except.hxx:249
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
result_size_type size_type
Definition result.hxx:75
Definition row.hxx:28
Reference to one row in a result.
Definition row.hxx:47
std::tuple< TYPE... > as() const
Extract entire row's values into a tuple.
Definition row.hxx:188
row_size_type size_type
Definition row.hxx:51
oid column_type(zview col_name) const
Return a column's type.
Definition row.hxx:128
row_difference_type difference_type
Definition row.hxx:52
result m_result
Result set of which this is one row.
Definition row.hxx:249
result::size_type m_index
Row number.
Definition row.hxx:256
constexpr result::size_type num() const noexcept
Definition row.hxx:159
row() noexcept=default
constexpr result::size_type rownumber() const noexcept
Row number, assuming this is a real row and not end()/rend().
Definition row.hxx:112
TUPLE as_tuple() const
Convert to a given tuple of values, don't check sizes.
Definition row.hxx:233
void to(Tuple &t) const
Extract entire row's values into a tuple.
Definition row.hxx:173
size_type table_column(zview col_name) const
What column number in its table did this result column come from?
Definition row.hxx:153
void convert(Tuple &t) const
Convert entire row to tuple fields, without checking row size.
Definition row.hxx:241
oid column_table(zview col_name) const
What table did this column come from?
Definition row.hxx:137
Iterator for fields in a row. Use as row::const_iterator.
Definition row.hxx:291
const_row_iterator operator-(difference_type) const noexcept
Definition row.hxx:547
const_row_iterator & operator=(const_row_iterator &&) noexcept=default
reference operator*() const noexcept
Definition row.hxx:315
const_row_iterator(field const &F) noexcept
Definition row.hxx:306
friend const_row_iterator operator+(difference_type, const_row_iterator const &) noexcept
Definition row.hxx:540
constexpr bool operator>=(const_row_iterator const &i) const noexcept
Definition row.hxx:380
const_row_iterator(const_row_iterator const &) noexcept=default
const_row_iterator & operator=(const_row_iterator const &) noexcept=default
std::random_access_iterator_tag iterator_category
Definition row.hxx:293
constexpr bool operator==(const_row_iterator const &i) const noexcept
Definition row.hxx:355
field const * pointer
Definition row.hxx:295
field const value_type
Definition row.hxx:294
constexpr bool operator!=(const_row_iterator const &i) const noexcept
Definition row.hxx:360
const_row_iterator(const_row_iterator &&) noexcept=default
row_size_type size_type
Definition row.hxx:296
const_row_iterator & operator--() noexcept
Definition row.hxx:332
const_row_iterator() noexcept=default
row_difference_type difference_type
Definition row.hxx:297
const_row_iterator & operator-=(difference_type i) noexcept
Definition row.hxx:343
const_row_iterator & operator+=(difference_type i) noexcept
Definition row.hxx:338
const_row_iterator(row const &t, row_size_type c) noexcept
Definition row.hxx:303
constexpr bool operator>(const_row_iterator const &i) const noexcept
Definition row.hxx:375
Reverse iterator for a row. Use as row::const_reverse_iterator.
Definition row.hxx:406
const_reverse_row_iterator operator++() noexcept
Definition row.hxx:447
bool operator!=(const_reverse_row_iterator const &rhs) const noexcept
Definition row.hxx:502
constexpr bool operator>=(const_reverse_row_iterator const &rhs) const noexcept
Definition row.hxx:523
constexpr bool operator>(const_reverse_row_iterator const &rhs) const noexcept
Definition row.hxx:518
difference_type operator-(const_reverse_row_iterator const &rhs) const noexcept
Definition row.hxx:486
const_reverse_row_iterator & operator+=(difference_type i) noexcept
Definition row.hxx:459
const_reverse_row_iterator operator+(difference_type i) const noexcept
Definition row.hxx:476
const_reverse_row_iterator & operator-=(difference_type i) noexcept
Definition row.hxx:464
const_reverse_row_iterator & operator--() noexcept
Definition row.hxx:453
row_difference_type difference_type
Definition row.hxx:297
bool operator==(const_reverse_row_iterator const &rhs) const noexcept
Definition row.hxx:497
const_reverse_row_iterator() noexcept=default
const_reverse_row_iterator operator-(difference_type i) noexcept
Definition row.hxx:481
iterator_type::value_type value_type
Definition row.hxx:413
Marker-type wrapper: zero-terminated std::string_view.
Definition zview.hxx:38