·

zlistx (3) Linux Manual Page

ByLinux Manual Posted on

zlistx – extended generic list container

Synopsis

//  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 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, czmq_destructor 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, czmq_duplicator 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, czmq_comparator comparator);

//  Runs selftest of class
CZMQ_EXPORT void
zlistx_test(int verbose);

Description

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.

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.

Example

From zlistx_test method. 

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, (czmq_destructor *)zstr_free);
zlistx_set_duplicator(list, (czmq_duplicator *)strdup);
zlistx_set_comparator(list, (czmq_comparator *)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);

Authors

The czmq manual was written by the authors in the AUTHORS file.

Resources

Main web site: m[blue]m[]

Report bugs to the email <m[blue]zeromq-dev [at] lists.zeromq.orgm[][1]>

Copyright

Copyright (c) 1991-2012 iMatix Corporation — http://www.imatix.com Copyright other 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.

Notes

1.

zeromq-dev [at] lists.zeromq.org

mailto:zeromq-dev [at] lists.zeromq.org

Leave a Reply

Your email address will not be published. Required fields are marked *