MySQL 9.0.0
Source Code Documentation
String Class Reference

Using this class is fraught with peril, and you need to be very careful when doing so. More...

#include <sql_string.h>

Inheritance diagram for String:
[legend]

Public Member Functions

 String ()
 
 String (size_t length_arg)
 
 String (const char *str, const CHARSET_INFO *cs)
 
 String (const char *str, size_t len, const CHARSET_INFO *cs)
 
 String (char *str, size_t len, const CHARSET_INFO *cs)
 
 String (const String &str)
 
 String (String &&str) noexcept
 
 ~String ()
 
void set_charset (const CHARSET_INFO *charset_arg)
 
const CHARSET_INFOcharset () const
 
size_t length () const
 
size_t alloced_length () const
 
const char & operator[] (size_t i) const
 
char & operator[] (size_t i)
 
void length (size_t len)
 
bool is_empty () const
 
void mark_as_const ()
 
const char * ptr () const
 
char * ptr ()
 
char * c_ptr ()
 
char * c_ptr_quick ()
 
char * c_ptr_safe ()
 Returns a pointer to a C-style null-terminated string. More...
 
LEX_STRING lex_string ()
 
LEX_CSTRING lex_cstring () const
 
void set (String &str, size_t offset, size_t arg_length)
 
void set (char *str, size_t arg_length, const CHARSET_INFO *cs)
 Points the internal buffer to the supplied one. More...
 
void set (const char *str, size_t arg_length, const CHARSET_INFO *cs)
 
bool set_ascii (const char *str, size_t arg_length)
 
void set_quick (char *str, size_t arg_length, const CHARSET_INFO *cs)
 
bool set_int (longlong num, bool unsigned_flag, const CHARSET_INFO *cs)
 
bool set (longlong num, const CHARSET_INFO *cs)
 
bool set (ulonglong num, const CHARSET_INFO *cs)
 
bool set_real (double num, uint decimals, const CHARSET_INFO *cs)
 Sets the contents of this string to the string representation of the given double value. More...
 
void chop ()
 
void mem_claim (bool claim)
 
void mem_free ()
 
bool alloc (size_t arg_length)
 
bool real_alloc (size_t arg_length)
 
bool mem_realloc (size_t arg_length, bool force_on_heap=false)
 Allocates a new buffer on the heap for this String. More...
 
void shrink (size_t arg_length)
 
bool is_alloced () const
 
Stringoperator= (const String &s)
 
Stringoperator= (String &&s) noexcept
 
void takeover (String &s)
 Takeover the buffer owned by another string. More...
 
bool copy ()
 
bool copy (const String &s)
 Copies the internal buffer from str. More...
 
bool copy (const char *s, size_t arg_length, const CHARSET_INFO *cs)
 
bool copy (const char *s, size_t arg_length, const CHARSET_INFO *from_cs, const CHARSET_INFO *to_cs, uint *errors)
 Copies the character data into this String, with optional character set conversion. More...
 
bool needs_conversion (const CHARSET_INFO *cs_to) const
 
bool is_valid_string (const CHARSET_INFO *cs_to) const
 
bool copy_aligned (const char *s, size_t arg_length, size_t offset, const CHARSET_INFO *cs)
 
bool set_or_copy_aligned (const char *s, size_t arg_length, const CHARSET_INFO *cs)
 
bool append (const String &s)
 
bool append (std::string_view s)
 
bool append (LEX_STRING *ls)
 
bool append (Simple_cstring str)
 
bool append (const char *s, size_t arg_length)
 
bool append (const char *s, size_t arg_length, const CHARSET_INFO *cs)
 
bool append_ulonglong (ulonglong val)
 Append an unsigned longlong to the string. More...
 
bool append_longlong (longlong val)
 Append a signed longlong to the string. More...
 
bool append_with_prefill (const char *s, size_t arg_length, size_t full_length, char fill_char)
 
bool append_parenthesized (int64_t nr)
 Append a parenthesized number to String. More...
 
int strstr (const String &search, size_t offset=0) const
 Search for a substring. More...
 
int strrstr (const String &search, size_t offset=0) const
 Reverse search for a substring. More...
 
String substr (int offset, int count) const
 Returns substring of given characters length, starting at given character offset. More...
 
bool replace (size_t offset, size_t arg_length, const char *to, size_t length)
 
