Imported Upstream version 4.3.99+cvs20050702

1 files changed, 337 insertions, 0 deletions

diff --git a/include/gutenprint/list.h b/include/gutenprint/list.h
new file mode 100644
index 0000000..64f3beb
--- /dev/null
+++ b/include/gutenprint/list.h
@@ -0,0 +1,337 @@
+/*
+ * "$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 */