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

'\" t
.\"     Title: zlistx
.\"    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 "ZLISTX" "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"
zlistx \- extended 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\&.
// Destroy an item
typedef void (zlistx_destructor_fn) (
    void **item);

// Duplicate an item
typedef void * (zlistx_duplicator_fn) (
    const void *item);

// Compare two items, for sorting
typedef int (zlistx_comparator_fn) (
    const void *item1, const void *item2);

//  Create a new, empty list\&.
CZMQ_EXPORT zlistx_t *
    zlistx_new (void);

//  Destroy a list\&. If an item destructor was specified, all items in the
//  list are automatically destroyed as well\&.
CZMQ_EXPORT void
    zlistx_destroy (zlistx_t **self_p);

//  Add an item to the head of the list\&. Calls the item duplicator, if any,
//  on the item\&. Resets cursor to list head\&. Returns an item handle on
//  success, NULL if memory was exhausted\&.
CZMQ_EXPORT void *
    zlistx_add_start (zlistx_t *self, void *item);

//  Add an item to the tail of the list\&. Calls the item duplicator, if any,
//  on the item\&. Resets cursor to list head\&. Returns an item handle on
//  success, NULL if memory was exhausted\&.
CZMQ_EXPORT void *
    zlistx_add_end (zlistx_t *self, void *item);

//  Return the number of items in the list
CZMQ_EXPORT size_t
    zlistx_size (zlistx_t *self);

//  Return first item in the list, or null, leaves the cursor
CZMQ_EXPORT void *
    zlistx_head (zlistx_t *self);

//  Return last item in the list, or null, leaves the cursor
CZMQ_EXPORT void *
    zlistx_tail (zlistx_t *self);

//  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 *
    zlistx_first (zlistx_t *self);

//  Return the next item\&. At the end of the list (or in an empty list),
//  returns NULL\&. Use repeated zlistx_next () calls to work through the list
//  from zlistx_first ()\&. First time, acts as zlistx_first()\&.
CZMQ_EXPORT void *
    zlistx_next (zlistx_t *self);

