MySQL 9.0.0
Source Code Documentation
properties.h
Go to the documentation of this file.
1/* Copyright (c) 2014, 2024, Oracle and/or its affiliates.
2
3 This program is free software; you can redistribute it and/or modify
4 it under the terms of the GNU General Public License, version 2.0,
5 as published by the Free Software Foundation.
6
7 This program is designed to work with certain software (including
8 but not limited to OpenSSL) that is licensed under separate terms,
9 as designated in a particular file or component or in included license
10 documentation. The authors of MySQL hereby grant you an additional
11 permission to link the program and your derivative works with the
12 separately licensed software that they have either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef DD__PROPERTIES_INCLUDED
25#define DD__PROPERTIES_INCLUDED
26
27#include <map>
28
29#include "sql/dd/string_type.h" // String_type, Stringstream_type
30
31struct MEM_ROOT;
32
33namespace dd {
34
35///////////////////////////////////////////////////////////////////////////
36
37/**
38 The Properties class defines an interface for storing key=value pairs,
39 where both key and value may be UTF-8 strings.
40
41 The interface contains functions for testing whether a key exists,
42 replacing or removing key=value pairs, iteration etc. The interface
43 also defines template functions for converting between strings and
44 various primitive types.
45
46 Please note that in debug builds, the get() functions will assert that
47 the key exists. This is to make sure that non-existing keys are
48 handled explicitly at the client side.
49
50 The raw_string() function returns a semicolon separated list of all
51 key=value pairs. Characters '=' and ';' that are part of key or value
52 are escaped using the '\' as an escape character. The escape character
53 itself must also be escaped if being part of key or value.
54
55 Examples of usage:
56
57 Add key=value:
58 p->set("akey=avalue");
59
60 Add a numeric value:
61 p->set("intvalue", 1234);
62
63 Get values:
64 int32 num;
65 p->get("intvalue", &num);
66
67 Get raw string:
68 String_type mylist= p->raw_string();
69
70 Further comments can be found in the files properties_impl.{h,cc}
71 where the interface is implemented.
72 */
73
75 public:
76 /**
77 Convert a string to a value of an integral type. Verify correct
78 sign, check for overflow and conversion errors.
79
80 @tparam T Value type.
81 @param number String containing integral value to convert.
82 @param[out] value Converted value.
83
84 @return operation status.
85 @retval true if an error occurred
86 @retval false if success
87 */
88 template <typename T>
89 static bool from_str(const String_type &number, T *value);
90
91 /**
92 Convert string to bool. Valid values are "true", "false", and
93 decimal numbers, where "0" will be taken to mean false, and
94 numbers != 0 will be taken to mean true.
95
96 @param bool_str String containing boolean value to convert.
97 @param[out] value Converted value.
98
99 @return operation status.
100 @retval true if an error occurred
101 @retval false if success
102 */
103 static bool from_str(const String_type &bool_str, bool *value);
104
105 /**
106 Convert a value of an integral type (including bool) to a string.
107 Create an output stream and write the value.
108
109 @tparam T Value type.
110 @param value Actual value to convert.
111
112 @return string containing representation of the value.
113 */
114 template <class T>
115 static String_type to_str(T value);
116
117 /**
118 Parse the submitted string for properties on the format
119 "key=value;key=value;...". Create new property object and add
120 the properties to the map in the object.
121
122 @param raw_properties string containing list of key=value pairs
123 @return pointer to new Property_impl object
124 @retval NULL if an error occurred
125 */
126 static Properties *parse_properties(const String_type &raw_properties);
127
128 typedef std::map<String_type, String_type> Map;
129 typedef std::map<String_type, String_type>::size_type size_type;
130 typedef Map::iterator iterator;
131 typedef Map::const_iterator const_iterator;
132
133 virtual iterator begin() = 0;
134 virtual const_iterator begin() const = 0;
135
136 virtual iterator end() = 0;
137 virtual const_iterator end() const = 0;
138
139 /**
140 Insert keys and values from a different property object.
141
142 @note The valid keys in the target object are used to filter out invalid
143 keys, which will be silently ignored. The set of valid keys in the
144 source object is not copied.
145
146 @pre The 'this' object shall be empty.
147
148 @param properties Object which will have its properties
149 copied to 'this' object.
150
151 @return operation outcome, false if success, otherwise true.
152 */
153 virtual bool insert_values(const Properties &properties) = 0;
154
155 /**
156 Insert keys and values from a raw string.
157
158 Invalid keys will be silently ignored, using the set of valid keys in
159 the target object as a filter. The source is a string, so it has no
160 definition of valid keys.
161
162 @pre The 'this' object shall be empty.
163
164 @param raw_string String with key/value pairs which will be
165 parsed and added to the 'this' object.
166
167 @return operation outcome, false if success, otherwise true.
168 */
169 virtual bool insert_values(const String_type &raw_string) = 0;
170
171 /**
172 Get the number of key=value pairs.
173
174 @note Invalid keys that are present will also be reflected in the count.
175
176 @return number of key=value pairs
177 */
178 virtual size_type size() const = 0;
179
180 /**
181 Are there any key=value pairs?
182
183 @return true if there is no key=value pair, else false.
184 */
185 virtual bool empty() const = 0;
186
187 /**
188 Remove all key=value pairs.
189 */
190 virtual void clear() = 0;
191
192 /**
193 Check if the submitted key is valid.
194
195 @param key Key to be checked.
196
197 @retval true if the key is valid, otherwise false.
198 */
199 virtual bool valid_key(const String_type &key) const = 0;
200
201 /**
202 Check for the existence of a key=value pair given the key.
203
204 @param key Key to be checked.
205
206 @return true if the given key exists, false otherwise.
207 */
208 virtual bool exists(const String_type &key) const = 0;
209
210 /**
211 Remove the key=value pair for the given key if it exists.
212 Otherwise, do nothing.
213
214 @param key key to lookup.
215
216 @return false if the given key existed, true otherwise.
217 */
218 virtual bool remove(const String_type &key) = 0;
219
220 /**
221 Create a string containing all key=value pairs as a semicolon
222 separated list. Key and value are separated by '='. The '=' and
223 ';' characters are escaped using '\' if part of key or value, hence,
224 the escape character '\' must also be escaped.
225
226 @return a string listing all key=value pairs.
227 */
228 virtual const String_type raw_string() const = 0;
229
230 /**
231 Get the string value for a given key.
232
233 Return true (assert in debug builds) if the operation fails, i.e.,
234 if the key does not exist or if the key is invalid.
235
236 @param key Key to lookup the value for.
237 @param[out] value String value.
238
239 @return operation outcome, false if success, otherwise true.
240 */
241 virtual bool get(const String_type &key, String_type *value) const = 0;
242
243 /**
244 Get the lex string value for a given key.
245
246 Return true (assert in debug builds) if the operation fails, i.e.,
247 if the key does not exist or if the key is invalid.
248
249 @tparam Lex_type Type of LEX string.
250 @param key Key to lookup the value for.
251 @param[out] value LEX_STRING or LEX_CSTRING value.
252 @param[in] mem_root MEM_ROOT to allocate string.
253
254 @return operation outcome, false if success, otherwise true.
255 */
256 template <typename Lex_type>
257 bool get(const String_type &key, Lex_type *value, MEM_ROOT *mem_root) const;
258
259 /**
260 Get the string value for the key and convert it to the appropriate type.
261
262 Return true (assert in debug builds) if the operation fails, i.e.,
263 if the key does not exist or is invalid, or if the type conversion fails.
264
265 @tparam Value_type Type of the value to get.
266 @param key Key to lookup.
267 @param[out] value Value of appropriate type.
268
269 @return operation outcome, false if success, otherwise true.
270 */
271 template <typename Value_type>
272 bool get(const String_type &key, Value_type *value) const;
273
274 /**
275 Add a new key=value pair where the value is a string. If the key already
276 exists, the associated value will be replaced by the new value argument.
277
278 Return true (assert in debug builds) if the operation fails, i.e.,
279 if the key is invalid.
280
281 @param key Key to map to a value.
282 @param value String value to be associated with the key.
283
284 @return operation outcome, false if success, otherwise true.
285 */
286 virtual bool set(const String_type &key, const String_type &value) = 0;
287
288 /**
289 Convert the value to a string and set it for the given key.
290
291 Return true (assert in debug builds) if the operation fails, i.e.,
292 if the key is invalid.
293
294 @tparam Value_type Type of the value to set.
295 @param key Key to assign to.
296 @param[out] value Value of appropriate type.
297
298 @return operation outcome, false if success, otherwise true.
299 */
300 template <typename Value_type>
301 bool set(const String_type &key, Value_type value) {
302 return set(key, to_str(value));
303 }
304
305 Properties() = default;
306
307 Properties(const Properties &) = default;
308
309 Properties &operator=(const Properties &) = delete;
310
311 virtual ~Properties() = default;
312};
313
314///////////////////////////////////////////////////////////////////////////
315
316} // namespace dd
317
318#endif // DD__PROPERTIES_INCLUDED
The Properties class defines an interface for storing key=value pairs, where both key and value may b...
Definition: properties.h:74
virtual size_type size() const =0
Get the number of key=value pairs.
Properties(const Properties &)=default
virtual bool exists(const String_type &key) const =0
Check for the existence of a key=value pair given the key.
virtual iterator end()=0
Properties()=default
virtual bool remove(const String_type &key)=0
Remove the key=value pair for the given key if it exists.
virtual bool get(const String_type &key, String_type *value) const =0
Get the string value for a given key.
bool set(const String_type &key, Value_type value)
Convert the value to a string and set it for the given key.
Definition: properties.h:301
Properties & operator=(const Properties &)=delete
std::map< String_type, String_type > Map
Definition: properties.h:128
virtual ~Properties()=default
virtual void clear()=0
Remove all key=value pairs.
Map::iterator iterator
Definition: properties.h:130
virtual bool insert_values(const String_type &raw_string)=0
Insert keys and values from a raw string.
virtual iterator begin()=0
virtual const_iterator end() const =0
std::map< String_type, String_type >::size_type size_type
Definition: properties.h:129
virtual const_iterator begin() const =0
virtual const String_type raw_string() const =0
Create a string containing all key=value pairs as a semicolon separated list.
virtual bool valid_key(const String_type &key) const =0
Check if the submitted key is valid.
virtual bool empty() const =0
Are there any key=value pairs?
static Properties * parse_properties(const String_type &raw_properties)
Parse the submitted string for properties on the format "key=value;key=value;...".
Definition: properties_impl.cc:48
Map::const_iterator const_iterator
Definition: properties.h:131
virtual bool set(const String_type &key, const String_type &value)=0
Add a new key=value pair where the value is a string.
virtual bool insert_values(const Properties &properties)=0
Insert keys and values from a different property object.
static String_type to_str(T value)
Convert a value of an integral type (including bool) to a string.
Definition: properties.cc:95
static bool from_str(const String_type &number, T *value)
Convert a string to a value of an integral type.
Definition: properties.cc:38
static MEM_ROOT mem_root
Definition: client_plugin.cc:114
The version of the current data dictionary table definitions.
Definition: dictionary_client.h:43
Char_string_template< String_type_allocator > String_type
Definition: string_type.h:51
required string key
Definition: replication_asynchronous_connection_failover.proto:60
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:83