Doubly-linked list manipulation module


Typedefs

typedef _gdsl_list * gdsl_list_t
 GDSL doubly-linked list type.
typedef _gdsl_list_cursor * gdsl_list_cursor_t
 GDSL doubly-linked list cursor type.

Functions

gdsl_list_t gdsl_list_alloc (const char *NAME, gdsl_alloc_func_t ALLOC_F, gdsl_free_func_t FREE_F)
 Create a new list.
void gdsl_list_free (gdsl_list_t L)
 Destroy a list.
void gdsl_list_flush (gdsl_list_t L)
 Flush a list.
const char * gdsl_list_get_name (const gdsl_list_t L)
 Get the name of a list.
ulong gdsl_list_get_size (const gdsl_list_t L)
 Get the size of a list.
bool gdsl_list_is_empty (const gdsl_list_t L)
 Check if a list is empty.
gdsl_element_t gdsl_list_get_head (const gdsl_list_t L)
 Get the head of a list.
gdsl_element_t gdsl_list_get_tail (const gdsl_list_t L)
 Get the tail of a list.
gdsl_list_t gdsl_list_set_name (gdsl_list_t L, const char *NEW_NAME)
 Set the name of a list.
gdsl_element_t gdsl_list_insert_head (gdsl_list_t L, void *VALUE)
 Insert an element at the head of a list.
gdsl_element_t gdsl_list_insert_tail (gdsl_list_t L, void *VALUE)
 Insert an element at the tail of a list.
gdsl_element_t gdsl_list_remove_head (gdsl_list_t L)
 Remove the head of a list.
gdsl_element_t gdsl_list_remove_tail (gdsl_list_t L)
 Remove the tail of a list.
gdsl_element_t gdsl_list_remove (gdsl_list_t L, gdsl_compare_func_t COMP_F, const void *VALUE)
 Remove a particular element from a list.
gdsl_list_t gdsl_list_delete_head (gdsl_list_t L)
 Delete the head of a list.
gdsl_list_t gdsl_list_delete_tail (gdsl_list_t L)
 Delete the tail of a list.
gdsl_list_t gdsl_list_delete (gdsl_list_t L, gdsl_compare_func_t COMP_F, const void *VALUE)
 Delete a particular element from a list.
gdsl_element_t gdsl_list_search (const gdsl_list_t L, gdsl_compare_func_t COMP_F, const void *VALUE)
 Search for a particular element into a list.
gdsl_element_t gdsl_list_search_by_position (const gdsl_list_t L, ulong POS)
 Search for an element by its position in a list.
gdsl_element_t gdsl_list_search_max (const gdsl_list_t L, gdsl_compare_func_t COMP_F)
 Search for the greatest element of a list.
gdsl_element_t gdsl_list_search_min (const gdsl_list_t L, gdsl_compare_func_t COMP_F)
 Search for the lowest element of a list.
gdsl_list_t gdsl_list_sort (gdsl_list_t L, gdsl_compare_func_t COMP_F)
 Sort a list.
gdsl_element_t gdsl_list_map_forward (const gdsl_list_t L, gdsl_map_func_t MAP_F, void *USER_DATA)
 Parse a list from head to tail.
gdsl_element_t gdsl_list_map_backward (const gdsl_list_t L, gdsl_map_func_t MAP_F, void *USER_DATA)
 Parse a list from tail to head.
