MySQL Connector/C++ 9.1.0
MySQL connector library for C and C++ applications
result.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2015, 2024, Oracle and/or its affiliates.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License, version 2.0, as
6 * published by the Free Software Foundation.
7 *
8 * This program is designed to work with certain software (including
9 * but not limited to OpenSSL) that is licensed under separate terms, as
10 * designated in a particular file or component or in included license
11 * documentation. The authors of MySQL hereby grant you an additional
12 * permission to link the program and your derivative works with the
13 * separately licensed software that they have either included with
14 * the program or referenced in the documentation.
15 *
16 * Without limiting anything contained in the foregoing, this file,
17 * which is part of Connector/C++, is also subject to the
18 * Universal FOSS Exception, version 1.0, a copy of which can be found at
19 * https://oss.oracle.com/licenses/universal-foss-exception.
20 *
21 * This program is distributed in the hope that it will be useful, but
22 * WITHOUT ANY WARRANTY; without even the implied warranty of
23 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
24 * See the GNU General Public License, version 2.0, for more details.
25 *
26 * You should have received a copy of the GNU General Public License
27 * along with this program; if not, write to the Free Software Foundation, Inc.,
28 * 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
29 */
30
31#ifndef MYSQLX_RESULT_H
32#define MYSQLX_RESULT_H
33
39#include "common.h"
40#include "document.h"
41#include "row.h"
42#include "collations.h"
43#include "detail/result.h"
44
45
46namespace mysqlx {
47MYSQLX_ABI_BEGIN(2,0)
48
49using std::ostream;
50
51class Session;
52class Schema;
53class Collection;
54class Result;
55class Row;
56class RowResult;
57class SqlResult;
58class DbDoc;
59class DocResult;
60
61template <class Res, class Op> class Executable;
62
63
64namespace internal {
65
66/*
67 A wrapper which adds methods common for all result classes.
68*/
69
70template <class Base>
71class Result_common
72 : protected Base
73{
74 using WarningList = internal::Result_detail::WarningList;
75
76public:
77
79
80 unsigned getWarningsCount() const
81 {
82 try {
83 return Base::get_warning_count();
84 }
85 CATCH_AND_WRAP
86 }
87
89
90 WarningList getWarnings()
91 {
92 try {
93 return Base::get_warnings();
94 }
95 CATCH_AND_WRAP
96 }
97
99 // TODO: Change arg type to size_t?
100
101 Warning getWarning(unsigned pos)
102 {
103 try {
104 return Base::get_warning(pos);
105 }
106 CATCH_AND_WRAP
107 }
108
109 // TODO: expose this in the API?
110 //using WarningsIterator = Result_detail::iterator;
111
116 uint64_t getAffectedItemsCount() const
117 {
118 try {
119 return Result_detail::get_affected_rows();
120 } CATCH_AND_WRAP
121 }
122
123protected:
124
125 // Wrap base ctors/assginment with catch handlers
126
127 Result_common()
128 try
129 : Base()
130 {}
131 CATCH_AND_WRAP
132
133 Result_common(Result_common &&other)
134 try
135 : Base(std::move(other))
136 {}
137 CATCH_AND_WRAP
138
139 Result_common& operator=(Result_common &&other)
140 try
141 {
142 Base::operator=(std::move(other));
143 return *this;
144 }
145 CATCH_AND_WRAP
146
147 Result_common(common::Result_init &init)
148 try
149 : Base(init)
150 {}
151 CATCH_AND_WRAP
152
153};
154
155} // internal namespace
156
157
183 : public internal::Result_common<internal::Result_detail>
184{
185
186public:
187
188 Result() = default;
189
195 uint64_t getAutoIncrementValue() const
196 {
197 try {
198 return Result_detail::get_auto_increment();
199 } CATCH_AND_WRAP
200 }
201
202
208 DocIdList getGeneratedIds() const
209 {
210 try {
211 return Result_detail::get_generated_ids();
212 } CATCH_AND_WRAP
213 }
214
215private:
216
217
218 Result(common::Result_init &init)
219 : Result_common(init)
220 {}
221
222 template <class Res, class Op>
223 friend class Executable;
224 friend Collection;
225};
226
227
228// Row based results
229// -----------------
230
240enum class Type : unsigned short
241{
242#undef TYPE_ENUM
243#define TYPE_ENUM(X,N) X=N,
244
245 RESULT_TYPE_LIST(TYPE_ENUM)
246};
247
248/*
249 Note: Normally we would put these docs in the RESULT_TYPE_LIST macro
250 but it would pollute documentation of methods like typeName() below
251 that also use this macro.
252*/
253
292
293
300inline
301const char* typeName(Type t)
302{
303#define TYPE_NAME(T,X) case Type::T: return #T;
304
305 switch (t)
306 {
307 RESULT_TYPE_LIST(TYPE_NAME)
308 default:
309 THROW("Unknown type");
310 }
311}
312
313inline
314std::ostream& operator<<(std::ostream &out, Type t)
315{
316 return out << typeName(t);
317}
318
319
326class Column
327 : public virtual common::Printable
328 , private internal::Column_detail
329{
330public:
331
332 string getSchemaName() const
333 {
334 try {
335 return Column_detail::get_schema_name();
336 }
337 CATCH_AND_WRAP
339
340 string getTableName() const
341 {
342 try {
343 return Column_detail::get_table_name();
344 }
345 CATCH_AND_WRAP
347
348 string getTableLabel() const
349 {
350 try {
351 return Column_detail::get_table_label();
352 }
353 CATCH_AND_WRAP
355
356 string getColumnName() const
357 {
358 try {
359 return Column_detail::get_name();
360 }
361 CATCH_AND_WRAP
363
364 string getColumnLabel() const
365 {
366 try {
367 return Column_detail::get_label();
368 }
369 CATCH_AND_WRAP
371
372 Type getType() const
373 {
374 try {
375 return Type(Column_detail::get_type());
376 }
377 CATCH_AND_WRAP
378 }
379
392 unsigned long getLength() const
393 {
394 try {
395 return Column_detail::get_length();
396 }
397 CATCH_AND_WRAP
399
400 unsigned short getFractionalDigits() const
401 {
402 try {
403 return Column_detail::get_decimals();
404 }
405 CATCH_AND_WRAP
407
408 bool isNumberSigned() const
409 {
410 try {
411 return Column_detail::is_signed();
412 }
413 CATCH_AND_WRAP
415
416 CharacterSet getCharacterSet() const
417 {
418 try {
419 return Column_detail::get_charset();
420 }
421 CATCH_AND_WRAP
422 }
425 std::string getCharacterSetName() const
426 {
427 try {
429 }
430 CATCH_AND_WRAP
432
433 const CollationInfo& getCollation() const
434 {
435 try {
436 return Column_detail::get_collation();
437 }
438 CATCH_AND_WRAP
439 }
442 std::string getCollationName() const
443 {
444 try {
445 return getCollation().getName();
446 }
447 CATCH_AND_WRAP
448 }
451 bool isPadded() const
452 {
453 try {
454 return Column_detail::is_padded();
455 }
456 CATCH_AND_WRAP
457 }
458
459protected:
460
461
462 using Column_detail::Impl;
463
464 Column(const Impl *impl)
465 try
466 : Column_detail(impl)
467 {}
468 CATCH_AND_WRAP
469
470 Column() = default;
471 Column(const Column&) = default;
472 Column(Column&&) = default;
473
474 Column& operator=(const Column&) = default;
475
476 void print(std::ostream &out) const
477 {
478 // TODO: not sure if this code will be called by operator<<.
479 try {
480 Column_detail::print(out);
481 }
482 CATCH_AND_WRAP
483 }
484
485public:
486
487 friend RowResult;
488 struct INTERNAL Access;
489 friend Access;
490};
491
492
493/*
494 Extern declarations for Columns_detail<Column> template specialization
495 elements that are defined in result.cc.
496
497 Note: "extern template" works with MSVC but not with GCC.
498*/
499
500namespace internal {
501
502template<> PUBLIC_API
503void Columns_detail<Column>::init(const Result_detail::Impl&);
504
505} // internal
506
507
508extern template PUBLIC_API
509void internal::Columns_detail<Column>::init(
510 const internal::Result_detail::Impl &impl
511);
512
513
514class Columns
515 : private internal::Columns_detail<Column>
516{
517public:
518
519 using Columns_detail::operator[];
520
521 using Columns_detail::iterator;
522
523 using Columns_detail::begin;
524 using Columns_detail::end;
525
526private:
527
528 using Columns_detail::init;
529
530 // note: Required by Row_result_detail
531
532 Columns() = default;
533 Columns(Columns&&) = default;
534 Columns& operator=(Columns&&) = default;
535
537 friend internal::Row_result_detail<Columns>;
539};
540
541
542/*
543 Extern declarations for Row_result_detail<Columns> template specialization
544 elements that are defined in result.cc.
545*/
546
547namespace internal {
548
549template<> PUBLIC_API
550bool Row_result_detail<Columns>::iterator_next();
551
552template<> PUBLIC_API
553col_count_t Row_result_detail<Columns>::col_count() const;
554
555template<> PUBLIC_API
556Row_result_detail<Columns>::Row_result_detail(
557 common::Result_init &init
558);
559
560template<> PUBLIC_API
561auto Row_result_detail<Columns>::get_column(col_count_t pos) const
562-> const Column&;
563
564template<> PUBLIC_API
565auto internal::Row_result_detail<Columns>::get_columns() const
566-> const Columns&;
567
568template<> PUBLIC_API
569row_count_t internal::Row_result_detail<Columns>::row_count();
570
571} // internal
572
573
585class RowResult
586 : public internal::Result_common<internal::Row_result_detail<Columns>>
587{
588public:
589
590 using Columns = mysqlx::Columns;
591
592 RowResult() = default;
593
594
596
597 col_count_t getColumnCount() const
598 {
599 try {
600 return Row_result_detail::col_count();
601 }
602 CATCH_AND_WRAP
603 }
604
606
607 const Column& getColumn(col_count_t pos) const
608 {
609 try {
610 return Row_result_detail::get_column(pos);
611 }
612 CATCH_AND_WRAP
613 }
614
621 const Columns& getColumns() const
622 {
623 try {
624 return Row_result_detail::get_columns();
625 }
626 CATCH_AND_WRAP
627 }
628
635 Row fetchOne()
636 {
637 try {
638 return Row_result_detail::get_row();
639 }
640 CATCH_AND_WRAP
641 }
642
651 RowList fetchAll()
652 {
653 try {
654 return Row_result_detail::get_rows();
655 }
656 CATCH_AND_WRAP
657 }
658
666 row_count_t count()
667 {
668 try {
669 return Row_result_detail::row_count();
670 }
671 CATCH_AND_WRAP
672 }
673
674 /*
675 Iterate over rows (range-for support).
676
677 Rows that have been fetched using iterator are not available when
678 calling fetchOne() or fetchAll()
679 */
680
681 iterator begin()
682 {
683 try {
684 return Row_result_detail::begin();
685 }
686 CATCH_AND_WRAP
687 }
688
689 iterator end() const
690 {
691 try {
692 return Row_result_detail::end();
693 }
694 CATCH_AND_WRAP
695 }
696
697
698private:
699
700 RowResult(common::Result_init &init)
701 : Result_common(init)
702 {}
703
704public:
705
706 template <class Res, class Op> friend class Executable;
707 friend SqlResult;
708 friend DocResult;
709};
710
711
730class SqlResult
731 : public RowResult
732{
733public:
734
735 SqlResult() = default;
736
744 bool hasData() const
745 {
746 try {
747 return Result_detail::has_data();
748 }
749 CATCH_AND_WRAP
750 }
751
752
762 bool nextResult()
763 {
764 try {
765 return Row_result_detail::next_result();
766 }
767 CATCH_AND_WRAP
768 }
769
770
776 uint64_t getAutoIncrementValue()
777 {
778 try {
779 return Result_detail::get_auto_increment();
780 }
781 CATCH_AND_WRAP
782 }
783
784private:
785
786 SqlResult(common::Result_init &init)
787 : RowResult(init)
788 {}
789
790 template <class Res, class Op>
791 friend class Executable;
792};
793
794
795// Document based results
796// ----------------------
797
798
815class DocResult
816 : public internal::Result_common<internal::Doc_result_detail>
817{
818
819public:
820
821 DocResult() = default;
822
829 DbDoc fetchOne()
830 {
831 try {
832 return Doc_result_detail::get_doc();
833 }
834 CATCH_AND_WRAP
835 }
836
845 DocList fetchAll()
846 {
847 try {
848 return Doc_result_detail::get_docs();
849 }
850 CATCH_AND_WRAP
851 }
852
860 uint64_t count()
861 {
862 try {
863 return Doc_result_detail::count();
864 }
865 CATCH_AND_WRAP
866 }
867
868 /*
869 Iterate over documents (range-for support).
870
871 Documents that have been fetched using iterator are not available when
872 calling fetchOne() or fetchAll()
873 */
874
875 using iterator = Doc_result_detail::iterator;
876
877 iterator begin()
878 {
879 try {
880 return Doc_result_detail::begin();
881 }
882 CATCH_AND_WRAP
883 }
884
885 iterator end() const
886 {
887 try {
888 return Doc_result_detail::end();
889 }
890 CATCH_AND_WRAP
891 }
892
893
894private:
895
896 DocResult(common::Result_init &init)
897 : Result_common(init)
898 {}
899
900 friend DbDoc;
901 template <class Res, class Op>
902 friend class Executable;
903};
904
905MYSQLX_ABI_END(2,0)
906} // mysqlx
907
908#endif
Represents a collection of documents in a schema.
Definition: xdevapi.h:912
Provides meta-data for a single result column.
Definition: result.h:327
const CollationInfo & getCollation() const
< TODO
Definition: result.h:431
std::string getCharacterSetName() const
TODO.
Definition: result.h:423
string getSchemaName() const
< TODO
Definition: result.h:330
bool isPadded() const
TODO.
Definition: result.h:449
std::string getCollationName() const
TODO.
Definition: result.h:440
CharacterSet getCharacterSet() const
< TODO
Definition: result.h:414
Represents an operation that can be executed.
Definition: executable.h:68
Represents a result of an operation that does not return data.
Definition: result.h:184
DocIdList getGeneratedIds() const
Return a list of identifiers of multiple documents added to a collection, generated by the server.
Definition: result.h:208
uint64_t getAutoIncrementValue() const
Get the auto-increment value if one was generated by a table insert statement.
Definition: result.h:195
Details for public API result classes.
Declaration of DbDoc and related classes.
const char * characterSetName(CharacterSet id)
Returns name of a character set given by its id.
Definition: collations.h:71
const char * typeName(Type t)
Return name of a given type.
Definition: result.h:300
Type
Types that can be reported in result meta-data.
Definition: result.h:241
TODO.
Structure that provides information about character set collation.
Definition: collations.h:94
const char * getName() const
String name of a collation, such as "latin1_generic_ci".
Definition: collations.h:101