bool replace (size_t offset, size_t arg_length, const String &to)
 
bool append (char chr)
 
bool fill (size_t max_length, char fill)
 
size_t numchars () const
 
size_t charpos (size_t i, size_t offset=0) const
 
bool reserve (size_t space_needed)
 
bool reserve (size_t space_needed, size_t grow_by)
 
char * prep_append (size_t arg_length, size_t step_alloc)
 
bool append (const char *s, size_t arg_length, size_t step_alloc)
 
void print (String *print) const
 
void swap (String &s) noexcept
 
bool uses_buffer_owned_by (const String *s) const
 
bool is_ascii () const
 
char * dup (MEM_ROOT *root) const
 Make a zero-terminated copy of our value,allocated in the specified MEM_ROOT. More...
 

Static Public Member Functions

static void * operator new (size_t size, MEM_ROOT *mem_root, const std::nothrow_t &arg=std::nothrow) noexcept
 
static void operator delete (void *ptr_arg, size_t size)
 
static void operator delete (void *, MEM_ROOT *, const std::nothrow_t &) noexcept
 
static bool needs_conversion (size_t arg_length, const CHARSET_INFO *cs_from, const CHARSET_INFO *cs_to, size_t *offset)
 Checks that the source string can be just copied to the destination string without conversion. More...
 
static bool needs_conversion_on_storage (size_t arg_length, const CHARSET_INFO *cs_from, const CHARSET_INFO *cs_to)
 

Private Member Functions

size_t next_realloc_exp_size (size_t sz)
 
bool mem_realloc_exp (size_t arg_length)
 This function is used by the various append() and replace() member functions, to ensure that functions have amortized constant cost. More...
 

Private Attributes

char * m_ptr
 
size_t m_length
 
const CHARSET_INFOm_charset
 
uint32 m_alloced_length
 
bool m_is_alloced
 

Friends

int sortcmp (const String *a, const String *b, const CHARSET_INFO *cs)
 
int stringcmp (const String *a, const String *b)
 
Stringcopy_if_not_alloced (String *to, String *from, size_t from_length)
 Makes a copy of a String's buffer unless it's already heap-allocated. More...
 

Detailed Description

Using this class is fraught with peril, and you need to be very careful when doing so.

In particular, copy construction and assignment does not do a deep nor a shallow copy; instead, it makes a reference to the original string that will be invalid as soon as that string goes out of scope. (Move constructiong and assignment is safe, though.) In general, it is probably better not to use this class at all if you can avoid it.

Constructor & Destructor Documentation

◆ String() [1/7]

String::String ( )
inline

◆ String() [2/7]

String::String ( size_t  length_arg)
inlineexplicit

◆ String() [3/7]

String::String ( const char *  str,
const CHARSET_INFO cs 
)
inline

◆ String() [4/7]

String::String ( const char *  str,
size_t  len,
const CHARSET_INFO cs 
)
inline

◆ String() [5/7]

String::String ( char *  str,
size_t  len,
const CHARSET_INFO cs 
)
inline

◆ String() [6/7]

String::String ( const String str)
inline

◆ String() [7/7]

String::String ( String &&  str)
inlinenoexcept

◆ ~String()

String::~String ( )
inline

Member Function Documentation

◆ alloc()

bool String::alloc ( size_t  arg_length)
inline

◆ alloced_length()

size_t String::alloced_length ( ) const
inline

◆ append() [1/8]

bool String::append ( char  chr)
inline

◆ append() [2/8]

bool String::append ( const char *  s,
size_t  arg_length 
)

◆ append() [3/8]

bool String::append ( const char *  s,
size_t  arg_length,
const CHARSET_INFO cs 
)

◆ append() [4/8]

bool String::append ( const char *  s,
size_t  arg_length,
size_t  step_alloc 
)
inline

◆ append() [5/8]

bool String::append ( const String s)

◆ append() [6/8]

bool String::append ( LEX_STRING ls)
inline

◆ append() [7/8]

bool String::append ( Simple_cstring  str)
inline

◆ append() [8/8]

bool String::append ( std::string_view  s)
inline

◆ append_longlong()

bool String::append_longlong ( longlong  val)

Append a signed longlong to the string.

◆ append_parenthesized()

bool String::append_parenthesized ( int64_t  nr)

Append a parenthesized number to String.

Used in various pieces of SHOW related code.

