MySQL++: mysqlpp::String Class Reference
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>`

## Public Types

typedef const char | value_type
| Type of the data stored in this object, when it is not equal to SQL null.
typedef size_t | 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. More...
| String (const String &other)
| Copy ctor. More...
| String (const char *str, size_type len, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
| Full constructor. More...
| String (const std::string &str, mysql_type_info type=mysql_type_info::string_type, bool is_null=false)
| C++ string version of full ctor. More...
| 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. More...
| ~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. More...
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. More...
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. More...
char | at (size_type pos) const
| Return a character within the string. More...
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<> More...
int | compare (const String &other) const
| Lexically compare this string to another. More...
int | compare (const std::string &other) const
| Lexically compare this string to another. More...
int | compare (size_type pos, size_type num, std::string &other) const
| Lexically compare this string to another. More...
int | compare (const char *other) const
| Lexically compare this string to another. More...
int | compare (size_type pos, size_type num, const char *other) const
| Lexically compare this string to another. More...
const char * | data () const
| Raw access to the underlying buffer, with no C string interpretation.
bool | empty () const
| Returns true if size() == 0.
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 bytes in the string. More...
size_type | max_size () const
| Return the maximum number of characters in the string. More...
bool | quote_q () const
| Returns true if data of this type should be quoted, false otherwise.
size_type | size () const
| Return number of bytes in string. More...
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. More...
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. More...
String & | operator= (const String &other)
| Assignment operator, from other String. More...
template<typename T >
bool | operator== (const T &rhs) const
| Equality comparison operator. More...
bool | operator== (const mysqlpp::null_type &) const
| Equality comparison operator. More...
template<typename T >
bool | operator != (const T &rhs) const
| Inequality comparison operator. More...
bool | operator != (const mysqlpp::null_type &) const
| Inequality comparison operator. More...
char | operator [] (size_type pos) const
| Return a character within the string. More...
| 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< T, B > () const
| Converts the String to a nullable data type. More...

## 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

## String() [1/5]

mysqlpp::String::String | ( |  | ) |

inline

Default constructor.

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

## String() [2/5]

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.

## String() [3/5]

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)

## String() [4/5]

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.

## String() [5/5]

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

## assign() [1/3]

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.

## assign() [2/3]

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.

## assign() [3/3]

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.

## at()

char mysqlpp::String::at | ( | size_type | pos | ) | const

Return a character within the string.

Exceptions

  mysqlpp::BadIndex | if the row is not initialized or there are less than `i` fields in the row.

References size().

## compare() [1/5]

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*)

References length().

Referenced by compare().

## compare() [2/5]

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*)

References compare(), and length().

## compare() [3/5]

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*)

References compare().

## compare() [4/5]

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*)

References compare(), and length().

## compare() [5/5]

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

References data(), and length().

## conv()

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.

## length()

String::size_type mysqlpp::String::length | ( |  | ) | const

Return number of bytes in the string.

Note that this doesn't count the number of characters in the string. If your database is configured to use an 8-bit character set, this is a distinction without a difference. But, if you're using UTF-8 in the database, you will need to "widen" the UTF-8 data to use a fixed-size character set like UCS-2 and count the characters that way. You might use std::wstring, for example.

Referenced by compare().

## max_size()

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.

## operator !=() [1/2]

template<typename T >

bool mysqlpp::String::operator != | ( | const T & | rhs | ) | const

inline

Inequality comparison operator.

For comparing this object to any of the data types we have a compare() overload for.

## operator !=() [2/2]

bool mysqlpp::String::operator != | ( | const mysqlpp::null_type & |  | ) | const

inline

Inequality comparison operator.

For checking object against MySQL++'s global `null` constant

## operator []()

char mysqlpp::String::operator [] | ( | size_type | pos | ) | const

inline

Return a character within the string.

This function is just syntactic sugar, wrapping the at() method.

Exceptions

  mysqlpp::BadIndex | if the string is not initialized or there are less than `i` fields in the string.

## operator Null< T, B >()

template<class T , class B >

mysqlpp::String::operator Null< T, B > | ( |  | ) | const

inline

Converts the String to a nullable data type.

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

## operator=() [1/2]

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.

References mysqlpp::mysql_type_info::string_type.

## operator=() [2/2]

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.

## operator==() [1/2]

template<typename T >

bool mysqlpp::String::operator== | ( | const T & | rhs | ) | const

inline

Equality comparison operator.

For comparing this object to any of the data types we have a compare() overload for.

## operator==() [2/2]

bool mysqlpp::String::operator== | ( | const mysqlpp::null_type & |  | ) | const

inline

Equality comparison operator.

For checking object against MySQL++'s global `null` constant

## size()

size_type mysqlpp::String::size | ( |  | ) | const

inline

Return number of bytes in string.

See commentary for length() about the difference between bytes and characters.

Referenced by at().

## to_string()

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