## e-book-query

e-book-query — Handles queries of addressboook data.

## Synopsis

    typedef     EBookQuery;
    enum        EBookQueryTest;
    EBookQuery* e_book_query_from_string        (const char *query_string);
    char*       e_book_query_to_string          (EBookQuery *q);
    EBookQuery* e_book_query_ref                (EBookQuery *q);
    void        e_book_query_unref              (EBookQuery *q);
    EBookQuery* e_book_query_and                (int nqs,
                                                 EBookQuery **qs,
                                                 gboolean unref);
    EBookQuery* e_book_query_andv               (EBookQuery *q,
                                                 ...);
    EBookQuery* e_book_query_or                 (int nqs,
                                                 EBookQuery **qs,
                                                 gboolean unref);
    EBookQuery* e_book_query_orv                (EBookQuery *q,
                                                 ...);
    EBookQuery* e_book_query_not                (EBookQuery *q,
                                                 gboolean unref);
    EBookQuery* e_book_query_field_exists       (EContactField field);
    EBookQuery* e_book_query_field_test         (EContactField field,
                                                 EBookQueryTest test,
                                                 const char *value);
    EBookQuery* e_book_query_any_field_contains (const char *value);

## Description

## Details

### EBookQuery

    typedef struct EBookQuery EBookQuery;

### enum EBookQueryTest

    typedef enum {
      E_BOOK_QUERY_IS,
      E_BOOK_QUERY_CONTAINS,
      E_BOOK_QUERY_BEGINS_WITH,
      E_BOOK_QUERY_ENDS_WITH,

      /*
        Consider these "coming soon".

        E_BOOK_QUERY_LT,
        E_BOOK_QUERY_LE,
        E_BOOK_QUERY_GT,
        E_BOOK_QUERY_GE,
        E_BOOK_QUERY_EQ,
      */
    } EBookQueryTest;

### e_book_query_from_string ()

    EBookQuery* e_book_query_from_string        (const char *query_string);

Parse `query_string` and return a new EBookQuery representing it.

`query_string` : | the query
Returns : | the new EBookValue

### e_book_query_to_string ()

    char*       e_book_query_to_string          (EBookQuery *q);

Return the string representation of `q`.

`q` : | an EBookQuery
Returns : | The string form of the query. This string should be freed when finished with.

### e_book_query_ref ()

    EBookQuery* e_book_query_ref                (EBookQuery *q);

Increment the reference count on `q`.

`q` : | a EBookQuery
Returns : | `q`

### e_book_query_unref ()

    void        e_book_query_unref              (EBookQuery *q);

Decrement the reference count on `q`. When the reference count reaches 0, `q` will be freed and any child queries will have `e_book_query_unref()` called.

`q` : | an EBookQuery

### e_book_query_and ()

    EBookQuery* e_book_query_and                (int nqs,
                                                 EBookQuery **qs,
                                                 gboolean unref);

Create a new EBookQuery which is the logical AND of the queries in qs.

`nqs` : | the number of queries to AND
`qs` : | pointer to an array of EBookQuery items
`unref` : | if `TRUE`, the new query takes ownership of the existing queries
Returns : | A new EBookQuery

### e_book_query_andv ()

    EBookQuery* e_book_query_andv               (EBookQuery *q,
                                                 ...);

Creates a new EBookQuery which is the logical AND of the queries specified.

`q` : | first EBookQuery
`...` : | NULL terminated list of EBookQuery pointers
Returns : | A new EBookQuery

### e_book_query_or ()

    EBookQuery* e_book_query_or                 (int nqs,
                                                 EBookQuery **qs,
                                                 gboolean unref);

Creates a new EBookQuery which is the logical OR of the queries in qs.

`nqs` : | the number of queries to OR
`qs` : | pointer to an array of EBookQuery items
`unref` : | if TRUE, the new query takes ownership of the existing queries
Returns : | A new EBookQuery

### e_book_query_orv ()

    EBookQuery* e_book_query_orv                (EBookQuery *q,
                                                 ...);

Creates a new EBookQuery which is the logical OR of the queries specified.

`q` : | first EBookQuery
`...` : | NULL terminated list of EBookQuery pointers
Returns : | A new EBookQuery

### e_book_query_not ()

    EBookQuery* e_book_query_not                (EBookQuery *q,
                                                 gboolean unref);

Creates a new EBookQuery which is the opposite of q.

`q` : | an EBookQuery
`unref` : | if TRUE, the new query takes ownership of the existing queries
Returns : | the new EBookQuery

### e_book_query_field_exists ()

    EBookQuery* e_book_query_field_exists       (EContactField field);

Creates a new EBookQuery which tests if the field `field` exists.

`field` : | a EContactField
Returns : | the new EBookQuery

### e_book_query_field_test ()

    EBookQuery* e_book_query_field_test         (EContactField field,
                                                 EBookQueryTest test,
                                                 const char *value);

Creates a new EBookQuery which tests `field` for `value` using the test `test`.

`field` : | an EContactField to test
`test` : | the test to apply
`value` : | the value to test for
Returns : | the new EBookQuery

### e_book_query_any_field_contains ()

    EBookQuery* e_book_query_any_field_contains (const char *value);

Creates a new EBookQuery which tests if any field contains `value`.

`value` : | a value
Returns : | the new EBookQuery