Parameters
nrNumber

◆ append_ulonglong()

bool String::append_ulonglong ( ulonglong  val)

Append an unsigned longlong to the string.

◆ append_with_prefill()

bool String::append_with_prefill ( const char *  s,
size_t  arg_length,
size_t  full_length,
char  fill_char 
)

◆ c_ptr()

char * String::c_ptr ( )
inline

◆ c_ptr_quick()

char * String::c_ptr_quick ( )
inline

◆ c_ptr_safe()

char * String::c_ptr_safe ( )
inline

Returns a pointer to a C-style null-terminated string.

The function is "safe" in the sense that the returned string is guaranteed to be null-terminated (as opposed to c_ptr_quick()). However, in terms of memory safety, this function might perform a heap allocation, so using it necessitates manual cleanup.

Note
One potential pitfall when using this function happens when calling c_ptr_safe() on a String object from the parser. In this case the internal m_ptr string is already allocated on a MEM_ROOT and is cleaned up as part of the query lifecycle. This cleanup is performed by simply clearing the MEM_ROOT (freeing its allocated memory) and does not involve destructing the String object. So in the case when the parser works with (ptr, length)-style strings that are placed in String objects and m_length = m_allocated_length we get a heap allocation when calling c_ptr_safe(), even if just to read the contents of the string, and this newly allocated memory is not on the same MEM_ROOT as the original string, and thus we get a memory leak if we do not make sure to free it.
Returns
Pointer to null-terminated string.

◆ charpos()

size_t String::charpos ( size_t  i,
size_t  offset = 0 
) const

◆ charset()

const CHARSET_INFO * String::charset ( ) const
inline

◆ chop()

void String::chop ( )
inline

◆ copy() [1/4]

bool String::copy ( )

◆ copy() [2/4]

bool String::copy ( const char *  s,
size_t  arg_length,
const CHARSET_INFO cs 
)

◆ copy() [3/4]

bool String::copy ( const char *  str,
size_t  arg_length,
const CHARSET_INFO from_cs,
const CHARSET_INFO to_cs,
uint *  errors 
)

Copies the character data into this String, with optional character set conversion.

Returns
false ok true Could not allocate result buffer

◆ copy() [4/4]

bool String::copy ( const String str)

Copies the internal buffer from str.

If this String has a private heap allocated buffer where new data does not fit, a new buffer is allocated before copying and the old buffer freed. Character set information is also copied.

If str is the same as this and str doesn't own its buffer, a new buffer is allocated and it's owned by str.

Parameters
strThe string whose internal buffer is to be copied.
Return values
falseSuccess.
trueMemory allocation failed.

◆ copy_aligned()

bool String::copy_aligned ( const char *  s,
size_t  arg_length,
size_t  offset,
const CHARSET_INFO cs 
)

◆ dup()

char * String::dup ( MEM_ROOT root) const

Make a zero-terminated copy of our value,allocated in the specified MEM_ROOT.

Parameters
rootMEM_ROOT to allocate the result
Returns
allocated string or NULL

◆ fill()

bool String::fill ( size_t  max_length,
char  fill 
)

◆ is_alloced()

bool String::is_alloced ( ) const
inline

◆ is_ascii()

bool String::is_ascii ( ) const
inline

◆ is_empty()

bool String::is_empty ( ) const
inline

◆ is_valid_string()

bool String::is_valid_string ( const CHARSET_INFO cs_to) const
inline

◆ length() [1/2]

size_t String::length ( ) const
inline

◆ length() [2/2]

void String::length ( size_t  len)
inline

◆ lex_cstring()

LEX_CSTRING String::lex_cstring ( ) const
inline

◆ lex_string()

LEX_STRING String::lex_string ( )
inline

◆ mark_as_const()

void String::mark_as_const ( )
inline

◆ mem_claim()

void String::mem_claim ( bool  claim)
inline

◆ mem_free()

void String::mem_free ( )
inline

◆ mem_realloc()

bool String::mem_realloc ( size_t  alloc_length,
bool  force_on_heap = false 
)