void gdsl_list_write (const gdsl_list_t L, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write all the elements of a list to a file.
void gdsl_list_write_xml (const gdsl_list_t L, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write the content of a list to a file into XML.
void gdsl_list_dump (const gdsl_list_t L, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Dump the internal structure of a list to a file.
gdsl_list_cursor_t gdsl_list_cursor_alloc (const gdsl_list_t L)
 Create a new list cursor.
void gdsl_list_cursor_free (gdsl_list_cursor_t C)
 Destroy a list cursor.
void gdsl_list_cursor_move_to_head (gdsl_list_cursor_t C)
 Put a cursor on the head of its list.
void gdsl_list_cursor_move_to_tail (gdsl_list_cursor_t C)
 Put a cursor on the tail of its list.
gdsl_element_t gdsl_list_cursor_move_to_value (gdsl_list_cursor_t C, gdsl_compare_func_t COMP_F, void *VALUE)
 Place a cursor on a particular element.
gdsl_element_t gdsl_list_cursor_move_to_position (gdsl_list_cursor_t C, ulong POS)
 Place a cursor on a element given by its position.
void gdsl_list_cursor_step_forward (gdsl_list_cursor_t C)
 Move a cursor one step forward of its list.
void gdsl_list_cursor_step_backward (gdsl_list_cursor_t C)
 Move a cursor one step backward of its list.
bool gdsl_list_cursor_is_on_head (const gdsl_list_cursor_t C)
 Check if a cursor is on the head of its list.
bool gdsl_list_cursor_is_on_tail (const gdsl_list_cursor_t C)
 Check if a cursor is on the tail of its list.
bool gdsl_list_cursor_has_succ (const gdsl_list_cursor_t C)
 Check if a cursor has a successor.
bool gdsl_list_cursor_has_pred (const gdsl_list_cursor_t C)
 Check if a cursor has a predecessor.
void gdsl_list_cursor_set_content (gdsl_list_cursor_t C, gdsl_element_t E)
 Set the content of the cursor.
gdsl_element_t gdsl_list_cursor_get_content (const gdsl_list_cursor_t C)
 Get the content of a cursor.
gdsl_element_t gdsl_list_cursor_insert_after (gdsl_list_cursor_t C, void *VALUE)
 Insert a new element after a cursor.
gdsl_element_t gdsl_list_cursor_insert_before (gdsl_list_cursor_t C, void *VALUE)
 Insert a new element before a cursor.
gdsl_element_t gdsl_list_cursor_remove (gdsl_list_cursor_t C)
 Removec the element under a cursor.
gdsl_element_t gdsl_list_cursor_remove_after (gdsl_list_cursor_t C)
 Removec the element after a cursor.
gdsl_element_t gdsl_list_cursor_remove_before (gdsl_list_cursor_t C)
 Remove the element before a cursor.
gdsl_list_cursor_t gdsl_list_cursor_delete (gdsl_list_cursor_t C)
 Delete the element under a cursor.
gdsl_list_cursor_t gdsl_list_cursor_delete_after (gdsl_list_cursor_t C)
 Delete the element after a cursor.
gdsl_list_cursor_t gdsl_list_cursor_delete_before (gdsl_list_cursor_t C)
 Delete the element before the cursor of a list.


Typedef Documentation

typedef struct _gdsl_list* gdsl_list_t
 

GDSL doubly-linked list type.

This type is voluntary opaque. Variables of this kind could'nt be directly used, but by the functions of this module.

Definition at line 51 of file gdsl_list.h.

typedef struct _gdsl_list_cursor* gdsl_list_cursor_t
 

GDSL doubly-linked list cursor type.

This type is voluntary opaque. Variables of this kind could'nt be directly used, but by the functions of this module.

Definition at line 59 of file gdsl_list.h.


Function Documentation

gdsl_list_t gdsl_list_alloc const char *  NAME,
gdsl_alloc_func_t  ALLOC_F,
gdsl_free_func_t  FREE_F
 

Create a new list.

Allocate a new list data structure which name is set to a copy of NAME. The function pointers ALLOC_F and FREE_F could be used to respectively, alloc and free elements in the list. These pointers could be set to NULL to use the default ones:

  • the default ALLOC_F simply returns its argument
  • the default FREE_F does nothing

Note:
Complexity: O( 1 )
Precondition:
nothing
Parameters:
NAME The name of the new list to create
ALLOC_F Function to alloc element when inserting it in the list
FREE_F Function to free element when removing it from the list
Returns:
the newly allocated list in case of success.

NULL in case of insufficient memory.

See also:
gdsl_list_free()

gdsl_list_flush()

void gdsl_list_free gdsl_list_t  L  ) 
 

Destroy a list.

Flush and destroy the list L. All the elements of L are freed using L's FREE_F function passed to gdsl_list_alloc().

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to destroy
See also:
gdsl_list_alloc()

gdsl_list_flush()

void gdsl_list_flush gdsl_list_t  L  ) 
 

Flush a list.

Destroy all the elements of the list L by calling L's FREE_F function passed to gdsl_list_alloc(). L is not deallocated itself and L's name is not modified.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to flush
See also:
gdsl_list_alloc()

gdsl_list_free()

const char* gdsl_list_get_name const gdsl_list_t  L  ) 
 

