[tracker: 1/2] docs: Add tracker_sparql_connection_query_statement() example

[Sam Thursfield <sthursfield src gnome org>]

commit 6e1315ae3bfcb18b1fbb1982a8987fbf68366ee5
Author: nitinosiris <nitinwartkar58 gmail com>
Date:   Tue May 11 20:51:34 2021 +0530

    docs: Add tracker_sparql_connection_query_statement() example
    
    Using tracker_sparql_connection_query_statement() instead of tracker_sparql_connection_query()
    can increase the performance as it gets parsed only once when we ran it multiple times.
    
    Fixes: #128

 docs/reference/libtracker-sparql/examples.xml      | 10 +++--
 .../libtracker-sparql/examples/readonly-example.c  | 43 ++++++++++++++++++++--
 2 files changed, 46 insertions(+), 7 deletions(-)
---
diff --git a/docs/reference/libtracker-sparql/examples.xml b/docs/reference/libtracker-sparql/examples.xml
index 7c475fd06..26aac6e3d 100644
--- a/docs/reference/libtracker-sparql/examples.xml
+++ b/docs/reference/libtracker-sparql/examples.xml
@@ -35,9 +35,12 @@
     </para>
 
     <para>
-      Once you end up with the query, remember to call <function><link 
linkend="g-object-unref">g_object_unref</link></function>
-      for the <type><link linkend="TrackerSparqlCursor-struct">TrackerSparqlCursor</link></type>. And the 
same applies to the
-      <type><link linkend="TrackerSparqlConnection-struct">TrackerSparqlConnection</link></type> when no 
longer needed.
+      The <function><link 
linkend="tracker-sparql-connection-query-statement">tracker_sparql_connection_query_statement</link></function>
+      function can be used to obtain a <link linkend="TrackerSparqlStatement">TrackerSparqlStatement</link> 
object holding a prepared SPARQL
+           query that can then be executed with <function><link 
linkend="tracker-sparql-statement-execute">tracker_sparql_statement_execute</link>.
+           The query string can contain <systemitem>~name</systemitem> placeholders which can be replaced 
with arbitrary values before query execution with the
+           <function><link 
linkend="tracker-sparql-statement-bind-string">tracker_sparql_statement_bind_string</link> and similar 
functions.
+           This allows parsing the query string only once and to execute it multiple times with different 
parameters with potentially significant performance gains.
     </para>
 
     <para>
@@ -133,4 +136,3 @@
   </chapter>
 
 </part>
-
diff --git a/docs/reference/libtracker-sparql/examples/readonly-example.c 
b/docs/reference/libtracker-sparql/examples/readonly-example.c
index 3759e5299..2aafd7e0d 100644
--- a/docs/reference/libtracker-sparql/examples/readonly-example.c
+++ b/docs/reference/libtracker-sparql/examples/readonly-example.c
@@ -5,6 +5,7 @@ int main (int argc, const char **argv)
   GError *error = NULL;
   TrackerSparqlConnection *connection;
   TrackerSparqlCursor *cursor;
+  TrackerSparqlStatement *stmt;
   const gchar *query = "SELECT nie:url(?u) WHERE { ?u a nfo:FileDataObject }";
 
   connection = tracker_sparql_connection_bus_new ("org.freedesktop.Tracker3.Miner.Files", NULL, NULL, 
&error);
@@ -18,9 +19,9 @@ int main (int argc, const char **argv)
 
   /* Make a synchronous query to the store */
   cursor = tracker_sparql_connection_query (connection,
-                                          query,
-                                          NULL,
-                                          &error);
+                                            query,
+                                            NULL,
+                                            &error);
 
   if (error) {
     /* Some error happened performing the query, not good */
@@ -49,6 +50,42 @@ int main (int argc, const char **argv)
     g_object_unref (cursor);
   }
 
+  /* Prepare the statement with tracker_sparql_connection_query_statement */
+  stmt = tracker_sparql_connection_query_statement (connection,
+                                                    query,
+                                                    NULL,
+                                                    &error);
+
+  if (error) {
+    /* Some error happened performing the query, not good */
+    g_printerr ("Couldn't query the Tracker Store: '%s'",
+                error->message);
+    g_clear_error (&error);
+
+    return 1;
+  }
+
+  /* Executes the SPARQL query with the currently bound values and get new cursor */
+  cursor = tracker_sparql_statement_execute (stmt, NULL, &error);
+
+  /* Check results... */
+  if (!cursor) {
+    g_print ("No results found :-/\n");
+  } else {
+    gint i = 0;
+
+    /* Iterate, synchronously, the results... */
+    while (tracker_sparql_cursor_next (cursor, NULL, &error)) {
+      g_print ("Result [%d]: %s\n",
+               i++,
+               tracker_sparql_cursor_get_string (cursor, 0, NULL));
+    }
+
+    g_print ("A total of '%d' results were found\n", i);
+
+    g_object_unref (cursor);
+  }
+
   g_object_unref (connection);
 
   return 0;