Allocates a new buffer on the heap for this String.

  • If the String's internal buffer is privately owned and heap allocated, one of the following is performed.
    • If the requested length is greater than what fits in the buffer, a new buffer is allocated, data moved and the old buffer freed.
    • If the requested length is less or equal to what fits in the buffer, a null character is inserted at the appropriate position.
  • If the String does not keep a private buffer on the heap:
    • If the requested length is greater than what fits in the buffer, or force_on_heap is true, a new buffer is allocated, data is copied.
    • If the requested length is less or equal to what fits in the buffer, and force_on_heap is false, a null character is inserted at the appropriate position.

For C compatibility, the new string buffer is null terminated.

Parameters
alloc_lengthThe requested string size in characters, excluding any null terminator.
force_on_heapIf the caller wants String's 'str' buffer to be on the heap in all cases.
Return values
falseEither the copy operation is complete or, if the size of the new buffer is smaller than the currently allocated buffer (if one exists), no allocation occurred.
trueAn error occurred when attempting to allocate memory or memory allocation length exceeded allowed limit (4GB) for String Class.

◆ mem_realloc_exp()

bool String::mem_realloc_exp ( size_t  alloc_length)
private

This function is used by the various append() and replace() member functions, to ensure that functions have amortized constant cost.

Once we have started to allocate buffer on the heap, we increase the buffer size exponentially, rather than linearly.

Parameters
alloc_lengthThe requested string size in characters, excluding any null terminator.
Return values
falseEither the copy operation is complete or, if the size of the new buffer is smaller than the currently allocated buffer (if one exists), no allocation occurred.
trueAn error occurred when attempting to allocate memory.
See also
mem_realloc.

◆ needs_conversion() [1/2]

bool String::needs_conversion ( const CHARSET_INFO cs_to) const
inline

◆ needs_conversion() [2/2]

bool String::needs_conversion ( size_t  arg_length,
const CHARSET_INFO from_cs,
const CHARSET_INFO to_cs,
size_t *  offset 
)
inlinestatic

Checks that the source string can be just copied to the destination string without conversion.

Parameters
arg_lengthLength of string to copy.
from_csCharacter set to copy from
to_csCharacter set to copy to
[out]offsetReturns number of unaligned characters.
Returns
true if conversion is required, false otherwise.
Note
to_cs may be nullptr for "no conversion" if the system variable character_set_results is NULL.

◆ needs_conversion_on_storage()

bool String::needs_conversion_on_storage ( size_t  arg_length,
const CHARSET_INFO cs_from,
const CHARSET_INFO cs_to 
)
static

◆ next_realloc_exp_size()

size_t String::next_realloc_exp_size ( size_t  sz)
inlineprivate

◆ numchars()

size_t String::numchars ( ) const

◆ operator delete() [1/2]

static void String::operator delete ( void *  ,
MEM_ROOT ,
const std::nothrow_t &   
)
inlinestaticnoexcept

◆ operator delete() [2/2]

static void String::operator delete ( void *  ptr_arg,
size_t  size 
)
inlinestatic

◆ operator new()

static void * String::operator new ( size_t  size,
MEM_ROOT mem_root,
const std::nothrow_t &  arg = std::nothrow 
)
inlinestaticnoexcept

◆ operator=() [1/2]

String & String::operator= ( const String s)
inline

◆ operator=() [2/2]

String & String::operator= ( String &&  s)
inlinenoexcept

◆ operator[]() [1/2]

char & String::operator[] ( size_t  i)
inline

◆ operator[]() [2/2]

const char & String::operator[] ( size_t  i) const
inline

◆ prep_append()

char * String::prep_append ( size_t  arg_length,
size_t  step_alloc 
)
inline

◆ print()

void String::print ( String print) const

◆ ptr() [1/2]

char * String::ptr ( )
inline

◆ ptr() [2/2]

const char * String::ptr ( ) const
inline

◆ real_alloc()

bool String::real_alloc ( size_t  arg_length)

◆ replace() [1/2]

bool String::replace ( size_t  offset,
size_t  arg_length,
const char *  to,
size_t  length 
)

◆ replace() [2/2]

bool String::replace ( size_t  offset,
size_t  arg_length,
const String to 
)

◆ reserve() [1/2]

bool String::reserve ( size_t  space_needed)
inline

◆ reserve() [2/2]

bool String::reserve ( size_t  space_needed,
size_t  grow_by 
)

◆ set() [1/5]

void String::set ( char *  str,
size_t  arg_length,
const CHARSET_INFO cs 
)
inline

Points the internal buffer to the supplied one.

The old buffer is freed.

