MySQL  8.0.17
Source Code Documentation
properties.h
Go to the documentation of this file.
1 /* Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
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 
30 struct MEM_ROOT;
31 
32 namespace 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 
73 class Properties {
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() {}
311 };
312 
313 ///////////////////////////////////////////////////////////////////////////
314 
315 } // namespace dd
316 
317 #endif // DD__PROPERTIES_INCLUDED
virtual iterator end()=0
Char_string_template< String_type_allocator > String_type
Definition: string_type.h:50
virtual size_type size() const =0
Get the number of key=value pairs.
static String_type to_str(T value)
Convert a value of an integral type (including bool) to a string.
Definition: properties.cc:94
Map::const_iterator const_iterator
Definition: properties.h:130
Properties & operator=(const Properties &)=delete
virtual ~Properties()
Definition: properties.h:310
virtual bool empty() const =0
Are there any key=value pairs?
virtual bool insert_values(const Properties &properties)=0
Insert keys and values from a different property object.
std::map< String_type, String_type > Map
Definition: properties.h:127
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
The Properties class defines an interface for storing key=value pairs, where both key and value may b...
Definition: properties.h:73
virtual const String_type raw_string() const =0
Create a string containing all key=value pairs as a semicolon separated list.
static const char * key
Definition: suite_stubs.c:14
static MEM_ROOT mem_root
Definition: client_plugin.cc:107
Properties()=default
std::map< String_type, String_type >::size_type size_type
Definition: properties.h:128
Map::iterator iterator
Definition: properties.h:129
static bool from_str(const String_type &number, T *value)
Convert a string to a value of an integral type.
Definition: properties.cc:37
virtual iterator begin()=0
const string value("\alue\)
The version of the current data dictionary table definitions.
Definition: dictionary_client.h:39
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:77
virtual bool exists(const String_type &key) const =0
Check for the existence of a key=value pair given the key.
virtual void clear()=0
Remove all key=value pairs.
virtual bool valid_key(const String_type &key) const =0
Check if the submitted key is valid.