Get the name of a list.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Postcondition:
The returned string MUST NOT be freed.
Parameters:
L The list to get the name from
Returns:
the name of the list L.
See also:
gdsl_list_set_name()

ulong gdsl_list_get_size const gdsl_list_t  L  ) 
 

Get the size of a list.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to get the size from
Returns:
the number of elements of the list L (noted |L|).

bool gdsl_list_is_empty const gdsl_list_t  L  ) 
 

Check if a list is empty.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to check
Returns:
TRUE if the list L is empty.

FALSE if the list L is not empty.

gdsl_element_t gdsl_list_get_head const gdsl_list_t  L  ) 
 

Get the head of a list.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to get the head from
Returns:
the element at L's head position if L is not empty. The returned element is not removed from L.

NULL if the list L is empty.

See also:
gdsl_list_get_tail()

gdsl_element_t gdsl_list_get_tail const gdsl_list_t  L  ) 
 

Get the tail of a list.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to get the tail from
Returns:
the element at L's tail position if L is not empty. The returned element is not removed from L.

NULL if L is empty.

See also:
gdsl_list_get_head()

gdsl_list_t gdsl_list_set_name gdsl_list_t  L,
const char *  NEW_NAME
 

Set the name of a list.

Changes the previous name of the list L to a copy of NEW_NAME.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to change the name
NEW_NAME The new name of L
Returns:
the modified list in case of success.

NULL in case of failure.

See also:
gdsl_list_get_name()

gdsl_element_t gdsl_list_insert_head gdsl_list_t  L,
void *  VALUE
 

Insert an element at the head of a list.

Allocate a new element E by calling L's ALLOC_F function on VALUE. ALLOC_F is the function pointer passed to gdsl_list_alloc(). The new element E is then inserted at the header position of the list L.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to insert into
VALUE The value used to make the new element to insert into L
Returns:
the inserted element E in case of success.

NULL in case of failure.

See also:
gdsl_list_insert_tail()

gdsl_list_remove_head()

gdsl_list_remove_tail()

gdsl_list_remove()

gdsl_element_t gdsl_list_insert_tail gdsl_list_t  L,
void *  VALUE
 

Insert an element at the tail of a list.

Allocate a new element E by calling L's ALLOC_F function on VALUE. ALLOC_F is the function pointer passed to gdsl_list_alloc(). The new element E is then inserted at the footer position of the list L.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to insert into
VALUE The value used to make the new element to insert into L
Returns:
the inserted element E in case of success.

NULL in case of failure.

See also:
gdsl_list_insert_head()

gdsl_list_remove_head()

gdsl_list_remove_tail()

gdsl_list_remove()

gdsl_element_t gdsl_list_remove_head gdsl_list_t  L  ) 
 

Remove the head of a list.

Remove the element at the head of the list L.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to remove the head from
Returns:
the removed element in case of success.

NULL in case of L is empty.

See also:
gdsl_list_insert_head()

gdsl_list_insert_tail()

gdsl_list_remove_tail()

gdsl_list_remove()

gdsl_element_t gdsl_list_remove_tail gdsl_list_t  L  ) 
 

Remove the tail of a list.

Remove the element at the tail of the list L.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to remove the tail from
Returns:
the removed element in case of success.

NULL in case of L is empty.

