MySQL 8.0.31
Source Code Documentation
mysql_string.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2022, 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 also distributed 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 included with MySQL.
13
14This program is distributed in the hope that it will be useful,
15but WITHOUT ANY WARRANTY; without even the implied warranty of
16MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17GNU General Public License, version 2.0, for more details.
18
19You should have received a copy of the GNU General Public License
20along with this program; if not, write to the Free Software
21Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22
23#ifndef MYSQL_STRING_SERVICE_H
24#define MYSQL_STRING_SERVICE_H
25
27
28#include "my_inttypes.h"
29
31
32/**
33 Get the "utf8mb4" CHARSET_INFO.
34*/
36
37/**
38 Find a CHARSET_INFO by name.
39 @param name The character set name, expressed in ASCII, zero terminated.
40*/
42
43/**
44 Lookup available character sets.
45 Status: Active.
46*/
48/** @sa get_charset_utf8mb4_v1_t */
50/** @sa get_charset_by_name_v1_t */
53
54/**
55 The string functions as a service to the mysql_server component.
56 So, that by default this service is available to all the components
57 register to the server.
58*/
59
62
63/**
64 Service for String create and destroy.
65*/
66BEGIN_SERVICE_DEFINITION(mysql_string_factory)
67/**
68 Creates a new instance of string object
69
70 @param out_string holds pointer to newly created string object.
71 @return Status of performed operation
72 @retval false success @retval true failure
73*/
75
76/**
77 Destroys specified string object and data contained by it.
78
79 @param string String object handle to release.
80 @return Status of performed operation
81 @retval false success
82 @retval true failure
83*/
85END_SERVICE_DEFINITION(mysql_string_factory)
86
87/**
88 Service for String case conversions, to lower case and to upper case.
89*/
90BEGIN_SERVICE_DEFINITION(mysql_string_case)
91/**
92 Convert a String pointed by handle to lower case. Conversion depends on the
93 client character set info
94
95 @param out_string Holds the converted lower case string object.
96 @param in_string Pointer to string object to be converted.
97 @return Status of performed operation
98 @retval false success
99 @retval true failure
100*/
102
103/**
104 Convert a String pointed by handle to upper case. Conversion depends on the
105 client character set info
106
107 @param out_string Holds the converted upper case string object.
108 @param in_string Pointer to string object to be converted.
109 @return Status of performed operation
110 @retval false success
111 @retval true failure
112*/
114END_SERVICE_DEFINITION(mysql_string_case)
115
116/**
117 Service for conversions, string to buffer and buffer to string.
118 Status: Deprecated, use mysql_string_charset_converter instead.
119*/
120BEGIN_SERVICE_DEFINITION(mysql_string_converter)
121/**
122 allocates a string object and converts the character buffer to string
123 of specified charset_name.
124 please call destroy() api to free the allocated string after this api.
125
126 @param [out] out_string Pointer to string object handle to set new string
127 to.
128 @param in_buffer Pointer to the buffer with data to be interpreted as
129 string.
130 @param length Length of the buffer to copy into string, in bytes, not in
131 character count.
132 @param charset_name charset that is used for conversion.
133 @return Status of performed operation
134 @retval false success
135 @retval true failure
136*/
137DECLARE_BOOL_METHOD(convert_from_buffer,
138 (my_h_string * out_string, const char *in_buffer,
139 uint64 length, const char *charset_name));
140
141/**
142 converts the mysql_string to the character set specified by
143 charset_name parameter.
144
145 @param in_string Pointer to string object handle to set new string
146 to.
147 @param [out] out_buffer Pointer to the buffer with data to be interpreted
148 as characters.
149 @param length Length of the buffer to hold out put in characters.
150 @param charset_name Handle to charset that is used for conversion.
151 @return Status of performed operation
152 @retval false success
153 @retval true failure
154*/
155DECLARE_BOOL_METHOD(convert_to_buffer,
156 (my_h_string in_string, char *out_buffer, uint64 length,
157 const char *charset_name));
158END_SERVICE_DEFINITION(mysql_string_converter)
159
160/**
161 Converts a character buffer to string of specified charset
162 to a string object.
163 The caller provides the destination string object,
164 which content will be modified.
165
166 @param [in,out] dest_string Destination string.
167 @param src_buffer Source buffer
168 @param src_length Length of the source buffer, in bytes
169 @param src_charset CHARSET is the source buffer
170 @return Conversion status
171 @retval false success
172 @retval true failure
173*/
175 my_h_string dest_string, const char *src_buffer, uint64 src_length,
176 CHARSET_INFO_h src_charset);
177
178/**
179 Converts the mysql_string to a given character set.
180
181 @param src_string Source string to convert
182 @param [out] dest_buffer Destination buffer
183 @param dest_length Length, in charset characters, of the destination buffer
184 @param dest_charset Destination CHARSET, that is, character set to convert to
185 @return Conversion status
186 @retval false success
187 @retval true failure
188*/
190 my_h_string src_string, char *dest_buffer, uint64 dest_length,
191 CHARSET_INFO_h dest_charset);
192
193/**
194 Service for conversions, string to buffer and buffer to string.
195 Status: Active.
196*/
197BEGIN_SERVICE_DEFINITION(mysql_string_charset_converter)
198/** @sa convert_from_buffer_v2_t */
199convert_from_buffer_v2_t convert_from_buffer;
200/** @sa convert_to_buffer_v2_t */
201convert_to_buffer_v2_t convert_to_buffer;
202END_SERVICE_DEFINITION(mysql_string_charset_converter)
203
204/**
205 Service to get a character in String and number of characters in string
206*/
207BEGIN_SERVICE_DEFINITION(mysql_string_character_access)
208/**
209 Gets client character code of character on specified index position in
210 string to a specified buffer.
211
212 @param string String object handle to get character from.
213 @param index Index, position of character to query.
214 @param [out] out_char Pointer to long value to store character to.
215 @return Status of performed operation
216 @retval false success
217 @retval true failure
218*/
219DECLARE_BOOL_METHOD(get_char,
220 (my_h_string string, uint index, ulong *out_char));
221
222/**
223 Gets length of specified string expressed as number of characters.
224
225 @param string String object handle to get length of.
226 @param [out] out_length Pointer to 64bit value to store length of string to.
227 @return Status of performed operation
228 @retval false success
229 @retval true failure
230*/
231DECLARE_BOOL_METHOD(get_char_length, (my_h_string string, uint *out_length));
232END_SERVICE_DEFINITION(mysql_string_character_access)
233
234/**
235 Service to get a byte in String and number of bytes in string
236*/
237BEGIN_SERVICE_DEFINITION(mysql_string_byte_access)
238/**
239 Gets byte code of string at specified index position to a
240 specified 32-bit buffer.
241
242 @param string String object handle to get character from.
243 @param index Index, position of character to query.
244 @param [out] out_char Pointer to 32bit value to store byte to.
245 @return Status of performed operation
246 @retval false success
247 @retval true failure
248*/
249DECLARE_BOOL_METHOD(get_byte, (my_h_string string, uint index, uint *out_char));
250
251/**
252 Gets length of specified string expressed as number of bytes.
253
254 @param string String object handle to get length of.
255 @param [out] out_length Pointer to 32bit value to store length of string to.
256 @return Status of performed operation
257 @retval false success
258 @retval true failure
259*/
260DECLARE_BOOL_METHOD(get_byte_length, (my_h_string string, uint *out_length));
261END_SERVICE_DEFINITION(mysql_string_byte_access)
262
263/**
264 Service for listing Strings by iterator.
265*/
266BEGIN_SERVICE_DEFINITION(mysql_string_iterator)
267/**
268 Creates an iterator for a specified string to allow iteration through all
269 characters in the string.
270
271 @param string String object handle to get iterator to.
272 @param [out] out_iterator Pointer to string iterator handle to store result
273 object to.
274 @return Status of performed operation
275 @retval false success
276 @retval true failure
277*/
278DECLARE_BOOL_METHOD(iterator_create,
279 (my_h_string string, my_h_string_iterator *out_iterator));
280
281/**
282 Retrieves character code at current iterator position and advances the
283 iterator.
284
285 @param iter String iterator object handle to advance.
286 @param [out] out_char Pointer to 64bit value to store character to. May be
287 NULL to omit retrieval of character and just advance the iterator.
288 @return Status of performed operation
289 @retval false success
290 @retval true failure
291*/
292DECLARE_BOOL_METHOD(iterator_get_next,
293 (my_h_string_iterator iter, int *out_char));
294
295/**
296 Releases the string iterator object specified.
297
298 @param iter String iterator object to handle the release.
299 @return Status of performed operation
300 @retval false success
301 @retval true failure
302*/
303DECLARE_METHOD(void, iterator_destroy, (my_h_string_iterator iter));
304END_SERVICE_DEFINITION(mysql_string_iterator)
305
306/**
307 Service for String c_type.
308*/
309BEGIN_SERVICE_DEFINITION(mysql_string_ctype)
310/**
311 Checks if character on current position the iterator points to is an upper
312 case.
313
314 @param iter String iterator object handle to advance.
315 @param [out] out Pointer to bool value to store if character is an upper
316 case.
317 @return Status of performed operation
318 @retval false success
319 @retval true failure
320*/
321DECLARE_BOOL_METHOD(is_upper, (my_h_string_iterator iter, bool *out));
322
323/**
324 Checks if character on current position the iterator points to is a lower
325 case.
326
327 @param iter String iterator object handle to advance.
328 @param [out] out Pointer to bool value to store if character is a lower
329 case.
330 @return Status of performed operation
331 @retval false success
332 @retval true failure
333*/
334DECLARE_BOOL_METHOD(is_lower, (my_h_string_iterator iter, bool *out));
335
336/**
337 Checks if character on current position the iterator points to is a digit.
338
339 @param iter String iterator object handle to advance.
340 @param [out] out Pointer to bool value to store if character is a digit.
341 @return Status of performed operation
342 @retval false success
343 @retval true failure
344*/
346END_SERVICE_DEFINITION(mysql_string_ctype)
347
348/* mysql_string_manipulation_v1 service. */
349
350/**
351 Reset a string to the empty string.
352
353 @param [in, out] s The string to reset.
354*/
356
357BEGIN_SERVICE_DEFINITION(mysql_string_reset)
359END_SERVICE_DEFINITION(mysql_string_reset)
360
361/**
362 Append a string.
363
364 @param [in, out] s1 The string to append to.
365 @param [in] s2 The string to append.
366*/
368 my_h_string s2);
369
370BEGIN_SERVICE_DEFINITION(mysql_string_append)
372END_SERVICE_DEFINITION(mysql_string_append)
373
374/**
375 Compare two strings.
376
377 @param [in] s1 First string to compare.
378 @param [in] s2 Second string to compare.
379 @param [out] cmp Comparison result (negative, zero, or positive) .
380*/
382 my_h_string s2,
383 int *cmp);
384BEGIN_SERVICE_DEFINITION(mysql_string_compare)
386END_SERVICE_DEFINITION(mysql_string_compare)
387
388/**
389 Access the string raw data.
390 The raw data returned is usable only while the string object
391 is valid.
392
393 @param [in] s String
394 @param [out] buffer_pointer String raw buffer.
395 @param [out] buffer_length String raw buffer size.
396 @param [out] buffer_charset String character set.
397*/
399 my_h_string s, const char **buffer_pointer, size_t *buffer_length,
400 CHARSET_INFO_h *buffer_charset);
401
402BEGIN_SERVICE_DEFINITION(mysql_string_get_data_in_charset)
404END_SERVICE_DEFINITION(mysql_string_get_data_in_charset)
405
406#endif /* MYSQL_STRING_SERVICE_H */
int get_byte(azio_stream *s)
Definition: azio.cc:225
Definition: item_cmpfunc.h:1646
static int cmp(Bigint *a, Bigint *b)
Definition: dtoa.cc:1064
static bool is_digit(unsigned codepoint)
Return true if the codepoint is a Unicode digit.
Definition: json_path.cc:677
Some integer typedefs for easier portability.
uint64_t uint64
Definition: my_inttypes.h:68
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:398
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:174
CHARSET_INFO_h(* get_charset_utf8mb4_v1_t)()
Get the "utf8mb4" CHARSET_INFO.
Definition: mysql_string.h:35
CHARSET_INFO_h(* get_charset_by_name_v1_t)(const char *name)
Find a CHARSET_INFO by name.
Definition: mysql_string.h:41
mysql_service_status_t(* mysql_string_reset_v1_t)(my_h_string s)
Reset a string to the empty string.
Definition: mysql_string.h:355
struct CHARSET_INFO_h_imp * CHARSET_INFO_h
Definition: mysql_string.h:30
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:189
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:381
mysql_service_status_t(* mysql_string_append_v1_t)(my_h_string s1, my_h_string s2)
Append a string.
Definition: mysql_string.h:367
std::string HARNESS_EXPORT reset()
get 'reset attributes' ESC sequence.
Definition: vt100.cc:36
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:75
static mysql_service_status_t get(reference_caching_cache cache, unsigned service_name_index, const my_h_service **refs) noexcept
Definition: component.cc:113
static mysql_service_status_t create(const char *service_names[], reference_caching_channel *out_channel) noexcept
Definition: component.cc:35
static mysql_service_status_t destroy(reference_caching_channel channel) noexcept
Definition: component.cc:49
static int compare(size_t a, size_t b)
Function to compare two size_t integers for their relative order.
Definition: rpl_utility.cc:104
#define DECLARE_METHOD(retval, name, args)
Declares a method as a part of the Service definition.
Definition: service.h:102
int mysql_service_status_t
Specific type for the service status return values.
Definition: service.h:33
#define END_SERVICE_DEFINITION(name)
A macro to end the last Service definition started with the BEGIN_SERVICE_DEFINITION macro.
Definition: service.h:90
#define BEGIN_SERVICE_DEFINITION(name)
Declares a new Service.
Definition: service.h:85
#define DEFINE_SERVICE_HANDLE(name)
Defines an object type that is meant for carrying handles to the implementation-specific objects used...
Definition: service.h:128
#define DECLARE_BOOL_METHOD(name, args)
Declares a method that returns bool as a part of the Service definition.
Definition: service.h:111
case opt name
Definition: sslopt-case.h:32
The string functions as a service to the mysql_server component.
Definition: mysql_string_service.cc:45
Definition: mysql_string_service.cc:47
unsigned int uint
Definition: uca-dump.cc:29