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:

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_INFO *	charset () 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
String &	operator= (const String &s)
String &	operator= (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_INFO *	m_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)
String *	copy_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

nr

Number

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

str	The string whose internal buffer is to be copied.

Return values

false	Success.
true	Memory 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

root	MEM_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_length	The requested string size in characters, excluding any null terminator.
force_on_heap	If the caller wants String's 'str' buffer to be on the heap in all cases.

Return values

false	Either 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.
true	An 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_length

The requested string size in characters, excluding any null terminator.

Return values

false	Either 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.
true	An 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_length	Length of string to copy.
	from_cs	Character set to copy from
	to_cs	Character set to copy to
[out]	offset	Returns 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

str	Pointer to the new buffer.
arg_length	Length of the new buffer in characters, excluding any null character.
cs	Character 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

num	the double value
decimals	the number of decimals
cs	the 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

search	substring to search for
offset	starting point, bytes from the start of the string

Returns

byte offset to the substring from the start of this string

Return values

-1	if 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

search	substring to search for
offset	starting point, bytes from the start of the string

Returns

byte offset to the substring from the start of this string

Return values

-1	if 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

to	destination string
from	source string
from_length	destination 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:

• include/sql_string.h
• sql-common/sql_string.cc