zlist(3)
CZMQ Manual - CZMQ/2.2.1
Name
zlist - generic type-free list container
Synopsis
// Comparison function for zlist_sort method
typedef bool (zlist_compare_fn) (void *item1, void *item2);
// Callback function for zlist_freefn method
typedef void (zlist_free_fn) (void *data);
// Create a new list container
CZMQ_EXPORT zlist_t *
zlist_new (void);
// Destroy a list container
CZMQ_EXPORT void
zlist_destroy (zlist_t **self_p);
// Return first item in the list, or null
CZMQ_EXPORT void *
zlist_first (zlist_t *self);
// Return last item in the list, or null
CZMQ_EXPORT void *
zlist_last (zlist_t *self);
// Return first item in the list, or null, leaves the cursor
CZMQ_EXPORT void *
zlist_head (zlist_t *self);
// Return last item in the list, or null, leaves the cursor
CZMQ_EXPORT void *
zlist_tail (zlist_t *self);
// Return next item in the list, or null
CZMQ_EXPORT void *
zlist_next (zlist_t *self);
// Append an item to the end of the list, return 0 if OK
// or -1 if this failed for some reason (out of memory).
CZMQ_EXPORT int
zlist_append (zlist_t *self, void *item);
// Push an item to the start of the list, return 0 if OK
// or -1 if this failed for some reason (out of memory).
CZMQ_EXPORT int
zlist_push (zlist_t *self, void *item);
// Pop the item off the start of the list, if any
CZMQ_EXPORT void *
zlist_pop (zlist_t *self);
// Remove the specified item from the list if present
CZMQ_EXPORT void
zlist_remove (zlist_t *self, void *item);
// Add an explicit free function to the item including a hint as to
// whether it can be found at the tail
CZMQ_EXPORT void *
zlist_freefn (zlist_t *self, void *item, zlist_free_fn *fn, bool at_tail);
// Make a copy of list. If the list has autofree set, the copied list will
// duplicate all items, which must be strings. Otherwise, the list will hold
// pointers back to the items in the original list.
CZMQ_EXPORT zlist_t *
zlist_dup (zlist_t *self);
// Return number of items in the list
CZMQ_EXPORT size_t
zlist_size (zlist_t *self);
// Sort the list by ascending key value using a straight ASCII comparison.
// The sort is not stable, so may reorder items with the same keys.
CZMQ_EXPORT void
zlist_sort (zlist_t *self, zlist_compare_fn *compare);
// Set list for automatic item destruction; item values MUST be strings.
// By default a list item refers to a value held elsewhere. When you set
// this, each time you append or push a list item, zlist will take a copy
// of the string value. Then, when you destroy the list, it will free all
// item values automatically. If you use any other technique to allocate
// list values, you must free them explicitly before destroying the list.
// The usual technique is to pop list items and destroy them, until the
// list is empty.
CZMQ_EXPORT void
zlist_autofree (zlist_t *self);
// Self test of this class
CZMQ_EXPORT void
zlist_test (int verbose);
Description
Provides a generic container implementing a fast singly-linked list. You can use this to construct multi-dimensional lists, and other structures together with other generic containers like zhash.
To iterate through a list, use zlist_first to get the first item, then loop while not null, and do zlist_next at the end of each iteration.
Example
From zlist_test method
zlist_t *list = zlist_new ();
assert (list);
assert (zlist_size (list) == 0);
// Three items we'll use as test data
// List items are void *, not particularly strings
char *cheese = "boursin";
char *bread = "baguette";
char *wine = "bordeaux";
zlist_append (list, cheese);
assert (zlist_size (list) == 1);
zlist_append (list, bread);
assert (zlist_size (list) == 2);
zlist_append (list, wine);
assert (zlist_size (list) == 3);
assert (zlist_head (list) == cheese);
assert (zlist_next (list) == cheese);
assert (zlist_first (list) == cheese);
assert (zlist_tail (list) == wine);
assert (zlist_next (list) == bread);
assert (zlist_first (list) == cheese);
assert (zlist_next (list) == bread);
assert (zlist_next (list) == wine);
assert (zlist_next (list) == NULL);
// After we reach end of list, next wraps around
assert (zlist_next (list) == cheese);
assert (zlist_size (list) == 3);
zlist_remove (list, wine);
assert (zlist_size (list) == 2);
assert (zlist_first (list) == cheese);
zlist_remove (list, cheese);
assert (zlist_size (list) == 1);
assert (zlist_first (list) == bread);
zlist_remove (list, bread);
assert (zlist_size (list) == 0);
zlist_append (list, cheese);
zlist_append (list, bread);
assert (zlist_last (list) == bread);
zlist_remove (list, bread);
assert (zlist_last (list) == cheese);
zlist_remove (list, cheese);
assert (zlist_last (list) == NULL);
zlist_push (list, cheese);
assert (zlist_size (list) == 1);
assert (zlist_first (list) == cheese);
zlist_push (list, bread);
assert (zlist_size (list) == 2);
assert (zlist_first (list) == bread);
zlist_append (list, wine);
assert (zlist_size (list) == 3);
assert (zlist_first (list) == bread);
zlist_t *sub_list = zlist_dup (list);
assert (sub_list);
assert (zlist_size (sub_list) == 3);
zlist_sort (list, s_compare);
char *item;
item = (char *) zlist_pop (list);
assert (item == bread);
item = (char *) zlist_pop (list);
assert (item == wine);
item = (char *) zlist_pop (list);
assert (item == cheese);
assert (zlist_size (list) == 0);
assert (zlist_size (sub_list) == 3);
zlist_push (list, sub_list);
zlist_t *sub_list_2 = zlist_dup (sub_list);
zlist_append (list, sub_list_2);
assert (zlist_freefn (list, sub_list, &s_zlist_free, false) == sub_list);
assert (zlist_freefn (list, sub_list_2, &s_zlist_free, true) == sub_list_2);
// Destructor should be safe to call twice
zlist_destroy (&list);
zlist_destroy (&list); assert (list == NULL);
See also
Authors
The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.
Resources
Main web site: http://czmq.zeromq.org/
Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>
Copyright
Copyright (c) 1991-2014 iMatix and Contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the CZMQ distribution.