## IAnjutaIterable

IAnjutaIterable — Implemented by objects that can iterate

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libanjuta/interfaces/ianjuta-iterable.h>

    #define             IANJUTA_ITERABLE_ERROR
                        IAnjutaIterable;
                        IAnjutaIterableIface;
    GQuark              ianjuta_iterable_error_quark        (void);
    void                ianjuta_iterable_assign             (IAnjutaIterable *obj,
                                                             IAnjutaIterable *src_iter,
                                                             GError **err);
    IAnjutaIterable *   ianjuta_iterable_clone              (IAnjutaIterable *obj,
                                                             GError **err);
    gint                ianjuta_iterable_compare            (IAnjutaIterable *obj,
                                                             IAnjutaIterable *iter2,
                                                             GError **err);
    gint                ianjuta_iterable_diff               (IAnjutaIterable *obj,
                                                             IAnjutaIterable *iter2,
                                                             GError **err);
    gboolean            ianjuta_iterable_first              (IAnjutaIterable *obj,
                                                             GError **err);
    void                ianjuta_iterable_foreach            (IAnjutaIterable *obj,
                                                             GFunc callback,
                                                             gpointer user_data,
                                                             GError **err);
    gint                ianjuta_iterable_get_length         (IAnjutaIterable *obj,
                                                             GError **err);
    gint                ianjuta_iterable_get_position       (IAnjutaIterable *obj,
                                                             GError **err);
    gboolean            ianjuta_iterable_last               (IAnjutaIterable *obj,
                                                             GError **err);
    gboolean            ianjuta_iterable_next               (IAnjutaIterable *obj,
                                                             GError **err);
    gboolean            ianjuta_iterable_previous           (IAnjutaIterable *obj,
                                                             GError **err);
    gboolean            ianjuta_iterable_set_position       (IAnjutaIterable *obj,
                                                             gint position,
                                                             GError **err);

## Object Hierarchy

      GInterface
       +----IAnjutaIterable

## Prerequisites

IAnjutaIterable requires GObject.

## Known Derived Interfaces

IAnjutaIterable is required by IAnjutaIterableTree.

## Description

## Details

### IANJUTA_ITERABLE_ERROR

    #define IANJUTA_ITERABLE_ERROR ianjuta_iterable_error_quark()

### IAnjutaIterable

    typedef struct _IAnjutaIterable IAnjutaIterable;

### IAnjutaIterableIface

    typedef struct {
    	GTypeInterface g_iface;

    	void (*assign) (IAnjutaIterable *obj, IAnjutaIterable *src_iter, GError **err);
    	IAnjutaIterable * (*clone) (IAnjutaIterable *obj, GError **err);
    	gint (*compare) (IAnjutaIterable *obj, IAnjutaIterable *iter2, GError **err);
    	gint (*diff) (IAnjutaIterable *obj, IAnjutaIterable *iter2, GError **err);
    	gboolean (*first) (IAnjutaIterable *obj, GError **err);
    	void (*foreach) (IAnjutaIterable *obj, GFunc callback,  gpointer user_data, GError **err);
    	gint (*get_length) (IAnjutaIterable *obj, GError **err);
    	gint (*get_position) (IAnjutaIterable *obj, GError **err);
    	gboolean (*last) (IAnjutaIterable *obj, GError **err);
    	gboolean (*next) (IAnjutaIterable *obj, GError **err);
    	gboolean (*previous) (IAnjutaIterable *obj, GError **err);
    	gboolean (*set_position) (IAnjutaIterable *obj, gint position, GError **err);
    } IAnjutaIterableIface;

### ianjuta_iterable_error_quark ()

    GQuark              ianjuta_iterable_error_quark        (void);

Returns : |

### ianjuta_iterable_assign ()

    void                ianjuta_iterable_assign             (IAnjutaIterable *obj,
                                                             IAnjutaIterable *src_iter,
                                                             GError **err);

Assigns the iter position from `src_iter`.

`obj` : | Self
`src_iter` : | Source iter from which to copy the assignment.
`err` : | Error propagation and reporting

### ianjuta_iterable_clone ()

    IAnjutaIterable *   ianjuta_iterable_clone              (IAnjutaIterable *obj,
                                                             GError **err);

Clones the iterable. The returned iterable object must be unreffed when done.

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | A new instance of this iterable pointing at the same location.

