![]() |
![]() |
![]() |
Reference Manual of the tinymail framework | ![]() |
---|---|---|---|---|
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);
TnyList is implemented by TnySimpleList, TnyGtkHeaderListModel, TnyGtkFolderStoreTreeModel, TnyGtkAccountListModel and TnyGtkAttachListModel.
typedef struct _TnyList TnyList;
A list of things
free-function: g_object_unref type-parameter: G
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;
gboolean (*TnyListMatcher) (TnyList *list, GObject *item, gpointer match_data);
|
|
|
|
|
|
Returns : |
guint tny_list_get_length (TnyList *self);
Get the amount of items in self
.
|
A TnyList |
Returns : |
the length of the list |
Since 1.0 audience: application-developer, type-implementer
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
|
A TnyList |
|
(type-parameter G): the item to prepend |
Since 1.0 audience: application-developer, type-implementer
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
|
A TnyList |
|
(type-parameter G): the item to prepend |
Since 1.0 audience: application-developer, type-implementer
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);
|
A TnyList |
|
(type-parameter G): the item to remove |
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.
|
A TnyList |
|
the function to call with each element's data. |
|
user data to pass to the function. |
Since 1.0 audience: application-developer, type-implementer
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.
|
A TnyList |
Returns : |
(caller-owns) (type-parameter G): A new iterator for the list |
Since 1.0 audience: application-developer, type-implementer
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.
|
A TnyList |
Returns : |
(caller-owns) (type-parameter G): A copy of this list |
Since 1.0 audience: application-developer, type-implementer
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.
|
A TnyList |
|
a TnyListMatcher to match match_data against items
|
|
data used by the comparer to remove items |
Since 1.0 audience: application-developer, type-implementer