MySQL++ Reference Manual

MySQL++: mysqlpp::Query Class Reference

MySQL++ 3.2.4

Classes | Public Member Functions | Public Attributes | Friends | List of all members
mysqlpp::Query Class Reference

A class for building and executing SQL queries. More...

`#include <query.h>`

Inheritance diagram for mysqlpp::Query:
[legend]
Collaboration diagram for mysqlpp::Query:
[legend]

## Classes
class | MaxPacketInsertPolicy
| An insert policy object that triggers a new INSERT statement if the object to be added would cause the statement to exceed a maximum size. More...
class | RowCountInsertPolicy
| An insert policy object that triggers a new INSERT statement after a given number of rows have been inserted. More...
class | SizeThresholdInsertPolicy
| An insert policy object that triggers a new INSERT statement after a size threshold for the length of the INSERT statement is exceeded. More...

## Public Member Functions
| Query (Connection *c, bool te=true, const char *qstr=0)
| Create a new query object attached to a connection. More...
| Query (const Query &q)
| Create a new query object as a copy of another. More...
ulonglong | affected_rows ()
| Return the number of rows affected by the last query.
size_t | escape_string (std::string *ps, const char *original=0, size_t length=0) const
| Return a SQL-escaped version of a character buffer. More...
size_t | escape_string (char *escaped, const char *original, size_t length) const
| Return a SQL-escaped version of the given character buffer. More...
int | errnum () const
| Get the last error number that was set. More...
const char * | error () const
| Get the last error message that was set. More...
std::string | info ()
| Returns information about the most recently executed query.
ulonglong | insert_id ()
| Get ID generated for an AUTO_INCREMENT column in the previous INSERT query. More...
Query & | operator= (const Query &rhs)
| Assign another query's state to this object. More...
| operator void * () const
| Test whether the object has experienced an error condition. More...
bool | operator! () const
| Returns true if the query object is not in a bad state. More...
void | parse ()
| Treat the contents of the query string as a template query. More...
void | reset ()
| Reset the query object so that it can be reused. More...
bool | result_empty ()
| Returns true if the most recent result set was empty. More...
std::string | str ()
| Get built query as a C++ string.
std::string | str (const SQLTypeAdapter &arg0)
| Get built query as a C++ string with template query parameter substitution. More...
std::string | str (SQLQueryParms &p)
| Get built query as a null-terminated C++ string. More...
bool | exec ()
| Execute a built-up query. More...
bool | exec (const std::string &str)
| Execute a query. More...
SimpleResult | execute ()
| Execute built-up query. More...
SimpleResult | execute (SQLQueryParms &p)
| Execute template query using given parameters. More...
SimpleResult | execute (const SQLTypeAdapter &str)
| Execute a query that returns no rows. More...
SimpleResult | execute (const char *str, size_t len)
| Execute query in a known-length string of characters. This can include null characters. More...
UseQueryResult | use ()
| Execute a query that can return rows, with access to the rows in sequence. More...
UseQueryResult | use (SQLQueryParms &p)
| Execute a template query that can return rows, with access to the rows in sequence. More...
UseQueryResult | use (const SQLTypeAdapter &str)
| Execute a query that can return rows, with access to the rows in sequence. More...
UseQueryResult | use (const char *str, size_t len)
| Execute a query that can return rows, with access to the rows in sequence. More...
StoreQueryResult | store ()
| Execute a query that can return a result set. More...
StoreQueryResult | store (SQLQueryParms &p)
| Store results from a template query using given parameters. More...
StoreQueryResult | store (const SQLTypeAdapter &str)
| Execute a query that can return rows, returning all of the rows in a random-access container. More...
StoreQueryResult | store (const char *str, size_t len)
| Execute a query that can return rows, returning all of the rows in a random-access container. More...
template<typename Function >
Function | for_each (const SQLTypeAdapter &query, Function fn)
| Execute a query, and call a functor for each returned row. More...
template<typename Function >
Function | for_each (Function fn)
| Execute the query, and call a functor for each returned row. More...
template<class SSQLS , typename Function >
Function | for_each (const SSQLS &ssqls, Function fn)
| Run a functor for every row in a table. More...
template<class Sequence , typename Function >
Function | store_if (Sequence &con, const SQLTypeAdapter &query, Function fn)
| Execute a query, conditionally storing each row in a container. More...
template<class Sequence , class SSQLS , typename Function >
Function | store_if (Sequence &con, const SSQLS &ssqls, Function fn)
| Pulls every row in a table, conditionally storing each one in a container. More...
template<class Sequence , typename Function >
Function | store_if (Sequence &con, Function fn)
| Execute the query, conditionally storing each row in a container. More...
StoreQueryResult | store_next ()
| Return next result set, when processing a multi-query. More...
bool | more_results ()
| Return whether more results are waiting for a multi-query or stored procedure response. More...
template<class Sequence >
void | storein_sequence (Sequence &con)
| Execute a query, storing the result set in an STL sequence container. More...
template<class Sequence >
void | storein_sequence (Sequence &con, const SQLTypeAdapter &s)
| Executes a query, storing the result rows in an STL sequence container. More...
template<class Seq >
void | storein_sequence (Seq &con, SQLQueryParms &p)
| Execute template query using given parameters, storing the results in a sequence type container. More...
template<class Set >
void | storein_set (Set &con)
| Execute a query, storing the result set in an STL associative container. More...
template<class Set >
void | storein_set (Set &con, const SQLTypeAdapter &s)
| Executes a query, storing the result rows in an STL set-associative container. More...
template<class Set >
void | storein_set (Set &con, SQLQueryParms &p)
| Execute template query using given parameters, storing the results in a set type container. More...
template<class Container >
void | storein (Container &con)
| Execute a query, and store the entire result set in an STL container. More...
template<class T >
void | storein (T &con, SQLQueryParms &p)
| Store template query results into a container. More...
template<class T >
void | storein (std::vector< T > &con, const SQLTypeAdapter &s)
| Specialization of storein_sequence() for `std::vector`.
template<class T >
void | storein (std::deque< T > &con, const SQLTypeAdapter &s)
| Specialization of storein_sequence() for `std::deque`.
template<class T >
void | storein (std::list< T > &con, const SQLTypeAdapter &s)
| Specialization of storein_sequence() for `std::list`.
template<class T >
void | storein (std::set< T > &con, const SQLTypeAdapter &s)
| Specialization of storein_set() for `std::set`.
template<class T >
void | storein (std::multiset< T > &con, const SQLTypeAdapter &s)
| Specialization of storein_set() for `std::multiset`.
template<class T >
Query & | update (const T &o, const T &n)
| Replace an existing row's data with new data. More...
template<class T >
Query & | insert (const T &v)
| Insert a new row. More...
template<class Iter >
Query & | insert (Iter first, Iter last)
| Insert multiple new rows. More...
template<class Iter , class InsertPolicy >
Query & | insertfrom (Iter first, Iter last, InsertPolicy &policy)
| Insert multiple new rows using an insert policy to control how the INSERT statements are created using items from an STL container. More...
template<class Iter , class InsertPolicy >
Query & | replacefrom (Iter first, Iter last, InsertPolicy &policy)
| Replace multiple new rows using an insert policy to control how the REPLACE statements are created using items from an STL container. More...
template<class T >
Query & | replace (const T &v)
| Insert new row unless there is an existing row that matches on a unique index, in which case we replace it. More...
template<class Iter >
Query & | replace (Iter first, Iter last)
| Insert multiple new rows, or replace existing ones if there are existing rows that match on key fields. More...
Public Member Functions inherited from mysqlpp::OptionalExceptions
| OptionalExceptions (bool e=true)
| Default constructor. More...
virtual | ~OptionalExceptions ()
| Destroy object.
void | enable_exceptions () const
| Enable exceptions from the object.
void | disable_exceptions () const
| Disable exceptions from the object.
bool | throw_exceptions () const
| Returns true if exceptions are enabled.

