zlist(3)

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

czmq(7)

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.