libtabula::SQLTypeAdapter Class Reference

Converts many different data types to strings suitable for use in SQL queries. More...

#include <stadapter.h>

Collaboration diagram for libtabula::SQLTypeAdapter:
Collaboration graph
[legend]

List of all members.

Public Types

typedef size_t size_type
 size of length values

Public Member Functions

 SQLTypeAdapter ()
 Default constructor; empty string.
 SQLTypeAdapter (const SQLTypeAdapter &other)
 Copy ctor.
 SQLTypeAdapter (const String &str, bool processed=false)
 Create a copy of a Libtabula string.
 SQLTypeAdapter (const std::string &str, bool processed=false)
 Create a copy of a C++ string.
 SQLTypeAdapter (const char *str, bool processed=false)
 Create a copy of a null-terminated C string.
 SQLTypeAdapter (const char *str, int len, bool processed=false)
 Create a copy of an arbitrary block of data.
 SQLTypeAdapter (char c)
 Create a single-character string.
 SQLTypeAdapter (tiny_int< signed char > i)
 Create a string representation of SQL TINYINT.
 SQLTypeAdapter (tiny_int< unsigned char > i)
 Create a string representation of SQL TINYINT UNSIGNED.
 SQLTypeAdapter (short i)
 Create a string representation of a short int value.
 SQLTypeAdapter (unsigned short i)
 Create a string representation of an unsigned short int value.
 SQLTypeAdapter (int i)
 Create a string representation of an int value.
 SQLTypeAdapter (unsigned i)
 Create a string representation of an unsigned int value.
 SQLTypeAdapter (long i)
 Create a string representation of a long int value.
 SQLTypeAdapter (unsigned long i)
 Create a string representation of an unsigned long int value.
 SQLTypeAdapter (longlong i)
 Create a string representation of a longlong value.
 SQLTypeAdapter (ulonglong i)
 Create a string representation of an unsigned longlong value.
 SQLTypeAdapter (float i)
 Create a string representation of a float value.
 SQLTypeAdapter (double i)
 Create a string representation of a double value.
 SQLTypeAdapter (const Date &d)
 Create a SQL string representation of a date.
 SQLTypeAdapter (const DateTime &dt)
 Create a SQL string representation of a date and time.
 SQLTypeAdapter (const Time &t)
 Create a SQL string representation of a time.
 SQLTypeAdapter (const null_type &i)
 Create object representing SQL NULL.
SQLTypeAdapteroperator= (const SQLTypeAdapter &rhs)
 Standard assignment operator.
SQLTypeAdapteroperator= (const null_type &n)
 Replace contents of object with a SQL null.
 operator const char * () const
 Returns a const char pointer to the object's raw data.
SQLTypeAdapterassign (const SQLTypeAdapter &sta)
 Copies another SQLTypeAdapter's data buffer into this object.
SQLTypeAdapterassign (const char *pc, int len=-1)
 Copies a C string or a raw buffer into this object.
SQLTypeAdapterassign (const null_type &n)
 Replaces contents of object with a SQL null.
char at (size_type i) const throw (std::out_of_range)
 Returns the character at a given position within the string buffer.
int compare (const SQLTypeAdapter &other) const
 Compare the internal buffer to the given string.
int compare (const std::string &other) const
 Compare the internal buffer to the given string.
int compare (size_type pos, size_type num, std::string &other) const
 Compare the internal buffer to the given string.
int compare (const char *other) const
 Compare the internal buffer to the given string.
int compare (size_type pos, size_type num, const char *other) const
 Compare the internal buffer to the given string.
const char * data () const
 Return pointer to raw data buffer.
bool escape_q () const
 Returns true if we were initialized with a data type that must be escaped when used in a SQL query.
bool is_null () const
 Return true if buffer's contents represent a SQL null.
bool is_processed () const
 Returns true if the internal 'processed' flag is set.
size_type length () const
 Return number of bytes in data buffer.
size_type size () const
 alias for length()
bool quote_q () const
 Returns true if we were initialized with a data type that must be quoted when used in a SQL query.
int type_id () const
 Returns the type ID of the buffer's data.
void set_processed ()
 Turns on the internal 'is_processed_' flag.

Detailed Description

Converts many different data types to strings suitable for use in SQL queries.

This class provides implicit conversion between many C++ types and SQL-formatted string representations of that data without losing important type information. This class is not for direct use outside Libtabula itself. It exists for those interfaces in the library that need to accept a value of any reasonable data type which it will use in building a query string.

One major use for this is in the Query class interfaces for building template queries: they have to be generic with respect to argument type, but because we know we want the data in some kind of string form eventually, we don't need to templatize it. The interface can just use SQLTypeAdapter, which lets callers pass any reasonable data type. The adapter converts the passed value implicitly.

The other major use for this type is the quoting and escaping logic in Query's stream interface: rather than overload the << operators and the manipulators for every single type we know the rules for a priori, we just specialize the manipulators for SQLTypeAdapter. The conversion to SQLTypeAdapter stringizes the data, which we needed anyway for stream insertion, and holds enough type information so that the manipulator can decide whether to do automatic quoting and/or escaping.