//  Return the previous item\&. At the start of the list (or in an empty list),
//  returns NULL\&. Use repeated zlistx_prev () calls to work through the list
//  backwards from zlistx_last ()\&. First time, acts as zlistx_last()\&.
CZMQ_EXPORT void *
    zlistx_prev (zlistx_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 *
    zlistx_last (zlistx_t *self);

//  Returns the value of the item at the cursor, or NULL if the cursor is
//  not pointing to an item\&.
CZMQ_EXPORT void *
    zlistx_item (zlistx_t *self);

//  Returns the handle of the item at the cursor, or NULL if the cursor is
//  not pointing to an item\&.
CZMQ_EXPORT void *
    zlistx_cursor (zlistx_t *self);

//  Returns the item associated with the given list handle, or NULL if passed
//  in handle is NULL\&. Asserts that the passed in handle points to a list element\&.
CZMQ_EXPORT void *
    zlistx_handle_item (void *handle);

//  Find an item in the list, searching from the start\&. Uses the item
//  comparator, if any, else compares item values directly\&. Returns the
//  item handle found, or NULL\&. Sets the cursor to the found item, if any\&.
CZMQ_EXPORT void *
    zlistx_find (zlistx_t *self, void *item);

//  Detach an item from the list, using its handle\&. The item is not modified,
//  and the caller is responsible for destroying it if necessary\&. If handle is
//  null, detaches the first item on the list\&. Returns item that was detached,
//  or null if none was\&. If cursor was at item, moves cursor to previous item,
//  so you can detach items while iterating forwards through a list\&.
CZMQ_EXPORT void *
    zlistx_detach (zlistx_t *self, void *handle);

//  Detach item at the cursor, if any, from the list\&. The item is not modified,
//  and the caller is responsible for destroying it as necessary\&. Returns item
//  that was detached, or null if none was\&. Moves cursor to previous item, so
//  you can detach items while iterating forwards through a list\&.
CZMQ_EXPORT void *
    zlistx_detach_cur (zlistx_t *self);

//  Delete an item, using its handle\&. Calls the item destructor is any is
//  set\&. If handle is null, deletes the first item on the list\&. Returns 0
//  if an item was deleted, \-1 if not\&. If cursor was at item, moves cursor
//  to previous item, so you can delete items while iterating forwards
//  through a list\&.
CZMQ_EXPORT int
    zlistx_delete (zlistx_t *self, void *handle);

//  Move an item to the start of the list, via its handle\&.
CZMQ_EXPORT void
    zlistx_move_start (zlistx_t *self, void *handle);

//  Move an item to the end of the list, via its handle\&.
CZMQ_EXPORT void
    zlistx_move_end (zlistx_t *self, void *handle);

//  Remove all items from the list, and destroy them if the item destructor
//  is set\&.
CZMQ_EXPORT void
    zlistx_purge (zlistx_t *self);

//  Sort the list\&. If an item comparator was set, calls that to compare
//  items, otherwise compares on item value\&. The sort is not stable, so may
//  reorder equal items\&.
CZMQ_EXPORT void
    zlistx_sort (zlistx_t *self);

//  Create a new node and insert it into a sorted list\&. Calls the item
//  duplicator, if any, on the item\&. If low_value is true, starts searching
//  from the start of the list, otherwise searches from the end\&. Use the item
//  comparator, if any, to find where to place the new node\&. Returns a handle
//  to the new node, or NULL if memory was exhausted\&. Resets the cursor to the
//  list head\&.
CZMQ_EXPORT void *
    zlistx_insert (zlistx_t *self, void *item, bool low_value);

//  Move an item, specified by handle, into position in a sorted list\&. Uses
//  the item comparator, if any, to determine the new location\&. If low_value
//  is true, starts searching from the start of the list, otherwise searches
//  from the end\&.
CZMQ_EXPORT void
    zlistx_reorder (zlistx_t *self, void *handle, bool low_value);

//  Make a copy of the list; items are duplicated if you set a duplicator
//  for the list, otherwise not\&. Copying a null reference returns a null
//  reference\&.
CZMQ_EXPORT zlistx_t *
    zlistx_dup (zlistx_t *self);

//  Set a user\-defined deallocator for list items; by default items are not
//  freed when the list is destroyed\&.
CZMQ_EXPORT void
    zlistx_set_destructor (zlistx_t *self, zlistx_destructor_fn destructor);

//  Set a user\-defined duplicator for list items; by default items are not
//  copied when the list is duplicated\&.
CZMQ_EXPORT void
    zlistx_set_duplicator (zlistx_t *self, zlistx_duplicator_fn duplicator);

//  Set a user\-defined comparator for zlistx_find and zlistx_sort; the method
//  must return \-1, 0, or 1 depending on whether item1 is less than, equal to,
//  or greater than, item2\&.
CZMQ_EXPORT void
    zlistx_set_comparator (zlistx_t *self, zlistx_comparator_fn comparator);

//  Self test of this class\&.
CZMQ_EXPORT void
    zlistx_test (bool verbose);

Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zlistx\&.c\*(Aq\&.
.fi
.SH "DESCRIPTION"
.sp
Provides a generic doubly\-linked list container\&. This container provides hooks for duplicator, comparator, and destructor functions\&. These tie into CZMQ and standard C semantics, so e\&.g\&. for string items you can use strdup, strcmp, and zstr_free\&. To store custom objects, define your own duplicator and comparator, and use the standard object destructor\&.
.sp
This is a reworking of the simpler zlist container\&. It is faster to insert and delete items anywhere in the list, and to keep ordered lists\&.
.SH "EXAMPLE"
.PP
\fBFrom zlistx_test method\fR. 
.sp
.if n \{\
.RS 4
.\}
.nf
zlistx_t *list = zlistx_new ();
assert (list);
assert (zlistx_size (list) == 0);

//  Test operations on an empty list
assert (zlistx_first (list) == NULL);
assert (zlistx_last (list) == NULL);
assert (zlistx_next (list) == NULL);
assert (zlistx_prev (list) == NULL);
assert (zlistx_find (list, "hello") == NULL);
assert (zlistx_delete (list, NULL) == \-1);
assert (zlistx_detach (list, NULL) == NULL);
assert (zlistx_delete (list, NULL) == \-1);
assert (zlistx_detach (list, NULL) == NULL);
zlistx_purge (list);
zlistx_sort (list);

//  Use item handlers
zlistx_set_destructor (list, (zlistx_destructor_fn *) zstr_free);
zlistx_set_duplicator (list, (zlistx_duplicator_fn *) strdup);
zlistx_set_comparator (list, (zlistx_comparator_fn *) strcmp);

//  Try simple insert/sort/delete/next
assert (zlistx_next (list) == NULL);
zlistx_add_end (list, "world");
assert (streq ((char *) zlistx_next (list), "world"));
zlistx_add_end (list, "hello");
assert (streq ((char *) zlistx_prev (list), "hello"));
zlistx_sort (list);
assert (zlistx_size (list) == 2);
void *handle = zlistx_find (list, "hello");
char *item1 = (char *) zlistx_item (list);
char *item2 = (char *) zlistx_handle_item (handle);
assert (item1 == item2);
assert (streq (item1, "hello"));
zlistx_delete (list, handle);
assert (zlistx_size (list) == 1);
char *string = (char *) zlistx_detach (list, NULL);
assert (streq (string, "world"));
free (string);
assert (zlistx_size (list) == 0);

//  Check next/back work
//  Now populate the list with items
zlistx_add_start (list, "five");
zlistx_add_end   (list, "six");
zlistx_add_start (list, "four");
zlistx_add_end   (list, "seven");
zlistx_add_start (list, "three");
zlistx_add_end   (list, "eight");
zlistx_add_start (list, "two");
zlistx_add_end   (list, "nine");
zlistx_add_start (list, "one");
zlistx_add_end   (list, "ten");

//  Test our navigation skills
assert (zlistx_size (list) == 10);
assert (streq ((char *) zlistx_last (list), "ten"));
assert (streq ((char *) zlistx_prev (list), "nine"));
assert (streq ((char *) zlistx_prev (list), "eight"));
assert (streq ((char *) zlistx_prev (list), "seven"));
assert (streq ((char *) zlistx_prev (list), "six"));
assert (streq ((char *) zlistx_prev (list), "five"));
assert (streq ((char *) zlistx_first (list), "one"));
assert (streq ((char *) zlistx_next (list), "two"));
assert (streq ((char *) zlistx_next (list), "three"));
assert (streq ((char *) zlistx_next (list), "four"));

//  Sort by alphabetical order
zlistx_sort (list);
assert (streq ((char *) zlistx_first (list), "eight"));
assert (streq ((char *) zlistx_last (list), "two"));

//  Moving items around
handle = zlistx_find (list, "six");
zlistx_move_start (list, handle);
assert (streq ((char *) zlistx_first (list), "six"));
zlistx_move_end (list, handle);
assert (streq ((char *) zlistx_last (list), "six"));
zlistx_sort (list);
assert (streq ((char *) zlistx_last (list), "two"));

//  Copying a list
zlistx_t *copy = zlistx_dup (list);
assert (copy);
assert (zlistx_size (copy) == 10);
assert (streq ((char *) zlistx_first (copy), "eight"));
assert (streq ((char *) zlistx_last (copy), "two"));
zlistx_destroy (&copy);

//  Delete items while iterating
string = (char *) zlistx_first (list);
assert (streq (string, "eight"));
string = (char *) zlistx_next (list);
assert (streq (string, "five"));
zlistx_delete (list, zlistx_cursor (list));
string = (char *) zlistx_next (list);
assert (streq (string, "four"));

zlistx_purge (list);
zlistx_destroy (&list);
.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