## Public Attributes
SQLQueryParms | template_defaults
| The default template parameters. More...

## Friends
class | SQLQueryParms

## Additional Inherited Members
Protected Member Functions inherited from mysqlpp::OptionalExceptions
void | set_exceptions (bool e) const
| Sets the exception state to a particular value. More...

## Detailed Description

A class for building and executing SQL queries.

One does not generally create Query objects directly. Instead, call mysqlpp::Connection::query() to get one tied to that connection.

There are several ways to build and execute SQL queries with this class.

The way most like other database libraries is to pass a SQL statement in either the form of a C or C++ string to one of the exec*(), store*(), or use() methods. The query is executed immediately, and any results returned.

For more complicated queries, it's often more convenient to build up the query string over several C++ statements using Query's stream interface. It works like any other C++ stream (`std::cout`, `std::ostringstream`, etc.) in that you can just insert things into the stream, building the query up piece by piece. When the query string is complete, you call the overloaded version of exec*(), store*(), or use() takes no parameters, which executes the built query and returns any results.

If you are using the library's Specialized SQL Structures feature, Query has several special functions for generating common SQL queries from those structures. For instance, it offers the insert() method, which builds an INSERT query to add the contents of the SSQLS to the database. As with the stream interface, these methods only build the query string; call one of the parameterless methods mentioned previously to actually execute the query.

