## GnomeDbCondition

GnomeDbCondition — Represents a condition within a query

##

# Synopsis

    struct      GnomeDbCondition;
    enum        GnomeDbConditionType;
    enum        GnomeDbConditionOperator;
    GType       gnome_db_condition_get_type     (void);
    GObject*    gnome_db_condition_new          (GnomeDbQuery *query,
                                                 GnomeDbConditionType type);
    GObject*    gnome_db_condition_new_copy     (GnomeDbCondition *orig,
                                                 GHashTable *replacements);
    GObject*    gnome_db_condition_new_from_sql (GnomeDbQuery *query,
                                                 const gchar *sql_cond,
                                                 GSList **targets,
                                                 GError **error);
    void        gnome_db_condition_set_cond_type
                                                (GnomeDbCondition *condition,
                                                 GnomeDbConditionType type);
    GnomeDbConditionType gnome_db_condition_get_cond_type
                                                (GnomeDbCondition *condition);
    GSList*     gnome_db_condition_get_children (GnomeDbCondition *condition);
    GnomeDbCondition* gnome_db_condition_get_parent
                                                (GnomeDbCondition *condition);
    GnomeDbCondition* gnome_db_condition_get_child_by_xml_id
                                                (GnomeDbCondition *condition,
                                                 const gchar *xml_id);
    gboolean    gnome_db_condition_is_ancestor  (GnomeDbCondition *condition,
                                                 GnomeDbCondition *ancestor);
    gboolean    gnome_db_condition_is_leaf      (GnomeDbCondition *condition);
    gboolean    gnome_db_condition_node_add_child
                                                (GnomeDbCondition *condition,
                                                 GnomeDbCondition *child,
                                                 GError **error);
    void        gnome_db_condition_node_del_child
                                                (GnomeDbCondition *condition,
                                                 GnomeDbCondition *child);
    void        gnome_db_condition_leaf_set_operator
                                                (GnomeDbCondition *condition,
                                                 GnomeDbConditionOperator op,
                                                 GnomeDbQfield *field);
    GnomeDbQfield* gnome_db_condition_leaf_get_operator
                                                (GnomeDbCondition *condition,
                                                 GnomeDbConditionOperator op);
    GSList*     gnome_db_condition_get_ref_objects_all
                                                (GnomeDbCondition *condition);
    gboolean    gnome_db_condition_represents_join
                                                (GnomeDbCondition *condition,
                                                 GnomeDbTarget **target1,
                                                 GnomeDbTarget **target2,
                                                 gboolean *is_equi_join);
    gboolean    gnome_db_condition_represents_join_strict
                                                (GnomeDbCondition *condition,
                                                 GnomeDbTarget **target1,
                                                 GnomeDbTarget **target2);
    GSList*     gnome_db_condition_get_main_conditions
                                                (GnomeDbCondition *condition);

## Object Hierarchy

      GObject
       +----GnomeDbBase
             +----GnomeDbCondition

## Implemented Interfaces

GnomeDbCondition implements GnomeDbXmlStorage, GnomeDbRenderer and GnomeDbReferer.

## Properties

      "join"                 gpointer             : Read / Write
      "query"                gpointer             : Read / Write

## Description

This object represents a condition within a query. Usually there is one such object to express a WHERE condition and sometimes a GnomeDbJoin 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

### struct GnomeDbCondition

    struct GnomeDbCondition;

### enum GnomeDbConditionType

    typedef enum {
            GNOME_DB_CONDITION_NODE_AND,
            GNOME_DB_CONDITION_NODE_OR,
            GNOME_DB_CONDITION_NODE_NOT,
    	GNOME_DB_CONDITION_LEAF_EQUAL,
            GNOME_DB_CONDITION_LEAF_DIFF,
            GNOME_DB_CONDITION_LEAF_SUP,
            GNOME_DB_CONDITION_LEAF_SUPEQUAL,
            GNOME_DB_CONDITION_LEAF_INF,
            GNOME_DB_CONDITION_LEAF_INFEQUAL,
            GNOME_DB_CONDITION_LEAF_LIKE,
    	GNOME_DB_CONDITION_LEAF_SIMILAR,
            GNOME_DB_CONDITION_LEAF_REGEX,
            GNOME_DB_CONDITION_LEAF_REGEX_NOCASE,
            GNOME_DB_CONDITION_LEAF_NOT_REGEX,
            GNOME_DB_CONDITION_LEAF_NOT_REGEX_NOCASE,
            GNOME_DB_CONDITION_LEAF_IN,
            GNOME_DB_CONDITION_LEAF_BETWEEN,
            GNOME_DB_CONDITION_TYPE_UNKNOWN
    } GnomeDbConditionType;

### enum GnomeDbConditionOperator

    typedef enum {
    	GNOME_DB_CONDITION_OP_LEFT   = 0,
    	GNOME_DB_CONDITION_OP_RIGHT  = 1,
    	GNOME_DB_CONDITION_OP_RIGHT2 = 2
    } GnomeDbConditionOperator;

