libpqxx  7.8.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-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_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:
53  using reference = field;
57 
58  row() noexcept = default;
59  row(row &&) noexcept = default;
60  row(row const &) noexcept = default;
61  row &operator=(row const &) noexcept = default;
62  row &operator=(row &&) noexcept = default;
63 
68  [[nodiscard]] PQXX_PURE bool operator==(row const &) const noexcept;
69  [[nodiscard]] bool operator!=(row const &rhs) const noexcept
70  {
71  return not operator==(rhs);
72  }
74 
75  [[nodiscard]] const_iterator begin() const noexcept;
76  [[nodiscard]] const_iterator cbegin() const noexcept;
77  [[nodiscard]] const_iterator end() const noexcept;
78  [[nodiscard]] const_iterator cend() const noexcept;
79 
84  [[nodiscard]] reference front() const noexcept;
85  [[nodiscard]] reference back() const noexcept;
86 
87  [[nodiscard]] const_reverse_row_iterator rbegin() const noexcept;
88  [[nodiscard]] const_reverse_row_iterator crbegin() const noexcept;
89  [[nodiscard]] const_reverse_row_iterator rend() const noexcept;
90  [[nodiscard]] const_reverse_row_iterator crend() const noexcept;
91 
92  [[nodiscard]] reference operator[](size_type) const noexcept;
96  [[nodiscard]] reference operator[](zview col_name) const;
97 
98  reference at(size_type) const;
102  reference at(zview col_name) const;
103 
104  [[nodiscard]] constexpr size_type size() const noexcept
105  {
106  return m_end - m_begin;
107  }
108 
109  [[deprecated("Swap iterators, not rows.")]] void swap(row &) noexcept;
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 
175  [[deprecated("Row slicing is going away. File a bug if you need it.")]] row
176  slice(size_type sbegin, size_type send) const;
177 
179  [[nodiscard, deprecated("Row slicing is going away.")]] PQXX_PURE bool
180  empty() const noexcept;
181 
183 
188  template<typename Tuple> void to(Tuple &t) const
189  {
190  check_size(std::tuple_size_v<Tuple>);
191  convert(t);
192  }
193 
195 
200  template<typename... TYPE> std::tuple<TYPE...> as() const
201  {
202  check_size(sizeof...(TYPE));
203  using seq = std::make_index_sequence<sizeof...(TYPE)>;
204  return get_tuple<std::tuple<TYPE...>>(seq{});
205  }
206 
207 protected:
208  friend class const_row_iterator;
209  friend class result;
210  row(result const &r, result_size_type index, size_type cols) noexcept;
211 
213  void check_size(size_type expected) const
214  {
215  if (size() != expected)
216  throw usage_error{internal::concat(
217  "Tried to extract ", expected, " field(s) from a row of ", size(),
218  ".")};
219  }
220 
222 
225  template<typename TUPLE> TUPLE as_tuple() const
226  {
227  using seq = std::make_index_sequence<std::tuple_size_v<TUPLE>>;
228  return get_tuple<TUPLE>(seq{});
229  }
230 
231  template<typename... T> friend class pqxx::internal::result_iter;
233  template<typename Tuple> void convert(Tuple &t) const
234  {
235  extract_fields(t, std::make_index_sequence<std::tuple_size_v<Tuple>>{});
236  }
237 
238  friend class field;
239 
242 
244 
248  result::size_type m_index = 0;
249 
250  // TODO: Remove m_begin and (if possible) m_end when we remove slice().
252  size_type m_begin = 0;
254  size_type m_end = 0;
255 
256 private:
257  template<typename Tuple, std::size_t... indexes>
258  void extract_fields(Tuple &t, std::index_sequence<indexes...>) const
259  {
260  (extract_value<Tuple, indexes>(t), ...);
261  }
262 
263  template<typename Tuple, std::size_t index>
264  void extract_value(Tuple &t) const;
265 
267  template<typename TUPLE, std::size_t... indexes>
268  auto get_tuple(std::index_sequence<indexes...>) const
269  {
270  return std::make_tuple(get_field<TUPLE, indexes>()...);
271  }
272 
274  template<typename TUPLE, std::size_t index> auto get_field() const
275  {
276  return (*this)[index].as<std::tuple_element_t<index, TUPLE>>();
277  }
278 };
279 
280 
282 class PQXX_LIBEXPORT const_row_iterator : public field
283 {
284 public:
285  using iterator_category = std::random_access_iterator_tag;
286  using value_type = field const;
287  using pointer = field const *;
290  using reference = field;
291 
292 #include "pqxx/internal/ignore-deprecated-pre.hxx"
293  const_row_iterator() noexcept = default;
294 #include "pqxx/internal/ignore-deprecated-post.hxx"
295  const_row_iterator(row const &t, row_size_type c) noexcept :
296  field{t.m_result, t.m_index, c}
297  {}
298  const_row_iterator(field const &F) noexcept : field{F} {}
299  const_row_iterator(const_row_iterator const &) noexcept = default;
300  const_row_iterator(const_row_iterator &&) noexcept = default;
301 
306  [[nodiscard]] constexpr pointer operator->() const noexcept
307  {
308  return this;
309  }
310  [[nodiscard]] reference operator*() const noexcept
311  {
312  return {*this};
313  }
315 
320  const_row_iterator &operator=(const_row_iterator const &) noexcept = default;
322 
323  const_row_iterator operator++(int) noexcept;
324  const_row_iterator &operator++() noexcept
325  {
326  ++m_col;
327  return *this;
328  }
329  const_row_iterator operator--(int) noexcept;
331  {
332  --m_col;
333  return *this;
334  }
335 
337  {
338  m_col = size_type(difference_type(m_col) + i);
339  return *this;
340  }
342  {
343  m_col = size_type(difference_type(m_col) - i);
344  return *this;
345  }
347 
352  [[nodiscard]] constexpr bool
353  operator==(const_row_iterator const &i) const noexcept
354  {
355  return col() == i.col();
356  }
357  [[nodiscard]] constexpr bool
358  operator!=(const_row_iterator const &i) const noexcept
359  {
360  return col() != i.col();
361  }
362  [[nodiscard]] constexpr bool
363  operator<(const_row_iterator const &i) const noexcept
364  {
365  return col() < i.col();
366  }
367  [[nodiscard]] constexpr bool
368  operator<=(const_row_iterator const &i) const noexcept
369  {
370  return col() <= i.col();
371  }
372  [[nodiscard]] constexpr bool
373  operator>(const_row_iterator const &i) const noexcept
374  {
375  return col() > i.col();
376  }
377  [[nodiscard]] constexpr bool
378  operator>=(const_row_iterator const &i) const noexcept
379  {
380  return col() >= i.col();
381  }
383 
388  [[nodiscard]] inline const_row_iterator
389  operator+(difference_type) const noexcept;
390 
391  friend const_row_iterator
392  operator+(difference_type, const_row_iterator const &) noexcept;
393 
394  [[nodiscard]] inline const_row_iterator
395  operator-(difference_type) const noexcept;
396  [[nodiscard]] inline difference_type
397  operator-(const_row_iterator const &) const noexcept;
399 };
400 
401 
403 class PQXX_LIBEXPORT const_reverse_row_iterator : private const_row_iterator
404 {
405 public:
413 
414  const_reverse_row_iterator() noexcept = default;
416  default;
418 
419  explicit const_reverse_row_iterator(super const &rhs) noexcept :
420  const_row_iterator{rhs}
421  {
422  super::operator--();
423  }
424 
425  [[nodiscard]] PQXX_PURE iterator_type base() const noexcept;
426 
431  using iterator_type::operator->;
432  using iterator_type::operator*;
434 
439  const_reverse_row_iterator &
440  operator=(const_reverse_row_iterator const &r) noexcept
441  {
442  iterator_type::operator=(r);
443  return *this;
444  }
446  {
447  iterator_type::operator--();
448  return *this;
449  }
450  const_reverse_row_iterator operator++(int) noexcept;
452  {
453  iterator_type::operator++();
454  return *this;
455  }
456  const_reverse_row_iterator operator--(int);
458  {
459  iterator_type::operator-=(i);
460  return *this;
461  }
463  {
464  iterator_type::operator+=(i);
465  return *this;
466  }
468 
473  [[nodiscard]] const_reverse_row_iterator
474  operator+(difference_type i) const noexcept
475  {
476  return const_reverse_row_iterator{base() - i};
477  }
478  [[nodiscard]] const_reverse_row_iterator
480  {
481  return const_reverse_row_iterator{base() + i};
482  }
483  [[nodiscard]] difference_type
484  operator-(const_reverse_row_iterator const &rhs) const noexcept
485  {
486  return rhs.const_row_iterator::operator-(*this);
487  }
489 
494  [[nodiscard]] bool
495  operator==(const_reverse_row_iterator const &rhs) const noexcept
496  {
497  return iterator_type::operator==(rhs);
498  }
499  [[nodiscard]] bool
500  operator!=(const_reverse_row_iterator const &rhs) const noexcept
501  {
502  return !operator==(rhs);
503  }
504 
505  [[nodiscard]] constexpr bool
506  operator<(const_reverse_row_iterator const &rhs) const noexcept
507  {
508  return iterator_type::operator>(rhs);
509  }
510  [[nodiscard]] constexpr bool
511  operator<=(const_reverse_row_iterator const &rhs) const noexcept
512  {
513  return iterator_type::operator>=(rhs);
514  }
515  [[nodiscard]] constexpr bool
516  operator>(const_reverse_row_iterator const &rhs) const noexcept
517  {
518  return iterator_type::operator<(rhs);
519  }
520  [[nodiscard]] constexpr bool
521  operator>=(const_reverse_row_iterator const &rhs) const noexcept
522  {
523  return iterator_type::operator<=(rhs);
524  }
526 };
527 
528 
529 const_row_iterator
531 {
532  // TODO:: More direct route to home().columns()?
533  return {
534  row{home(), idx(), home().columns()},
535  size_type(difference_type(col()) + o)};
536 }
537 
540 {
541  return i + o;
542 }
543 
544 inline const_row_iterator
546 {
547  // TODO:: More direct route to home().columns()?
548  return {
549  row{home(), idx(), home().columns()},
550  size_type(difference_type(col()) - o)};
551 }
552 
555 {
556  return difference_type(num() - i.num());
557 }
558 
559 
560 template<typename Tuple, std::size_t index>
561 inline void row::extract_value(Tuple &t) const
562 {
563  using field_type = strip_t<decltype(std::get<index>(t))>;
564  field const f{m_result, m_index, index};
565  std::get<index>(t) = from_string<field_type>(f);
566 }
567 } // namespace pqxx
568 #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:91
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:538
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:238
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:263
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:49
oid column_type(zview col_name) const
Return a column's type.
Definition: row.hxx:128
row_difference_type difference_type
Definition: row.hxx:50
result m_result
Result set of which this is one row.
Definition: row.hxx:241
result::size_type m_index
Row number.
Definition: row.hxx:248
std::tuple< TYPE... > as() const
Extract entire row's values into a tuple.
Definition: row.hxx:200
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:225
void check_size(size_type expected) const
Throw usage_error if row size is not expected.
Definition: row.hxx:213
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:233
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:283
const_row_iterator operator-(difference_type) const noexcept
Definition: row.hxx:545
reference operator*() const noexcept
Definition: row.hxx:310
const_row_iterator(field const &F) noexcept
Definition: row.hxx:298
const_row_iterator & operator--() noexcept
Definition: row.hxx:330
constexpr bool operator>=(const_row_iterator const &i) const noexcept
Definition: row.hxx:378
const_row_iterator(const_row_iterator const &) noexcept=default
std::random_access_iterator_tag iterator_category
Definition: row.hxx:285
constexpr bool operator==(const_row_iterator const &i) const noexcept
Definition: row.hxx:353
const_row_iterator & operator=(const_row_iterator &&) noexcept=default
field const * pointer
Definition: row.hxx:287
field const value_type
Definition: row.hxx:286
constexpr bool operator!=(const_row_iterator const &i) const noexcept
Definition: row.hxx:358
const_row_iterator(const_row_iterator &&) noexcept=default
const_row_iterator & operator-=(difference_type i) noexcept
Definition: row.hxx:341
const_row_iterator() noexcept=default
const_row_iterator & operator=(const_row_iterator const &) noexcept=default
row_difference_type difference_type
Definition: row.hxx:289
const_row_iterator(row const &t, row_size_type c) noexcept
Definition: row.hxx:295
constexpr bool operator>(const_row_iterator const &i) const noexcept
Definition: row.hxx:373
const_row_iterator & operator+=(difference_type i) noexcept
Definition: row.hxx:336
const_row_iterator operator+(difference_type) const noexcept
Definition: row.hxx:530
Reverse iterator for a row. Use as row::const_reverse_iterator.
Definition: row.hxx:404
const_reverse_row_iterator operator++() noexcept
Definition: row.hxx:445
bool operator!=(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:500
constexpr bool operator>=(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:521
const_reverse_row_iterator & operator--() noexcept
Definition: row.hxx:451
const_reverse_row_iterator & operator+=(difference_type i) noexcept
Definition: row.hxx:457
constexpr bool operator>(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:516
difference_type operator-(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:484
const_reverse_row_iterator operator+(difference_type i) const noexcept
Definition: row.hxx:474
bool operator==(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:495
const_reverse_row_iterator() noexcept=default
const_reverse_row_iterator operator-(difference_type i) noexcept
Definition: row.hxx:479
const_reverse_row_iterator & operator-=(difference_type i) noexcept
Definition: row.hxx:462
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:38