[libgdamm] Connection: Add statement_to_sql() method overloads.

[Murray Cumming <murrayc src gnome org>]

commit c2987497858e2c82518917ea0f581a0464b27159
Author: Murray Cumming <murrayc murrayc com>
Date:   Wed Sep 21 09:08:44 2011 +0200

    Connection: Add statement_to_sql() method overloads.
    
    * libgda/src/connection.[hg|ccg]: Because some parameters can be NULL.

 ChangeLog                 |   16 ++++++++--------
 libgda/src/connection.ccg |   25 +++++++++++++++++++++++++
 libgda/src/connection.hg  |   34 ++++++++++++++++++++++++++++++++--
 3 files changed, 65 insertions(+), 10 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 33f4eb5..50250c9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -2,19 +2,19 @@
 
 2011-09-21  Murray Cumming  <murrayc murrayc com>
 
+	Value: operator=(): Check for identical instance.
+
+	* libgda/libgdamm/value.cc: This is generally a good idea in operator=()
+	implementations.
+
+2011-09-21  Murray Cumming  <murrayc murrayc com>
+
 	Minor documentation improvements.
 
 	* libgda/src/metastore.hg:
 	* libgda/src/quarklist.hg:
 	* libgda/src/statement.hg: Minor documentation improvements and TODO
-	comments.
-	
-2011-09-21  Murray Cumming  <murrayc murrayc com>
-
-	Value: operator=(): Check for identical instance.
-
-	* libgda/libgdamm/value.cc: This is generally a good idea in operator=()
-	implementations.
+	comments.	
 
 2011-09-20  Murray Cumming  <murrayc murrayc com>
 
diff --git a/libgda/src/connection.ccg b/libgda/src/connection.ccg
index e4af5f0..09c1c52 100644
--- a/libgda/src/connection.ccg
+++ b/libgda/src/connection.ccg
@@ -190,6 +190,31 @@ Glib::ustring Connection::statement_to_sql(const Glib::RefPtr<const Statement>&
   return retvalue;
 }
 
+
+Glib::ustring Connection::statement_to_sql(const Glib::RefPtr<const Statement>& statement, const Glib::RefPtr<const Set>& params, StatementSqlFlag flags) const
+{
+  GError* gerror = 0;
+  const Glib::ustring retvalue = Glib::convert_return_gchar_ptr_to_ustring(gda_connection_statement_to_sql(const_cast<GdaConnection*>(gobj()), const_cast<GdaStatement*>(Glib::unwrap(statement)), const_cast<GdaSet*>(Glib::unwrap(params)), ((GdaStatementSqlFlag)(flags)), 0, &(gerror)));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return retvalue;
+}
+  
+
+Glib::ustring Connection::statement_to_sql(const Glib::RefPtr<const Statement>& statement, StatementSqlFlag flags) const
+{
+  GError* gerror = 0;
+  const Glib::ustring retvalue = Glib::convert_return_gchar_ptr_to_ustring(gda_connection_statement_to_sql(const_cast<GdaConnection*>(gobj()), const_cast<GdaStatement*>(Glib::unwrap(statement)), 0, ((GdaStatementSqlFlag)(flags)), 0, &(gerror)));
+
+  if(gerror)
+    ::Glib::Error::throw_exception(gerror);
+
+  return retvalue;
+}
+  
+
 Glib::RefPtr<DataModel> Connection::statement_execute_select(const Glib::RefPtr<const Statement>& stmt, StatementModelUsage model_usage)
 {
   GError* gerror = 0;
diff --git a/libgda/src/connection.hg b/libgda/src/connection.hg
index e8d9797..4d83efb 100644
--- a/libgda/src/connection.hg
+++ b/libgda/src/connection.hg
@@ -105,7 +105,6 @@ public:
   _WRAP_METHOD(void clear_events_list(), gda_connection_clear_events_list)
 
   _WRAP_METHOD_DOCS_ONLY(gda_connection_statement_execute)
-
   Glib::RefPtr<Glib::Object> statement_execute(const Glib::RefPtr<const Statement>& stmt, const Glib::RefPtr<const Set>& params, StatementModelUsage model_usage, Glib::RefPtr<const Set>& last_insert_row);
 
 //TODO: Documentation:
@@ -210,7 +209,11 @@ public:
   //TODO: Wrap the GdaSet** output parameter:
   //_WRAP_METHOD(Glib::RefPtr<Statement> parse_sql_string(const Glib::ustring& sql, GdaSet** params), gda_connection_parse_sql_string, errthrow)
 
-  //TODO: Documentation:
+  /** This helps to parse a SQL string.
+   *
+   * @param sql An SQL command to parse.
+   * @result A Statement representing the SQL command or an empty RefPtr if an error occurred.
+   */
   Glib::RefPtr<Statement> parse_sql_string(const Glib::ustring& sql);
   _IGNORE(gda_connection_parse_sql_string)
 
@@ -297,9 +300,36 @@ public:
 
   _WRAP_METHOD_DOCS_ONLY(gda_connection_statement_to_sql)
 
+  //TODO: What errors does this really throw? Document that in libgda.
   //TODO: Add an overload without the params_used.
+  /** Renders a Statement as a SQL statement string, adapted to the SQL dialect used by the connection.
+   *
+   * @param stmt A Statement object.
+   * @param A Set object (which can be obtained using Statement::get_parameters()).
+   * @param flags SQL rendering flags, as StatementSqlFlag OR'ed values
+   * @param params_used A place to store the list of individual Holder objects within @a params which have been used.
+   * @throws ConnectionError
+   */
   Glib::ustring statement_to_sql(const Glib::RefPtr<const Statement>& stmt, const Glib::RefPtr<const Set>& params, StatementSqlFlag flags, std::vector< Glib::RefPtr<Holder> >& params_used) const;
 
+  /** Renders a Statement as a SQL statement string, adapted to the SQL dialect used by the connection.
+   *
+   * @param stmt A Statement object.
+   * @param A Set object (which can be obtained using Statement::get_parameters()).
+   * @param flags SQL rendering flags, as StatementSqlFlag OR'ed values
+   * @throws ConnectionError
+   */
+  Glib::ustring statement_to_sql(const Glib::RefPtr<const Statement>& stmt, const Glib::RefPtr<const Set>& params, StatementSqlFlag flags = STATEMENT_SQL_PARAMS_AS_VALUES) const;
+  
+  /** Renders a Statement as a SQL statement string, adapted to the SQL dialect used by the connection.
+   *
+   * @param stmt A Statement object..
+   * @param flags SQL rendering flags, as StatementSqlFlag OR'ed values
+   * @throws ConnectionError
+   */
+  Glib::ustring statement_to_sql(const Glib::RefPtr<const Statement>& stmt, StatementSqlFlag flags = STATEMENT_SQL_PARAMS_AS_VALUES) const;
+
+
   _IGNORE(gda_connection_internal_reset_transaction_status)
 
   #m4 _CONVERSION(`GdaConnectionEvent*',`const Glib::RefPtr<ConnectionEvent>&',Glib::wrap($3, true))