### gnome_db_condition_get_type ()

    GType       gnome_db_condition_get_type     (void);

Returns : |

### gnome_db_condition_new ()

    GObject*    gnome_db_condition_new          (GnomeDbQuery *query,
                                                 GnomeDbConditionType type);

Creates a new GnomeDbCondition object

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

### gnome_db_condition_new_copy ()

    GObject*    gnome_db_condition_new_copy     (GnomeDbCondition *orig,
                                                 GHashTable *replacements);

This is a copy constructor

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

### gnome_db_condition_new_from_sql ()

    GObject*    gnome_db_condition_new_from_sql (GnomeDbQuery *query,
                                                 const gchar *sql_cond,
                                                 GSList **targets,
                                                 GError **error);

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

`query` : | a GnomeDbQuery 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 GnomeDbCondition, or `NULL` if there was an error in `sql_cond`

### gnome_db_condition_set_cond_type ()

    void        gnome_db_condition_set_cond_type
                                                (GnomeDbCondition *condition,
                                                 GnomeDbConditionType 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 GnomeDbCondition object
`type` : |

### gnome_db_condition_get_cond_type ()

    GnomeDbConditionType gnome_db_condition_get_cond_type
                                                (GnomeDbCondition *condition);

Get the type of `condition`

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

### gnome_db_condition_get_children ()

    GSList*     gnome_db_condition_get_children (GnomeDbCondition *condition);

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

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

### gnome_db_condition_get_parent ()

    GnomeDbCondition* gnome_db_condition_get_parent
                                                (GnomeDbCondition *condition);

Get the GnomeDbCondition object which is parent of `condition`

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

### gnome_db_condition_get_child_by_xml_id ()

    GnomeDbCondition* gnome_db_condition_get_child_by_xml_id
                                                (GnomeDbCondition *condition,
                                                 const gchar *xml_id);

Get a pointer to a GnomeDbCondition child from its XML Id

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

### gnome_db_condition_is_ancestor ()

    gboolean    gnome_db_condition_is_ancestor  (GnomeDbCondition *condition,
                                                 GnomeDbCondition *ancestor);

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

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

### gnome_db_condition_is_leaf ()

    gboolean    gnome_db_condition_is_leaf      (GnomeDbCondition *condition);

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

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

### gnome_db_condition_node_add_child ()

    gboolean    gnome_db_condition_node_add_child
                                                (GnomeDbCondition *condition,
                                                 GnomeDbCondition *child,
                                                 GError **error);

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

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

### gnome_db_condition_node_del_child ()

    void        gnome_db_condition_node_del_child
                                                (GnomeDbCondition *condition,
                                                 GnomeDbCondition *child);

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

`condition` : | a GnomeDbCondition object
`child` : | a GnomeDbCondition object

### gnome_db_condition_leaf_set_operator ()

    void        gnome_db_condition_leaf_set_operator
                                                (GnomeDbCondition *condition,
                                                 GnomeDbConditionOperator op,
                                                 GnomeDbQfield *field);

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

### gnome_db_condition_leaf_get_operator ()

    GnomeDbQfield* gnome_db_condition_leaf_get_operator
                                                (GnomeDbCondition *condition,
                                                 GnomeDbConditionOperator op);

Get one of `condition`'s operators.

`condition` : | a GnomeDbCondition object
`op` : | which oparetor is concerned
Returns : | the requested GnomeDbQfield object

### gnome_db_condition_get_ref_objects_all ()

    GSList*     gnome_db_condition_get_ref_objects_all
                                                (GnomeDbCondition *condition);

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

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

### gnome_db_condition_represents_join ()

    gboolean    gnome_db_condition_represents_join
                                                (GnomeDbCondition *condition,
                                                 GnomeDbTarget **target1,
                                                 GnomeDbTarget **target2,
                                                 gboolean *is_equi_join);

Tells if `condition` represents a join condition: it is a condition (within a GnomeDbQuery object) for which the only GnomeDbQfField fields taking part in the condition are from two distincts GnomeDbTarget objects. Such conditions can be assigned to a GnomeDbJoin object using the `gnome_db_join_set_condition()` or `gnome_db_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 GnomeDbTarget 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 GnomeDbCondition 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

### gnome_db_condition_represents_join_strict ()

    gboolean    gnome_db_condition_represents_join_strict
                                                (GnomeDbCondition *condition,
                                                 GnomeDbTarget **target1,
                                                 GnomeDbTarget **target2);

Tells if `condition` represents a strict join condition: it is a join condition as defined for the `gnome_db_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 GnomeDbCondition 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

### gnome_db_condition_get_main_conditions ()

    GSList*     gnome_db_condition_get_main_conditions
                                                (GnomeDbCondition *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 GnomeDbCondition object
Returns : | a new list of GnomeDbCondition objects

## Properties

"`join`" (gpointer : Read / Write) |
"`query`" (gpointer : Read / Write) |