Data Model Iterators
[Data Model API]

Iterators and their usage with models. More...

Functions

Eina_Iteratoreina_model_child_iterator_get (Eina_Model *model)
 create an iterator that outputs a child model on each iteration.
Eina_Iteratoreina_model_child_slice_iterator_get (Eina_Model *model, unsigned int start, unsigned int count)
 Gets an iterator to a slice of model's children.
Eina_Iteratoreina_model_child_reversed_iterator_get (Eina_Model *model)
 create an iterator that outputs a child model in reversed order.
Eina_Iteratoreina_model_child_slice_reversed_iterator_get (Eina_Model *model, unsigned int start, unsigned int count)
 Gets a reversed iterator to a slice of model's children.
Eina_Iteratoreina_model_child_sorted_iterator_get (Eina_Model *model, Eina_Compare_Cb compare)
 create an iterator that outputs a child model using sort criteria.
Eina_Iteratoreina_model_child_slice_sorted_iterator_get (Eina_Model *model, unsigned int start, unsigned int count, Eina_Compare_Cb compare)
 Returns a sorted iterator to a slice of model's children.
Eina_Iteratoreina_model_child_filtered_iterator_get (Eina_Model *model, Eina_Each_Cb match, const void *data)
 create an iterator that indexes of children that matches.
Eina_Iteratoreina_model_child_slice_filtered_iterator_get (Eina_Model *model, unsigned int start, unsigned int count, Eina_Each_Cb match, const void *data)
 Returns a filtered slice of the model's children.

Detailed Description

Iterators and their usage with models.

One of the most common tasks of models is to iterate over their children, either forwards or backwards, filtering by some criteria or a different ordering function.


Function Documentation

Eina_Iterator* eina_model_child_iterator_get ( Eina_Model model  ) 

create an iterator that outputs a child model on each iteration.

Parameters:
model the model instance.
Returns:
Newly created iterator instance on success or NULL on failure.
  Eina_Model *child;
  Eina_Iterator *it = eina_model_child_iterator_get(model);
  EINA_ITERATOR_FOREACH(it, child)
    {
       use_child(child);
       eina_model_unref(child);
    }
  eina_iterator_free(it);
This code shows how to use iterators to do something (in this example call use_child()) on every child element.

Warning:
Each iteration(call to eina_iterator_next()) gives a child model with reference increased! You must call eina_model_unref() after you're done with it.
See also:
eina_model_child_slice_iterator_get()

eina_model_child_reversed_iterator_get()

eina_model_child_sorted_iterator_get()

eina_model_child_filtered_iterator_get()

Since:
1.2

References eina_model_child_count().

Eina_Iterator* eina_model_child_slice_iterator_get ( Eina_Model model,
unsigned int  start,
unsigned int  count 
)

Gets an iterator to a slice of model's children.

Parameters:
model The model whose children to iterate over.
start The first child included in the iterator.
count The number of children included in the iterator.
Returns:
Newly created iterator instance on success or NULL on failure.
Warning:
Each iteration(call to eina_iterator_next()) gives a child model with reference increased! You must call eina_model_unref() after you're done with it.
See also:
eina_model_child_iterator_get()

eina_model_child_slice_reversed_iterator_get()

Since:
1.2

Eina_Iterator* eina_model_child_reversed_iterator_get ( Eina_Model model  ) 

create an iterator that outputs a child model in reversed order.

Parameters:
model the model instance.
Returns:
Newly created iterator instance on success or NULL on failure.
Each iteration output a child model with reference increased! You must call eina_model_unref() after you're done with it.

The order is reversed, that is, the last element is outputted first.

This code shows how to use iterators to do something (in this example call use_child()) on every child element starting from last to first.

Warning:
Each iteration(call to eina_iterator_next()) gives a child model with reference increased! You must call eina_model_unref() after you're done with it.
See also:
eina_model_child_slice_iterator_get()

eina_model_child_reversed_iterator_get()

eina_model_child_sorted_iterator_get()

eina_model_child_filtered_iterator_get()

Since:
1.2

References eina_model_child_count().

Eina_Iterator* eina_model_child_slice_reversed_iterator_get ( Eina_Model model,
unsigned int  start,
unsigned int  count 
)

Gets a reversed iterator to a slice of model's children.

