GdaQueryCondition

## GdaQueryCondition GdaQueryCondition — Represents a condition within a query |

## Synopsis

                GdaQueryCondition;
    enum        GdaQueryConditionType;
    enum        GdaQueryConditionOperator;
    GObject*    gda_query_condition_new         (GdaQuery *query,
                                                 GdaQueryConditionType type);
    GObject*    gda_query_condition_new_copy    (GdaQueryCondition *orig,
                                                 GHashTable *replacements);
    GObject*    gda_query_condition_new_from_sql
                                                (GdaQuery *query,
                                                 const gchar *sql_cond,
                                                 GSList **targets,
                                                 GError **error);
    void        gda_query_condition_set_cond_type
                                                (GdaQueryCondition *condition,
                                                 GdaQueryConditionType type);
    GdaQueryConditionType gda_query_condition_get_cond_type
                                                (GdaQueryCondition *condition);
    GSList*     gda_query_condition_get_children
                                                (GdaQueryCondition *condition);
    GdaQueryCondition* gda_query_condition_get_parent
                                                (GdaQueryCondition *condition);
    GdaQueryCondition* gda_query_condition_get_child_by_xml_id
                                                (GdaQueryCondition *condition,
                                                 const gchar *xml_id);
    gboolean    gda_query_condition_is_ancestor (GdaQueryCondition *condition,
                                                 GdaQueryCondition *ancestor);
    gboolean    gda_query_condition_is_leaf     (GdaQueryCondition *condition);
    gboolean    gda_query_condition_node_add_child
                                                (GdaQueryCondition *condition,
                                                 GdaQueryCondition *child,
                                                 GError **error);
    void        gda_query_condition_node_del_child
                                                (GdaQueryCondition *condition,
                                                 GdaQueryCondition *child);
    void        gda_query_condition_leaf_set_operator
                                                (GdaQueryCondition *condition,
                                                 GdaQueryConditionOperator op,
                                                 GdaQueryField *field);
    GdaQueryField* gda_query_condition_leaf_get_operator
                                                (GdaQueryCondition *condition,
                                                 GdaQueryConditionOperator op);
    gboolean    gda_query_condition_represents_join
                                                (GdaQueryCondition *condition,
                                                 GdaQueryTarget **target1,
                                                 GdaQueryTarget **target2,
                                                 gboolean *is_equi_join);
    gboolean    gda_query_condition_represents_join_strict
                                                (GdaQueryCondition *condition,
                                                 GdaQueryTarget **target1,
                                                 GdaQueryTarget **target2);
    GSList*     gda_query_condition_get_main_conditions
                                                (GdaQueryCondition *condition);
    GSList*     gda_query_condition_get_ref_objects_all
                                                (GdaQueryCondition *condition);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaQueryObject
                   +----GdaQueryCondition

## Implemented Interfaces

GdaQueryCondition implements GdaXmlStorage, GdaReferer and GdaRenderer.

## Properties

      "cond-type"            gint                  : Read / Write
      "join"                 gpointer              : Read / Write
      "query"                gpointer              : Read / Write / Construct Only

## Description

This object represents a condition within a query. Usually there is one such object to express a WHERE condition and sometimes a GdaQueryJoin object con contain one as well to express a specific joinning condition.

There are two types of conditions: 'node' conditions (AND, OR, NOT), where there are one or more children condition and 'leaf' conditions, where there are only operands.

## Details

### GdaQueryCondition

    typedef struct _GdaQueryCondition GdaQueryCondition;

### enum GdaQueryConditionType

    typedef enum {
            GDA_QUERY_CONDITION_NODE_AND,
            GDA_QUERY_CONDITION_NODE_OR,
            GDA_QUERY_CONDITION_NODE_NOT,
    	GDA_QUERY_CONDITION_LEAF_EQUAL,
            GDA_QUERY_CONDITION_LEAF_DIFF,
            GDA_QUERY_CONDITION_LEAF_SUP,
            GDA_QUERY_CONDITION_LEAF_SUPEQUAL,
            GDA_QUERY_CONDITION_LEAF_INF,
            GDA_QUERY_CONDITION_LEAF_INFEQUAL,
            GDA_QUERY_CONDITION_LEAF_LIKE,
    	GDA_QUERY_CONDITION_LEAF_SIMILAR,
            GDA_QUERY_CONDITION_LEAF_REGEX,
            GDA_QUERY_CONDITION_LEAF_REGEX_NOCASE,
            GDA_QUERY_CONDITION_LEAF_NOT_REGEX,
            GDA_QUERY_CONDITION_LEAF_NOT_REGEX_NOCASE,
            GDA_QUERY_CONDITION_LEAF_IN,
            GDA_QUERY_CONDITION_LEAF_BETWEEN,
            GDA_QUERY_CONDITION_TYPE_UNKNOWN
    } GdaQueryConditionType;