Constructor & Destructor Documentation

libtabula::SQLTypeAdapter::SQLTypeAdapter ( const SQLTypeAdapter other  ) 

Copy ctor.

Parameters:
other the other SQLTypeAdapter object

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

libtabula::SQLTypeAdapter::SQLTypeAdapter ( const String str,
bool  processed = false 
)

Create a copy of a Libtabula string.

This does reference-counted buffer sharing with the other object. If you need a deep copy, pass the result of either String::c_str() or String::conv() instead, which will call one of the other string ctors.

libtabula::SQLTypeAdapter::SQLTypeAdapter ( char  c  ) 

Create a single-character string.

If you mean for c to be treated as a small integer, you should be using libtabula::tiny_int instead. It avoids the confusion in C++ between integer and character. See the documentation for tiny_int.h for details.


Member Function Documentation

SQLTypeAdapter & libtabula::SQLTypeAdapter::assign ( const null_type n  ) 

Replaces contents of object with a SQL null.

Parameters:
n typically, the Libtabula global object libtabula::null
Return values:
*this 
SQLTypeAdapter & libtabula::SQLTypeAdapter::assign ( const char *  pc,
int  len = -1 
)

Copies a C string or a raw buffer into this object.

Parameters:
pc Pointer to char buffer to copy
len Number of characters to copy; default tells function to use the return value of strlen() instead.
Return values:
*this If you give the len parameter, this function will treat pc as a pointer to an array of char, not as a C string. It only treats null characters as special when you leave len at its default.

References libtabula::mysql_type_info::string_type.

SQLTypeAdapter & libtabula::SQLTypeAdapter::assign ( const SQLTypeAdapter sta  ) 

Copies another SQLTypeAdapter's data buffer into this object.

Parameters:
sta Other object to copy
Return values:
*this Detaches this object from its internal buffer and attaches itself to the other object's buffer, with reference counting on each side. If you need a deep copy, call one of the assign() overloads taking a C or C++ string instead.

Referenced by operator=().

char libtabula::SQLTypeAdapter::at ( size_type  i  )  const throw (std::out_of_range)

Returns the character at a given position within the string buffer.

Exceptions:
libtabula::BadIndex if the internal buffer is not initialized (default ctor called, and no subsequent assignment) or if there are not at least i + 1 characters in the buffer.

WARNING: The throw-spec is incorrect, but it can't be changed until v4, where we can break the ABI. Throw-specs shouldn't be relied on anyway.

int libtabula::SQLTypeAdapter::compare ( size_type  pos,
size_type  num,
const char *  other 
) const

Compare the internal buffer to the given string.

Works just like string::compare(size_type, size_type, const char*).

References data().

int libtabula::SQLTypeAdapter::compare ( const char *  other  )  const

Compare the internal buffer to the given string.

Works just like string::compare(const char*).

References compare(), and length().

int libtabula::SQLTypeAdapter::compare ( size_type  pos,
size_type  num,
std::string &  other 
) const

Compare the internal buffer to the given string.

Works just like string::compare(size_type, size_type, std::string&).

References compare().

int libtabula::SQLTypeAdapter::compare ( const std::string &  other  )  const

Compare the internal buffer to the given string.

Works just like string::compare(const std::string&).

References compare(), and length().

int libtabula::SQLTypeAdapter::compare ( const SQLTypeAdapter other  )  const

Compare the internal buffer to the given string.

Works just like string::compare(const std::string&).

References length().

Referenced by compare().

bool libtabula::SQLTypeAdapter::is_null (  )  const [inline]

Return true if buffer's contents represent a SQL null.

The buffer's actual content will probably be "NULL" or something like it, but in the SQL data type system, a SQL null is distinct from a plain string with value "NULL".

bool libtabula::SQLTypeAdapter::is_processed (  )  const [inline]

Returns true if the internal 'processed' flag is set.

This is an implementation detail of template queries, used to prevent repeated processing of values.

SQLTypeAdapter & libtabula::SQLTypeAdapter::operator= ( const null_type n  ) 

Replace contents of object with a SQL null.

See also:
assign(const null_type&) for details

References assign().

SQLTypeAdapter & libtabula::SQLTypeAdapter::operator= ( const SQLTypeAdapter rhs  ) 

Standard assignment operator.

See also:
assign(const SQLTypeAdapter&) for details

References assign().

void libtabula::SQLTypeAdapter::set_processed (  )  [inline]

Turns on the internal 'is_processed_' flag.

This is an implementation detail of template queries, used to prevent repeated processing of values.

int libtabula::SQLTypeAdapter::type_id (  )  const

Returns the type ID of the buffer's data.

Values from type_info.h. At the moment, these are the same as the underlying MySQL C API type IDs, but it's not a good idea to count on this remaining the case.


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

Generated on 26 May 2014 for Libtabula by  doxygen 1.6.1