Parameters:
model The model whose children to iterate over.
start The first child included in the iterator.
count The number of children included in the iterator.
Returns:
Newly created iterator instance on success or NULL on failure.
Warning:
Each iteration(call to eina_iterator_next()) gives a child model with reference increased! You must call eina_model_unref() after you're done with it.
See also:
eina_model_child_reversed_iterator_get()

eina_model_child_slice_iterator_get()

Since:
1.2

Eina_Iterator* eina_model_child_sorted_iterator_get ( Eina_Model model,
Eina_Compare_Cb  compare 
)

create an iterator that outputs a child model using sort criteria.

Parameters:
model the model instance.
compare compare function to use as sort criteria.
Returns:
Newly created iterator instance on success or NULL on failure.
Each iteration output a child model with reference increased! You must call eina_model_unref() after you're done with it.

The sort will not affect the main object model, it's just a view of it.

This bit of code shows how to use iterators to do something (in this example call use_child()) on every child element in the order given by the compare function.

Warning:
Each iteration(call to eina_iterator_next()) gives a child model with reference increased! You must call eina_model_unref() after you're done with it.
See also:
eina_model_child_slice_iterator_get()

eina_model_child_reversed_iterator_get()

eina_model_child_sorted_iterator_get()

eina_model_child_filtered_iterator_get()

Since:
1.2

References eina_model_child_count().

Eina_Iterator* eina_model_child_slice_sorted_iterator_get ( Eina_Model model,
unsigned int  start,
unsigned int  count,
Eina_Compare_Cb  compare 
)

Returns a sorted iterator to a slice of model's children.

Parameters:
model The model whose children to iterate over.
start The position(before sorting) of the first child included in the iterator.
count The number of children included in the iterator.
compare The function used to sort the children.
Returns:
Newly created iterator instance on success or NULL on failure.
Warning:
Each iteration(call to eina_iterator_next()) gives a child model with reference increased! You must call eina_model_unref() after you're done with it.
See also:
eina_model_child_slice_iterator_get()

eina_model_child_reversed_iterator_get()

eina_model_child_sorted_iterator_get()

eina_model_child_filtered_iterator_get()

Since:
1.2

Eina_Iterator* eina_model_child_filtered_iterator_get ( Eina_Model model,
Eina_Each_Cb  match,
const void *  data 
)

create an iterator that indexes of children that matches.

Parameters:
model the model instance.
match function to select children.
data extra context given to match function.
Returns:
Newly created iterator instance on success or NULL on failure.
Unlike other iterators, each iteration output an integer index! This is useful if you want to highlight the matching model somewhere else.

If no child element matches a valid, and empty, iterator will be returned. Indexes returned by this iterator are guaranteed to exists.

  unsigned int idx;
  Eina_Iterator *it = eina_model_child_filtered_iterator_get(model, filter, ctx);
  EINA_ITERATOR_FOREACH(it, idx)
    {
       Eina_Model *child = eina_model_child_get(model, idx);
       printf("matches at %u %p\n", idx, child);
       eina_model_unref(child);
    }
  eina_iterator_free(it);
This bit of code shows how to use iterators to do something (in this example print the address) on child elements that match the criteria given of match.

See also:
eina_model_child_slice_iterator_get()

eina_model_child_reversed_iterator_get()

eina_model_child_sorted_iterator_get()

eina_model_child_filtered_iterator_get()

Since:
1.2

References eina_model_child_count().

Eina_Iterator* eina_model_child_slice_filtered_iterator_get ( Eina_Model model,
unsigned int  start,
unsigned int  count,
Eina_Each_Cb  match,
const void *  data 
)

Returns a filtered slice of the model's children.

Parameters:
model The model whose children to iterate over.
start The position of the first child to be tested for inclusion in the iterator.
count The number of children to be tested for inclusion in the iterator.
match The function used to decide which children will be included in the iterator.
data Data passed to the match function.
Returns:
Newly created iterator instance on success or NULL on failure.
Note:
Only children for whom match returns EINA_TRUE will be included in the iterator.

Each iteration(call to eina_iterator_next()) gives an integer index!

Warning:
The iterator may have less than count children, but not more.
See also:
eina_model_child_slice_iterator_get()

eina_model_child_reversed_iterator_get()

eina_model_child_sorted_iterator_get()

eina_model_child_filtered_iterator_get()

Since:
1.2