/*
 * "$Id: list.h,v 1.2 2004/11/28 15:59:29 rleigh Exp $"
 *
 *   libgimpprint generic list type
 *
 *   Copyright 1997-2000 Michael Sweet (mike@easysw.com),
 *	Robert Krawitz (rlk@alum.mit.edu) and Michael Natterer (mitch@gimp.org)
 *   Copyright 2002 Roger Leigh (rleigh@debian.org)
 *
 *   This program is free software; you can redistribute it and/or modify it
 *   under the terms of the GNU General Public License as published by the Free
 *   Software Foundation; either version 2 of the License, or (at your option)
 *   any later version.
 *
 *   This program is distributed in the hope that it will be useful, but
 *   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
 *   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 *   for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program; if not, write to the Free Software
 *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/**
 * @file gutenprint/list.h
 * @brief Generic list functions.
 */

/*
 * This file must include only standard C header files.  The core code must
 * compile on generic platforms that don't support glib, gimp, gtk, etc.
 */

#ifndef GUTENPRINT_LIST_H
#define GUTENPRINT_LIST_H

#ifdef __cplusplus
extern "C" {
#endif

/**
 * The list data type implements a fast generic doubly-linked list.
 * It supports all of the operations you might want in a list (insert,
 * remove, iterate over the list, copy whole lists), plus some
 * (optional) less common features: finding items by index, name or
 * long name, and sorting.  These should also be fairly fast, due to
 * caching in the list head.
 *
 * @defgroup list list
 * @{
 */

  struct stp_list_item;
  /**
   * The list item opaque data type.
   * This object is a node in the list.
   */
  typedef struct stp_list_item stp_list_item_t;

  struct stp_list;
  /**
   * The list opaque data type.
   * This object represents the list as a whole.
   */
  typedef struct stp_list stp_list_t;

  /**
   * A callback function to free the data a node contains.
   * The parameter is a pointer to the node data.
   */
  typedef void (*stp_node_freefunc)(void *);

  /**
   * A callback function to copy the data a node contains.
   * The parameter is a pointer to the node data.
   * The return value is a pointer to the new copy of the data.
   */
  typedef void *(*stp_node_copyfunc)(const void *);

  /**
   * A callback function to get the name of a node.
   * The parameter is a pointer to the node data.
   * The return value is a pointer to the name of the
   * node, or NULL if there is no name.
   */
  typedef const char *(*stp_node_namefunc)(const void *);

  /**
   * A callback function to compare two nodes.
   * The two parameters are pointers to node data.
   * The return value is <0 if the first sorts before the
   * second, 0 if they sort identically, and >0 if the
   * first sorts after the second.
   */
  typedef int (*stp_node_sortfunc)(const void *, const void *);

  /**
   * Free node data allocated with stp_malloc.
   * This function is indended for use as an stp_node_freefunc, which
   * uses stp_free to free the node data.
   * @param item the node data to free
   */
  extern void stp_list_node_free_data(void *item);

  /**
   * Create a new list object.
   * @returns the newly created list object.
   */
  extern stp_list_t *stp_list_create(void);

  /**
   * Copy and allocate a list object.
   * list must be a valid list object previously created with
   * stp_list_create().
   * @param list the list to copy.
   * @returns a pointer to the new copy of the list.
   */
  extern stp_list_t *stp_list_copy(const stp_list_t *list);

  /**
   * Destroy a list object.
   * It is an error to destroy the list more than once.
   * @param list the list to destroy.
   * @returns 0 on success, 1 on failure.
   */
  extern int stp_list_destroy(stp_list_t *list);

  /**
   * Find the first item in a list.
   * @param list the list to use.
   * @returns a pointer to the first list item, or NULL if the list is
   * empty.
   */
  extern stp_list_item_t *stp_list_get_start(const stp_list_t *list);

  /**
   * Find the last item in a list.
   * @param list the list to use.
   * @returns a pointer to the last list item, or NULL if the list is
   * empty.
   */
  extern stp_list_item_t *stp_list_get_end(const stp_list_t *list);

  /**
   * Find an item in a list by its index.
   * @param list the list to use.
   * @param idx the index to find.
   * @returns a pointer to the list item, or NULL if the index is
   * invalid or the list is empty.
   */
  extern stp_list_item_t *stp_list_get_item_by_index(const stp_list_t *list,
						     int idx);

  /**
   * Find an item in a list by its name.
   * @param list the list to use.
   * @param name the name to find.
   * @returns a pointer to the list item, or NULL if the name is
   * invalid or the list is empty.
   */
  extern stp_list_item_t *stp_list_get_item_by_name(const stp_list_t *list,
						    const char *name);

  /**
   * Find an item in a list by its long name.
   * @param list the list to use.
   * @param long_name the long name to find.
   * @returns a pointer to the list item, or NULL if the long name is
   * invalid or the list is empty.
   */
  extern stp_list_item_t *stp_list_get_item_by_long_name(const stp_list_t *list,
							 const char *long_name);

  /**
   * Get the length of a list.
   * @param list the list to use.
   * @returns the list length (number of list items).
   */
  extern int stp_list_get_length(const stp_list_t *list);

  /**
   * Set a list node free function.
   * This callback function will be called whenever a list item is
   * destroyed.  Its intended use is for automatic object destruction
   * and any other cleanup required.
   * @param list the list to use.
   * @param freefunc the function to set.
   */
  extern void stp_list_set_freefunc(stp_list_t *list,
				    stp_node_freefunc freefunc);

  /**
   * Get a list node free function.
   * @param list the list to use.
   * @returns the function previously set with stp_list_set_freefunc,
   * or NULL if no function has been set.
   */
  extern stp_node_freefunc stp_list_get_freefunc(const stp_list_t *list);

  /**
   * Set a list node copy function.
   * This callback function will be called whenever a list item is
   * copied.  Its intended use is for automatic object copying
   * (since C lacks a copy constructor).
   * @param list the list to use.
   * @param copyfunc the function to set.
   */
  extern void stp_list_set_copyfunc(stp_list_t *list,
				    stp_node_copyfunc copyfunc);

  /**
   * Get a list node copy function.
   * @param list the list to use.
   * @returns the function previously set with stp_list_set_copyfunc,
   * or NULL if no function has been set.
   */
  extern stp_node_copyfunc stp_list_get_copyfunc(const stp_list_t *list);

  /**
   * Set a list node name function.
   * This callback function will be called whenever the name of a list
   * item needs to be determined.  This is used to find list items by
   * name.
   * @param list the list to use.
   * @param namefunc the function to set.
   */
  extern void stp_list_set_namefunc(stp_list_t *list,
				    stp_node_namefunc namefunc);

  /**
   * Get a list node name function.
   * @param list the list to use.
   * @returns the function previously set with stp_list_set_namefunc,
   * or NULL if no function has been set.
   */
  extern stp_node_namefunc stp_list_get_namefunc(const stp_list_t *list);

  /**
   * Set a list node long name function.
   * This callback function will be called whenever the long name of a list
   * item needs to be determined.  This is used to find list items by
   * long name.
   * @param list the list to use.
   * @param long_namefunc the function to set.
   */
  extern void stp_list_set_long_namefunc(stp_list_t *list,
					 stp_node_namefunc long_namefunc);

  /**
   * Get a list node long name function.
   * @param list the list to use.
   * @returns the function previously set with
   * stp_list_set_long_namefunc, or NULL if no function has been set.
   */
  extern stp_node_namefunc stp_list_get_long_namefunc(const stp_list_t *list);

  /**
   * Set a list node sort function.
   * This callback function will be called to determine the sort
   * order for list items in sorted lists.
   * @param list the list to use.
   * @param sortfunc the function to set.
   */
  extern void stp_list_set_sortfunc(stp_list_t *list,
				    stp_node_sortfunc sortfunc);

  /**
   * Get a list node sort function.
   * @param list the list to use.
   * @returns the function previously set with
   * stp_list_set_sortfunc, or NULL if no function has been set.
   */
  extern stp_node_sortfunc stp_list_get_sortfunc(const stp_list_t *list);

  /**
   * Create a new list item.
   * @param list the list to use.
   * @param next the next item in the list, or NULL to insert at the end of
   * the list.
   * @param data the data the list item will contain.
   * @returns 0 on success, 1 on failure (if data is NULL, for example).
   */
  extern int stp_list_item_create(stp_list_t *list,
				  stp_list_item_t *next,
				  const void *data);

  /**
   * Destroy a list item.
   * @param list the list to use.
   * @param item the item to destroy.
   * @returns 0 on success, 1 on failure.
   */
  extern int stp_list_item_destroy(stp_list_t *list,
				   stp_list_item_t *item);

  /**
   * Get the previous item in the list.
   * @param item the item to start from.
   * @returns a pointer to the list item prior to item, or NULL if
   * item is the start of the list.
   */
  extern stp_list_item_t *stp_list_item_prev(const stp_list_item_t *item);

  /**
   * Get the next item in the list.
   * @param item the item to start from.
   * @returns a pointer to the list item following from item, or NULL
   * if item is the end of the list.
   */
  extern stp_list_item_t *stp_list_item_next(const stp_list_item_t *item);

  /**
   * Get the data associated with a list item.
   * @param item the list item to use.
   * @returns the data associated with item.
   */
  extern void *stp_list_item_get_data(const stp_list_item_t *item);

  /**
   * Set the data associated with a list item.
   * @warning Note that if a sortfunc is in use, changing the data
   * will NOT re-sort the list!
   * @param item the list item to use.
   * @param data the data to set.
   * @returns 0 on success, 1 on failure (if data is NULL).
   */
  extern int stp_list_item_set_data(stp_list_item_t *item,
				    void *data);

  /** @} */

#ifdef __cplusplus
  }
#endif

#endif /* GUTENPRINT_LIST_H */