Branch data Line data Source code
1 : : /******************************************************************************
2 : : ------------- Copyright (c) 2009-2023 H a r a l d A c h i t z ---------------
3 : : ---------- < h a r a l d dot a c h i t z at g m a i l dot c o m > ------------
4 : : ---- This Source Code Form is subject to the terms of the Mozilla Public -----
5 : : ---- License, v. 2.0. If a copy of the MPL was not distributed with this -----
6 : : ---------- file, You can obtain one at http://mozilla.org/MPL/2.0/. ----------
7 : : ******************************************************************************/
8 : :
9 : : #ifndef SL3_COLUMNS_HPP
10 : : #define SL3_COLUMNS_HPP
11 : :
12 : : #include <sl3/config.hpp>
13 : : #include <sl3/dbvalues.hpp>
14 : :
15 : : struct sqlite3_stmt;
16 : :
17 : : namespace sl3
18 : : {
19 : :
20 : : // TODO add to docu
21 : : // index access always checked, since docu says
22 : : // 'if the column index is out of range, the result is undefined'
23 : : // but if you fell lke preoptimization is requiresd,
24 : : // feel free to access the underlying sqlite3_stmt via
25 : : // and adopt the index access!
26 : :
27 : : /**
28 : : * \brief Class to access data of query results.
29 : : *
30 : : * A Columns instance is constructed by a Command and passed to the
31 : : * callback which handles the results of a query.
32 : : *
33 : : * \see RowCallback
34 : : * \see Command::Callback
35 : : * \see Database::Callback
36 : : */
37 : : class LIBSL3_API Columns
38 : : {
39 : : friend class Command;
40 : :
41 : : Columns (sqlite3_stmt* stmt);
42 : :
43 : : // not be needed, even if they would not harm ..
44 : : Columns& operator= (const Columns&) = delete;
45 : :
46 : : // not be needed, even if they would not harm ..
47 : : Columns& operator= (Columns&&) = delete;
48 : :
49 : : Columns (const Columns&) = default;
50 : :
51 : : public:
52 : : /**
53 : : * \brief Move constructor
54 : : * A column is movable
55 : : */
56 : : Columns (Columns&&) = default;
57 : :
58 : : /**
59 : : * \brief Destructor
60 : : *
61 : : */
62 : : ~Columns () = default;
63 : :
64 : : /**
65 : : * \brief Number of columns in the statement.
66 : : *
67 : : * \return number of columns
68 : : */
69 : : int count () const;
70 : :
71 : : /**
72 : : * \brief Column name of given index.
73 : : *
74 : : *
75 : : * \throw sl3::ErrOutOfRange if idx is invalid,
76 : : * \param idx wanted column index
77 : : * \return column name or an empty string if index is invalid
78 : : */
79 : : std::string getName (int idx) const;
80 : :
81 : : /**
82 : : * \brief Get columns names
83 : : *
84 : : * Will return a list of size count() .
85 : : * Unnamed columns will be an ampty string
86 : : *
87 : : * \return the names
88 : : */
89 : : std::vector<std::string> getNames () const;
90 : :
91 : : /**
92 : : * \brief Get the value at a given index
93 : : *
94 : : * The returned DbValue::getType() will be a Type::Variant and
95 : : * DbValue::getStorageType() will be set to the sqlite3 storage type.
96 : : *
97 : : * \param idx wanted index
98 : : * \throw sl3::ErrOutOfRange if idx is invalid,
99 : : * \return DbValue of requested column
100 : : */
101 : : DbValue getValue (int idx) const;
102 : :
103 : : /**
104 : : * \brief Get the value at a given index
105 : : *
106 : : * The returned DbValue::getType() and DbValue::getStorageType()
107 : : * will be set to the given type.
108 : : *
109 : : * \param idx wanted index
110 : : * \param type wanted type
111 : : * \throw sl3::ErrTypeMisMatch if type is not the sqlite type
112 : : * \throw sl3::ErrOutOfRange if idx is invalid,
113 : : * \return DbValue of requested column
114 : : */
115 : : DbValue getValue (int idx, Type type) const;
116 : :
117 : : /**
118 : : * \brief Get all columns at once
119 : : *
120 : : * All DbValue object will be of Type::Variant
121 : : *
122 : : * \return DbValues of the column values
123 : : */
124 : : DbValues getRow () const;
125 : :
126 : : /**
127 : : * \brief Get all columns at once using the given types
128 : : *
129 : : * If a value does not math the given types an exception will be thown
130 : : *
131 : : * \param types wanted Types
132 : : * \throw sl3::ErrTypeMisMatch in case of an incorrect type
133 : : * \return DbValues of the column values
134 : : */
135 : : DbValues getRow (const Types& types) const;
136 : :
137 : : /**
138 : : * \brief Get the sqlite type for a column
139 : : *
140 : : * If used, should be called before accessing the value of the column
141 : : * at the given index, otherwise the typed access might set the type.
142 : : *
143 : : * This method can be used to check if a column isNull.
144 : : *
145 : : * \param idx wanted index
146 : : * \throw sl3::ErrOutOfRange if idx is invalid
147 : : * \return Type sqlite interprets the value
148 : : */
149 : : Type getType (int idx) const;
150 : :
151 : : /**
152 : : * \brief Get the size of a column
153 : : *
154 : : * The size sqlite3 uses to store the value of the given field.
155 : : *
156 : : * \param idx wanted index
157 : : * \throw sl3::ErrOutOfRange if idx is invalid
158 : : * \return size sqlite uses for the column
159 : : */
160 : : size_t getSize (int idx) const;
161 : :
162 : : /**
163 : : * \brief Get the value of a column.
164 : : *
165 : : * If a column is Null of of a different type, the sqlite3 conversion
166 : : * rules are applied.
167 : : *
168 : : * \param idx column index
169 : : * \throw sl3::ErrOutOfRange if idx is invalid
170 : : * \return column value
171 : : */
172 : : std::string getText (int idx) const;
173 : :
174 : : /**
175 : : * \brief Get the value of a column.
176 : : *
177 : : * If a column is Null of of a different type, the sqlite3 conversion
178 : : * rules are applied.
179 : : *
180 : : * \param idx column index
181 : : * \throw sl3::ErrOutOfRange if idx is invalid
182 : : * \return column value
183 : : */
184 : : int getInt (int idx) const;
185 : :
186 : : /**
187 : : * \brief Get the value of a column.
188 : : *
189 : : * If a column is Null of of a different type, the sqlite3 conversion
190 : : * rules are applied.
191 : : * \param idx column index
192 : : * \throw sl3::ErrOutOfRange if idx is invalid
193 : : * \return column value
194 : : */
195 : : int64_t getInt64 (int idx) const;
196 : :
197 : : /**
198 : : * \brief Get the value of a column.
199 : : *
200 : : * If a column is Null of of a different type, the sqlite3 conversion
201 : : * rules are applied.
202 : : *
203 : : * \param idx column index
204 : : * \throw sl3::ErrOutOfRange if idx is invalid
205 : : * \return column value
206 : : */
207 : : double getReal (int idx) const;
208 : :
209 : : /**
210 : : * \brief Get the value of a column.
211 : : *
212 : : * If a column is Null of of a different type, the sqlite3 conversion
213 : : * rules are applied.
214 : : *
215 : : * \param idx column index
216 : : * \throw sl3::ErrOutOfRange if idx is invalid
217 : : * \return column value
218 : : */
219 : : Blob getBlob (int idx) const;
220 : :
221 : : /**
222 : : * \brief Get the underlying sqlite3_stmt
223 : : *
224 : : * User defined QueryCallbacks might have their own way to do things,
225 : : * so this getter provides access to the underlying sqlite3_stmt.
226 : : *
227 : : * \return underlying sqlite3_stmt
228 : : */
229 : : sqlite3_stmt*
230 : 1 : get_stmt () const
231 : : {
232 : 1 : return _stmt;
233 : : }
234 : :
235 : : private:
236 : : sqlite3_stmt* _stmt;
237 : : };
238 : : }
239 : :
240 : : #endif
|