### enum GdaQueryConditionOperator

    typedef enum {
    	GDA_QUERY_CONDITION_OP_LEFT   = 0,
    	GDA_QUERY_CONDITION_OP_RIGHT  = 1,
    	GDA_QUERY_CONDITION_OP_RIGHT2 = 2
    } GdaQueryConditionOperator;

### gda_query_condition_new ()

    GObject*    gda_query_condition_new         (GdaQuery *query,
                                                 GdaQueryConditionType type);

Creates a new GdaQueryCondition object

`query` : | a GdaQuery object
`type` : | the condition type
Returns : | the newly created object

### gda_query_condition_new_copy ()

    GObject*    gda_query_condition_new_copy    (GdaQueryCondition *orig,
                                                 GHashTable *replacements);

This is a copy constructor

`orig` : | a GdaQueryCondition to copy
`replacements` : | a hash table to store replacements, or `NULL`
Returns : | the new object

### gda_query_condition_new_from_sql ()

    GObject*    gda_query_condition_new_from_sql
                                                (GdaQuery *query,
                                                 const gchar *sql_cond,
                                                 GSList **targets,
                                                 GError **error);

Creates a new GdaQueryCondition object, which references other objects of `query`, from the `sql_cond` statement.

`query` : | a GdaQuery object
`sql_cond` : | a SQL statement representing a valid condition
`targets` : | location to store a list of targets used by the new condition (and its children), or `NULL`
`error` : | location to store error, or `NULL`
Returns : | a new GdaQueryCondition, or `NULL` if there was an error in `sql_cond`

### gda_query_condition_set_cond_type ()

    void        gda_query_condition_set_cond_type
                                                (GdaQueryCondition *condition,
                                                 GdaQueryConditionType type);

Sets the kind of condition `condition` represents. If `type` implies a node condition and `condition` currently represents a leaf, or if `type` implies a leaf condition and `condition` currently represents a node, then `condition` is changed without any error.

`condition` : | a GdaQueryCondition object
`type` : |

### gda_query_condition_get_cond_type ()

    GdaQueryConditionType gda_query_condition_get_cond_type
                                                (GdaQueryCondition *condition);

Get the type of `condition`

`condition` : | a GdaQueryCondition object
Returns : | the type

### gda_query_condition_get_children ()

    GSList*     gda_query_condition_get_children
                                                (GdaQueryCondition *condition);

Get a list of GdaQueryCondition objects which are children of `condition`

`condition` : | a GdaQueryCondition object
Returns : | a new list of GdaQueryCondition objects

### gda_query_condition_get_parent ()

    GdaQueryCondition* gda_query_condition_get_parent
                                                (GdaQueryCondition *condition);

Get the GdaQueryCondition object which is parent of `condition`

`condition` : | a GdaQueryCondition object
Returns : | the parent object, or `NULL`

### gda_query_condition_get_child_by_xml_id ()

    GdaQueryCondition* gda_query_condition_get_child_by_xml_id
                                                (GdaQueryCondition *condition,
                                                 const gchar *xml_id);

Get a pointer to a GdaQueryCondition child from its XML Id

`condition` : | a GdaQueryCondition object
`xml_id` : | the XML Id of the requested GdaQueryCondition child
Returns : | the GdaQueryCondition object, or `NULL` if not found

### gda_query_condition_is_ancestor ()

    gboolean    gda_query_condition_is_ancestor (GdaQueryCondition *condition,
                                                 GdaQueryCondition *ancestor);

Tests if `ancestor` is an ancestor of `condition`

`condition` : | a GdaQueryCondition object
`ancestor` : | a GdaQueryCondition object
Returns : | TRUE if `ancestor` is an ancestor of `condition`

### gda_query_condition_is_leaf ()

    gboolean    gda_query_condition_is_leaf     (GdaQueryCondition *condition);

Tells if `condition` is a leaf condition (not AND, OR, NOT, etc)

`condition` : | a GdaQueryCondition object
Returns : | TRUE if `condition` is a leaf condition

### gda_query_condition_node_add_child ()

    gboolean    gda_query_condition_node_add_child
                                                (GdaQueryCondition *condition,
                                                 GdaQueryCondition *child,
                                                 GError **error);

Adds a child to `condition`; this is possible only if `condition` is a node type (AND, OR, etc)

