Query Results 3 RASQAL Library
Query Results Query results as variable bindings, boolean or RDF graphs.

## Synopsis

    typedef     rasqal_query_results;
    void        rasqal_free_query_results       (rasqal_query_results *query_results);
    int         rasqal_query_results_finished   (rasqal_query_results *query_results);
    const unsigned char* rasqal_query_results_get_binding_name
                                                (rasqal_query_results *query_results,
                                                 int offset);
    rasqal_literal* rasqal_query_results_get_binding_value
                                                (rasqal_query_results *query_results,
                                                 int offset);
    rasqal_literal* rasqal_query_results_get_binding_value_by_name
                                                (rasqal_query_results *query_results,
                                                 unsigned char *name);
    int         rasqal_query_results_get_bindings
                                                (rasqal_query_results *query_results,
                                                 unsigned char ***names,
                                                 rasqal_literal ***values);
    int         rasqal_query_results_get_bindings_count
                                                (rasqal_query_results *query_results);
    int         rasqal_query_results_get_boolean
                                                (rasqal_query_results *query_results);
    int         rasqal_query_results_get_count  (rasqal_query_results *query_results);
    raptor_statement* rasqal_query_results_get_triple
                                                (rasqal_query_results *query_results);
    int         rasqal_query_results_is_bindings
                                                (rasqal_query_results *query_results);
    int         rasqal_query_results_is_boolean (rasqal_query_results *query_results);
    int         rasqal_query_results_is_graph   (rasqal_query_results *query_results);
    int         rasqal_query_results_next       (rasqal_query_results *query_results);
    int         rasqal_query_results_next_triple
                                                (rasqal_query_results *query_results);
    int         rasqal_query_results_write      (raptor_iostream *iostr,
                                                 rasqal_query_results *results,
                                                 raptor_uri *format_uri,
                                                 raptor_uri *base_uri);

## Description

A query results object is only ever constructed by the internal query engine evaluating a rasqal_query with `rasqal_query_execute()`. It provides interface to the multiple types of result supported.

There are a large set of methods for returning all or parts of a variable binding query result including the names, values or individuals. A boolean result is straightforward to get with `rasqal_query_results_get_boolean()` and an RDF graph returns a sequence of raptor triples than can be easily passed to the Raptor library for serializing to a syntax.

## Details

### rasqal_query_results

    rasqal_graph_query_results* query_results;

Rasqal query results class.

rasqal_query_results

### rasqal_free_query_results ()

    void        rasqal_free_query_results       (rasqal_query_results *query_results);

Destructor - destroy a rasqal_query_results.

query_results :

  rasqal_query_results object

rasqal_free_query_results

### rasqal_query_results_finished ()

    int         rasqal_query_results_finished   (rasqal_query_results *query_results);

Find out if binding results are exhausted.

query_results :

  rasqal_query_results query_results

Returns :

  non-0 if results are finished or query failed

rasqal_query_results_finished

### rasqal_query_results_get_binding_name ()

    const unsigned char* rasqal_query_results_get_binding_name
                                                (rasqal_query_results *query_results,
                                                 int offset);

Get binding name for the current result.

query_results :

  rasqal_query_results query_results

offset :

  offset of binding name into array of known names

Returns :

  a pointer to a shared copy of the binding name or NULL on failure

rasqal_query_results_get_binding_name

### rasqal_query_results_get_binding_value ()

    rasqal_literal* rasqal_query_results_get_binding_value
                                                (rasqal_query_results *query_results,
                                                 int offset);

Get one binding value for the current result.

query_results :

  rasqal_query_results query_results

offset :

  offset of binding name into array of known names

Returns :

  a pointer to a shared rasqal_literal binding value or NULL on failure

rasqal_query_results_get_binding_value

### rasqal_query_results_get_binding_value_by_name ()

    rasqal_literal* rasqal_query_results_get_binding_value_by_name
                                                (rasqal_query_results *query_results,
                                                 unsigned char *name);

Get one binding value for a given name in the current result.

query_results :

  rasqal_query_results query_results

name :

  variable name

Returns :

  a pointer to a shared rasqal_literal binding value or NULL on failure

rasqal_query_results_get_binding_value_by_name

