GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
ZLIST(3) CZMQ Manual ZLIST(3)

zlist - Class for simple generic list container

//  This is a stable class, and may not change except for emergencies. It
//  is provided in stable builds.
// Comparison function e.g. for sorting and removing.
typedef int (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 the item at the head of list. If the list is empty, returns NULL.
//  Leaves cursor pointing at the head item, or NULL if the list is empty.
CZMQ_EXPORT void *
    zlist_first (zlist_t *self);
//  Return the next item. If the list is empty, returns NULL. To move to
//  the start of the list call zlist_first (). Advances the cursor.
CZMQ_EXPORT void *
    zlist_next (zlist_t *self);
//  Return the item at the tail of list. If the list is empty, returns NULL.
//  Leaves cursor pointing at the tail item, or NULL if the list is empty.
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 the current item of list. If the list is empty, returns NULL.
//  Leaves cursor pointing at the current item, or NULL if the list is empty.
CZMQ_EXPORT void *
    zlist_item (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). Note that if a duplicator has
//  been set, this method will also duplicate the item.
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). Note that if a duplicator has
//  been set, this method will also duplicate the item.
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);
//  Checks if an item already is present. Uses compare method to determine if
//  items are equal. If the compare method is NULL the check will only compare
//  pointers. Returns true if item is present else false.
CZMQ_EXPORT bool
    zlist_exists (zlist_t *self, void *item);
//  Remove the specified item from the list if present
CZMQ_EXPORT void
    zlist_remove (zlist_t *self, void *item);
//  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. If list is null, returns
//  NULL.
//  Caller owns return value and must destroy it when done.
CZMQ_EXPORT zlist_t *
    zlist_dup (zlist_t *self);
//  Purge all items from list
CZMQ_EXPORT void
    zlist_purge (zlist_t *self);
//  Return number of items in the list
CZMQ_EXPORT size_t
    zlist_size (zlist_t *self);
//  Sort the list. If the compare function is null, sorts the list by
//  ascending key value using a straight ASCII comparison. If you specify
//  a compare function, this decides how items are sorted. The sort is not
//  stable, so may reorder items with the same keys. The algorithm used is
//  combsort, a compromise between performance and simplicity.
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);
//  Sets a compare function for this list. The function compares two items.
//  It returns an integer less than, equal to, or greater than zero if the
//  first item is found, respectively, to be less than, to match, or be
//  greater than the second item.
//  This function is used for sorting, removal and exists checking.
CZMQ_EXPORT void
    zlist_comparefn (zlist_t *self, zlist_compare_fn fn);
//  Set a free function for the specified list item. When the item is
//  destroyed, the free function, if any, is called on that item.
//  Use this when list items are dynamically allocated, to ensure that
//  you don't have memory leaks. You can pass 'free' or NULL as a free_fn.
//  Returns the item, or NULL if there is no such item.
CZMQ_EXPORT void *
    zlist_freefn (zlist_t *self, void *item, zlist_free_fn fn, bool at_tail);
//  Self test of this class.
CZMQ_EXPORT void
    zlist_test (bool verbose);
Please add '@interface' section in './../src/zlist.c'.

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. This is a simple class. For demanding applications we recommend using zlistx.

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.

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);
assert ( zlist_exists (list, cheese));
assert (!zlist_exists (list, bread));
assert (!zlist_exists (list, wine));
zlist_append (list, bread);
assert (zlist_size (list) == 2);
assert ( zlist_exists (list, cheese));
assert ( zlist_exists (list, bread));
assert (!zlist_exists (list, wine));
zlist_append (list, wine);
assert (zlist_size (list) == 3);
assert ( zlist_exists (list, cheese));
assert ( zlist_exists (list, bread));
assert ( zlist_exists (list, wine));
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);
assert (zlist_item (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, NULL);
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);
zlist_destroy (&list);
//  Test autofree functionality
list = zlist_new ();
assert (list);
zlist_autofree (list);
//  Set equals function otherwise equals will not work as autofree copies strings
zlist_comparefn (list, (zlist_compare_fn *) strcmp);
zlist_push (list, bread);
zlist_append (list, cheese);
assert (zlist_size (list) == 2);
zlist_append (list, wine);
assert (zlist_exists (list, wine));
zlist_remove (list, wine);
assert (!zlist_exists (list, wine));
assert (streq ((const char *) zlist_first (list), bread));
item = (char *) zlist_pop (list);
assert (streq (item, bread));
freen (item);
item = (char *) zlist_pop (list);
assert (streq (item, cheese));
freen (item);
zlist_destroy (&list);
assert (list == NULL);
#if defined (__WINDOWS__)
zsys_shutdown();
#endif

The czmq manual was written by the authors in the AUTHORS file.

Main web site:

Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>

Copyright (c) the Contributors as noted in the AUTHORS file. This file is part of CZMQ, the high-level C binding for 0MQ: http://czmq.zeromq.org. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/. LICENSE included with the czmq distribution.

1.
zeromq-dev@lists.zeromq.org
mailto:zeromq-dev@lists.zeromq.org
04/09/2022 CZMQ 4.2.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.