openpilot_comma/external/zmq/share/man/man3/zlist.3

'\" t
.\"     Title: zlist
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 12/31/2016
.\"    Manual: CZMQ Manual
.\"    Source: CZMQ 4.0.2
.\"  Language: English
.\"
.TH "ZLIST" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "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 \- 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));
free (item);
item = (char *) zlist_pop (list);
assert (streq (item, cheese));
free (item);

zlist_destroy (&list);
assert (list == NULL);
.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