Finally, you can build "template queries". This is something like C's `printf()` function, in that you insert a specially-formatted query string into the object which contains placeholders for data. You call the parse() method to tell the Query object that the query string contains placeholders. Having done that, you call one of the the many exec*(), store*(), or use() overloads that take SQLTypeAdapter objects. There are 25 of each by default, differing only in the number of STA objects they take. (See `lib/querydef.pl` if you need to change the limit, or `examples/tquery2.cpp` for a way around it that doesn't require changing the library.) Only the version taking a single STA object is documented below, as to document all of them would just be repetitive. For each Query method that takes a single STA object, there's a good chance there's a set of undocumented overloads that take more of them for the purpose of filling out a template query.

See the user manual for more details about these options.

## Constructor & Destructor Documentation

## ◆ Query() [1/2]

mysqlpp::Query::Query | ( | Connection * | c,
|  | bool | te = `true`,
|  | const char * | qstr = `0`
| ) |  |

Create a new query object attached to a connection.

This is the constructor used by mysqlpp::Connection::query().

Parameters

  c | connection the finished query should be sent out on
  te | if true, throw exceptions on errors
  qstr | an optional initial query string

## ◆ Query() [2/2]

mysqlpp::Query::Query | ( | const Query & | q | ) |

Create a new query object as a copy of another.

This is not a traditional copy ctor! Its only purpose is to make it possible to assign the return of Connection::query() to an empty Query object. In particular, the stream buffer and template query stuff will be empty in the copy, regardless of what values they have in the original.

References operator=().

## Member Function Documentation

## ◆ errnum()

int mysqlpp::Query::errnum | ( |  | ) | const

Get the last error number that was set.

This just delegates to Connection::errnum(). Query has nothing extra to say, so use either, as makes sense in your program.

References mysqlpp::Connection::errnum().

Referenced by exec(), execute(), store(), store_next(), and use().

## ◆ error()

const char * mysqlpp::Query::error | ( |  | ) | const

Get the last error message that was set.

This just delegates to Connection::error(). Query has nothing extra to say, so use either, as makes sense in your program.

References mysqlpp::Connection::error().

Referenced by exec(), execute(), store(), store_next(), and use().

## ◆ escape_string() [1/2]

size_t mysqlpp::Query::escape_string | ( | std::string * | ps,
|  | const char * | original = `0`,
|  | size_t | length = `0`
| ) |  | const

Return a SQL-escaped version of a character buffer.

Parameters

  ps | pointer to C++ string to hold escaped version; if original is 0, also holds the original data to be escaped
  original | if given, pointer to the character buffer to escape instead of contents of *ps
  length | if both this and original are given, number of characters to escape instead of ps->length()

Return values

  number | of characters placed in *ps

See also
  comments for escape_string(char*, const char*, size_t) and DBDriver::escape_string(std::string*, const char *, size_t) for further details.

References mysqlpp::Connection::driver(), mysqlpp::DBDriver::escape_string(), and mysqlpp::DBDriver::escape_string_no_conn().

## ◆ escape_string() [2/2]

size_t mysqlpp::Query::escape_string | ( | char * | escaped,
|  | const char * | original,
|  | size_t | length
| ) |  | const

Return a SQL-escaped version of the given character buffer.

Parameters

  escaped | character buffer to hold escaped version; must point to at least (length * 2 + 1) bytes
  original | pointer to the character buffer to escape
  length | number of characters to escape

Return values

  number | of characters placed in escaped

DBDriver provides two versions of this method and Query::escape_string() calls the appropriate one based on whether or not a database connection is available. If the connection is available, it can call the DBDriver::escape_string() method. If there is no database connection available (normally only in testing), then DBDriver provides a static version of the function that doesn't use a database connection.

See also
  comments for DBDriver::escape_string(char*, const char*, size_t), DBDriver::escape_string_no_conn(char*, const char*, size_t) for further details.

References mysqlpp::Connection::driver(), mysqlpp::DBDriver::escape_string(), and mysqlpp::DBDriver::escape_string_no_conn().

## ◆ exec() [1/2]

bool mysqlpp::Query::exec | ( |  | ) |
| inline

Execute a built-up query.

Same as exec(), except that it uses the query string built up within the query object already instead of accepting a query string from the caller.

Returns
  true if query was executed successfully

See also
  exec(const std::string& str), execute(), store(), storein(), and use()

References exec().

Referenced by mysqlpp::Connection::create_db(), mysqlpp::Connection::drop_db(), and exec().

## ◆ exec() [2/2]

bool mysqlpp::Query::exec | ( | const std::string & | str | ) |

Execute a query.

Same as execute(), except that it only returns a flag indicating whether the query succeeded or not. It is basically a thin wrapper around the C API function `mysql_real_query()`.

Parameters

  str | the query to execute

Returns
  true if query was executed successfully

See also
  execute(), store(), storein(), and use()

