'\" t .\" Title: zlist .\" Author: [see the "AUTHORS" section] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 01/17/2021 .\" Manual: CZMQ Manual .\" Source: CZMQ 4.2.1 .\" Language: English .\" .TH "ZLIST" "3" "01/17/2021" "CZMQ 4\&.2\&.1" "CZMQ Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" zlist \- Class for simple generic list container .SH "SYNOPSIS" .sp .nf // 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\*(Aqt have memory leaks\&. You can pass \*(Aqfree\*(Aq 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 \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zlist\&.c\*(Aq\&. .fi .SH "DESCRIPTION" .sp 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\&. .sp 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\&. .SH "EXAMPLE" .PP \fBFrom zlist_test method\fR. .sp .if n \{\ .RS 4 .\} .nf zlist_t *list = zlist_new (); assert (list); assert (zlist_size (list) == 0); // Three items we\*(Aqll 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 .fi .if n \{\ .RE .\} .sp .SH "AUTHORS" .sp The czmq manual was written by the authors in the AUTHORS file\&. .SH "RESOURCES" .sp Main web site: \m[blue]\fB\%\fR\m[] .sp Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2> .SH "COPYRIGHT" .sp 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\&. .SH "NOTES" .IP " 1." 4 zeromq-dev@lists.zeromq.org .RS 4 \%mailto:zeromq-dev@lists.zeromq.org .RE