/***************************************************************************
 $RCSfile$
 -------------------
 cvs         : $Id: list2.tmpl 646 2004-12-15 13:41:08Z cstim $
 begin       : Sat Jun 28 2003
 copyright   : (C) 2003 by Martin Preuss
 email       : martin@libchipcard.de

 ***************************************************************************
 *                                                                         *
 *   This library is free software; you can redistribute it and/or         *
 *   modify it under the terms of the GNU Lesser General Public            *
 *   License as published by the Free Software Foundation; either          *
 *   version 2.1 of the License, or (at your option) any later version.    *
 *                                                                         *
 *   This library 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     *
 *   Lesser General Public License for more details.                       *
 *                                                                         *
 *   You should have received a copy of the GNU Lesser General Public      *
 *   License along with this library; if not, write to the Free Software   *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 *                                                                         *
 ***************************************************************************/


#ifndef @TYPENAME@_LIST2_H
#define @TYPENAME@_LIST2_H


#ifdef __cplusplus
extern "C" {
#endif

  /**
   * Defines a list of pointers to @TYPENAME@. The pointers stored in
   * a list are not taken over by the list, so you must take care of freeing
   * the elements of the list yourself.
   * (see @ref @FN_PREFIX@_List2_new)
   */
  typedef struct @TYPENAME@_LIST2 @TYPENAME@_LIST2;

  /**
   * An iterator is used to traverse a list.
   */
  typedef struct @TYPENAME@_LIST2_ITERATOR @TYPENAME@_LIST2_ITERATOR;

  /**
   * See @ref @FN_PREFIX@_List2_ForEach.
   */
  typedef @TYPENAME@* (@TYPENAME@_LIST2_FOREACH)(@TYPENAME@ *element,
                                                 void *user_data);

  /**
   * Creates a new list. This mus be freed using @ref @FN_PREFIX@_List2_free.
   */
  @TYPENAME@_LIST2 *@FN_PREFIX@_List2_new(); 

  /**
   * Destroys the list. Please note that the members in this list are not destroyed!
   */
  void @FN_PREFIX@_List2_free(@TYPENAME@_LIST2 *l); 

  /**
   * Dumps the contents of the list to an open file (e.g. stderr).
   */
  void @FN_PREFIX@_List2_Dump(@TYPENAME@_LIST2 *l, FILE *f, unsigned int indent); 

  /**
   * Appends an element to a list making it the new last element.
   */
  void @FN_PREFIX@_List2_PushBack(@TYPENAME@_LIST2 *l, @TYPENAME@ *p); 
   
  /**
   * Inserts an element at the start of the list, making it the new
   * first element.
   */
  void @FN_PREFIX@_List2_PushFront(@TYPENAME@_LIST2 *l, @TYPENAME@ *p); 

  /**
   * Returns the first element of the list. (The element is not
   * removed from the list.)
   */
  @TYPENAME@ *@FN_PREFIX@_List2_GetFront(@TYPENAME@_LIST2 *l); 
   
  /**
   * Returns the last element of the list. (The element is not
   * removed from the list.)
   */
  @TYPENAME@ *@FN_PREFIX@_List2_GetBack(@TYPENAME@_LIST2 *l); 

  /**
   * Removes the element currently pointed to by the given iterator
   * from the list.
   */
  void @FN_PREFIX@_List2_Erase(@TYPENAME@_LIST2 *l,
			       @TYPENAME@_LIST2_ITERATOR *it);

 /** Returns the size of this list, i.e. the number of elements in this
   * list. 
   *
   * This number is counted in the list metadata, so this is a cheap
   * operation. */
  unsigned int @FN_PREFIX@_List2_GetSize(@TYPENAME@_LIST2 *l); 

  /**
   * Removes the list's last element from the list. (The element is not
   * freed.)
   */
  void @FN_PREFIX@_List2_PopBack(@TYPENAME@_LIST2 *l); 
   
  /**
   * Removes the list's first element from the list. (The element is not
   * freed.)
   */
  void @FN_PREFIX@_List2_PopFront(@TYPENAME@_LIST2 *l); 

  /**
   * Removes all list elements from the list. (The elements are not freed.)
   */
  void @FN_PREFIX@_List2_Clear(@TYPENAME@_LIST2 *l); 

  /**
   * Returns a list iterator pointing to the first element.
   */
  @TYPENAME@_LIST2_ITERATOR *@FN_PREFIX@_List2_First(@TYPENAME@_LIST2 *l); 
   
  /**
   * Returns a list iterator pointing to the last element.
   */
  @TYPENAME@_LIST2_ITERATOR *@FN_PREFIX@_List2_Last(@TYPENAME@_LIST2 *l); 

  /**
   * Creates a list iterator for the given list. (FIXME: Should be private).
   */
  @TYPENAME@_LIST2_ITERATOR *@FN_PREFIX@_List2Iterator_new(@TYPENAME@_LIST2 *l);

  /**
   * Destroys the list iterator.
   */
  void @FN_PREFIX@_List2Iterator_free(@TYPENAME@_LIST2_ITERATOR *li); 

  /**
   * Moves the list iterator to the predecessor of the currenty selected
   * element and returns that predecessor element.
   */
  @TYPENAME@ *@FN_PREFIX@_List2Iterator_Previous(@TYPENAME@_LIST2_ITERATOR *li); 
   
  /**
   * Moves the list iterator to the successor of the currenty selected
   * element and returns that successor element.
   */
  @TYPENAME@ *@FN_PREFIX@_List2Iterator_Next(@TYPENAME@_LIST2_ITERATOR *li); 

  /**
   * Returns the pointer to the element stored at the list position the
   * iterator currently points to.
   */
  @TYPENAME@ *@FN_PREFIX@_List2Iterator_Data(@TYPENAME@_LIST2_ITERATOR *li); 

  /** Traverses the list, calling the callback function 'func' on
   * each list element.  Traversal will stop when 'func' returns a
   * non-NULL value, and the routine will return with that
   * value. Otherwise the routine will return NULL. 
   * @param list The list to traverse.
   * @param func The function to be called with each list element.
   * @param user_data A pointer passed on to the function 'func'.
   * @return The non-NULL pointer returned by 'func' as soon as it
   * returns one. Otherwise (i.e. 'func' always returns NULL)
   * returns NULL.
   */
  @TYPENAME@ *@FN_PREFIX@_List2_ForEach(@TYPENAME@_LIST2 *list,
					@TYPENAME@_LIST2_FOREACH func,
					void *user_data);


  typedef struct @TYPENAME@_CONSTLIST2 @TYPENAME@_CONSTLIST2; 
  typedef struct @TYPENAME@_CONSTLIST2_ITERATOR @TYPENAME@_CONSTLIST2_ITERATOR; 
  typedef const @TYPENAME@*
    (@TYPENAME@_CONSTLIST2_FOREACH)(const @TYPENAME@ *element,
                                    void *user_data);
  
   
  @TYPENAME@_CONSTLIST2 *@FN_PREFIX@_ConstList2_new(); 
   
  void @FN_PREFIX@_ConstList2_free(@TYPENAME@_CONSTLIST2 *l); 
   
  void @FN_PREFIX@_ConstList2_PushBack(@TYPENAME@_CONSTLIST2 *l, const @TYPENAME@ *p); 
   
  void @FN_PREFIX@_ConstList2_PushFront(@TYPENAME@_CONSTLIST2 *l, const @TYPENAME@ *p); 
   
  const @TYPENAME@ *@FN_PREFIX@_ConstList2_GetFront(@TYPENAME@_CONSTLIST2 *l); 
   
  const @TYPENAME@ *@FN_PREFIX@_ConstList2_GetBack(@TYPENAME@_CONSTLIST2 *l); 
   
  unsigned int @FN_PREFIX@_ConstList2_GetSize(@TYPENAME@_CONSTLIST2 *l); 
   
  void @FN_PREFIX@_ConstList2_PopBack(@TYPENAME@_CONSTLIST2 *l); 
   
  void @FN_PREFIX@_ConstList2_PopFront(@TYPENAME@_CONSTLIST2 *l); 
   
  void @FN_PREFIX@_ConstList2_Clear(@TYPENAME@_CONSTLIST2 *l); 
   
  @TYPENAME@_CONSTLIST2_ITERATOR *@FN_PREFIX@_ConstList2_First(@TYPENAME@_CONSTLIST2 *l); 
   
  @TYPENAME@_CONSTLIST2_ITERATOR *@FN_PREFIX@_ConstList2_Last(@TYPENAME@_CONSTLIST2 *l); 
   
  @TYPENAME@_CONSTLIST2_ITERATOR *@FN_PREFIX@_ConstList2Iterator_new(@TYPENAME@_CONSTLIST2 *l); 
   
  void @FN_PREFIX@_ConstList2Iterator_free(@TYPENAME@_CONSTLIST2_ITERATOR *li); 
   
  const @TYPENAME@ *@FN_PREFIX@_ConstList2Iterator_Previous(@TYPENAME@_CONSTLIST2_ITERATOR *li); 
   
  const @TYPENAME@ *@FN_PREFIX@_ConstList2Iterator_Next(@TYPENAME@_CONSTLIST2_ITERATOR *li); 
   
  const @TYPENAME@ *@FN_PREFIX@_ConstList2Iterator_Data(@TYPENAME@_CONSTLIST2_ITERATOR *li); 
   
  /** Traverses the list, calling the callback function 'func' on
   * each list element.  Traversal will stop when 'func' returns a
   * non-NULL value, and the routine will return with that
   * value. Otherwise the routine will return NULL. 
   * @param list The list to traverse.
   * @param func The function to be called with each list element.
   * @param user_data A pointer passed on to the function 'func'.
   * @return The non-NULL pointer returned by 'func' as soon as it
   * returns one. Otherwise (i.e. 'func' always returns NULL)
   * returns NULL.
   */
  const @TYPENAME@ *@FN_PREFIX@_ConstList2_ForEach(@TYPENAME@_CONSTLIST2 *list,
	@TYPENAME@_CONSTLIST2_FOREACH func, void *user_data);


#ifdef __cplusplus
}
#endif


#endif /* @TYPENAME@_LIST_H */