See also:
gdsl_list_insert_head()

gdsl_list_insert_tail()

gdsl_list_remove_head()

gdsl_list_remove()

gdsl_element_t gdsl_list_remove gdsl_list_t  L,
gdsl_compare_func_t  COMP_F,
const void *  VALUE
 

Remove a particular element from a list.

Search into the list L for the first element E equal to VALUE by using COMP_F. If E is found, it is removed from L and then returned.

Note:
Complexity: O( |L| / 2 )
Precondition:
L must be a valid gdsl_list_t & COMP_F != NULL
Parameters:
L The list to remove the element from
COMP_F The comparison function used to find the element to remove
VALUE The value used to compare the element to remove with
Returns:
the founded element E if it was found.

NULL in case the searched element E was not found.

See also:
gdsl_list_insert_head()

gdsl_list_insert_tail()

gdsl_list_remove_head()

gdsl_list_remove_tail()

gdsl_list_t gdsl_list_delete_head gdsl_list_t  L  ) 
 

Delete the head of a list.

Remove the header element from the list L and deallocates it using the FREE_F function passed to gdsl_list_alloc().

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to destroy the head from
Returns:
the modified list L in case of success.

NULL if L is empty.

See also:
gdsl_list_alloc()

gdsl_list_destroy_tail()

gdsl_list_destroy()

gdsl_list_t gdsl_list_delete_tail gdsl_list_t  L  ) 
 

Delete the tail of a list.

Remove the footer element from the list L and deallocates it using the FREE_F function passed to gdsl_list_alloc().

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list to destroy the tail from
Returns:
the modified list L in case of success.

NULL if L is empty.

See also:
gdsl_list_alloc()

gdsl_list_destroy_head()

gdsl_list_destroy()

gdsl_list_t gdsl_list_delete gdsl_list_t  L,
gdsl_compare_func_t  COMP_F,
const void *  VALUE
 

Delete a particular element from a list.

Search into the list L for the first element E equal to VALUE by using COMP_F. If E is found, it is removed from L and deallocated using the FREE_F function passed to gdsl_list_alloc().

Note:
Complexity: O( |L| / 2 )
Precondition:
L must be a valid gdsl_list_t & COMP_F != NULL
Parameters:
L The list to destroy the element from
COMP_F The comparison function used to find the element to destroy
VALUE The value used to compare the element to destroy with
Returns:
the modified list L if the element is found.

NULL if the element to destroy is not found.

See also:
gdsl_list_alloc()

gdsl_list_destroy_head()

gdsl_list_destroy_tail()

gdsl_element_t gdsl_list_search const gdsl_list_t  L,
gdsl_compare_func_t  COMP_F,
const void *  VALUE
 

Search for a particular element into a list.

Search the first element E equal to VALUE in the list L, by using COMP_F to compare all L's element with.

Note:
Complexity: O( |L| / 2 )
Precondition:
L must be a valid gdsl_list_t & COMP_F != NULL
Parameters:
L The list to search the element in
COMP_F The comparison function used to compare L's element with VALUE
VALUE The value to compare L's elemenst with
Returns:
the first founded element E in case of success.

NULL in case the searched element E was not found.

See also:
gdsl_list_search_by_position()

gdsl_list_search_max()

gdsl_list_search_min()

gdsl_element_t gdsl_list_search_by_position const gdsl_list_t  L,
ulong  POS
 

Search for an element by its position in a list.

Note:
Complexity: O( |L| / 2 )
Precondition:
L must be a valid gdsl_list_t & POS > 0 & POS <= |L|
Parameters:
L The list to search the element in
POS The position where is the element to search
Returns:
the element at the POS-th position in the list L.

NULL if POS > |L| or POS <= 0.

See also:
gdsl_list_search()

gdsl_list_search_max()

gdsl_list_search_min()

gdsl_element_t gdsl_list_search_max const gdsl_list_t  L,
gdsl_compare_func_t  COMP_F
 

Search for the greatest element of a list.

