Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
linkedlist(3m)		     MBA Library Functions		linkedlist(3m)

NAME
       linkedlist - a sigularly	linked list

SYNOPSIS
       #include	<mba/linkedlist.h>

       int linkedlist_init(struct linkedlist *l, unsigned int max_size,	struct allocator *al);
       int linkedlist_deinit(struct linkedlist *l, del_fn data_del, void *context);
       struct linkedlist *linkedlist_new(unsigned int max_size,	struct allocator *al);
       int linkedlist_del(struct linkedlist *l,	del_fn data_del, void *context);
       int linkedlist_clear(struct linkedlist *l, del_fn data_del, void	*context);

       int linkedlist_add(struct linkedlist *l,	void *data);
       int linkedlist_insert(struct linkedlist *l, unsigned int	idx, void *data);
       int linkedlist_insert_sorted(struct linkedlist *l,
		   cmp_fn cmp,
		   void	*context,
		   void	**replaced,
		   const void *data);
       int linkedlist_is_empty(const struct linkedlist *l);
       unsigned	int linkedlist_size(const struct linkedlist *l);
       void *linkedlist_get(const struct linkedlist *l,	unsigned int idx);
       void *linkedlist_get_last(const struct linkedlist *l);
       void linkedlist_iterate(void *l,	iter_t *iter);
       void *linkedlist_next(void *l, iter_t *iter);
       void *linkedlist_remove(struct linkedlist *l, unsigned int idx);
       void *linkedlist_remove_data(struct linkedlist *l, const	void *data);
       void *linkedlist_remove_last(struct linkedlist *l);

DESCRIPTION
       The  linkedlist	functions  manipulate  a sigularly linked list of data
       pointers.

       init   The linkedlist_init function initializes	a  linkedlist  object.
	      The  linkedlist  will  accepts  no  more than max_size items. If
	      max_size is zero the list	 will  accept  no  more	 than  MAX_INT
	      items. Memory for	list elements will be allocated	from the allo-
	      cator al.	 It may	be necessary to	call linkedlist_deinit to  re-
	      lease memory from	the allocator al.

       deinit The linkedlist_deinit function calls the data_del	function if it
	      is not NULL with each data pointer in the	list and  the  context
	      parameter	 context  and  then releases memory allocated for list
	      elements.

       new

       del    The linkedlist_del function deinitializes	the list  l  with  the
	      linkedlist_deinit	function before	freeing	l itself.

       clear  The  linkedlist_clear  function clears the list of all elements.
	      If the data_del function is not NULL it will be called with  the
	      context  argument	 and  each data	pointer	in the list before re-
	      leasing memory for list elements.

       add    The linkedlist_add function appends a data pointer to the	end of
	      the  list. If the	list has max_size elements, -1 is returned and
	      errno is set to ERANGE.

       insert inserts a	data pointer before the	item at	idx.  Ifidxequals  the
	      size of the list,	the data pointer will be appended to the list.

       insert_sorted
	      The  linkedlist_insert_sorted  function inserts the data pointer
	      data into	the linked list	l in a position	determined by the com-
	      parison function cmp which is defined as follows:

	      typedef int (*cmp_fn)(const void *object1, const void *object2, void *context);

       This  function  will be called repeatedly with the new data pointer and
       each data pointer in the	list until the insertion is complete or	an er-
       ror  occurs.  The  context parameter is passed as-is. The following de-
       scribes the outcome of the insertion based on the return	value  of  the
       cmp_fn:

       >  0  - No operation is performed. The next data	element	in the list is
       compared.
       == 0 - If the replaced parameter	is not NULL the	replaced data  pointer
       is  assigned  to	 it, removed from the list, and	the new	pointer	is in-
       serted in it's place. If	the replaced parameter is NULL	the  new  data
       pointer is inserted before the equal element.
       < 0 - The new data pointer is inserted before the compared element.

       is_empty
	      The linkedlist_is_empty function returns non-zero	if the list is
	      empty and	zero if	it is not empty.

       size   The linkedlist_size function returns the number of items in  the
	      list.

       get    The  linkedlist_get  function retrieves an item from the list by
	      index. If	elements are accessed forward-sequentially  each  call
	      is an O(1) operation.

       get_last
	      The  linkedlist_get_last	function returns the last data pointer
	      int the list or a	null pointer if	the list is empty.

       iterate,	next
	      Enumerate	each element in	the list. The linkedlist_iterate func-
	      tion  initializes	 the iter object to point to the first item in
	      the list.	Each subsequent	call to	 linkedlist_next  returns  the
	      next  element in the list	or NULL	if all elements	have been enu-
	      merated. The elements are	returned in order.

	      Because linkedlist uses an element index for the state of	an in-
	      terator,	after a	data object returned by	linkedlist_next	is re-
	      moved a subsequent call to linkedlist_next will skip an element.
	      Therefore,  to  remove elements during iteration,	linkedlist_get
	      should be	used instead. This will	have no	performance impact  as
	      sequential access	is O(1)	optimized.

	      To  enumerate each element in a list the following code might be
	      used:

	      iter_t iter;
	      linkedlist_iterate(lst, &iter);
	      while ((el = linkedlist_next(lst,	&iter))) {
		  /* use el */
	      }

       remove The linkedlist_remove function removes the data pointer  at  idx
	      from the list. Please refer to the description of	linkedlist_it-
	      erate for	important information regarding	the  removal  of  ele-
	      ments during an iteration.

       remove_data
	      The  linkedlist_remove_data  function  removes  the data pointer
	      data from	the list l.  Note that if the key is not  returned  or
	      freed  --	that operation must be performed independantly if nec-
	      essary. Also, please refer to the	description of	linkedlist_it-
	      erate  for  important  information regarding the removal of ele-
	      ments during an iteration.

       remove_last
	      The  linkedlist_remove_last  function  removes  the  last	  data
	      pointer in the list.