### rasqal_query_results_get_bindings ()

    int         rasqal_query_results_get_bindings
                                                (rasqal_query_results *query_results,
                                                 unsigned char ***names,
                                                 rasqal_literal ***values);

Get all binding names, values for current result.

If names is not NULL, it is set to the address of a shared array of names of the bindings (an output parameter). These names are shared and must not be freed by the caller

If values is not NULL, it is set to the address of a shared array of rasqal_literal* binding values. These values are shaerd and must not be freed by the caller.

query_results :

  rasqal_query_results query_results

names :

  pointer to an array of binding names (or NULL)

values :

  pointer to an array of binding value rasqal_literal (or NULL)

Returns :

  non-0 if the assignment failed

rasqal_query_results_get_bindings

### rasqal_query_results_get_bindings_count ()

    int         rasqal_query_results_get_bindings_count
                                                (rasqal_query_results *query_results);

Get the number of bound variables in the result.

query_results :

  rasqal_query_results query_results

Returns :

  <0 if failed or results exhausted

rasqal_query_results_get_bindings_count

### rasqal_query_results_get_boolean ()

    int         rasqal_query_results_get_boolean
                                                (rasqal_query_results *query_results);

Get boolean query result.

The return value is only meaningful if this is a boolean query result - see `rasqal_query_results_is_boolean()`

query_results :

  rasqal_query_results query_results

Returns :

  boolean query result - >0 is true, 0 is false, <0 on error or finished

rasqal_query_results_get_boolean

### rasqal_query_results_get_count ()

    int         rasqal_query_results_get_count  (rasqal_query_results *query_results);

Get number of bindings so far.

query_results :

  rasqal_query_results query_results

Returns :

  number of bindings found so far or < 0 on failure

rasqal_query_results_get_count

### rasqal_query_results_get_triple ()

    raptor_statement* rasqal_query_results_get_triple
                                                (rasqal_query_results *query_results);

Get the current triple in the result.

The return value is a shared raptor_statement.

query_results :

  rasqal_query_results query_results

Returns :

  raptor_statement or NULL if failed or results exhausted

rasqal_query_results_get_triple

### rasqal_query_results_is_bindings ()

    int         rasqal_query_results_is_bindings
                                                (rasqal_query_results *query_results);

Test if rasqal_query_results is variable bindings format.

query_results :

  rasqal_query_results object

Returns :

  non-0 if true

rasqal_query_results_is_bindings

### rasqal_query_results_is_boolean ()

    int         rasqal_query_results_is_boolean (rasqal_query_results *query_results);

Test if rasqal_query_results is boolean format.

query_results :

  rasqal_query_results object

Returns :

  non-0 if true

rasqal_query_results_is_boolean

### rasqal_query_results_is_graph ()

    int         rasqal_query_results_is_graph   (rasqal_query_results *query_results);

Test if rasqal_query_results is RDF graph format.

query_results :

  rasqal_query_results object

Returns :

  non-0 if true

rasqal_query_results_is_graph

### rasqal_query_results_next ()

    int         rasqal_query_results_next       (rasqal_query_results *query_results);

Move to the next result.

query_results :

  rasqal_query_results query_results

Returns :

  non-0 if failed or results exhausted

rasqal_query_results_next

### rasqal_query_results_next_triple ()

    int         rasqal_query_results_next_triple
                                                (rasqal_query_results *query_results);

Move to the next triple result.

query_results :

  rasqal_query_results query_results

Returns :

  non-0 if failed or results exhausted

rasqal_query_results_next_triple

### rasqal_query_results_write ()

    int         rasqal_query_results_write      (raptor_iostream *iostr,
                                                 rasqal_query_results *results,
                                                 raptor_uri *format_uri,
                                                 raptor_uri *base_uri);

Write the query results to an iostream in a format.

This uses the rasqal_query_results_formatter class and the `rasqal_query_results_formatter_write()` method to perform the formatting. See `rasqal_query_results_formats_enumerate()` for obtaining the supported format URIs at run time.

iostr :

  raptor_iostream to write the query to

results :

  rasqal_query_results query results format

format_uri :

  raptor_uri describing the format to write (or NULL for default)

base_uri :

  raptor_uri base URI of the output format

Returns :

  non-0 on failure

rasqal_query_results_write