Search the greatest element of the list L, by using COMP_F to compare L's elements with.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & COMP_F != NULL
Parameters:
L The list to search the element in
COMP_F The comparison function to use to compare L's element with
Returns:
the highest element of L, by using COMP_F function.

NULL if L is empty.

See also:
gdsl_list_search()

gdsl_list_search_by_position()

gdsl_list_search_min()

gdsl_element_t gdsl_list_search_min const gdsl_list_t  L,
gdsl_compare_func_t  COMP_F
 

Search for the lowest element of a list.

Search the lowest element of the list L, by using COMP_F to compare L's elements with.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & COMP_F != NULL
Parameters:
L The list to search the element in
COMP_F The comparison function to use to compare L's element with
Returns:
the lowest element of L, by using COMP_F function.

NULL if L is empty.

See also:
gdsl_list_search()

gdsl_list_search_by_position()

gdsl_list_search_max()

gdsl_list_t gdsl_list_sort gdsl_list_t  L,
gdsl_compare_func_t  COMP_F
 

Sort a list.

Sort the list L using COMP_F to order L's elements.

Note:
Complexity: O( |L| * log( |L| ) )
Precondition:
L must be a valid gdsl_list_t & COMP_F != NULL & L must not contains elements that are equals
Parameters:
L The list to sort
COMP_F The comparison function used to order L's elements
Returns:
the sorted list L.

gdsl_element_t gdsl_list_map_forward const gdsl_list_t  L,
gdsl_map_func_t  MAP_F,
void *  USER_DATA
 

Parse a list from head to tail.

Parse all elements of the list L from head to tail. The MAP_F function is called on each L's element with USER_DATA argument. If MAP_F returns GDSL_MAP_STOP, then gdsl_list_map_forward() stops and returns its last examinated element.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & MAP_F != NULL
Parameters:
L The list to parse
MAP_F The map function to apply on each L's element
USER_DATA User's datas passed to MAP_F
Returns:
the first element for which MAP_F returns GDSL_MAP_STOP.

NULL when the parsing is done.

See also:
gdsl_list_map_backward()

gdsl_element_t gdsl_list_map_backward const gdsl_list_t  L,
gdsl_map_func_t  MAP_F,
void *  USER_DATA
 

Parse a list from tail to head.

Parse all elements of the list L from tail to head. The MAP_F function is called on each L's element with USER_DATA argument. If MAP_F returns GDSL_MAP_STOP then gdsl_list_map_backward() stops and returns its last examinated element.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & MAP_F != NULL
Parameters:
L The list to parse
MAP_F The map function to apply on each L's element
USER_DATA User's datas passed to MAP_F
Returns:
the first element for which MAP_F returns GDSL_MAP_STOP.

NULL when the parsing is done.

See also:
gdsl_list_map_forward()

void gdsl_list_write const gdsl_list_t  L,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA
 

Write all the elements of a list to a file.

Write the elements of the list L to OUTPUT_FILE, using WRITE_F function. Additionnal USER_DATA argument could be passed to WRITE_F.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & OUTPUT_FILE != NULL & WRITE_F != NULL
Parameters:
L The list to write.
WRITE_F The write function.
OUTPUT_FILE The file where to write L's elements.
USER_DATA User's datas passed to WRITE_F.
See also:
gdsl_list_write_xml()

gdsl_list_dump()

void gdsl_list_write_xml const gdsl_list_t  L,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA
 

Write the content of a list to a file into XML.

Write the elements of the list L to OUTPUT_FILE, into XML language. If WRITE_F != NULL, then uses WRITE_F to write L's elements to OUTPUT_FILE. Additionnal USER_DATA argument could be passed to WRITE_F.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & OUTPUT_FILE != NULL
Parameters:
L The list to write.
WRITE_F The write function.
OUTPUT_FILE The file where to write L's elements.
USER_DATA User's datas passed to WRITE_F.
See also:
gdsl_list_write()

gdsl_list_dump()

void gdsl_list_dump const gdsl_list_t  L,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA
 

