/**
 * list.h
 **/

#ifndef LIST_H__
#define LIST_H__

typedef struct List_tag *List_T;
typedef struct List_node *List_iterator_T;

#define T List_T
#define TI List_iterator_T

/*
 * Creates a new list.
 *
 * It is a checked runtime error if a new list can not be created. 
 */
extern T        List_new(void);

/*
 * Deletes an existing list.
 * after deleting, the value of the list should be NULL
 *
 * It is a checked runtime error for list to be NULL
 */
extern void     List_delete(T *list);

/*
 * Insert 'x' in 'list' before the node pointed to by 'pos'. 'pos' can
 * be any position >= List_begin() and <= List_end().
 *
 * It is a checked runtime error for list, pos or x to be NULL
 * It is a checked runtime error if a new list element can not be created. 
 */
extern void     List_insert(T list, TI pos, void *x);

/*
 * Erase the element pointed to by 'pos'. 'pos' can be any position >=
 * List_begin() and < List_end(), it means, 'pos' cannot be equal to
 * List_end(). Return the element of the erased node.
 *
 * It is a checked runtime error for list or pos to be NULL
 * It is a checked runtime error if pos is equal to List_end() or if the list is empty
 */
extern void    *List_erase(T list, TI pos);

/*
 * Return the element in the node pointed to by 'pos'.
 *
 * It is a checked runtime error for list or pos to be NULL
 * It is a checked runtime error if pos is equal to the List_end()
 */
extern void    *List_element(T list, TI pos);

/*
 * Return an iterator to the first node of 'list'.
 *
 * It is a checked runtime error for list to be NULL
 */
extern TI       List_begin(T list);

/*
 * Returns an iterator that indicates the fact that we have gone past
 * the last node of the list.  List_end does *not* return an iterator
 * to the last node in 'list'.
 *
 * It is a checked runtime error for list to be NULL
 */
extern TI       List_end(T list);

/*
 * Return an iterator to the node after the one pointed to by 'pos'.
 *
 * It is a checked runtime error for pos to be NULL
 */
extern TI       List_next(TI pos);

/*
 * Return an iterator to the first before the one pointed to by 'pos'.
 *
 * It is a checked runtime error for pos to be NULL
 */
extern TI       List_previous(TI pos);

/*
 * Return the number of elements in 'list'.
 *
 * It is a checked runtime error for list to be NULL
 */
extern int      List_size(T list);

/*
 * Returns 1 if 'list' is empty, and 0 otherwise.
 *
 * It is a checked runtime error for list to be NULL
 */
extern int      List_is_empty(T list);

/*
 * Insert the subrange of 'list2' nodes specified by ['start_pos', 'end_pos'),
 * into 'list', before the node pointed to by 'pos'. Also, remove the original
 * subrange from 'list2'. 
 * Specifically, the subrange ['start_pos', 'end_pos') is the sequence of 
 * nodes that starts at (and includes) the node pointed to by 'start_pos', 
 * and ends with (but excludes) the node pointed at by 'end_pos'.
 * 'start_pos' and 'end_pos' must both be iterators for list2. 
 * 'start_pos' can be any position >= List_begin(list2) and < List_end(list2).
 * 'end_pos' can be any position > List_begin(list2) and <= List_end(list2).
 * 'pos' can be any position >= List_begin(list) and <= List_end(list).
 *
 * It is a checked runtime error for list or list2 to be NULL
 * It is a checked runtime error for pos, start_pos or end_pos to be NULL
 */
extern void	List_splice(T list, TI pos, T list2, TI start_pos, TI end_pos);


#undef T
#undef TI

#endif			   /* LIST_H__ */