1ZLIST(3) CZMQ Manual ZLIST(3)
2
6 zlist - Class for simple generic list container
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // Comparison function e.g. for sorting and removing.
12 typedef int (zlist_compare_fn) (
13 void *item1, void *item2);
14 // Callback function for zlist_freefn method
16 typedef void (zlist_free_fn) (
17 void *data);
18 // Create a new list container
20 CZMQ_EXPORT zlist_t *
21 zlist_new (void);
22 // Destroy a list container
24 CZMQ_EXPORT void
25 zlist_destroy (zlist_t **self_p);
26 // Return the item at the head of list. If the list is empty, returns NULL.
28 // Leaves cursor pointing at the head item, or NULL if the list is empty.
29 CZMQ_EXPORT void *
30 zlist_first (zlist_t *self);
31 // Return the next item. If the list is empty, returns NULL. To move to
33 // the start of the list call zlist_first (). Advances the cursor.
34 CZMQ_EXPORT void *
35 zlist_next (zlist_t *self);
36 // Return the item at the tail of list. If the list is empty, returns NULL.
38 // Leaves cursor pointing at the tail item, or NULL if the list is empty.
39 CZMQ_EXPORT void *
40 zlist_last (zlist_t *self);
41 // Return first item in the list, or null, leaves the cursor
43 CZMQ_EXPORT void *
44 zlist_head (zlist_t *self);
45 // Return last item in the list, or null, leaves the cursor
47 CZMQ_EXPORT void *
48 zlist_tail (zlist_t *self);
49 // Return the current item of list. If the list is empty, returns NULL.
51 // Leaves cursor pointing at the current item, or NULL if the list is empty.
52 CZMQ_EXPORT void *
53 zlist_item (zlist_t *self);
54 // Append an item to the end of the list, return 0 if OK or -1 if this
56 // failed for some reason (out of memory). Note that if a duplicator has
57 // been set, this method will also duplicate the item.
58 CZMQ_EXPORT int
59 zlist_append (zlist_t *self, void *item);
60 // Push an item to the start of the list, return 0 if OK or -1 if this
62 // failed for some reason (out of memory). Note that if a duplicator has
63 // been set, this method will also duplicate the item.
64 CZMQ_EXPORT int
65 zlist_push (zlist_t *self, void *item);
66 // Pop the item off the start of the list, if any
68 CZMQ_EXPORT void *
69 zlist_pop (zlist_t *self);
70 // Checks if an item already is present. Uses compare method to determine if
72 // items are equal. If the compare method is NULL the check will only compare
73 // pointers. Returns true if item is present else false.
74 CZMQ_EXPORT bool
75 zlist_exists (zlist_t *self, void *item);
76 // Remove the specified item from the list if present
78 CZMQ_EXPORT void
79 zlist_remove (zlist_t *self, void *item);
80 // Make a copy of list. If the list has autofree set, the copied list will
82 // duplicate all items, which must be strings. Otherwise, the list will hold
83 // pointers back to the items in the original list. If list is null, returns
84 // NULL.
85 // Caller owns return value and must destroy it when done.
86 CZMQ_EXPORT zlist_t *
87 zlist_dup (zlist_t *self);
88 // Purge all items from list
90 CZMQ_EXPORT void
91 zlist_purge (zlist_t *self);
92 // Return number of items in the list
94 CZMQ_EXPORT size_t
95 zlist_size (zlist_t *self);
96 // Sort the list. If the compare function is null, sorts the list by
98 // ascending key value using a straight ASCII comparison. If you specify
99 // a compare function, this decides how items are sorted. The sort is not
100 // stable, so may reorder items with the same keys. The algorithm used is
101 // combsort, a compromise between performance and simplicity.
102 CZMQ_EXPORT void
103 zlist_sort (zlist_t *self, zlist_compare_fn compare);
104 // Set list for automatic item destruction; item values MUST be strings.
106 // By default a list item refers to a value held elsewhere. When you set
107 // this, each time you append or push a list item, zlist will take a copy
108 // of the string value. Then, when you destroy the list, it will free all
109 // item values automatically. If you use any other technique to allocate
110 // list values, you must free them explicitly before destroying the list.
111 // The usual technique is to pop list items and destroy them, until the
112 // list is empty.
113 CZMQ_EXPORT void
114 zlist_autofree (zlist_t *self);
115 // Sets a compare function for this list. The function compares two items.
117 // It returns an integer less than, equal to, or greater than zero if the
118 // first item is found, respectively, to be less than, to match, or be
119 // greater than the second item.
120 // This function is used for sorting, removal and exists checking.
121 CZMQ_EXPORT void
122 zlist_comparefn (zlist_t *self, zlist_compare_fn fn);
123 // Set a free function for the specified list item. When the item is
125 // destroyed, the free function, if any, is called on that item.
126 // Use this when list items are dynamically allocated, to ensure that
127 // you don't have memory leaks. You can pass 'free' or NULL as a free_fn.
128 // Returns the item, or NULL if there is no such item.
129 CZMQ_EXPORT void *
130 zlist_freefn (zlist_t *self, void *item, zlist_free_fn fn, bool at_tail);
131 // Self test of this class.
133 CZMQ_EXPORT void
134 zlist_test (bool verbose);
135 Please add '@interface' section in './../src/zlist.c'.
137
139 Provides a generic container implementing a fast singly-linked list.
140 You can use this to construct multi-dimensional lists, and other
141 structures together with other generic containers like zhash. This is a
142 simple class. For demanding applications we recommend using zlistx.
143 To iterate through a list, use zlist_first to get the first item, then
145 loop while not null, and do zlist_next at the end of each iteration.
146
148 From zlist_test method.
149 zlist_t *list = zlist_new ();
151 assert (list);
152 assert (zlist_size (list) == 0);
153 // Three items we'll use as test data
155 // List items are void *, not particularly strings
156 char *cheese = "boursin";
157 char *bread = "baguette";
158 char *wine = "bordeaux";
159 zlist_append (list, cheese);
161 assert (zlist_size (list) == 1);
162 assert ( zlist_exists (list, cheese));
163 assert (!zlist_exists (list, bread));
164 assert (!zlist_exists (list, wine));
165 zlist_append (list, bread);
166 assert (zlist_size (list) == 2);
167 assert ( zlist_exists (list, cheese));
168 assert ( zlist_exists (list, bread));
169 assert (!zlist_exists (list, wine));
170 zlist_append (list, wine);
171 assert (zlist_size (list) == 3);
172 assert ( zlist_exists (list, cheese));
173 assert ( zlist_exists (list, bread));
174 assert ( zlist_exists (list, wine));
175 assert (zlist_head (list) == cheese);
177 assert (zlist_next (list) == cheese);
178 assert (zlist_first (list) == cheese);
180 assert (zlist_tail (list) == wine);
181 assert (zlist_next (list) == bread);
182 assert (zlist_first (list) == cheese);
184 assert (zlist_next (list) == bread);
185 assert (zlist_next (list) == wine);
186 assert (zlist_next (list) == NULL);
187 // After we reach end of list, next wraps around
188 assert (zlist_next (list) == cheese);
189 assert (zlist_size (list) == 3);
190 zlist_remove (list, wine);
192 assert (zlist_size (list) == 2);
193 assert (zlist_first (list) == cheese);
195 zlist_remove (list, cheese);
196 assert (zlist_size (list) == 1);
197 assert (zlist_first (list) == bread);
198 zlist_remove (list, bread);
200 assert (zlist_size (list) == 0);
201 zlist_append (list, cheese);
203 zlist_append (list, bread);
204 assert (zlist_last (list) == bread);
205 zlist_remove (list, bread);
206 assert (zlist_last (list) == cheese);
207 zlist_remove (list, cheese);
208 assert (zlist_last (list) == NULL);
209 zlist_push (list, cheese);
211 assert (zlist_size (list) == 1);
212 assert (zlist_first (list) == cheese);
213 zlist_push (list, bread);
215 assert (zlist_size (list) == 2);
216 assert (zlist_first (list) == bread);
217 assert (zlist_item (list) == bread);
218 zlist_append (list, wine);
220 assert (zlist_size (list) == 3);
221 assert (zlist_first (list) == bread);
222 zlist_t *sub_list = zlist_dup (list);
224 assert (sub_list);
225 assert (zlist_size (sub_list) == 3);
226 zlist_sort (list, NULL);
228 char *item;
229 item = (char *) zlist_pop (list);
230 assert (item == bread);
231 item = (char *) zlist_pop (list);
232 assert (item == wine);
233 item = (char *) zlist_pop (list);
234 assert (item == cheese);
235 assert (zlist_size (list) == 0);
236 assert (zlist_size (sub_list) == 3);
238 zlist_push (list, sub_list);
239 zlist_t *sub_list_2 = zlist_dup (sub_list);
240 zlist_append (list, sub_list_2);
241 assert (zlist_freefn (list, sub_list, &s_zlist_free, false) == sub_list);
242 assert (zlist_freefn (list, sub_list_2, &s_zlist_free, true) == sub_list_2);
243 zlist_destroy (&list);
244 // Test autofree functionality
246 list = zlist_new ();
247 assert (list);
248 zlist_autofree (list);
249 // Set equals function otherwise equals will not work as autofree copies strings
250 zlist_comparefn (list, (zlist_compare_fn *) strcmp);
251 zlist_push (list, bread);
252 zlist_append (list, cheese);
253 assert (zlist_size (list) == 2);
254 zlist_append (list, wine);
255 assert (zlist_exists (list, wine));
256 zlist_remove (list, wine);
257 assert (!zlist_exists (list, wine));
258 assert (streq ((const char *) zlist_first (list), bread));
259 item = (char *) zlist_pop (list);
260 assert (streq (item, bread));
261 freen (item);
262 item = (char *) zlist_pop (list);
263 assert (streq (item, cheese));
264 freen (item);
265 zlist_destroy (&list);
267 assert (list == NULL);
268 #if defined (__WINDOWS__)
270 zsys_shutdown();
271 #endif
272
275 The czmq manual was written by the authors in the AUTHORS file.
276
278 Main web site:
279 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
281
283 Copyright (c) the Contributors as noted in the AUTHORS file. This file
284 is part of CZMQ, the high-level C binding for 0MQ:
285 http://czmq.zeromq.org. This Source Code Form is subject to the terms
286 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
287 distributed with this file, You can obtain one at
288 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
289 distribution.
290
292 1. zeromq-dev@lists.zeromq.org
293 mailto:zeromq-dev@lists.zeromq.org
294CZMQ 4.2.1 07/20/2022 ZLIST(3)