Dump the internal structure of a list to a file.

Dump the structure of the list L to OUTPUT_FILE. If WRITE_F != NULL, then uses WRITE_F to write L's elements to OUTPUT_FILE. Additionnal USER_DATA argument could be passed to WRITE_F.

Note:
Complexity: O( |L| )
Precondition:
L must be a valid gdsl_list_t & OUTPUT_FILE != NULL
Parameters:
L The list to write.
WRITE_F The write function.
OUTPUT_FILE The file where to write L's elements.
USER_DATA User's datas passed to WRITE_F.
See also:
gdsl_list_write()

gdsl_list_write_xml()

gdsl_list_cursor_t gdsl_list_cursor_alloc const gdsl_list_t  L  ) 
 

Create a new list cursor.

Note:
Complexity: O( 1 )
Precondition:
L must be a valid gdsl_list_t
Parameters:
L The list on wich the cursor is positionned.
Returns:
the newly allocated list cursor in case of success.

NULL in case of insufficient memory.

See also:
gdsl_list_cursor_free()

void gdsl_list_cursor_free gdsl_list_cursor_t  C  ) 
 

Destroy a list cursor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t.
Parameters:
C The list cursor to destroy.
See also:
gdsl_list_cursor_alloc()

void gdsl_list_cursor_move_to_head gdsl_list_cursor_t  C  ) 
 

Put a cursor on the head of its list.

Put the cursor C on the head of C's list. Does nothing if C's list is empty.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to use
See also:
gdsl_list_cursor_move_to_tail()

void gdsl_list_cursor_move_to_tail gdsl_list_cursor_t  C  ) 
 

Put a cursor on the tail of its list.

Put the cursor C on the tail of C's list. Does nothing if C's list is empty.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to use
See also:
gdsl_list_cursor_move_to_head()

gdsl_element_t gdsl_list_cursor_move_to_value gdsl_list_cursor_t  C,
gdsl_compare_func_t  COMP_F,
void *  VALUE
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t & COMP_F != NULL
Parameters:
C The cursor to put on the element E
COMP_F The comparison function to search for E
VALUE The value used to compare list's elements with
Returns:
the first founded element E in case it exists.

NULL in case of element E is not found.

See also:
gdsl_list_cursor_move_to_position()

gdsl_element_t gdsl_list_cursor_move_to_position gdsl_list_cursor_t  C,
ulong  POS
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t & POS > 0 & POS <= |L|
Parameters:
C The cursor to put on the POS-th element
POS The position of the element to move on
Returns:
the element at the POS-th position

NULL if POS <= 0 or POS > |L|

See also:
gdsl_list_cursor_move_to_value()

void gdsl_list_cursor_step_forward gdsl_list_cursor_t  C  ) 
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to use
See also:
gdsl_list_cursor_step_backward()

void gdsl_list_cursor_step_backward gdsl_list_cursor_t  C  ) 
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to use
See also:
gdsl_list_cursor_step_forward()

bool gdsl_list_cursor_is_on_head const gdsl_list_cursor_t  C  ) 
 

Check if a cursor is on the head of its list.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to check
Returns:
TRUE if C is on its list's head.

FALSE if C is not on its lits's head.

See also:
gdsl_list_cursor_is_on_tail()

bool gdsl_list_cursor_is_on_tail const gdsl_list_cursor_t  C  ) 
 

Check if a cursor is on the tail of its list.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to check
Returns:
TRUE if C is on its lists's tail.

FALSE if C is not on its list's tail.

See also:
gdsl_list_cursor_is_on_head()

bool gdsl_list_cursor_has_succ const gdsl_list_cursor_t  C  ) 
 

Check if a cursor has a successor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to check
Returns:
TRUE if there exists an element after the cursor C.

FALSE if there is no element after the cursor C.

See also:
gdsl_list_cursor_has_pred()

bool gdsl_list_cursor_has_pred const gdsl_list_cursor_t  C  ) 
 

