1//
2// Copyright (c) 2019-2024 Ruben Perez Hidalgo (rubenperez038 at gmail dot com)
3//
4// Distributed under the Boost Software License, Version 1.0. (See accompanying
5// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6//
7
8#ifndef BOOST_MYSQL_METADATA_HPP
9#define BOOST_MYSQL_METADATA_HPP
10
11#include <boost/mysql/column_type.hpp>
12#include <boost/mysql/string_view.hpp>
13
14#include <boost/mysql/detail/access.hpp>
15#include <boost/mysql/detail/coldef_view.hpp>
16#include <boost/mysql/detail/flags.hpp>
17
18#include <string>
19
20namespace boost {
21namespace mysql {
22
23/**
24 * \brief Metadata about a column in a SQL query.
25 * \details This is a regular, value type. Instances of this class are not created by the user
26 * directly, but by the library.
27 */
28class metadata
29{
30public:
31 /**
32 * \brief Default constructor.
33 * \details The constructed metadata object has undefined
34 * values for all of its members.
35 *
36 * \par Exception safety
37 * No-throw guarantee.
38 */
39 metadata() = default;
40
41 /**
42 * \brief Move constructor.
43 *
44 * \par Exception safety
45 * No-throw guarantee.
46 *
47 * \par Object lifetimes
48 * `string_view`s obtained by calling accessor functions on `other` are invalidated.
49 */
50 metadata(metadata&& other) = default;
51
52 /**
53 * \brief Copy constructor.
54 *
55 * \par Exception safety
56 * Strong guarantee. Internal allocations may throw.
57 */
58 metadata(const metadata& other) = default;
59
60 /**
61 * \brief Move assignment.
62 *
63 * \par Exception safety
64 * No-throw guarantee.
65 *
66 * \par Object lifetimes
67 * `string_view`s obtained by calling accessor functions on both `*this` and `other`
68 * are invalidated.
69 */
70 metadata& operator=(metadata&& other) = default;
71
72 /**
73 * \brief Copy assignment.
74 *
75 * \par Exception safety
76 * Basic guarantee. Internal allocations may throw.
77 *
78 * \par Object lifetimes
79 * `string_view`s obtained by calling accessor functions on `*this`
80 * are invalidated.
81 */
82 metadata& operator=(const metadata& other) = default;
83
84 /// Destructor.
85 ~metadata() = default;
86
87 /**
88 * \brief Returns the name of the database (schema) the column belongs to.
89 * \details
90 * This is optional information - it won't be populated unless
91 * the connection executing the query has `meta_mode() == metadata_mode::full`.
92 *
93 * \par Exception safety
94 * No-throw guarantee.
95 *
96 * \par Object lifetimes
97 * The returned reference is valid as long as `*this` is alive and hasn't been
98 * assigned to or moved from.
99 */
100 string_view database() const noexcept { return schema_; }
101
102 /**
103 * \brief Returns the name of the virtual table the column belongs to.
104 * \details If the table was aliased, this will be the name of the alias
105 * (e.g. in `"SELECT * FROM employees emp"`, `table()` will be `"emp"`).
106 *\n
107 * This is optional information - it won't be populated unless
108 * the connection executing the query has `meta_mode() == metadata_mode::full`.
109 *
110 * \par Exception safety
111 * No-throw guarantee.
112 *
113 * \par Object lifetimes
114 * The returned reference is valid as long as `*this` is alive and hasn't been
115 * assigned to or moved from.
116 */
117 string_view table() const noexcept { return table_; }
118
119 /**
120 * \brief Returns the name of the physical table the column belongs to.
121 * \details E.g. in `"SELECT * FROM employees emp"`,
122 * `original_table()` will be `"employees"`.
123 * \n
124 * This is optional information - it won't be populated unless
125 * the connection executing the query has `meta_mode() == metadata_mode::full`.
126 *
127 * \par Exception safety
128 * No-throw guarantee.
129 *
130 * \par Object lifetimes
131 * The returned reference is valid as long as `*this` is alive and hasn't been
132 * assigned to or moved from.
133 */
134 string_view original_table() const noexcept { return org_table_; }
135
136 /**
137 * \brief Returns the actual name of the column.
138 * \details If the column was aliased, this will be the name of the alias
139 * (e.g. in `"SELECT id AS employee_id FROM employees"`,
140 * `column_name()` will be `"employee_id"`).
141 *\n
142 * This is optional information - it won't be populated unless
143 * the connection executing the query has `meta_mode() == metadata_mode::full`.
144 *
145 * \par Exception safety
146 * No-throw guarantee.
147 *
148 * \par Object lifetimes
149 * The returned reference is valid as long as `*this` is alive and hasn't been
150 * assigned to or moved from.
151 */
152 string_view column_name() const noexcept { return name_; }
153
154 /**
155 * \brief Returns the original (physical) name of the column.
156 * \details E.g. in `"SELECT id AS employee_id FROM employees"`,
157 * `original_column_name()` will be `"id"`.
158 * \n
159 * This is optional information - it won't be populated unless
160 * the connection executing the query has `meta_mode() == metadata_mode::full`.
161 *
162 * \par Exception safety
163 * No-throw guarantee.
164 *
165 * \par Object lifetimes
166 * The returned reference is valid as long as `*this` is alive and hasn't been
167 * assigned to or moved from.
168 */
169 string_view original_column_name() const noexcept { return org_name_; }
170
171 /**
172 * \brief Returns the ID of the collation that fields belonging to this column use.
173 * \details This is <b>not</b> the collation used when defining the column
174 * in a `CREATE TABLE` statement, but the collation that fields that belong to
175 * this column and are sent to the client have. It usually matches the connection's collation.
176 *
177 * \par Exception safety
178 * No-throw guarantee.
179 */
180 std::uint16_t column_collation() const noexcept { return character_set_; }
181
182 /**
183 * \brief Returns the maximum length of the column.
184 * \par Exception safety
185 * No-throw guarantee.
186 */
187 unsigned column_length() const noexcept { return column_length_; }
188
189 /**
190 * \brief Returns the type of the column (see \ref column_type for more info).
191 * \par Exception safety
192 * No-throw guarantee.
193 */
194 column_type type() const noexcept { return type_; }
195
196 /**
197 * \brief Returns the number of decimals of the column.
198 * \par Exception safety
199 * No-throw guarantee.
200 */
201 unsigned decimals() const noexcept { return decimals_; }
202
203 /**
204 * \brief Returns `true` if the column is not allowed to be NULL, `false` if it is nullable.
205 * \par Exception safety
206 * No-throw guarantee.
207 */
208 bool is_not_null() const noexcept { return flag_set(flag: detail::column_flags::not_null); }
209
210 /**
211 * \brief Returns `true` if the column is part of a `PRIMARY KEY`.
212 * \par Exception safety
213 * No-throw guarantee.
214 */
215 bool is_primary_key() const noexcept { return flag_set(flag: detail::column_flags::pri_key); }
216
217 /**
218 * \brief Returns `true` if the column is part of a `UNIQUE KEY` (but not a `PRIMARY KEY`).
219 * \par Exception safety
220 * No-throw guarantee.
221 */
222 bool is_unique_key() const noexcept { return flag_set(flag: detail::column_flags::unique_key); }
223
224 /**
225 * \brief Returns `true` if the column is part of a `KEY` (but not a `UNIQUE KEY` or `PRIMARY KEY`).
226 * \par Exception safety
227 * No-throw guarantee.
228 */
229 bool is_multiple_key() const noexcept { return flag_set(flag: detail::column_flags::multiple_key); }
230
231 /**
232 * \brief Returns `true` if the column has no sign (is `UNSIGNED`).
233 * \par Exception safety
234 * No-throw guarantee.
235 */
236 bool is_unsigned() const noexcept { return flag_set(flag: detail::column_flags::unsigned_); }
237
238 /**
239 * \brief Returns `true` if the column is defined as `ZEROFILL` (padded to its maximum length by
240 * zeros).
241 * \par Exception safety
242 * No-throw guarantee.
243 */
244 bool is_zerofill() const noexcept { return flag_set(flag: detail::column_flags::zerofill); }
245
246 /**
247 * \brief Returns `true` if the column is defined as `AUTO_INCREMENT`.
248 * \par Exception safety
249 * No-throw guarantee.
250 */
251 bool is_auto_increment() const noexcept { return flag_set(flag: detail::column_flags::auto_increment); }
252
253 /**
254 * \brief Returns `true` if the column does not have a default value.
255 * \par Exception safety
256 * No-throw guarantee.
257 */
258 bool has_no_default_value() const noexcept { return flag_set(flag: detail::column_flags::no_default_value); }
259
260 /**
261 * \brief Returns `true` if the column is defined as `ON UPDATE CURRENT_TIMESTAMP`.
262 * \par Exception safety
263 * No-throw guarantee.
264 */
265 bool is_set_to_now_on_update() const noexcept { return flag_set(flag: detail::column_flags::on_update_now); }
266
267private:
268 std::string schema_;
269 std::string table_; // virtual table
270 std::string org_table_; // physical table
271 std::string name_; // virtual column name
272 std::string org_name_; // physical column name
273 std::uint16_t character_set_;
274 std::uint32_t column_length_; // maximum length of the field
275 column_type type_; // type of the column
276 std::uint16_t flags_; // Flags as defined in Column Definition Flags
277 std::uint8_t decimals_; // max shown decimal digits. 0x00 for int/static strings; 0x1f for
278 // dynamic strings, double, float
279
280 metadata(const detail::coldef_view& coldef, bool copy_strings)
281 : schema_(copy_strings ? coldef.database : string_view()),
282 table_(copy_strings ? coldef.table : string_view()),
283 org_table_(copy_strings ? coldef.org_table : string_view()),
284 name_(copy_strings ? coldef.name : string_view()),
285 org_name_(copy_strings ? coldef.org_name : string_view()),
286 character_set_(coldef.collation_id),
287 column_length_(coldef.column_length),
288 type_(coldef.type),
289 flags_(coldef.flags),
290 decimals_(coldef.decimals)
291 {
292 }
293
294 bool flag_set(std::uint16_t flag) const noexcept { return flags_ & flag; }
295
296#ifndef BOOST_MYSQL_DOXYGEN
297 friend struct detail::access;
298#endif
299};
300
301} // namespace mysql
302} // namespace boost
303
304#endif
305

source code of boost/libs/mysql/include/boost/mysql/metadata.hpp