You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
316 lines
11 KiB
316 lines
11 KiB
'\" 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
|
|
|