libpqxx  7.7.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-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_ROW
14 #define PQXX_H_ROW
15 
16 #include "pqxx/except.hxx"
17 #include "pqxx/field.hxx"
18 #include "pqxx/result.hxx"
19 
20 #include "pqxx/internal/concat.hxx"
21 
22 namespace pqxx::internal
23 {
24 template<typename... T> class result_iter;
25 } // namespace pqxx::internal
26 
27 
28 namespace pqxx
29 {
31 
42 class PQXX_LIBEXPORT row
43 {
44 public:
49  using reference = field;
53 
54  row() = default;
55  row(row &&) = default;
56  row(row const &) = default;
57  row &operator=(row const &) = default;
58  row &operator=(row &&) = default;
59 
64  [[nodiscard]] PQXX_PURE bool operator==(row const &) const noexcept;
65  [[nodiscard]] bool operator!=(row const &rhs) const noexcept
66  {
67  return not operator==(rhs);
68  }
70 
71  [[nodiscard]] const_iterator begin() const noexcept;
72  [[nodiscard]] const_iterator cbegin() const noexcept;
73  [[nodiscard]] const_iterator end() const noexcept;
74  [[nodiscard]] const_iterator cend() const noexcept;
75 
80  [[nodiscard]] reference front() const noexcept;
81  [[nodiscard]] reference back() const noexcept;
82 
83  [[nodiscard]] const_reverse_row_iterator rbegin() const;
84  [[nodiscard]] const_reverse_row_iterator crbegin() const;
85  [[nodiscard]] const_reverse_row_iterator rend() const;
86  [[nodiscard]] const_reverse_row_iterator crend() const;
87 
88  [[nodiscard]] reference operator[](size_type) const noexcept;
92  [[nodiscard]] reference operator[](zview col_name) const;
93 
94  reference at(size_type) const;
98  reference at(zview col_name) const;
99 
100  [[nodiscard]] size_type size() const noexcept { return m_end - m_begin; }
101 
102  [[deprecated("Swap iterators, not rows.")]] void swap(row &) noexcept;
103 
105  [[nodiscard]] result::size_type rownumber() const noexcept
106  {
107  return m_index;
108  }
109 
114  [[nodiscard]] size_type column_number(zview col_name) const;
116 
118  [[nodiscard]] oid column_type(size_type) const;
119 
121  [[nodiscard]] oid column_type(zview col_name) const
122  {
123  return column_type(column_number(col_name));
124  }
125 
127  [[nodiscard]] oid column_table(size_type col_num) const;
128 
130  [[nodiscard]] oid column_table(zview col_name) const
131  {
132  return column_table(column_number(col_name));
133  }
134 
136 
143  [[nodiscard]] size_type table_column(size_type) const;
144 
146  [[nodiscard]] size_type table_column(zview col_name) const
147  {
148  return table_column(column_number(col_name));
149  }
151 
152  [[nodiscard]] result::size_type num() const { return rownumber(); }
153 
165  [[deprecated("Row slicing is going away. File a bug if you need it.")]] row
166  slice(size_type sbegin, size_type send) const;
167 
169  [[nodiscard, deprecated("Row slicing is going away.")]] PQXX_PURE bool
170  empty() const noexcept;
171 
173 
175  template<typename Tuple> void to(Tuple &t) const
176  {
177  check_size(std::tuple_size_v<Tuple>);
178  convert(t);
179  }
180 
181  template<typename... TYPE> std::tuple<TYPE...> as() const
182  {
183  check_size(sizeof...(TYPE));
184  using seq = std::make_index_sequence<sizeof...(TYPE)>;
185  return get_tuple<std::tuple<TYPE...>>(seq{});
186  }
187 
188 protected:
189  friend class const_row_iterator;
190  friend class result;
191  row(result const &r, result_size_type index, size_type cols) noexcept;
192 
194  void check_size(size_type expected) const
195  {
196  if (size() != expected)
197  throw usage_error{internal::concat(
198  "Tried to extract ", expected, " field(s) from a row of ", size(),
199  ".")};
200  }
201 
202  template<typename... T> friend class pqxx::internal::result_iter;
204  template<typename Tuple> void convert(Tuple &t) const
205  {
206  // C++20: constinit.
207  constexpr auto tup_size{std::tuple_size_v<Tuple>};
208  extract_fields(t, std::make_index_sequence<tup_size>{});
209  }
210 
211  friend class field;
212 
215 
217 
221  result::size_type m_index = 0;
222 
223  // TODO: Remove m_begin and (if possible) m_end when we remove slice().
225  size_type m_begin = 0;
227  size_type m_end = 0;
228 
229 private:
230  template<typename Tuple, std::size_t... indexes>
231  void extract_fields(Tuple &t, std::index_sequence<indexes...>) const
232  {
233  (extract_value<Tuple, indexes>(t), ...);
234  }
235 
236  template<typename Tuple, std::size_t index>
237  void extract_value(Tuple &t) const;
238 
240  template<typename TUPLE, std::size_t... indexes>
241  auto get_tuple(std::index_sequence<indexes...>) const
242  {
243  return std::make_tuple(get_field<TUPLE, indexes>()...);
244  }
245 
247  template<typename TUPLE, std::size_t index> auto get_field() const
248  {
249  return (*this)[index].as<std::tuple_element_t<index, TUPLE>>();
250  }
251 };
252 
253 
255 class PQXX_LIBEXPORT const_row_iterator : public field
256 {
257 public:
258  using iterator_category = std::random_access_iterator_tag;
259  using value_type = field const;
260  using pointer = field const *;
263  using reference = field;
264 
265 #include "pqxx/internal/ignore-deprecated-pre.hxx"
266  const_row_iterator() = default;
267 #include "pqxx/internal/ignore-deprecated-post.hxx"
268  const_row_iterator(row const &t, row_size_type c) noexcept :
269  field{t.m_result, t.m_index, c}
270  {}
271  const_row_iterator(field const &F) noexcept : field{F} {}
272  const_row_iterator(const_row_iterator const &) = default;
273  const_row_iterator(const_row_iterator &&) = default;
274 
279  [[nodiscard]] pointer operator->() const { return this; }
280  [[nodiscard]] reference operator*() const { return {*this}; }
282 
287  const_row_iterator &operator=(const_row_iterator const &) = default;
288  const_row_iterator &operator=(const_row_iterator &&) = default;
289 
290  const_row_iterator operator++(int);
292  {
293  ++m_col;
294  return *this;
295  }
296  const_row_iterator operator--(int);
298  {
299  --m_col;
300  return *this;
301  }
302 
304  {
305  m_col = size_type(difference_type(m_col) + i);
306  return *this;
307  }
309  {
310  m_col = size_type(difference_type(m_col) - i);
311  return *this;
312  }
314 
319  [[nodiscard]] bool operator==(const_row_iterator const &i) const
320  {
321  return col() == i.col();
322  }
323  [[nodiscard]] bool operator!=(const_row_iterator const &i) const
324  {
325  return col() != i.col();
326  }
327  [[nodiscard]] bool operator<(const_row_iterator const &i) const
328  {
329  return col() < i.col();
330  }
331  [[nodiscard]] bool operator<=(const_row_iterator const &i) const
332  {
333  return col() <= i.col();
334  }
335  [[nodiscard]] bool operator>(const_row_iterator const &i) const
336  {
337  return col() > i.col();
338  }
339  [[nodiscard]] bool operator>=(const_row_iterator const &i) const
340  {
341  return col() >= i.col();
342  }
344 
349  [[nodiscard]] inline const_row_iterator operator+(difference_type) const;
350 
351  friend const_row_iterator
352  operator+(difference_type, const_row_iterator const &);
353 
354  [[nodiscard]] inline const_row_iterator operator-(difference_type) const;
355  [[nodiscard]] inline difference_type
356  operator-(const_row_iterator const &) const;
358 };
359 
360 
362 class PQXX_LIBEXPORT const_reverse_row_iterator : private const_row_iterator
363 {
364 public:
372 
373  const_reverse_row_iterator() = default;
376 
377  explicit const_reverse_row_iterator(super const &rhs) noexcept :
378  const_row_iterator{rhs}
379  {
380  super::operator--();
381  }
382 
383  [[nodiscard]] PQXX_PURE iterator_type base() const noexcept;
384 
389  using iterator_type::operator->;
390  using iterator_type::operator*;
392 
398  {
399  iterator_type::operator=(r);
400  return *this;
401  }
403  {
404  iterator_type::operator--();
405  return *this;
406  }
407  const_reverse_row_iterator operator++(int);
409  {
410  iterator_type::operator++();
411  return *this;
412  }
413  const_reverse_row_iterator operator--(int);
415  {
416  iterator_type::operator-=(i);
417  return *this;
418  }
420  {
421  iterator_type::operator+=(i);
422  return *this;
423  }
425 
431  {
432  return const_reverse_row_iterator{base() - i};
433  }
435  {
436  return const_reverse_row_iterator{base() + i};
437  }
438  [[nodiscard]] difference_type
440  {
441  return rhs.const_row_iterator::operator-(*this);
442  }
444 
449  [[nodiscard]] bool
450  operator==(const_reverse_row_iterator const &rhs) const noexcept
451  {
452  return iterator_type::operator==(rhs);
453  }
454  [[nodiscard]] bool
455  operator!=(const_reverse_row_iterator const &rhs) const noexcept
456  {
457  return !operator==(rhs);
458  }
459 
460  [[nodiscard]] bool operator<(const_reverse_row_iterator const &rhs) const
461  {
462  return iterator_type::operator>(rhs);
463  }
464  [[nodiscard]] bool operator<=(const_reverse_row_iterator const &rhs) const
465  {
466  return iterator_type::operator>=(rhs);
467  }
468  [[nodiscard]] bool operator>(const_reverse_row_iterator const &rhs) const
469  {
470  return iterator_type::operator<(rhs);
471  }
472  [[nodiscard]] bool operator>=(const_reverse_row_iterator const &rhs) const
473  {
474  return iterator_type::operator<=(rhs);
475  }
477 };
478 
479 
481 {
482  // TODO:: More direct route to home().columns()?
483  return {
484  row{home(), idx(), home().columns()},
485  size_type(difference_type(col()) + o)};
486 }
487 
488 inline const_row_iterator
490 {
491  return i + o;
492 }
493 
494 inline const_row_iterator
496 {
497  // TODO:: More direct route to home().columns()?
498  return {
499  row{home(), idx(), home().columns()},
500  size_type(difference_type(col()) - o)};
501 }
502 
505 {
506  return difference_type(num() - i.num());
507 }
508 
509 
510 template<typename Tuple, std::size_t index>
511 inline void row::extract_value(Tuple &t) const
512 {
513  using field_type = strip_t<decltype(std::get<index>(t))>;
514  field const f{m_result, m_index, index};
515  std::get<index>(t) = from_string<field_type>(f);
516 }
517 } // namespace pqxx
518 #endif
const_row_iterator(field const &F) noexcept
Definition: row.hxx:271
void check_size(size_type expected) const
Throw usage_error if row size is not expected.
Definition: row.hxx:194
bool operator==(const_row_iterator const &i) const
Definition: row.hxx:319
const_row_iterator & operator--()
Definition: row.hxx:297
const_row_iterator & operator+=(difference_type i)
Definition: row.hxx:303
row_size_type col() const noexcept
Definition: field.hxx:255
row_size_type size_type
Definition: row.hxx:45
Error in usage of libpqxx library, similar to std::logic_error.
Definition: except.hxx:161
result::size_type m_index
Row number.
Definition: row.hxx:221
bool operator>(const_row_iterator const &i) const
Definition: row.hxx:335
std::random_access_iterator_tag iterator_category
Definition: row.hxx:258
Reference to one row in a result.
Definition: row.hxx:42
result::size_type num() const
Definition: row.hxx:152
const_reverse_row_iterator & operator-=(difference_type i)
Definition: row.hxx:419
field const value_type
Definition: row.hxx:259
bool operator>=(const_reverse_row_iterator const &rhs) const
Definition: row.hxx:472
Marker-type wrapper: zero-terminated std::string_view.
Definition: zview.hxx:37
Reverse iterator for a row. Use as row::const_reverse_iterator.
Definition: row.hxx:362
Reference to a field in a result set.
Definition: field.hxx:30
bool operator>=(const_row_iterator const &i) const
Definition: row.hxx:339
Definition: row.hxx:24
Result set containing data returned by a query or command.
Definition: result.hxx:67
row_size_type size_type
Definition: row.hxx:261
result m_result
Result set of which this is one row.
Definition: row.hxx:214
PQXX_PURE row_size_type num() const
Return row number. The first row is row 0, the second is row 1, etc.
Definition: field.hxx:94
result_size_type size_type
Definition: result.hxx:70
bool operator>(const_reverse_row_iterator const &rhs) const
Definition: row.hxx:468
Iterator for fields in a row. Use as row::const_iterator.
Definition: row.hxx:255
oid column_type(zview col_name) const
Return a column&#39;s type.
Definition: row.hxx:121
result::size_type rownumber() const noexcept
Row number, assuming this is a real row and not end()/rend().
Definition: row.hxx:105
row_difference_type difference_type
Definition: row.hxx:46
field_size_type size_type
Definition: field.hxx:33
int result_size_type
Number of rows in a result set.
Definition: types.hxx:24
bool operator==(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:450
const_reverse_row_iterator operator-(difference_type i)
Definition: row.hxx:434
int row_difference_type
Difference between row sizes.
Definition: types.hxx:33
const_reverse_row_iterator operator++()
Definition: row.hxx:402
result const & home() const noexcept
Definition: field.hxx:253
const_row_iterator operator-(difference_type) const
Definition: row.hxx:495
const_reverse_row_iterator & operator--()
Definition: row.hxx:408
The home of all libpqxx classes, functions, templates, etc.
Definition: array.hxx:22
PQXX_PURE row_size_type columns() const noexcept
Number of columns in result.
Definition: result.cxx:477
bool operator<(const_reverse_row_iterator const &rhs) const
Definition: row.hxx:460
difference_type operator-(const_reverse_row_iterator const &rhs) const
Definition: row.hxx:439
field const * pointer
Definition: row.hxx:260
bool operator<=(const_reverse_row_iterator const &rhs) const
Definition: row.hxx:464
std::remove_cv_t< std::remove_reference_t< TYPE > > strip_t
Remove any constness, volatile, and reference-ness from a type.
Definition: types.hxx:87
const_row_iterator(row const &t, row_size_type c) noexcept
End a code block started by "ignore-deprecated-pre.hxx".
Definition: row.hxx:268
const_row_iterator & operator++()
Definition: row.hxx:291
row_difference_type difference_type
Definition: row.hxx:262
int row_size_type
Number of fields in a row of database data.
Definition: types.hxx:30
const_row_iterator operator+(const_row_iterator::difference_type o, const_row_iterator const &i)
Definition: row.hxx:489
bool operator!=(row const &rhs) const noexcept
Definition: row.hxx:65
void convert(Tuple &t) const
Convert entire row to tuple fields, without checking row size.
Definition: row.hxx:204
Internal items for libpqxx&#39; own use. Do not use these yourself.
Definition: composite.hxx:79
const_reverse_row_iterator(super const &rhs) noexcept
Definition: row.hxx:377
bool operator!=(const_reverse_row_iterator const &rhs) const noexcept
Definition: row.hxx:455
const_reverse_row_iterator & operator+=(difference_type i)
Definition: row.hxx:414
result::size_type idx() const noexcept
Definition: field.hxx:254
oid column_table(zview col_name) const
What table did this column come from?
Definition: row.hxx:130
std::tuple< TYPE... > as() const
Definition: row.hxx:181
reference operator*() const
Definition: row.hxx:280
size_type table_column(zview col_name) const
What column number in its table did this result column come from?
Definition: row.hxx:146
const_row_iterator operator+(difference_type) const
Definition: row.hxx:480
bool operator!=(const_row_iterator const &i) const
Definition: row.hxx:323
bool operator<=(const_row_iterator const &i) const
Definition: row.hxx:331
bool operator<(const_row_iterator const &i) const
Definition: row.hxx:327
const_reverse_row_iterator operator+(difference_type i) const
Definition: row.hxx:430
const_row_iterator & operator-=(difference_type i)
Definition: row.hxx:308
pointer operator->() const
Definition: row.hxx:279