Check if a cursor has a predecessor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to check
Returns:
TRUE if there exists an element before the cursor C.

FALSE if there is no element before the cursor C.

See also:
gdsl_list_cursor_has_succ()

void gdsl_list_cursor_set_content gdsl_list_cursor_t  C,
gdsl_element_t  E
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor in which the content must be modified.
E The value used to modify C's content.
See also:
gdsl_list_cursor_get_content()

gdsl_element_t gdsl_list_cursor_get_content const gdsl_list_cursor_t  C  ) 
 

Get the content of a cursor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to get the content from.
Returns:
the element contained in the cursor C.
See also:
gdsl_list_cursor_set_content()

gdsl_element_t gdsl_list_cursor_insert_after gdsl_list_cursor_t  C,
void *  VALUE
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor after which the new element must be inserted
VALUE The value used to allocate the new element to insert
Returns:
the newly inserted element in case of success.

NULL in case of failure.

See also:
gdsl_list_cursor_insert_before()

gdsl_list_cursor_remove_after()

gdsl_list_cursor_remove_before()

gdsl_element_t gdsl_list_cursor_insert_before gdsl_list_cursor_t  C,
void *  VALUE
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor before which the new element must be inserted
VALUE The value used to allocate the new element to insert
Returns:
the newly inserted element in case of success.

NULL in case of failure.

See also:
gdsl_list_cursor_insert_after()

gdsl_list_cursor_remove_after()

gdsl_list_cursor_remove_before()

gdsl_element_t gdsl_list_cursor_remove gdsl_list_cursor_t  C  ) 
 

Removec the element under a cursor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Postcondition:
After this operation, the cursor is positionned on to its successor.
Parameters:
C The cursor to remove the content from.
Returns:
the removed element if it exists.

NULL if there is not element to remove.

See also:
gdsl_list_cursor_insert_after()

gdsl_list_cursor_insert_before()

gdsl_list_cursor_remove()

gdsl_list_cursor_remove_before()

gdsl_element_t gdsl_list_cursor_remove_after gdsl_list_cursor_t  C  ) 
 

Removec the element after a cursor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to remove the successor from.
Returns:
the removed element if it exists.

NULL if there is not element to remove.

See also:
gdsl_list_cursor_insert_after()

gdsl_list_cursor_insert_before()

gdsl_list_cursor_remove()

gdsl_list_cursor_remove_before()

gdsl_element_t gdsl_list_cursor_remove_before gdsl_list_cursor_t  C  ) 
 

Remove the element before a cursor.

Note:
Complexity: O( 1 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to remove the predecessor from.
Returns:
the removed element if it exists.

NULL if there is not element to remove.

See also:
gdsl_list_cursor_insert_after()

gdsl_list_cursor_insert_before()

gdsl_list_cursor_remove()

gdsl_list_cursor_remove_after()

gdsl_list_cursor_t gdsl_list_cursor_delete gdsl_list_cursor_t  C  ) 
 

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 )

Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to delete the content.
Returns:
the cursor C if the element was removed.

NULL if there is not element to remove.

See also:
gdsl_list_cursor_delete_before()

gdsl_list_cursor_delete_after()

gdsl_list_cursor_t gdsl_list_cursor_delete_after gdsl_list_cursor_t  C  ) 
 

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 )

Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to delete the successor from.
Returns:
the cursor C if the element was removed.

NULL if there is not element to remove.

See also:
gdsl_list_cursor_delete()

gdsl_list_cursor_delete_before()

gdsl_list_cursor_t gdsl_list_cursor_delete_before gdsl_list_cursor_t  C  ) 
 

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 )
Precondition:
C must be a valid gdsl_list_cursor_t
Parameters:
C The cursor to delete the predecessor from.
Returns:
the cursor C if the element was removed.

NULL if there is not element to remove.

See also:
gdsl_list_cursor_delete()

gdsl_list_cursor_delete_after()


Generated on Thu Jun 22 11:15:30 2006 for gdsl by  doxygen 1.4.6