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