1<class name = "zlist" state = "stable">
2    <!--
3    Copyright (c) the Contributors as noted in the AUTHORS file.
4    This file is part of CZMQ, the high-level C binding for 0MQ:
5    http://czmq.zeromq.org.
6
7    This Source Code Form is subject to the terms of the Mozilla Public
8    License, v. 2.0. If a copy of the MPL was not distributed with this
9    file, You can obtain one at http://mozilla.org/MPL/2.0/.
10    -->
11    simple generic list container
12
13    <callback_type name = "compare_fn">
14        Comparison function e.g. for sorting and removing.
15        <argument name = "item1" type = "anything" />
16        <argument name = "item2" type = "anything" />
17        <return type = "integer" />
18    </callback_type>
19
20    <callback_type name = "free_fn">
21        Callback function for zlist_freefn method
22        <argument name = "data" type = "anything" />
23    </callback_type>
24
25    <constructor>
26        Create a new list container
27    </constructor>
28
29    <destructor>
30        Destroy a list container
31    </destructor>
32
33    <method name = "first">
34        Return the item at the head of list. If the list is empty, returns NULL.
35        Leaves cursor pointing at the head item, or NULL if the list is empty.
36        <return type = "anything" />
37    </method>
38
39    <method name = "next">
40        Return the next item. If the list is empty, returns NULL. To move to
41        the start of the list call zlist_first (). Advances the cursor.
42        <return type = "anything" />
43    </method>
44
45    <method name = "last">
46        Return the item at the tail of list. If the list is empty, returns NULL.
47        Leaves cursor pointing at the tail item, or NULL if the list is empty.
48        <return type = "anything" />
49    </method>
50
51    <method name = "head">
52        Return first item in the list, or null, leaves the cursor
53        <return type = "anything" />
54    </method>
55
56    <method name = "tail">
57        Return last item in the list, or null, leaves the cursor
58        <return type = "anything" />
59    </method>
60
61    <method name = "item">
62        Return the current item of list. If the list is empty, returns NULL.
63        Leaves cursor pointing at the current item, or NULL if the list is empty.
64        <return type = "anything" />
65    </method>
66
67    <method name = "append">
68        Append an item to the end of the list, return 0 if OK or -1 if this
69        failed for some reason (out of memory). Note that if a duplicator has
70        been set, this method will also duplicate the item.
71        <argument name = "item" type = "anything" />
72        <return type = "integer" />
73    </method>
74
75    <method name = "push">
76        Push an item to the start of the list, return 0 if OK or -1 if this
77        failed for some reason (out of memory). Note that if a duplicator has
78        been set, this method will also duplicate the item.
79        <argument name = "item" type = "anything" />
80        <return type = "integer" />
81    </method>
82
83    <method name = "pop">
84        Pop the item off the start of the list, if any
85        <return type = "anything" />
86    </method>
87
88    <method name = "exists">
89        Checks if an item already is present. Uses compare method to determine if
90        items are equal. If the compare method is NULL the check will only compare
91        pointers. Returns true if item is present else false.
92        <argument name = "item" type = "anything" />
93        <return type = "boolean" />
94    </method>
95
96    <method name = "remove">
97        Remove the specified item from the list if present
98        <argument name = "item" type = "anything" />
99    </method>
100
101    <method name = "dup">
102        Make a copy of list. If the list has autofree set, the copied list will
103        duplicate all items, which must be strings. Otherwise, the list will hold
104        pointers back to the items in the original list. If list is null, returns
105        NULL.
106        <return type = "zlist" fresh = "1" />
107    </method>
108
109    <method name = "purge">
110        Purge all items from list
111    </method>
112
113    <method name = "size">
114        Return number of items in the list
115        <return type = "size" />
116    </method>
117
118    <method name = "sort">
119        Sort the list. If the compare function is null, sorts the list by
120        ascending key value using a straight ASCII comparison. If you specify
121        a compare function, this decides how items are sorted. The sort is not
122        stable, so may reorder items with the same keys. The algorithm used is
123        combsort, a compromise between performance and simplicity.
124        <argument name = "compare" type = "zlist_compare_fn" callback = "1" />
125    </method>
126
127    <method name = "autofree">
128        Set list for automatic item destruction; item values MUST be strings.
129        By default a list item refers to a value held elsewhere. When you set
130        this, each time you append or push a list item, zlist will take a copy
131        of the string value. Then, when you destroy the list, it will free all
132        item values automatically. If you use any other technique to allocate
133        list values, you must free them explicitly before destroying the list.
134        The usual technique is to pop list items and destroy them, until the
135        list is empty.
136    </method>
137
138    <method name = "comparefn">
139        Sets a compare function for this list. The function compares two items.
140        It returns an integer less than, equal to, or greater than zero if the
141        first item is found, respectively, to be less than, to match, or be
142        greater than the second item.
143        This function is used for sorting, removal and exists checking.
144        <argument name = "fn" type = "zlist_compare_fn" callback = "1" />
145    </method>
146
147    <method name = "freefn">
148        Set a free function for the specified list item. When the item is
149        destroyed, the free function, if any, is called on that item.
150        Use this when list items are dynamically allocated, to ensure that
151        you don't have memory leaks. You can pass 'free' or NULL as a free_fn.
152        Returns the item, or NULL if there is no such item.
153        <argument name = "item" type = "anything" />
154        <argument name = "fn" type = "zlist_free_fn" callback = "1" />
155        <argument name = "at tail" type = "boolean" />
156        <return type = "anything" />
157    </method>
158</class>
159