`condition` : | a GdaQueryCondition object
`child` : | a GdaQueryCondition object
`error` : | location to store error, or `NULL`
Returns : | TRUE if no error occurred

### gda_query_condition_node_del_child ()

    void        gda_query_condition_node_del_child
                                                (GdaQueryCondition *condition,
                                                 GdaQueryCondition *child);

Removes a child from `condition`; this is possible only if `condition` is a node type (AND, OR, etc)

`condition` : | a GdaQueryCondition object
`child` : | a GdaQueryCondition object

### gda_query_condition_leaf_set_operator ()

    void        gda_query_condition_leaf_set_operator
                                                (GdaQueryCondition *condition,
                                                 GdaQueryConditionOperator op,
                                                 GdaQueryField *field);

`condition` : |
`op` : |
`field` : |

### gda_query_condition_leaf_get_operator ()

    GdaQueryField* gda_query_condition_leaf_get_operator
                                                (GdaQueryCondition *condition,
                                                 GdaQueryConditionOperator op);

Get one of `condition`'s operators.

`condition` : | a GdaQueryCondition object
`op` : | which oparetor is concerned
Returns : | the requested GdaQueryField object

### gda_query_condition_represents_join ()

    gboolean    gda_query_condition_represents_join
                                                (GdaQueryCondition *condition,
                                                 GdaQueryTarget **target1,
                                                 GdaQueryTarget **target2,
                                                 gboolean *is_equi_join);

Tells if `condition` represents a join condition: it is a condition (within a GdaQuery object) for which the only GdaQueryFieldField fields taking part in the condition are from two distincts GdaQueryTarget objects. Such conditions can be assigned to a GdaQueryJoin object using the `gda_query_join_set_condition()` or `gda_query_join_set_condition_from_fkcons()` methods.

Additionnaly, if `condition` is a join condition, and if `target1` and `target2` are not `NULL` then they are set to point to the two GdaQueryTarget objects taking part in the condition. In this case `target1` and `target2` wil hold non `NULL` values.

In a similar way, if `is_equi_join` is not `NULL`, then it will be set to TRUE if the join condition is an equi join (that is the only comparison operator is the equal sign and there are only AND operators in the condition).

If `condition` is not a join condition, then `target1`, `target2` and `is_equi_join` are left untouched.

`condition` : | a GdaQueryCondition object
`target1` : | place to store one of the targets, or `NULL`
`target2` : | place to store the other target, or `NULL`
`is_equi_join` : | place to store if the join is an equi join
Returns : | TRUE if `condition` is a join condition

### gda_query_condition_represents_join_strict ()

    gboolean    gda_query_condition_represents_join_strict
                                                (GdaQueryCondition *condition,
                                                 GdaQueryTarget **target1,
                                                 GdaQueryTarget **target2);

Tells if `condition` represents a strict join condition: it is a join condition as defined for the `gda_query_condition_represents_join()` method, but where the condition is either "target1.field1=target2.field2" or a list of such conditions conjuncted by the AND operator.

If `condition` is not a join condition, then `target1` and `target2` are left untouched.

`condition` : | a GdaQueryCondition object
`target1` : | place to store one of the targets, or `NULL`
`target2` : | place to store the other target, or `NULL`
Returns : | TRUE if `condition` is a strict join condition

### gda_query_condition_get_main_conditions ()

    GSList*     gda_query_condition_get_main_conditions
                                                (GdaQueryCondition *condition);

Makes a list of all the conditions which are always verified by `condition` when it returns TRUE when evaluated. Basically the returned list lists the atomic conditions which are AND'ed together to form the complex `condition`.

Examples: if `condition` is:

- "A and B" then the list will contains {A, B}

- "A and (B or C)" it will contain {A, B or C}

- "A and (B and not C)", it will contain {A, B, not C}

`condition` : | a GdaQueryCondition object
Returns : | a new list of GdaQueryCondition objects

### gda_query_condition_get_ref_objects_all ()

    GSList*     gda_query_condition_get_ref_objects_all
                                                (GdaQueryCondition *condition);

Get a complete list of the objects referenced by `cond`, including its descendants (unlike the `gda_referer_get_ref_objects()` function applied to `cond`).

`condition` : |
Returns : | a new list of referenced objects

## Properties

### The "`cond-type`" property

      "cond-type"            gint                  : Read / Write

Allowed values: [0,17]

Default value: 17

### The "`join`" property

      "join"                 gpointer              : Read / Write

### The "`query`" property

      "query"                gpointer              : Read / Write / Construct Only