RETURNS
       init   The  linkedlist_init function returns -1 if sets errno to	an ap-
	      propriate	value if the operation failed or 0  if	the  list  was
	      successfully initialized.

       deinit The  linkedlist_deinit  function returns -1 and sets errno to an
	      appropriate value	if the operation failed	or 0 if	the  list  was
	      successfully deinitialized.

       new    The  linkedlist_new function allocates memory from the allocator
	      al, initializes it with the linkedlist_init function and returns
	      a	 pointer  to  the  a  new linkedlist object. If	memory for the
	      linkedlist cannot	be allocated a null pointer  is	 returned  and
	      errno is set appropriately.

       add    The  linkedlist_insert  function	returns	0 if the operation was
	      successful and -1	if an error occurred in	which case errno  will
	      be set appropriately.

       insert The  linkedlist_insert  function	returns	0 if the operation was
	      successful and -1	if an error occurred in	which case errno  will
	      be set appropriately.

       insert_sorted
	      The linkedlist_insert_sorted function returns 0 if the operation
	      was successful and -1 if an error	occurred in which  case	 errno
	      will be set appropriately.

       get    The  linkedlist_get  function returns the	data pointer being re-
	      trieved. If the specified	idx was	out of range, a	 null  pointer
	      is returned and errno is set to ERANGE.

       next   The  linkedlist_next  function  returns the next data pointer in
	      the list or NULL if all elements have been enumerated.

       remove The linkedlist_remove function returns the data pointer  removed
	      from the list.

       remove_data
	      The linkedlist_remove_data function returns the data pointer re-
	      moved from the list.

       remove_last
	      The linkedlist_remove_last function returns the data pointer re-
	      moved from the list.

libmba-0.9.1			 Apr 29, 2005			linkedlist(3m)

NAME | SYNOPSIS | DESCRIPTION | RETURNS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=linkedlist&sektion=3m&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help