gdsl_list.h

一个通用的C语言实现的数据结构

 * @param C The cursor to use
 * @see gdsl_list_cursor_move_to_head()
 */
extern void
gdsl_list_cursor_move_to_tail (gdsl_list_cursor_t C
			       );

/**
 * @brief Place a cursor on a particular element.
 *
 * Search a particular element E in the cursor's list L by comparing all list's 
 * elements to VALUE, by using COMP_F. If E is found, C is positionned on it.
 *
 * @note Complexity: O( |L| / 2 )
 * @pre C must be a valid gdsl_list_cursor_t & COMP_F != NULL
 * @param C The cursor to put on the element E
 * @param COMP_F The comparison function to search for E
 * @param VALUE The value used to compare list's elements with
 * @return the first founded element E in case it exists.
 * @return NULL in case of element E is not found.
 * @see gdsl_list_cursor_move_to_position()
 */ 
extern gdsl_element_t
gdsl_list_cursor_move_to_value (gdsl_list_cursor_t C,
				gdsl_compare_func_t COMP_F,
				void* VALUE
				);

/**
 * @brief Place a cursor on a element given by its position.
 *
 * Search for the POS-th element in the cursor's list L. In case this element
 * exists, the cursor C is positionned on it.
 *
 * @note Complexity: O( |L| / 2 )
 * @pre C must be a valid gdsl_list_cursor_t & POS > 0 & POS <= |L|
 * @param C The cursor to put on the POS-th element
 * @param POS The position of the element to move on
 * @return the element at the POS-th position
 * @return NULL if POS <= 0 or POS > |L|
 * @see gdsl_list_cursor_move_to_value()
 */
extern gdsl_element_t
gdsl_list_cursor_move_to_position (gdsl_list_cursor_t C,
				   ulong POS
				   );

/**
 * @brief Move a cursor one step forward of its list.
 *
 * Move the cursor C one node forward (from head to tail). Does nothing if C is 
 * already on its list's tail.
 *
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to use
 * @see gdsl_list_cursor_step_backward()
 */
extern void
gdsl_list_cursor_step_forward (gdsl_list_cursor_t C
			       );

/**
 * @brief Move a cursor one step backward of its list.
 *
 * Move the cursor C one node backward (from tail to head.) Does nothing if C is
 * already on its list's head.
 *
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to use
 * @see gdsl_list_cursor_step_forward()
 */
extern void
gdsl_list_cursor_step_backward (gdsl_list_cursor_t C
				);

/**
 * @brief Check if a cursor is on the head of its list.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to check
 * @return TRUE if C is on its list's head.
 * @return FALSE if C is not on its lits's head.
 * @see gdsl_list_cursor_is_on_tail()
 */
extern bool
gdsl_list_cursor_is_on_head (const gdsl_list_cursor_t C
			     );

/**
 * @brief Check if a cursor is on the tail of its list.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to check
 * @return TRUE if C is on its lists's tail.
 * @return FALSE if C is not on its list's tail.
 * @see gdsl_list_cursor_is_on_head()
 */
extern bool
gdsl_list_cursor_is_on_tail (const gdsl_list_cursor_t C
			     );

/** 
 * @brief Check if a cursor has a successor.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to check
 * @return TRUE if there exists an element after the cursor C.
 * @return FALSE if there is no element after the cursor C.
 * @see gdsl_list_cursor_has_pred()
 */
extern bool 
gdsl_list_cursor_has_succ (const gdsl_list_cursor_t C
			   );

/**
 * @brief Check if a cursor has a predecessor.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to check
 * @return TRUE if there exists an element before the cursor C.
 * @return FALSE if there is no element before the cursor C.
 * @see gdsl_list_cursor_has_succ()
 */
extern bool 
gdsl_list_cursor_has_pred (const gdsl_list_cursor_t C
			   );

/**
 * @brief Set the content of the cursor.
 *
 * Set C's element to E. The previous element is *NOT* deallocated. If it must 
 * be deallocated, gdsl_list_cursor_get_content() could be used to get it in 
 * order to free it before.
 *
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor in which the content must be modified.
 * @param E The value used to modify C's content.
 * @see gdsl_list_cursor_get_content()
 */
extern void
 gdsl_list_cursor_set_content (gdsl_list_cursor_t C,
			       gdsl_element_t E
			       );
/**
 * @brief Get the content of a cursor.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to get the content from.
 * @return the element contained in the cursor C.
 * @see gdsl_list_cursor_set_content()
 */
extern gdsl_element_t
gdsl_list_cursor_get_content (const gdsl_list_cursor_t C
			      );

