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 
26 namespace pqxx::internal
27 {
28 template<typename... T> class result_iter;
29 } // namespace pqxx::internal
30 
31 
32 namespace pqxx
33 {
35 
46 class PQXX_LIBEXPORT row
47 {
48 public:
49  // TODO: Some of these types conflict: class is both iterator and container.
50  // TODO: Set iterator nested types using std::iterator_traits.
55  using reference = field;
59 
60  row() noexcept = default;
61  row(row &&) noexcept = default;
62  row(row const &) noexcept = default;
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 
89  [[nodiscard]] const_reverse_row_iterator rbegin() const noexcept;
90  [[nodiscard]] const_reverse_row_iterator crbegin() const noexcept;
91  [[nodiscard]] const_reverse_row_iterator rend() const noexcept;
92  [[nodiscard]] const_reverse_row_iterator crend() const noexcept;
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 
106  [[nodiscard]] constexpr size_type size() const noexcept
107  {
108  return m_end - m_begin;
109  }
110 
112  [[nodiscard]] constexpr result::size_type rownumber() const noexcept
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 
128  [[nodiscard]] oid column_type(zview col_name) const
129  {
130  return column_type(column_number(col_name));
131  }
132 
134  [[nodiscard]] oid column_table(size_type col_num) const;
135 
137  [[nodiscard]] oid column_table(zview col_name) const
138  {
139  return column_table(column_number(col_name));
140  }
141 
143 
150  [[nodiscard]] size_type table_column(size_type) const;
151 
153  [[nodiscard]] size_type table_column(zview col_name) const
154  {
155  return table_column(column_number(col_name));
156  }
158 
159  [[nodiscard]] constexpr result::size_type num() const noexcept
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 
215 protected:
216  friend class const_row_iterator;
217  friend class result;
218  row(result const &r, result_size_type index, size_type cols) noexcept;
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 
264 private:
265  template<typename Tuple, std::size_t... indexes>
266  void extract_fields(Tuple &t, std::index_sequence<indexes...>) const
267  {
268  (extract_value<Tuple, indexes>(t), ...);
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 
290 class PQXX_LIBEXPORT const_row_iterator : public field
291 {
292 public:
293  using iterator_category = std::random_access_iterator_tag;
294  using value_type = field const;
295  using pointer = field const *;
298  using reference = field;
299 
300 #include "pqxx/internal/ignore-deprecated-pre.hxx"
301  const_row_iterator() noexcept = default;
302 #include "pqxx/internal/ignore-deprecated-post.hxx"
303  const_row_iterator(row const &t, row_size_type c) noexcept :
304  field{t.m_result, t.m_index, c}
305  {}
306  const_row_iterator(field const &F) noexcept : field{F} {}
307  const_row_iterator(const_row_iterator const &) noexcept = default;
308  const_row_iterator(const_row_iterator &&) 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;
326  const_row_iterator &operator++() 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 
390  [[nodiscard]] inline const_row_iterator
391  operator+(difference_type) const noexcept;
392 
393  friend const_row_iterator
394  operator+(difference_type, const_row_iterator const &) noexcept;
395 
396  [[nodiscard]] inline const_row_iterator
397  operator-(difference_type) const noexcept;
398  [[nodiscard]] inline difference_type
399  operator-(const_row_iterator const &) const noexcept;
401 };
402 
403 
405 class PQXX_LIBEXPORT const_reverse_row_iterator : private const_row_iterator
406 {
407 public:
415 
416  const_reverse_row_iterator() noexcept = default;
418  default;
420 
421  explicit const_reverse_row_iterator(super const &rhs) noexcept :
422  const_row_iterator{rhs}
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 &
442  operator=(const_reverse_row_iterator const &r) noexcept
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 
475  [[nodiscard]] const_reverse_row_iterator
476  operator+(difference_type i) const noexcept
477  {
478  return const_reverse_row_iterator{base() - i};
479  }
480  [[nodiscard]] const_reverse_row_iterator
482  {
483  return const_reverse_row_iterator{base() + i};
484  }
485  [[nodiscard]] difference_type
486  operator-(const_reverse_row_iterator const &rhs) const noexcept
487  {
488  return rhs.const_row_iterator::operator-(*this);
489  }
491 
496  [[nodiscard]] bool
497  operator==(const_reverse_row_iterator const &rhs) const noexcept
498  {
499  return iterator_type::operator==(rhs);
500  }
501  [[nodiscard]] bool
502  operator!=(const_reverse_row_iterator const &rhs) const noexcept
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
518  operator>(const_reverse_row_iterator const &rhs) const noexcept
519  {
520  return iterator_type::operator<(rhs);
521  }
522  [[nodiscard]] constexpr bool
523  operator>=(const_reverse_row_iterator const &rhs) const noexcept
524  {
525  return iterator_type::operator<=(rhs);
526  }
528 };
529 
530 
531 const_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 
546 inline const_row_iterator
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 
562 template<typename Tuple, std::size_t index>
563 inline void row::extract_value(Tuple &t) const
564 {
565  using field_type = strip_t<decltype(std::get<index>(t))>;
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 row_size_type
Number of fields in a row of database data.
Definition: types.hxx:34
std::remove_cv_t< std::remove_reference_t< TYPE > > strip_t
Remove any constness, volatile, and reference-ness from a type.
Definition: types.hxx:78
int row_difference_type
Difference between row sizes.
Definition: types.hxx:37
const_row_iterator operator+(const_row_iterator::difference_type o, const_row_iterator const &i) noexcept
Definition: row.hxx:540
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
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
field_size_type size_type
Definition: field.hxx:37
constexpr row_size_type col() const noexcept
Definition: field.hxx:274
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
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
std::tuple< TYPE... > as() const
Extract entire row's values into a tuple.
Definition: row.hxx:188
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
reference operator*() const noexcept
Definition: row.hxx:315
const_row_iterator(field const &F) noexcept
Definition: row.hxx:306
const_row_iterator & operator--() noexcept
Definition: row.hxx:332
constexpr bool operator>=(const_row_iterator const &i) const noexcept
Definition: row.hxx:380
const_row_iterator(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
const_row_iterator & operator=(const_row_iterator &&) noexcept=default
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
const_row_iterator & operator-=(difference_type i) noexcept
Definition: row.hxx:343
const_row_iterator() noexcept=default
const_row_iterator & operator=(const_row_iterator const &) noexcept=default
row_difference_type difference_type
Definition: row.hxx:297
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
const_row_iterator & operator+=(difference_type i) noexcept
Definition: row.hxx:338
const_row_iterator operator+(difference_type) const noexcept
Definition: row.hxx:532
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
const_reverse_row_iterator & operator--() noexcept
Definition: row.hxx:453
const_reverse_row_iterator & operator+=(difference_type i) noexcept
Definition: row.hxx:459
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) const noexcept
Definition: row.hxx:476
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
const_reverse_row_iterator & operator-=(difference_type i) noexcept
Definition: row.hxx:464
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:38