TnyList

TnyList — A list type

Synopsis




                    TnyList;
                    TnyListIface;
gboolean            (*TnyListMatcher)                   (TnyList *list,
                                                         GObject *item,
                                                         gpointer match_data);
guint               tny_list_get_length                 (TnyList *self);
void                tny_list_prepend                    (TnyList *self,
                                                         GObject *item);
void                tny_list_append                     (TnyList *self,
                                                         GObject *item);
void                tny_list_remove                     (TnyList *self,
                                                         GObject *item);
void                tny_list_foreach                    (TnyList *self,
                                                         GFunc func,
                                                         gpointer user_data);
TnyIterator*        tny_list_create_iterator            (TnyList *self);
TnyList*            tny_list_copy                       (TnyList *self);
void                tny_list_remove_matches             (TnyList *self,
                                                         TnyListMatcher matcher,
                                                         gpointer match_data);

Object Hierarchy


  GInterface
   +----TnyList

Known Implementations

TnyList is implemented by TnySimpleList, TnyGtkHeaderListModel, TnyGtkFolderStoreTreeModel, TnyGtkAccountListModel and TnyGtkAttachListModel.

Description

An iteratable list type

Details

TnyList

typedef struct _TnyList TnyList;

A list of things

free-function: g_object_unref type-parameter: G


TnyListIface

typedef struct {
	GTypeInterface parent;

	guint (*get_length) (TnyList *self);
	void (*prepend) (TnyList *self, GObject* item);
	void (*append) (TnyList *self, GObject* item);
	void (*remove) (TnyList *self, GObject* item);
	void (*foreach) (TnyList *self, GFunc func, gpointer user_data);
	TnyList* (*copy) (TnyList *self);
	TnyIterator* (*create_iterator) (TnyList *self);
	void (*remove_matches) (TnyList *self, TnyListMatcher matcher, gpointer match_data);
} TnyListIface;


TnyListMatcher ()

gboolean            (*TnyListMatcher)                   (TnyList *list,
                                                         GObject *item,
                                                         gpointer match_data);

list :
item :
match_data :
Returns :

tny_list_get_length ()

guint               tny_list_get_length                 (TnyList *self);

Get the amount of items in self.

self : A TnyList
Returns : the length of the list

Since 1.0 audience: application-developer, type-implementer


tny_list_prepend ()

void                tny_list_prepend                    (TnyList *self,
                                                         GObject *item);

Prepends an item to a list. You can only prepend items that inherit from the GObject base item. That's because Tinymail's list infrastructure does reference counting. Consider using a doubly linked list, a pointer array or any other list-type available on your development platform for non-GObject lists.

The item you add will get a reference added by self, with self claiming ownership of item. When self is finalised, that reference is taken from item.

Prepending an item invalidates all existing iterators and puts them in an unspecified state. You'll need to recreate the iterator(s) when prepending items.

When implementing, if you have to choose, make this one the fast one

self : A TnyList
item : (type-parameter G): the item to prepend

Since 1.0 audience: application-developer, type-implementer


tny_list_append ()

void                tny_list_append                     (TnyList *self,
                                                         GObject *item);

Appends an item to a list. You can only prepend items that inherit from the GObject base item. That's because Tinymail's list infrastructure does reference counting. Consider using a doubly linked list, a pointer array or any other list-type available on your development platform for non-GObject lists.

The item you add will get a reference added by self, with self claiming ownership of item. When self is finalised, that reference is taken from item.

Appending an item invalidates all existing iterators and puts them in an unspecified state. You'll need to recreate the iterator(s) when appending items.

When implementing, if you have to choose, make the prepend one the fast one

self : A TnyList
item : (type-parameter G): the item to prepend

Since 1.0 audience: application-developer, type-implementer


tny_list_remove ()

void                tny_list_remove                     (TnyList *self,
                                                         GObject *item);

Removes an item from a list. Removing a item invalidates all existing iterators and puts them in an unspecified state. You'll need to recreate the iterator(s) when removing an item.

If you want to clear a list, consider using the tny_list_foreach() or simply destroy the list instance and construct a new one. If you want to remove specific items from a list, consider using a second list. You should not attempt to remove items from a list while an iterator is active on the same list.

Removing item from self will decrease the reference count of item by one.

Example (removing even items):