Parameters
strPointer to the new buffer.
arg_lengthLength of the new buffer in characters, excluding any null character.
csCharacter set to use for interpreting string data.
Note
The new buffer will not be null terminated.

◆ set() [2/5]

void String::set ( const char *  str,
size_t  arg_length,
const CHARSET_INFO cs 
)
inline

◆ set() [3/5]

bool String::set ( longlong  num,
const CHARSET_INFO cs 
)
inline

◆ set() [4/5]

void String::set ( String str,
size_t  offset,
size_t  arg_length 
)
inline

◆ set() [5/5]

bool String::set ( ulonglong  num,
const CHARSET_INFO cs 
)
inline

◆ set_ascii()

bool String::set_ascii ( const char *  str,
size_t  arg_length 
)

◆ set_charset()

void String::set_charset ( const CHARSET_INFO charset_arg)
inline

◆ set_int()

bool String::set_int ( longlong  num,
bool  unsigned_flag,
const CHARSET_INFO cs 
)

◆ set_or_copy_aligned()

bool String::set_or_copy_aligned ( const char *  s,
size_t  arg_length,
const CHARSET_INFO cs 
)

◆ set_quick()

void String::set_quick ( char *  str,
size_t  arg_length,
const CHARSET_INFO cs 
)
inline

◆ set_real()

bool String::set_real ( double  num,
uint  decimals,
const CHARSET_INFO cs 
)

Sets the contents of this string to the string representation of the given double value.

Parameters
numthe double value
decimalsthe number of decimals
csthe character set of the string
Returns
false on success, true on error

◆ shrink()

void String::shrink ( size_t  arg_length)
inline

◆ strrstr()

int String::strrstr ( const String search,
size_t  offset = 0 
) const

Reverse search for a substring.

Parameters
searchsubstring to search for
offsetstarting point, bytes from the start of the string
Returns
byte offset to the substring from the start of this string
Return values
-1if the substring is not found starting from the offset

◆ strstr()

int String::strstr ( const String search,
size_t  offset = 0 
) const

Search for a substring.

Parameters
searchsubstring to search for
offsetstarting point, bytes from the start of the string
Returns
byte offset to the substring from the start of this string
Return values
-1if the substring is not found starting from the offset

◆ substr()

String String::substr ( int  offset,
int  count 
) const

Returns substring of given characters length, starting at given character offset.

Note that parameter indexes are character indexes and not byte indexes.

◆ swap()

void String::swap ( String s)
noexcept

◆ takeover()

void String::takeover ( String s)
inline

Takeover the buffer owned by another string.

"this" becomes the owner of the buffer and is further responsible to free it. The string "s" is detached from the buffer (cleared).

Parameters
s- a String object to steal buffer from.

◆ uses_buffer_owned_by()

bool String::uses_buffer_owned_by ( const String s) const
inline

Friends And Related Function Documentation

◆ copy_if_not_alloced

String * copy_if_not_alloced ( String to,
String from,
size_t  from_length 
)
friend

Makes a copy of a String's buffer unless it's already heap-allocated.

If the buffer ('str') of 'from' is on the heap, this function returns 'from', possibly re-allocated to be at least from_length bytes long. It is also the case if from==to or to==NULL. Otherwise, this function makes and returns a copy of "from" into "to"; the buffer of "to" is heap-allocated; a pre-condition is that from->str and to->str must point to non-overlapping buffers. The logic behind this complex design, is that a caller, typically a val_str() function, sometimes has an input String ('from') which buffer it wants to modify; but this String's buffer may or not be heap-allocated; if it's not heap-allocated it is possibly in static storage or belongs to an outer context, and thus should not be modified; in that case the caller wants a heap-allocated copy which it can freely modify.

Parameters
todestination string
fromsource string
from_lengthdestination string will hold at least from_length bytes.

◆ sortcmp

int sortcmp ( const String a,
const String b,
const CHARSET_INFO cs 
)
friend

◆ stringcmp

int stringcmp ( const String a,
const String b 
)
friend

Member Data Documentation

◆ m_alloced_length

uint32 String::m_alloced_length
private

◆ m_charset

const CHARSET_INFO* String::m_charset
private

◆ m_is_alloced

bool String::m_is_alloced
private

◆ m_length

size_t String::m_length
private

◆ m_ptr

char* String::m_ptr
private

The documentation for this class was generated from the following files: