mysqlpp::String Class Reference

A std::string work-alike that can convert itself from SQL text data formats to C++ data types. More...

#include <mystring.h>

Collaboration diagram for mysqlpp::String:

[legend]List of all members.

Public Types
typedef const char	value_type
	Type of the data stored in this object, when it is not equal to SQL null.
typedef unsigned int	size_type
	Type of "size" integers.
typedef const char *	const_iterator
	Type of iterators.
typedef const_iterator	iterator
	Same as const_iterator because the data cannot be changed.
Public Member Functions
	String ()
	Default constructor.
	String (const String &other)
	Copy ctor.
	String (const char *str, size_type len, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
	Full constructor.
	String (const std::string &str, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
	C++ string version of full ctor.
	String (const char *str, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
	Null-terminated C string version of full ctor.
	~String ()
	Destroy string.
void	assign (const char *str, size_type len, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
	Assign raw data to this object.
void	assign (const std::string &str, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
	Assign a C++ string to this object.
void	assign (const char *str, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
	Assign a C string to this object.
char	at (size_type pos) const
	Return a character within the string.
const_iterator	begin () const
	Return iterator pointing to the first character of the string.
const char *	c_str () const
	Return a const pointer to the string data.
template<class Type>
Type	conv (Type) const
	Template for converting the column data to most any numeric data type.
template<class T, class B>
Null< T, B >	conv (Null< T, B >) const
	Overload of conv() for types wrapped with Null<>.
int	compare (const String &other) const
	Lexically compare this string to another.
int	compare (const std::string &other) const
	Lexically compare this string to another.
int	compare (size_type pos, size_type num, std::string &other) const
	Lexically compare this string to another.
int	compare (const char *other) const
	Lexically compare this string to another.
int	compare (size_type pos, size_type num, const char *other) const
	Lexically compare this string to another.
const char *	data () const
	Raw access to the underlying buffer, with no C string interpretation.
const_iterator	end () const
	Return iterator pointing to one past the last character of the string.
bool	escape_q () const
	Returns true if data of this type should be escaped, false otherwise.
bool	is_null () const
	Returns true if this object is a SQL null.
void	it_is_null ()
	Set a flag indicating that this object is a SQL null.
size_type	length () const
	Return number of characters in the string.
size_type	max_size () const
	Return the maximum number of characters in the string.
bool	quote_q () const
	Returns true if data of this type should be quoted, false otherwise.
size_type	size () const
	Return number of characters in string.
void	strip_leading_blanks (std::string &s) const
	Returns a copy of our internal string without leading blanks.
void	to_string (std::string &s) const
	Copies this object's data into a C++ string.
mysql_type_info	type () const
	Get this object's current MySQL type.
String &	operator= (const std::string &rhs)
	Assignment operator, from C++ string.
String &	operator= (const char *str)
	Assignment operator, from C string.
String &	operator= (const String &other)
	Assignment operator, from other String.
char	operator[] (size_type pos) const
	Return a character within the string.
	operator const char * () const
	Returns a const char pointer to the object's raw data.
	operator signed char () const
	Converts this object's string data to a signed char.
	operator unsigned char () const
	Converts this object's string data to an unsigned char.
	operator int () const
	Converts this object's string data to an int.
	operator unsigned int () const
	Converts this object's string data to an unsigned int.
	operator short int () const
	Converts this object's string data to a short int.
	operator unsigned short int () const
	Converts this object's string data to an unsigned short int.
	operator long int () const
	Converts this object's string data to a long int.
	operator unsigned long int () const
	Converts this object's string data to an unsigned long int.
	operator longlong () const
	Converts this object's string data to the platform- specific 'longlong' type, usually a 64-bit integer.
	operator ulonglong () const
	Converts this object's string data to the platform- specific 'ulonglong' type, usually a 64-bit unsigned integer.
	operator float () const
	Converts this object's string data to a float.
	operator double () const
	Converts this object's string data to a double.
	operator bool () const
	Converts this object's string data to a bool.
	operator Date () const
	Converts this object's string data to a mysqlpp::Date.
	operator DateTime () const
	Converts this object's string data to a mysqlpp::DateTime.
	operator Time () const
	Converts this object's string data to a mysqlpp::Time.
template<class T, class B>
	operator Null () const
	Converts the String to a nullable data type.
Friends
class	SQLTypeAdapter

---

Detailed Description

A std::string work-alike that can convert itself from SQL text data formats to C++ data types.

This class is an intermediate form for a SQL field, normally converted to a more useful native C++ type, not used directly. The only exception is in dealing with BLOB data, which stays in String form for efficiency and to avoid corrupting the data with facile conversions. Even then, it's best to use it through the typedef aliases like sql_blob in sql_types.h, in case we later change this underlying representation.

String's implicit conversion operators let you can use these objects naturally:

 String("12.86") + 2.0 

That will give you 14.86 (approximately) as you expect, but be careful not to get tripped up by C++'s type conversion rules. If you had said this instead:

 String("12.86") + 2 

the result would be 14 because 2 is an integer, and C++'s type conversion rules put the String object in an integer context.

You can disable the operator overloads that allow these things by defining MYSQLPP_NO_BINARY_OPERS.

This class also has some basic information about the type of data stored in it, to allow it to do the conversions more intelligently than a trivial implementation would allow.

---

Constructor & Destructor Documentation

mysqlpp::String::String

(

)

[inline]

Default constructor.

An object constructed this way is essentially useless, but sometimes you just need to construct a default object.

mysqlpp::String::String

(

const String &

other

)

[inline]

Copy ctor.

Parameters:

other

the other String object

This ctor only copies the pointer to the other String's data buffer and increments its reference counter. If you need a deep copy, use one of the ctors that takes a string.

mysqlpp::String::String	(	const char *	str,
		size_type	len,
		mysql_type_info	type = mysql_type_info::string_type,
		bool	is_null = false
	)			[inline, explicit]

Full constructor.

Parameters:

	str	the string this object represents, or 0 for SQL null
	len	the length of the string; embedded nulls are legal
	type	MySQL type information for data within str
	is_null	string represents a SQL null, not literal data

The resulting object will contain a copy of the string buffer. The buffer will actually be 1 byte longer than the value given for len, to hold a null terminator for safety. We do this because this ctor may be used for things other than null-terminated C strings. (e.g. BLOB data)

mysqlpp::String::String	(	const std::string &	str,
		mysql_type_info	type = mysql_type_info::string_type,
		bool	is_null = false
	)			[inline, explicit]

C++ string version of full ctor.

Parameters:

	str	the string this object represents, or 0 for SQL null
	type	MySQL type information for data within str
	is_null	string represents a SQL null, not literal data

The resulting object will contain a copy of the string buffer.

mysqlpp::String::String	(	const char *	str,
		mysql_type_info	type = mysql_type_info::string_type,
		bool	is_null = false
	)			[inline, explicit]

Null-terminated C string version of full ctor.

Parameters:

	str	the string this object represents, or 0 for SQL null
	type	MySQL type information for data within str
	is_null	string represents a SQL null, not literal data

The resulting object will contain a copy of the string buffer.

---

Member Function Documentation

void mysqlpp::String::assign	(	const char *	str,
		mysql_type_info	type = mysql_type_info::string_type,
		bool	is_null = false
	)			[inline]

Assign a C string to this object.

This parallels the ctor with the same parameters, for when you must do a 2-step create, or when you want to reassign the data without creating a String temporary to get around the fact that operator=() can only take one parameter.

void mysqlpp::String::assign	(	const std::string &	str,
		mysql_type_info	type = mysql_type_info::string_type,
		bool	is_null = false
	)			[inline]

Assign a C++ string to this object.

This parallels the ctor with the same parameters, for when you must do a 2-step create, or when you want to reassign the data without creating a String temporary to get around the fact that operator=() can only take one parameter.

void mysqlpp::String::assign	(	const char *	str,
		size_type	len,
		mysql_type_info	type = mysql_type_info::string_type,
		bool	is_null = false
	)			[inline]

Assign raw data to this object.

This parallels the ctor with the same parameters, for when you must do a 2-step create, or when you want to reassign the data without creating a String temporary to get around the fact that operator=() can only take one parameter.

char mysqlpp::String::at

(

size_type

pos

)

const

Return a character within the string.

Unlike operator[](), this function throws an std::out_of_range exception if the index isn't within range.

int mysqlpp::String::compare	(	size_type	pos,
		size_type	num,
		const char *	other
	)			const

Lexically compare this string to another.

Parameters:

	pos	position within this string to begin comparison
	num	maximum number of characters within this string to use in comparison
	other	string to compare against this one

Return values:

	<	0 if this string is lexically "less than" other
	0	if this string is equal to other
	>	0 if this string is lexically "greater than" other

int mysqlpp::String::compare

(

const char *

other

)

const

Lexically compare this string to another.

Parameters:

other

string to compare against this one

See also:

compare(size_type, size_type, const char*)

int mysqlpp::String::compare	(	size_type	pos,
		size_type	num,
		std::string &	other
	)			const

Lexically compare this string to another.

Parameters:

	pos	position within this string to begin comparison
	num	maximum number of characters within this string to use in comparison
	other	string to compare against this one

See also:

compare(size_type, size_type, const char*)

int mysqlpp::String::compare

(

const std::string &

other

)

const

Lexically compare this string to another.

Parameters:

other

string to compare against this one

See also:

compare(size_type, size_type, const char*)

int mysqlpp::String::compare

(

const String &

other

)

const

Lexically compare this string to another.

Parameters:

other

string to compare against this one

See also:

compare(size_type, size_type, const char*)

template<class T, class B>

Null<T, B> mysqlpp::String::conv

(

Null< T, B >

)

const [inline]

Overload of conv() for types wrapped with Null<>.

If the String object was initialized with some string we recognize as a SQL null, we just return a copy of the global 'null' object converted to the requested type. Otherwise, we return the String's value wrapped in the Null<> template.

size_type mysqlpp::String::max_size

(

)

const [inline]

Return the maximum number of characters in the string.

Because this is a const string, this is just an alias for size(); its size is always equal to the amount of data currently stored.

template<class T, class B>

mysqlpp::String::operator Null

(

)

const [inline]

Converts the String to a nullable data type.

This is just an implicit version of conv(Null<T, B>)

String& mysqlpp::String::operator=

(

const String &

other

)

[inline]

Assignment operator, from other String.

This only copies the pointer to the other String's data buffer and increments its reference counter. If you need a deep copy, assign a string to this object instead.

String& mysqlpp::String::operator=

(

const char *

str

)

[inline]

Assignment operator, from C string.

This creates a copy of the entire string, not just a copy of the pointer.

char mysqlpp::String::operator[]

(

size_type

pos

)

const

Return a character within the string.

Unlike at(), this access method doesn't check the index for sanity.

void mysqlpp::String::to_string

(

std::string &

s

)

const

Copies this object's data into a C++ string.

If you know the data doesn't contain null characters (i.e. it's a typical string, not BLOB data), it's more efficient to just assign this object to anything taking const char*. (Or equivalently, call the data() method.) This copies a pointer to a buffer instead of copying the buffer's contents.

---

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

• mystring.h
• mystring.cpp

---