/** 
 * @brief Insert a new element after a cursor.
 *
 * A new element is created using ALLOC_F called on VALUE. ALLOC_F is the
 * pointer passed to gdsl_list_alloc(). If the returned value is not NULL, then
 * the new element is placed after the cursor C. If C's list is empty, the 
 * element is inserted at the head position of C's list.
 *
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor after which the new element must be inserted
 * @param VALUE The value used to allocate the new element to insert
 * @return the newly inserted element in case of success.
 * @return NULL in case of failure.
 * @see gdsl_list_cursor_insert_before()
 * @see gdsl_list_cursor_remove_after()
 * @see gdsl_list_cursor_remove_before()
 */
extern gdsl_element_t
gdsl_list_cursor_insert_after (gdsl_list_cursor_t C,
			       void* VALUE
			       );
/** 
 * @brief Insert a new element before a cursor.
 *
 * A new element is created using ALLOC_F called on VALUE. ALLOC_F is the 
 * pointer passed to gdsl_list_alloc(). If the returned value is not NULL, then
 * the new element is placed before the cursor C. If C's list is empty, the
 * element is inserted at the head position of C's list.
 *
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor before which the new element must be inserted
 * @param VALUE The value used to allocate the new element to insert
 * @return the newly inserted element in case of success.
 * @return NULL in case of failure.
 * @see gdsl_list_cursor_insert_after()
 * @see gdsl_list_cursor_remove_after()
 * @see gdsl_list_cursor_remove_before()
 */
extern gdsl_element_t
gdsl_list_cursor_insert_before (gdsl_list_cursor_t C,
				void* VALUE
				);

/**
 * @brief Removec the element under a cursor.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @post After this operation, the cursor is positionned on to its successor.
 * @param C The cursor to remove the content from.
 * @return the removed element if it exists.
 * @return NULL if there is not element to remove.
 * @see gdsl_list_cursor_insert_after()
 * @see gdsl_list_cursor_insert_before()
 * @see gdsl_list_cursor_remove()
 * @see gdsl_list_cursor_remove_before()
 */
extern gdsl_element_t
gdsl_list_cursor_remove (gdsl_list_cursor_t C
			 );

/**
 * @brief Removec the element after a cursor.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to remove the successor from.
 * @return the removed element if it exists.
 * @return NULL if there is not element to remove.
 * @see gdsl_list_cursor_insert_after()
 * @see gdsl_list_cursor_insert_before()
 * @see gdsl_list_cursor_remove()
 * @see gdsl_list_cursor_remove_before()
 */
extern gdsl_element_t
gdsl_list_cursor_remove_after (gdsl_list_cursor_t C
			       );

/**
 * @brief Remove the element before a cursor.
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to remove the predecessor from.
 * @return the removed element if it exists.
 * @return NULL if there is not element to remove.
 * @see gdsl_list_cursor_insert_after()
 * @see gdsl_list_cursor_insert_before()
 * @see gdsl_list_cursor_remove()
 * @see gdsl_list_cursor_remove_after()
 */
extern gdsl_element_t
gdsl_list_cursor_remove_before (gdsl_list_cursor_t C
				);

/**
 * @brief Delete the element under a cursor.
 *
 * Remove the element under the cursor C. The removed element is also 
 * deallocated using FREE_F passed to gdsl_list_alloc().
 *
 * Complexity: O( 1 )
 *
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to delete the content.
 * @returns the cursor C if the element was removed.
 * @returns NULL if there is not element to remove.
 * @see gdsl_list_cursor_delete_before()
 * @see gdsl_list_cursor_delete_after()
 */
extern gdsl_list_cursor_t
gdsl_list_cursor_delete (gdsl_list_cursor_t C
			 );

/**
 * @brief Delete the element after a cursor.
 *
 * Remove the element after the cursor C. The removed element is also 
 * deallocated using FREE_F passed to gdsl_list_alloc().
 *
 * Complexity: O( 1 )
 *
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to delete the successor from.
 * @returns the cursor C if the element was removed.
 * @returns NULL if there is not element to remove.
 * @see gdsl_list_cursor_delete()
 * @see gdsl_list_cursor_delete_before()
 */
extern gdsl_list_cursor_t
gdsl_list_cursor_delete_after (gdsl_list_cursor_t C
			       );

/**
 * @brief Delete the element before the cursor of a list.
 *
 * Remove the element before the cursor C. The removed element is also
 * deallocated using FREE_F passed to gdsl_list_alloc().
 *
 * @note Complexity: O( 1 )
 * @pre C must be a valid gdsl_list_cursor_t
 * @param C The cursor to delete the predecessor from.
 * @return the cursor C if the element was removed.
 * @return NULL if there is not element to remove.
 * @see gdsl_list_cursor_delete()
 * @see gdsl_list_cursor_delete_after()
 */
extern gdsl_list_cursor_t
gdsl_list_cursor_delete_before (gdsl_list_cursor_t C
				);


/*
 * @}
 */


#ifdef __cplusplus
}
#endif /* __cplusplus */


#endif /* GDSL_LIST_H_ */


/** EMACS **
 * Local variables:
 * mode: c
 * c-basic-offset: 4
 * End:
 */