TnyList *toremovefrom = ...
TnyList *removethese = tny_simple_list_new ();
TnyIterator *iter = tny_list_create_iterator (toremovefrom);
int i = 0;
while (!tny_iterator_is_done (iter))
{
     if (i % 2 == 0)
     {
          GObject *obj = tny_iterator_get_current (iter);
          tny_list_prepend (removethese, obj);
          g_object_unref (G_OBJECT (obj));
     }
     i++;
     tny_iterator_next (iter);
}
g_object_unref (iter);
iter = tny_list_create_iterator (removethese);
while (!tny_iterator_is_done (iter))
{
     GObject *obj = tny_iterator_get_current (iter);
     tny_list_remove (toremovefrom, obj);
     g_object_unref (G_OBJECT (obj));
     tny_iterator_next (iter);
}
g_object_unref (iter);
g_object_unref (removethese);
g_object_unref (toremovefrom);

self : A TnyList
item : (type-parameter G): the item to remove

tny_list_foreach ()

void                tny_list_foreach                    (TnyList *self,
                                                         GFunc func,
                                                         gpointer user_data);

Calls func for each element in a TnyList. It will use an internal iteration which you don't have to worry about as application developer.

Example:

static void
list_foreach_item (TnyHeader *header, gpointer user_data)
{
     g_print ("%s\n", tny_header_get_subject (header));
}

TnyFolder *folder = ...
TnyList *headers = tny_simple_list_new ();
tny_folder_get_headers (folder, headers, FALSE);
tny_list_foreach (headers, list_foreach_item, NULL);
g_object_unref (G_OBJECT (list));

The purpose of this method is to have a fast foreach iteration. Using this is faster than inventing your own foreach loop using the is_done and next methods. The order is guaranteed to be the first element first, the last element last. If during the iteration you don't remove items, it's guaranteed that all current items will be iterated.

In the func implementation and during the foreach operation you must not append, remove nor prepend items to the list. In multithreaded environments it's advisable to introduce a lock when using this functionality.

self : A TnyList
func : the function to call with each element's data.
user_data : user data to pass to the function.

Since 1.0 audience: application-developer, type-implementer


tny_list_create_iterator ()

TnyIterator*        tny_list_create_iterator            (TnyList *self);

Creates a new iterator instance for the list. The initial position of the iterator is the first element.

An iterator keeps a position state of a list iteration. The list itself does not keep any position information. Using multiple iterator instances makes it possible to have simultaneous list iterations (i.e. multiple threads or in a loop that uses with multiple position states in a single list).

Example:

TnyList *list = tny_simple_list_new ();
TnyIterator *iter1 = tny_list_create_iterator (list);
TnyIterator *iter2 = tny_list_create_iterator (list);
while (!tny_iterator_is_done (iter1))
{
     while (!tny_iterator_is_done (iter2))
           tny_iterator_next (iter2);
     tny_iterator_next (iter1);
}
g_object_unref (iter1);
g_object_unref (iter2);
g_object_unref (list);

The reason why the method isn't called get_iterator is because it's a object creation method (a factory method). Therefore it's not a property. Instead it creates a new instance of an iterator. The returned iterator object should (therefore) be unreferenced after use.

self : A TnyList
Returns : (caller-owns) (type-parameter G): A new iterator for the list

Since 1.0 audience: application-developer, type-implementer


tny_list_copy ()

TnyList*            tny_list_copy                       (TnyList *self);

Creates a shallow copy of self: it doesn't copy the content of the items. It creates a new list with new references to the same items. The items will get an extra reference added for the new list being their second owner, setting their reference count to for example two. Which means that the returned value must be unreferenced after use.

self : A TnyList
Returns : (caller-owns) (type-parameter G): A copy of this list

Since 1.0 audience: application-developer, type-implementer


tny_list_remove_matches ()

void                tny_list_remove_matches             (TnyList *self,
                                                         TnyListMatcher matcher,
                                                         gpointer match_data);

Removes items from a list. Removing items invalidates all existing iterators and put them in an unknown and unspecified state. You'll need to recreate the iterator(s) when removing items.

Example (items that match):

static void 
matcher (TnyList *list, GObject *item, gpointer match_data) {
    if (!strcmp (tny_header_get_subject ((TnyHeader *) item), match_data))
         return TRUE;
    return FALSE;
}
TnyList *headers = ...
tny_list_remove_matches (headers, matcher, "Remove subject");

There's no guarantee whatsoever that existing iterators of self will be valid after this method returned.

Note that if you didn't remove the initial reference when putting the item in the list, this remove will not take care of that initial reference either.

self : A TnyList
matcher : a TnyListMatcher to match match_data against items
match_data : data used by the comparer to remove items

Since 1.0 audience: application-developer, type-implementer

See Also

TnyIterator