MySQL 9.0.0
Source Code Documentation
mysql_string.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2024, Oracle and/or its affiliates.
2
3This program is free software; you can redistribute it and/or modify
4it under the terms of the GNU General Public License, version 2.0,
5as published by the Free Software Foundation.
6
7This program is designed to work with certain software (including
8but not limited to OpenSSL) that is licensed under separate terms,
9as designated in a particular file or component or in included license
10documentation. The authors of MySQL hereby grant you an additional
11permission to link the program and your derivative works with the
12separately licensed software that they have either included with
13the program or referenced in the documentation.
14
15This program is distributed in the hope that it will be useful,
16but WITHOUT ANY WARRANTY; without even the implied warranty of
17MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18GNU General Public License, version 2.0, for more details.
19
20You should have received a copy of the GNU General Public License
21along with this program; if not, write to the Free Software
22Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef MYSQL_STRING_SERVICE_H
25#define MYSQL_STRING_SERVICE_H
26
28
30
31#include "my_inttypes.h"
32
33/* clang-format off */
34/**
35 @defgroup group_string_component_services_inventory MySQL string services
36 @ingroup group_components_services_inventory
37*/
38
39/* clang-format on */
40
42
43/**
44 Get the "utf8mb4" CHARSET_INFO.
45*/
47
48/**
49 Find a CHARSET_INFO by name.
50 @param name The character set name, expressed in ASCII, zero terminated.
51*/
53
54/**
55 @ingroup group_string_component_services_inventory
56
57 Lookup available character sets.
58 Status: Active.
59*/
61/** @sa get_charset_utf8mb4_v1_t */
63/** @sa get_charset_by_name_v1_t */
66
67/**
68 The string functions as a service to the mysql_server component.
69 So, that by default this service is available to all the components
70 register to the server.
71*/
72
75
76/**
77 @ingroup group_string_component_services_inventory
78
79 Service for String create and destroy.
80*/
81BEGIN_SERVICE_DEFINITION(mysql_string_factory)
82/**
83 Creates a new instance of string object
84
85 @param out_string holds pointer to newly created string object.
86 @return Status of performed operation
87 @retval false success @retval true failure
88*/
90
91/**
92 Destroys specified string object and data contained by it.
93
94 @param string String object handle to release.
95 @return Status of performed operation
96 @retval false success
97 @retval true failure
98*/
100END_SERVICE_DEFINITION(mysql_string_factory)
101
102/**
103 @ingroup group_string_component_services_inventory
104
105 Service for String case conversions, to lower case and to upper case.
106*/
107BEGIN_SERVICE_DEFINITION(mysql_string_case)
108/**
109 Convert a String pointed by handle to lower case. Conversion depends on the
110 client character set info
111
112 @param out_string Holds the converted lower case string object.
113 @param in_string Pointer to string object to be converted.
114 @return Status of performed operation
115 @retval false success
116 @retval true failure
117*/
119
120/**
121 Convert a String pointed by handle to upper case. Conversion depends on the
122 client character set info
123
124 @param out_string Holds the converted upper case string object.
125 @param in_string Pointer to string object to be converted.
126 @return Status of performed operation
127 @retval false success
128 @retval true failure
129*/
131END_SERVICE_DEFINITION(mysql_string_case)
132
133/**
134 @ingroup group_string_component_services_inventory
135
136 Service for conversions, string to buffer and buffer to string.
137 Status: Deprecated, use mysql_string_charset_converter instead.
138*/
139BEGIN_SERVICE_DEFINITION(mysql_string_converter)
140/**
141 allocates a string object and converts the character buffer to string
142 of specified charset_name.
143 please call destroy() api to free the allocated string after this api.
144
145 @param [out] out_string Pointer to string object handle to set new string
146 to.
147 @param in_buffer Pointer to the buffer with data to be interpreted as
148 string.
149 @param length Length of the buffer to copy into string, in bytes, not in
150 character count.
151 @param charset_name charset that is used for conversion.
152 @return Status of performed operation
153 @retval false success
154 @retval true failure
155*/
157 (my_h_string * out_string, const char *in_buffer,
158 uint64 length, const char *charset_name));
159
160/**
161 converts the mysql_string to the character set specified by
162 charset_name parameter.
163
164 @param in_string Pointer to string object handle to set new string
165 to.
166 @param [out] out_buffer Pointer to the buffer with data to be interpreted
167 as characters.
168 @param length Length of the buffer to hold out put in characters.
169 @param charset_name Handle to charset that is used for conversion.
170 @return Status of performed operation
171 @retval false success
172 @retval true failure
173*/
175 (my_h_string in_string, char *out_buffer, uint64 length,
176 const char *charset_name));
177END_SERVICE_DEFINITION(mysql_string_converter)
178
179/**
180 Converts a character buffer to string of specified charset
181 to a string object.
182 The caller provides the destination string object,
183 which content will be modified.
184
185 @param [in,out] dest_string Destination string.
186 @param src_buffer Source buffer
187 @param src_length Length of the source buffer, in bytes
188 @param src_charset CHARSET is the source buffer
189 @return Conversion status
190 @retval false success
191 @retval true failure
192*/
194 my_h_string dest_string, const char *src_buffer, uint64 src_length,
195 CHARSET_INFO_h src_charset);
196
197/**
198 Converts the mysql_string to a given character set.
199
200 @param src_string Source string to convert
201 @param [out] dest_buffer Destination buffer
202 @param dest_length Length, in charset characters, of the destination buffer
203 @param dest_charset Destination CHARSET, that is, character set to convert to
204 @return Conversion status
205 @retval false success
206 @retval true failure
207*/
209 my_h_string src_string, char *dest_buffer, uint64 dest_length,
210 CHARSET_INFO_h dest_charset);
211
212/**
213 @ingroup group_string_component_services_inventory
214
215 Service for conversions, string to buffer and buffer to string.
216 Status: Active.
217*/
218BEGIN_SERVICE_DEFINITION(mysql_string_charset_converter)
219/** @sa convert_from_buffer_v2_t */
221/** @sa convert_to_buffer_v2_t */
223END_SERVICE_DEFINITION(mysql_string_charset_converter)
224
225/**
226 @ingroup group_string_component_services_inventory
227
228 Service to get a character in String and number of characters in string
229*/
230BEGIN_SERVICE_DEFINITION(mysql_string_character_access)
231/**
232 Gets client character code of character on specified index position in
233 string to a specified buffer.
234
235 @param string String object handle to get character from.
236 @param index Index, position of character to query.
237 @param [out] out_char Pointer to long value to store character to.
238 @return Status of performed operation
239 @retval false success
240 @retval true failure
241*/
242DECLARE_BOOL_METHOD(get_char,
243 (my_h_string string, uint index, ulong *out_char));
244
245/**
246 Gets length of specified string expressed as number of characters.
247
248 @param string String object handle to get length of.
249 @param [out] out_length Pointer to 64bit value to store length of string to.
250 @return Status of performed operation
251 @retval false success
252 @retval true failure
253*/
254DECLARE_BOOL_METHOD(get_char_length, (my_h_string string, uint *out_length));
255END_SERVICE_DEFINITION(mysql_string_character_access)
256
257/**
258 @ingroup group_string_component_services_inventory
259
260 Service to get a byte in String and number of bytes in string
261*/
262BEGIN_SERVICE_DEFINITION(mysql_string_byte_access)
263/**
264 Gets byte code of string at specified index position to a
265 specified 32-bit buffer.
266
267 @param string String object handle to get character from.
268 @param index Index, position of character to query.
269 @param [out] out_char Pointer to 32bit value to store byte to.
270 @return Status of performed operation
271 @retval false success
272 @retval true failure
273*/
274DECLARE_BOOL_METHOD(get_byte, (my_h_string string, uint index, uint *out_char));
275
276/**
277 Gets length of specified string expressed as number of bytes.
278
279 @param string String object handle to get length of.
280 @param [out] out_length Pointer to 32bit value to store length of string to.
281 @return Status of performed operation
282 @retval false success
283 @retval true failure
284*/
285DECLARE_BOOL_METHOD(get_byte_length, (my_h_string string, uint *out_length));
286END_SERVICE_DEFINITION(mysql_string_byte_access)
287
288/**
289 @ingroup group_string_component_services_inventory
290
291 Service for listing Strings by iterator.
292*/
293BEGIN_SERVICE_DEFINITION(mysql_string_iterator)
294/**
295 Creates an iterator for a specified string to allow iteration through all
296 characters in the string.
297
298 @param string String object handle to get iterator to.
299 @param [out] out_iterator Pointer to string iterator handle to store result
300 object to.
301 @return Status of performed operation
302 @retval false success
303 @retval true failure
304*/
305DECLARE_BOOL_METHOD(iterator_create,
306 (my_h_string string, my_h_string_iterator *out_iterator));
307
308/**
309 Retrieves character type code at current iterator position and advances the
310 iterator. Character type code is a bit mask describing various properties.
311 Refer to types in mysql_string_bits.h
312
313 @param iter String iterator object handle to advance.
314 @param [out] out_ctype Pointer to 64bit value to store character type.
315 May be NULL to omit retrieval and just advance
316 the iterator.
317 @return Status of performed operation
318 @retval false success
319 @retval true failure
320*/
321DECLARE_BOOL_METHOD(iterator_get_next,
322 (my_h_string_iterator iter, int *out_ctype));
323
324/**
325 Releases the string iterator object specified.
326
327 @param iter String iterator object to handle the release.
328 @return Status of performed operation
329 @retval false success
330 @retval true failure
331*/
332DECLARE_METHOD(void, iterator_destroy, (my_h_string_iterator iter));
333END_SERVICE_DEFINITION(mysql_string_iterator)
334
335/**
336 @ingroup group_string_component_services_inventory
337
338 Service for String c_type.
339*/
340BEGIN_SERVICE_DEFINITION(mysql_string_ctype)
341/**
342 Checks if character on current position the iterator points to is an upper
343 case.
344
345 @param iter String iterator object handle to advance.
346 @param [out] out Pointer to bool value to store if character is an upper
347 case.
348 @return Status of performed operation
349 @retval false success
350 @retval true failure
351*/
352DECLARE_BOOL_METHOD(is_upper, (my_h_string_iterator iter, bool *out));
353
354/**
355 Checks if character on current position the iterator points to is a lower
356 case.
357
358 @param iter String iterator object handle to advance.
359 @param [out] out Pointer to bool value to store if character is a lower
360 case.
361 @return Status of performed operation
362 @retval false success
363 @retval true failure
364*/
365DECLARE_BOOL_METHOD(is_lower, (my_h_string_iterator iter, bool *out));
366
367/**
368 Checks if character on current position the iterator points to is a digit.
369
370 @param iter String iterator object handle to advance.
371 @param [out] out Pointer to bool value to store if character is a digit.
372 @return Status of performed operation
373 @retval false success
374 @retval true failure
375*/
377END_SERVICE_DEFINITION(mysql_string_ctype)
378
379/**
380 @ingroup group_string_component_services_inventory
381
382 Service for retrieving one character from a string.
383 It relies on string iterator and access ulong representation
384 of the character.
385*/
386BEGIN_SERVICE_DEFINITION(mysql_string_value)
387
388/**
389 Retrieves character value at current iterator position
390
391 @param iter String iterator object handle
392 @param [out] out Pointer to long value to store character to
393
394 @return Status of performed operation
395 @retval false success
396 @retval true failure
397*/
399
400END_SERVICE_DEFINITION(mysql_string_value)
401
402/* mysql_string_manipulation_v1 service. */
403
404/**
405 Reset a string to the empty string.
406
407 @param [in, out] s The string to reset.
408*/
410
411/**
412 @ingroup group_string_component_services_inventory
413
414 Reset a string to the empty string.
415*/
416BEGIN_SERVICE_DEFINITION(mysql_string_reset)
418END_SERVICE_DEFINITION(mysql_string_reset)
419
420/**
421 Substring.
422 Allocates a string object and sets it value as substring of the input
423 string. Caller must free the allocated string by calling destroy().
424
425 @param [in] in_string String handle to extract substring from.
426 @param [in] offset Character offset of the substring.
427 @param [in] count Number of characters of the substring.
428 @param [out] out_string Pointer to string handle holding the created result
429string.
430 @return Status of performed operation
431 @retval false success
432 @retval true failure
433*/
435 my_h_string in_string, uint offset, uint count, my_h_string *out_string);
436
437/**
438 @ingroup group_string_component_services_inventory
439
440 Substring a string.
441*/
442BEGIN_SERVICE_DEFINITION(mysql_string_substr)
444END_SERVICE_DEFINITION(mysql_string_substr)
445
446/**
447 Append a string.
448
449 @param [in, out] s1 The string to append to.
450 @param [in] s2 The string to append.
451*/
453 my_h_string s2);
454
455/**
456 @ingroup group_string_component_services_inventory
457
458 Append a string to another one.
459*/
460BEGIN_SERVICE_DEFINITION(mysql_string_append)
462END_SERVICE_DEFINITION(mysql_string_append)
463
464/**
465 Compare two strings.
466
467 @param [in] s1 First string to compare.
468 @param [in] s2 Second string to compare.
469 @param [out] cmp Comparison result (negative, zero, or positive) .
470*/
472 my_h_string s2,
473 int *cmp);
474
475/**
476 @ingroup group_string_component_services_inventory
477
478 Compare two strings.
479*/
480BEGIN_SERVICE_DEFINITION(mysql_string_compare)
482END_SERVICE_DEFINITION(mysql_string_compare)
483
484/**
485 Access the string raw data.
486 The raw data returned is usable only while the string object
487 is valid.
488
489 @param [in] s String
490 @param [out] buffer_pointer String raw buffer.
491 @param [out] buffer_length String raw buffer size.
492 @param [out] buffer_charset String character set.
493*/
495 my_h_string s, const char **buffer_pointer, size_t *buffer_length,
496 CHARSET_INFO_h *buffer_charset);
497
498/**
499 @ingroup group_string_component_services_inventory
500
501 Access the string raw data.
502*/
503BEGIN_SERVICE_DEFINITION(mysql_string_get_data_in_charset)
505END_SERVICE_DEFINITION(mysql_string_get_data_in_charset)
506
507#endif /* MYSQL_STRING_SERVICE_H */
int get_byte(azio_stream *s)
Definition: azio.cc:225
int destroy(azio_stream *s)
Definition: azio.cc:371
Definition: item_cmpfunc.h:1656
static int cmp(Bigint *a, Bigint *b)
Definition: dtoa.cc:1059
static bool is_digit(unsigned codepoint)
Return true if the codepoint is a Unicode digit.
Definition: json_path.cc:686
Some integer typedefs for easier portability.
uint64_t uint64
Definition: my_inttypes.h:69
static int count
Definition: myisam_ftdump.cc:45
mysql_service_status_t(* mysql_string_get_data_v1_t)(my_h_string s, const char **buffer_pointer, size_t *buffer_length, CHARSET_INFO_h *buffer_charset)
Access the string raw data.
Definition: mysql_string.h:494
mysql_service_status_t(* convert_from_buffer_v2_t)(my_h_string dest_string, const char *src_buffer, uint64 src_length, CHARSET_INFO_h src_charset)
Converts a character buffer to string of specified charset to a string object.
Definition: mysql_string.h:193
CHARSET_INFO_h(* get_charset_utf8mb4_v1_t)()
Get the "utf8mb4" CHARSET_INFO.
Definition: mysql_string.h:46
CHARSET_INFO_h(* get_charset_by_name_v1_t)(const char *name)
Find a CHARSET_INFO by name.
Definition: mysql_string.h:52
mysql_service_status_t(* mysql_string_reset_v1_t)(my_h_string s)
Reset a string to the empty string.
Definition: mysql_string.h:409
struct CHARSET_INFO_h_imp * CHARSET_INFO_h
Definition: mysql_string.h:41
mysql_service_status_t(* convert_to_buffer_v2_t)(my_h_string src_string, char *dest_buffer, uint64 dest_length, CHARSET_INFO_h dest_charset)
Converts the mysql_string to a given character set.
Definition: mysql_string.h:208
mysql_service_status_t(* mysql_string_substr_v1_t)(my_h_string in_string, uint offset, uint count, my_h_string *out_string)
Substring.
Definition: mysql_string.h:434
mysql_service_status_t(* mysql_string_compare_v1_t)(my_h_string s1, my_h_string s2, int *cmp)
Compare two strings.
Definition: mysql_string.h:471
mysql_service_status_t(* mysql_string_append_v1_t)(my_h_string s1, my_h_string s2)
Append a string.
Definition: mysql_string.h:452
Type information related to strings.
std::string HARNESS_EXPORT reset()
get 'reset attributes' ESC sequence.
Definition: vt100.cc:37
bool length(const dd::Spatial_reference_system *srs, const Geometry *g1, double *length, bool *null) noexcept
Computes the length of linestrings and multilinestrings.
Definition: length.cc:76
char tolower(const char &ch)
Definition: parsing_helpers.h:41
static mysql_service_status_t get(THD **thd) noexcept
Definition: mysql_current_thread_reader_all_empty.cc:31
static mysql_service_status_t convert_to_buffer(my_h_string, char *, uint64, const char *) noexcept
Definition: mysql_string_all_empty.cc:39
static mysql_service_status_t convert_from_buffer(my_h_string *, const char *, uint64, const char *) noexcept
Definition: mysql_string_all_empty.cc:34
static mysql_service_status_t create(my_h_string *) noexcept
Definition: mysql_string_all_empty.cc:43
static int compare(size_t a, size_t b)
Function to compare two size_t integers for their relative order.
Definition: rpl_utility.cc:107
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:103
int mysql_service_status_t
Specific type for the service status return values.
Definition: service.h:34
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:91
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:86
#define DEFINE_SERVICE_HANDLE(name)
Defines an object type that is meant for carrying handles to the implementation-specific objects used...
Definition: service.h:129
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:112
case opt name
Definition: sslopt-case.h:29
Definition: mysql_string_service.cc:60
Definition: mysql_string_service.cc:62