References mysqlpp::Connection::driver(), errnum(), error(), mysqlpp::DBDriver::execute(), reset(), str(), and mysqlpp::OptionalExceptions::throw_exceptions().

## ◆ execute() [1/4]

SimpleResult mysqlpp::Query::execute | ( |  | ) |

Execute built-up query.

Use one of the execute() overloads if you don't expect the server to return a result set. For instance, a DELETE query. The returned SimpleResult object contains status information from the server, such as whether the query succeeded, and if so how many rows were affected.

This overloaded version of execute() simply executes the query that you have built up in the object in some way. (For instance, via the insert() method, or by using the object's stream interface.)

Returns
  SimpleResult status information about the query

See also
  exec(), store(), storein(), and use()

References str(), and template_defaults.

Referenced by mysqlpp::Transaction::commit(), execute(), mysqlpp::Transaction::rollback(), and mysqlpp::Transaction::Transaction().

## ◆ execute() [2/4]

SimpleResult mysqlpp::Query::execute | ( | SQLQueryParms & | p | ) |

Execute template query using given parameters.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Parameters

  p | parameters to use in the template query.

References execute(), str(), and template_defaults.

## ◆ execute() [3/4]

SimpleResult mysqlpp::Query::execute | ( | const SQLTypeAdapter & | str | ) |

Execute a query that returns no rows.

Parameters

  str | if this object is set up as a template query, this is the value to substitute for the first template query parameter; else, it is the SQL query string to execute

Because SQLTypeAdapter can be initialized from either a C string or a C++ string, this overload accepts query strings in either form. Beware, SQLTypeAdapter also accepts many other data types (this is its raison d'etre), so it will let you write code that compiles but results in bogus SQL queries.

To support template queries, there many more overloads of this type (25 total, by default; see `lib/querydef.pl`), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

References mysqlpp::SQLTypeAdapter::data(), execute(), mysqlpp::SQLTypeAdapter::length(), and template_defaults.

## ◆ execute() [4/4]

SimpleResult mysqlpp::Query::execute | ( | const char * | str,
|  | size_t | len
| ) |  |

Execute query in a known-length string of characters. This can include null characters.

Executes the query immediately, and returns the results.

References affected_rows(), mysqlpp::Connection::driver(), errnum(), error(), mysqlpp::DBDriver::execute(), execute(), info(), insert_id(), reset(), str(), template_defaults, and mysqlpp::OptionalExceptions::throw_exceptions().

## ◆ for_each() [1/3]

template<typename Function >

Function mysqlpp::Query::for_each | ( | const SQLTypeAdapter & | query,
|  | Function | fn
| ) |  |
| inline

Execute a query, and call a functor for each returned row.

This method wraps a use() query, calling the given functor for every returned row. It is analogous to STL's for_each() algorithm, but instead of iterating over some range within a container, it iterates over a result set produced by a query.

Parameters

  query | the query string
  fn | the functor called for each row

Returns
  a copy of the passed functor

References mysqlpp::UseQueryResult::fetch_row().

## ◆ for_each() [2/3]

template<typename Function >

Function mysqlpp::Query::for_each | ( | Function | fn | ) |
| inline

Execute the query, and call a functor for each returned row.

Just like for_each(const SQLTypeAdapter&, Function), but it uses the query string held by the Query object already

Parameters

  fn | the functor called for each row

Returns
  a copy of the passed functor

References mysqlpp::UseQueryResult::fetch_row().

## ◆ for_each() [3/3]

template<class SSQLS , typename Function >

Function mysqlpp::Query::for_each | ( | const SSQLS & | ssqls,
|  | Function | fn
| ) |  |
| inline

Run a functor for every row in a table.

Just like for_each(Function), except that it builds a "select * from TABLE" query using the SQL table name from the SSQLS instance you pass.

Parameters

  ssqls | the SSQLS instance to get a table name from
  fn | the functor called for each row

Returns
  a copy of the passed functor

References mysqlpp::UseQueryResult::fetch_row().

## ◆ insert() [1/2]

template<class T >

Query& mysqlpp::Query::insert | ( | const T & | v | ) |
| inline

Insert a new row.

This function builds an INSERT SQL query. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters

  v | new row

See also
  replace(), update()

## ◆ insert() [2/2]

template<class Iter >

Query& mysqlpp::Query::insert | ( | Iter | first,
|  | Iter | last
| ) |  |
| inline

Insert multiple new rows.

Builds an INSERT SQL query using items from a range within an STL container. Insert the entire contents of the container by using the begin() and end() iterators of the container as parameters to this function.

Parameters

  first | iterator pointing to first element in range to insert
  last | iterator pointing to one past the last element to insert

See also
  insertfrom(), replace(), update()

## ◆ insert_id()

ulonglong mysqlpp::Query::insert_id | ( |  | ) |

Get ID generated for an AUTO_INCREMENT column in the previous INSERT query.

Return values

  0 | if the previous query did not generate an ID. Use the SQL function LAST_INSERT_ID() if you need the last ID generated by any query, not just the previous one. This applies to stored procedure calls because this function returns the ID generated by the last query, which was a CALL statement, and CALL doesn't generate IDs. You need to use LAST_INSERT_ID() to get the ID in this case.

References mysqlpp::Connection::driver(), and mysqlpp::DBDriver::insert_id().

Referenced by execute().

## ◆ insertfrom()

template<class Iter , class InsertPolicy >

Query& mysqlpp::Query::insertfrom | ( | Iter | first,
|  | Iter | last,
|  | InsertPolicy & | policy
| ) |  |
| inline

Insert multiple new rows using an insert policy to control how the INSERT statements are created using items from an STL container.

Parameters

  first | iterator pointing to first element in range to insert
  last | iterator pointing to one past the last element to insert
  policy | insert policy object, see insertpolicy.h for details

See also
  insert()

## ◆ more_results()

bool mysqlpp::Query::more_results | ( |  | ) |

Return whether more results are waiting for a multi-query or stored procedure response.

If this function returns true, you must call store_next() to fetch the next result set before you can execute more queries.

Wraps mysql_more_results() in the MySQL C API. That function only exists in MySQL v4.1 and higher. Therefore, this function always returns false when built against older API libraries.

Returns
  true if another result set exists

References mysqlpp::Connection::driver(), and mysqlpp::DBDriver::more_results().

## ◆ operator void *()

mysqlpp::Query::operator void * | ( |  | ) | const

Test whether the object has experienced an error condition.

Allows for code constructs like this:

Query q = conn.query();
.... use query object
if (q) {
... no problems in using query object
}
else {
... an error has occurred
}

This method returns false if either the Query object or its associated Connection object has seen an error condition since the last operation.

## ◆ operator!()

bool mysqlpp::Query::operator! | ( |  | ) | const
| inline

Returns true if the query object is not in a bad state.

This just returns the opposite of operator void*(), and is required only because basic_ios defines it, so we have to override it to get Query-specific behavior in code like this:

if (!query) ...

## ◆ operator=()

Query & mysqlpp::Query::operator= | ( | const Query & | rhs | ) |

Assign another query's state to this object.

The same caveats apply to this operator as apply to the copy ctor.

References mysqlpp::OptionalExceptions::set_exceptions(), template_defaults, and mysqlpp::OptionalExceptions::throw_exceptions().

Referenced by Query().

## ◆ parse()

void mysqlpp::Query::parse | ( |  | ) |

Treat the contents of the query string as a template query.

This method sets up the internal structures used by all of the other members that accept template query parameters. See the "Template Queries" chapter in the user manual for more information.

References str().

## ◆ replace() [1/2]

template<class T >

Query& mysqlpp::Query::replace | ( | const T & | v | ) |
| inline

Insert new row unless there is an existing row that matches on a unique index, in which case we replace it.

This function builds a REPLACE SQL query. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters

  v | new row

See also
  insert(), update()

## ◆ replace() [2/2]

template<class Iter >

Query& mysqlpp::Query::replace | ( | Iter | first,
|  | Iter | last
| ) |  |
| inline

Insert multiple new rows, or replace existing ones if there are existing rows that match on key fields.

Builds a REPLACE SQL query using items from a range within an STL container. Insert the entire contents of the container by using the begin() and end() iterators of the container as parameters to this function.

Parameters

  first | iterator pointing to first element in range to insert/replace
  last | iterator pointing to one past the last element to insert/replace

See also
  insertfrom(), replace(), update()

## ◆ replacefrom()

template<class Iter , class InsertPolicy >

Query& mysqlpp::Query::replacefrom | ( | Iter | first,
|  | Iter | last,
|  | InsertPolicy & | policy
| ) |  |
| inline

Replace multiple new rows using an insert policy to control how the REPLACE statements are created using items from an STL container.

Parameters

  first | iterator pointing to first element in range to replace
  last | iterator pointing to one past the last element to replace
  policy | insert policy object, see insertpolicy.h for details

See also
  insert()

## ◆ reset()

void mysqlpp::Query::reset | ( |  | ) |

Reset the query object so that it can be reused.

As of v3.0, Query objects auto-reset upon query execution unless you've set it up for making template queries. (It can't auto-reset in that situation, because it would forget the template info.) Therefore, the only time you must call this is if you have a Query object set up for making template queries, then want to build queries using one of the other methods. (Static strings, SSQLS, or the stream interface.)

References mysqlpp::SQLQueryParms::clear(), and template_defaults.

Referenced by exec(), execute(), store(), and use().

## ◆ result_empty()

bool mysqlpp::Query::result_empty | ( |  | ) |

Returns true if the most recent result set was empty.

Wraps DBDriver::result_empty()

References mysqlpp::Connection::driver(), and mysqlpp::DBDriver::result_empty().

## ◆ store() [1/4]

StoreQueryResult mysqlpp::Query::store | ( |  | ) |

Execute a query that can return a result set.

Use one of the store() overloads to execute a query and retrieve the entire result set into memory. This is useful if you actually need all of the records at once, but if not, consider using one of the use() methods instead, which returns the results one at a time, so they don't allocate as much memory as store().

You must use store(), storein() or use() for `SELECT`, `SHOW`, `DESCRIBE` and `EXPLAIN` queries. You can use these functions with other query types, but since they don't return a result set, exec() and execute() are more efficient.

The name of this method comes from the MySQL C API function it is implemented in terms of, `mysql_store_result()`.

This function has the same set of overloads as execute().

Returns
  StoreQueryResult object containing entire result set

See also
  exec(), execute(), storein(), and use()

References str(), and template_defaults.

Referenced by mysqlpp::Connection::count_rows(), store(), and store_next().

## ◆ store() [2/4]

StoreQueryResult mysqlpp::Query::store | ( | SQLQueryParms & | p | ) |

Store results from a template query using given parameters.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Parameters

  p | parameters to use in the template query.

References store(), str(), and template_defaults.

## ◆ store() [3/4]

StoreQueryResult mysqlpp::Query::store | ( | const SQLTypeAdapter & | str | ) |

Execute a query that can return rows, returning all of the rows in a random-access container.

Parameters

  str | if this object is set up as a template query, this is the value to substitute for the first template query parameter; else, it is the SQL query string to execute

Because SQLTypeAdapter can be initialized from either a C string or a C++ string, this overload accepts query strings in either form. Beware, SQLTypeAdapter also accepts many other data types (this is its raison d'etre), so it will let you write code that compiles but results in bogus SQL queries.

To support template queries, there many more overloads of this type (25 total, by default; see `lib/querydef.pl`), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

References mysqlpp::SQLTypeAdapter::data(), mysqlpp::SQLTypeAdapter::length(), store(), and template_defaults.

## ◆ store() [4/4]

StoreQueryResult mysqlpp::Query::store | ( | const char * | str,
|  | size_t | len
| ) |  |

Execute a query that can return rows, returning all of the rows in a random-access container.

This overload is for situations where you have the query in a C string and have its length already. If you want to execute a query in a null-terminated C string or have the query string in some other form, you probably want to call store(const SQLTypeAdapter&) instead. SQLTypeAdapter converts from plain C strings and other useful data types implicitly.

References mysqlpp::Connection::driver(), mysqlpp::Connection::errnum(), errnum(), error(), mysqlpp::DBDriver::execute(), reset(), store(), mysqlpp::DBDriver::store_result(), str(), template_defaults, and mysqlpp::OptionalExceptions::throw_exceptions().

## ◆ store_if() [1/3]

template<class Sequence , typename Function >

Function mysqlpp::Query::store_if | ( | Sequence & | con,
|  | const SQLTypeAdapter & | query,
|  | Function | fn
| ) |  |
| inline

Execute a query, conditionally storing each row in a container.

This method wraps a use() query, calling the given functor for every returned row, and storing the results in the given sequence container if the functor returns true.

This is analogous to the STL copy_if() algorithm, except that the source rows come from a database query instead of another container. (copy_if() isn't a standard STL algorithm, but only due to an oversight by the standardization committee.) This fact may help you to remember the order of the parameters: the container is the destination, the query is the source, and the functor is the predicate; it's just like an STL algorithm.

Parameters

  con | the destination container; needs a push_back() method
  query | the query string
  fn | the functor called for each row

Returns
  a copy of the passed functor

References mysqlpp::UseQueryResult::fetch_row().

## ◆ store_if() [2/3]

template<class Sequence , class SSQLS , typename Function >

Function mysqlpp::Query::store_if | ( | Sequence & | con,
|  | const SSQLS & | ssqls,
|  | Function | fn
| ) |  |
| inline

Pulls every row in a table, conditionally storing each one in a container.

Just like store_if(Sequence&, const SQLTypeAdapter&, Function), but it uses the SSQLS instance to construct a "select * from TABLE" query, using the table name field in the SSQLS.

Parameters

  con | the destination container; needs a push_back() method
  ssqls | the SSQLS instance to get a table name from
  fn | the functor called for each row

Returns
  a copy of the passed functor

References mysqlpp::UseQueryResult::fetch_row().

## ◆ store_if() [3/3]

template<class Sequence , typename Function >

Function mysqlpp::Query::store_if | ( | Sequence & | con,
|  | Function | fn
| ) |  |
| inline

Execute the query, conditionally storing each row in a container.

Just like store_if(Sequence&, const SQLTypeAdapter&, Function), but it uses the query string held by the Query object already

Parameters

  con | the destination container; needs a push_back() method
  fn | the functor called for each row

Returns
  a copy of the passed functor

References mysqlpp::UseQueryResult::fetch_row().

## ◆ store_next()

StoreQueryResult mysqlpp::Query::store_next | ( |  | ) |

Return next result set, when processing a multi-query.

There are two cases where you'd use this function instead of the regular store() functions.

First, when handling the result of executing multiple queries at once. (See this page in the MySQL documentation for details.)

Second, when calling a stored procedure, MySQL can return the result as a set of results.

In either case, you must consume all results before making another MySQL query, even if you don't care about the remaining results or result sets.

As the MySQL documentation points out, you must set the MYSQL_OPTION_MULTI_STATEMENTS_ON flag on the connection in order to use this feature. See Connection::set_option().

Multi-queries only exist in MySQL v4.1 and higher. Therefore, this function just wraps store() when built against older API libraries.

Returns
  StoreQueryResult object containing the next result set.

References mysqlpp::Connection::driver(), mysqlpp::Connection::errnum(), errnum(), error(), mysqlpp::DBDriver::next_result(), mysqlpp::DBDriver::nr_error, mysqlpp::DBDriver::nr_more_results, store(), mysqlpp::DBDriver::store_result(), and mysqlpp::OptionalExceptions::throw_exceptions().

## ◆ storein() [1/2]

template<class Container >

void mysqlpp::Query::storein | ( | Container & | con | ) |
| inline

Execute a query, and store the entire result set in an STL container.

This is a set of specialized template functions that call either storein_sequence() or storein_set(), depending on the type of container you pass it. It understands `std::vector`, `deque`, `list`, `slist` (a common C++ library extension), `set`, and `multiset`.

Like the functions it wraps, this is actually an overloaded set of functions. See the other functions' documentation for details.

Use this function if you think you might someday switch your program from using a set-associative container to a sequence container for storing result sets, or vice versa.

See exec(), execute(), store(), and use() for alternative query execution mechanisms.

## ◆ storein() [2/2]

template<class T >

void mysqlpp::Query::storein | ( | T & | con,
|  | SQLQueryParms & | p
| ) |  |
| inline

Store template query results into a container.

This method is not intended to be used directly. It is part of the call chain in processing calls to one of the many storein() overloads that take a container and one or more SQLTypeAdapter parameters.

## ◆ storein_sequence() [1/3]

template<class Sequence >

void mysqlpp::Query::storein_sequence | ( | Sequence & | con | ) |
| inline

Execute a query, storing the result set in an STL sequence container.

This function works much like store() from the caller's perspective, because it returns the entire result set at once. It's actually implemented in terms of use(), however, so that memory for the result set doesn't need to be allocated twice.

There are many overloads for this function, pretty much the same as for execute(), except that there is a Container parameter at the front of the list. So, you can pass a container and a query string, or a container and template query parameters.

Parameters

  con | any STL sequence container, such as `std::vector`

See also
  exec(), execute(), store(), and use()

## ◆ storein_sequence() [2/3]

template<class Sequence >

void mysqlpp::Query::storein_sequence | ( | Sequence & | con,
|  | const SQLTypeAdapter & | s
| ) |  |
| inline

Executes a query, storing the result rows in an STL sequence container.

Parameters

  con | the container to store the results in
  s | if Query is set up as a template query, this is the value to substitute for the first template query parameter; else, the SQL query string

There many more overloads of this type (25 total, by default; see `lib/querydef.pl`), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

## ◆ storein_sequence() [3/3]

template<class Seq >

void mysqlpp::Query::storein_sequence | ( | Seq & | con,
|  | SQLQueryParms & | p
| ) |  |
| inline

Execute template query using given parameters, storing the results in a sequence type container.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Parameters

  con | container that will receive the results
  p | parameters to use in the template query.

## ◆ storein_set() [1/3]

template<class Set >

void mysqlpp::Query::storein_set | ( | Set & | con | ) |
| inline

Execute a query, storing the result set in an STL associative container.

The same thing as storein_sequence(), except that it's used with associative STL containers, such as `std::set`. Other than that detail, that method's comments apply equally well to this one.

## ◆ storein_set() [2/3]

template<class Set >

void mysqlpp::Query::storein_set | ( | Set & | con,
|  | const SQLTypeAdapter & | s
| ) |  |
| inline

Executes a query, storing the result rows in an STL set-associative container.

Parameters

  con | the container to store the results in
  s | if Query is set up as a template query, this is the value to substitute for the first template query parameter; else, the SQL query string

There many more overloads of this type (25 total, by default; see `lib/querydef.pl`), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

## ◆ storein_set() [3/3]

template<class Set >

void mysqlpp::Query::storein_set | ( | Set & | con,
|  | SQLQueryParms & | p
| ) |  |
| inline

Execute template query using given parameters, storing the results in a set type container.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Parameters

  con | container that will receive the results
  p | parameters to use in the template query.

## ◆ str() [1/2]

std::string mysqlpp::Query::str | ( | const SQLTypeAdapter & | arg0 | ) |
| inline

Get built query as a C++ string with template query parameter substitution.

Parameters

  arg0 | the value to substitute for the first template query parameter; because SQLTypeAdapter implicitly converts from many different data types, this method is very flexible in what it accepts as a parameter. You shouldn't have to use the SQLTypeAdapter data type directly in your code.

There many more overloads of this type (25 total, by default; see `lib/querydef.pl`), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

## ◆ str() [2/2]

std::string mysqlpp::Query::str | ( | SQLQueryParms & | p | ) |

Get built query as a null-terminated C++ string.

Parameters

  p | template query parameters to use, overriding the ones this object holds, if any

## ◆ update()

template<class T >

Query& mysqlpp::Query::update | ( | const T & | o,
|  | const T & | n
| ) |  |
| inline

Replace an existing row's data with new data.

This function builds an UPDATE SQL query using the new row data for the SET clause, and the old row data for the WHERE clause. One uses it with MySQL++'s Specialized SQL Structures mechanism.

Parameters

  o | old row
  n | new row

See also
  insert(), replace()

## ◆ use() [1/4]

UseQueryResult mysqlpp::Query::use | ( |  | ) |

Execute a query that can return rows, with access to the rows in sequence.

Use one of the use() overloads if memory efficiency is important. They return an object that can walk through the result records one by one, without fetching the entire result set from the server. This is superior to store() when there are a large number of results; store() would have to allocate a large block of memory to hold all those records, which could cause problems.

A potential downside of this method is that MySQL database resources are tied up until the result set is completely consumed. Do your best to walk through the result set as expeditiously as possible.

The name of this method comes from the MySQL C API function that initiates the retrieval process, `mysql_use_result()`. This method is implemented in terms of that function.

This function has the same set of overloads as execute().

Returns
  UseQueryResult object that can walk through result set serially

See also
  exec(), execute(), store() and storein()

References str(), and template_defaults.

Referenced by use().

## ◆ use() [2/4]

UseQueryResult mysqlpp::Query::use | ( | SQLQueryParms & | p | ) |

Execute a template query that can return rows, with access to the rows in sequence.

This method should only be used by code that doesn't know, at compile time, how many parameters it will have. This is useful within the library, and also for code that builds template queries dynamically, at run time.

Parameters

  p | parameters to use in the template query.

References str(), template_defaults, and use().

## ◆ use() [3/4]

UseQueryResult mysqlpp::Query::use | ( | const SQLTypeAdapter & | str | ) |

Execute a query that can return rows, with access to the rows in sequence.

Parameters

  str | if this object is set up as a template query, this is the value to substitute for the first template query parameter; else, it is the SQL query string to execute

Because SQLTypeAdapter can be initialized from either a C string or a C++ string, this overload accepts query strings in either form. Beware, SQLTypeAdapter also accepts many other data types (this is its raison d'etre), so it will let you write code that compiles but results in bogus SQL queries.

To support template queries, there many more overloads of this type (25 total, by default; see `lib/querydef.pl`), each taking one more SQLTypeAdapter object than the previous one. See the template query overview above for more about this topic.

References mysqlpp::SQLTypeAdapter::data(), mysqlpp::SQLTypeAdapter::length(), template_defaults, and use().

## ◆ use() [4/4]

UseQueryResult mysqlpp::Query::use | ( | const char * | str,
|  | size_t | len
| ) |  |

Execute a query that can return rows, with access to the rows in sequence.

This overload is for situations where you have the query in a C string and have its length already. If you want to execute a query in a null-terminated C string or have the query string in some other form, you probably want to call use(const SQLTypeAdapter&) instead. SQLTypeAdapter converts from plain C strings and other useful data types implicitly.

References mysqlpp::Connection::driver(), mysqlpp::Connection::errnum(), errnum(), error(), mysqlpp::DBDriver::execute(), reset(), str(), template_defaults, mysqlpp::OptionalExceptions::throw_exceptions(), use(), and mysqlpp::DBDriver::use_result().

## Member Data Documentation

## ◆ template_defaults

SQLQueryParms mysqlpp::Query::template_defaults

The default template parameters.

Used for filling in parameterized queries.

Referenced by execute(), operator=(), reset(), store(), and use().

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

- query.h
- query.cpp