### ianjuta_iterable_compare ()

    gint                ianjuta_iterable_compare            (IAnjutaIterable *obj,
                                                             IAnjutaIterable *iter2,
                                                             GError **err);

Compares the position of `iter2` with this `obj`. Returns -1 value if this `obj` is smaller than `iter2`. Returns +1 value if this `obj` is larger than `iter2`. And returns 0 if both are equal. If you want difference of the iter positions, use #`ianjuta_iterable_diff()`. This method is meant for fast comparision.

`obj` : | Self
`iter2` : | Second iter to compare.
`err` : | Error propagation and reporting
Returns : | 0 if equal, -1 if `obj` is smaller than `iter2` or +1 if `obj` is larger than `iter2`.

### ianjuta_iterable_diff ()

    gint                ianjuta_iterable_diff               (IAnjutaIterable *obj,
                                                             IAnjutaIterable *iter2,
                                                             GError **err);

Compares the position of `iter2` with this `obj` and returns difference in position of the two (`obj` - `iter2`).

`obj` : | Self
`iter2` : | Second iter to differenciate.
`err` : | Error propagation and reporting
Returns : | The position difference of `obj` - `iter2`

### ianjuta_iterable_first ()

    gboolean            ianjuta_iterable_first              (IAnjutaIterable *obj,
                                                             GError **err);

Set iter to first element position. Returns FALSE if there is no element in the iterable (hence does not have first). The iter points to the first valid item.

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | TRUE if sucessful, other FALSE.

### ianjuta_iterable_foreach ()

    void                ianjuta_iterable_foreach            (IAnjutaIterable *obj,
                                                             GFunc callback,
                                                             gpointer user_data,
                                                             GError **err);

Call callback for each element in the list. Call back is passed the same iter, but with different position set (from first to last). This method does not affect current position. i.e. current position is restored at the end of this method.

`obj` : | Self
`callback` : | Callback to call for each element.
`user_data` : | user data that is passed back to the callback.
`err` : | Error propagation and reporting

### ianjuta_iterable_get_length ()

    gint                ianjuta_iterable_get_length         (IAnjutaIterable *obj,
                                                             GError **err);

Length of the iterable (number of elements indexable by it).

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | total length of the list.

### ianjuta_iterable_get_position ()

    gint                ianjuta_iterable_get_position       (IAnjutaIterable *obj,
                                                             GError **err);

Index of the current iter in the iterable. It will be from 0 to length - 1 (`ianjuta_iter_get_length()`) if iter is pointed at valid element. It will return -1 if iter is pointed at end-iter.

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | integer index, or -1 for end-iter.

### ianjuta_iterable_last ()

    gboolean            ianjuta_iterable_last               (IAnjutaIterable *obj,
                                                             GError **err);

Set iter position to end-iter (one past last element) position. Returns FALSE if there is no element in the iterable (already at end-iter).

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | TRUE if sucessful, other FALSE.

### ianjuta_iterable_next ()

    gboolean            ianjuta_iterable_next               (IAnjutaIterable *obj,
                                                             GError **err);

Set the iter position to next element position. Iter can go until one item past the last item and lands in end-iter. end-iter does not point to any valid item and signifies end of the list. Returns FALSE if iter was already at end-iter (iter can not go past it) and remains pointed to the end-iter.

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | TRUE if sucessful, otherwise FALSE if already at end-iter.

### ianjuta_iterable_previous ()

    gboolean            ianjuta_iterable_previous           (IAnjutaIterable *obj,
                                                             GError **err);

Set the iter position to previous element position. Returns FALSE if there is no previous element and the iter remains pointed to the first element.

`obj` : | Self
`err` : | Error propagation and reporting
Returns : | TRUE if sucessful, other FALSE.

### ianjuta_iterable_set_position ()

    gboolean            ianjuta_iterable_set_position       (IAnjutaIterable *obj,
                                                             gint position,
                                                             GError **err);

Sets the current position of the iter to `position`. The given `position` must be from 0 to length - 1 (#`ianjuta_iter_get_length()`) to point to a valid element. Passing `position` < 0 will set it to end-iter. It returns TRUE for the above cases. FLASE will be returned, if out-of-range `position` is passed (`position` > length - 1) and iter is set to end-iter.

`obj` : | Self
`position` : | New position for the iter.
`err` : | Error propagation and reporting
Returns : | TRUE if successfully set (i.e. `position` is within the range or end-iter). otherwise returns FALSE (i.e. `position` is out of data range).