gdsl_list.3

书籍上的数据结构源代码

.SS "\fBgdsl_element_t\fP gdsl_list_remove_tail (\fBgdsl_list_t\fP L)"
.PP
Remove the tail of a list. 
.PP
Remove the element at the tail of the list L.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to remove the tail from 
.RE
.PP
\fBReturns:\fP
.RS 4
the removed element in case of success. 
.PP
NULL in case of L is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_insert_head()\fP 
.PP
\fBgdsl_list_insert_tail()\fP 
.PP
\fBgdsl_list_remove_head()\fP 
.PP
\fBgdsl_list_remove()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_remove (\fBgdsl_list_t\fP L, \fBgdsl_compare_func_t\fP COMP_F, const void * VALUE)"
.PP
Remove a particular element from a list. 
.PP
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.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| / 2 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & COMP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to remove the element from 
.br
\fICOMP_F\fP The comparison function used to find the element to remove 
.br
\fIVALUE\fP The value used to compare the element to remove with 
.RE
.PP
\fBReturns:\fP
.RS 4
the founded element E if it was found. 
.PP
NULL in case the searched element E was not found. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_insert_head()\fP 
.PP
\fBgdsl_list_insert_tail()\fP 
.PP
\fBgdsl_list_remove_head()\fP 
.PP
\fBgdsl_list_remove_tail()\fP 
.RE
.PP

.SS "\fBgdsl_list_t\fP gdsl_list_delete_head (\fBgdsl_list_t\fP L)"
.PP
Delete the head of a list. 
.PP
Remove the header element from the list L and deallocates it using the FREE_F function passed to \fBgdsl_list_alloc()\fP.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to destroy the head from 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified list L in case of success. 
.PP
NULL if L is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_alloc()\fP 
.PP
gdsl_list_destroy_tail() 
.PP
gdsl_list_destroy() 
.RE
.PP

.SS "\fBgdsl_list_t\fP gdsl_list_delete_tail (\fBgdsl_list_t\fP L)"
.PP
Delete the tail of a list. 
.PP
Remove the footer element from the list L and deallocates it using the FREE_F function passed to \fBgdsl_list_alloc()\fP.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to destroy the tail from 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified list L in case of success. 
.PP
NULL if L is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_alloc()\fP 
.PP
gdsl_list_destroy_head() 
.PP
gdsl_list_destroy() 
.RE
.PP

.SS "\fBgdsl_list_t\fP gdsl_list_delete (\fBgdsl_list_t\fP L, \fBgdsl_compare_func_t\fP COMP_F, const void * VALUE)"
.PP
Delete a particular element from a list. 
.PP
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 \fBgdsl_list_alloc()\fP.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| / 2 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & COMP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to destroy the element from 
.br
\fICOMP_F\fP The comparison function used to find the element to destroy 
.br
\fIVALUE\fP The value used to compare the element to destroy with 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified list L if the element is found. 
.PP
NULL if the element to destroy is not found. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_alloc()\fP 
.PP
gdsl_list_destroy_head() 
.PP
gdsl_list_destroy_tail() 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_search (const \fBgdsl_list_t\fP L, \fBgdsl_compare_func_t\fP COMP_F, const void * VALUE)"
.PP
Search for a particular element into a list. 
.PP
Search the first element E equal to VALUE in the list L, by using COMP_F to compare all L's element with.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| / 2 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & COMP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to search the element in 
.br
\fICOMP_F\fP The comparison function used to compare L's element with VALUE 
.br
\fIVALUE\fP The value to compare L's elemenst with 
.RE
.PP
\fBReturns:\fP
.RS 4
the first founded element E in case of success. 
.PP
NULL in case the searched element E was not found. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_search_by_position()\fP 
.PP
\fBgdsl_list_search_max()\fP 
.PP
\fBgdsl_list_search_min()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_search_by_position (const \fBgdsl_list_t\fP L, \fBulong\fP POS)"
.PP
Search for an element by its position in a list. 
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| / 2 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & POS > 0 & POS <= |L| 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to search the element in 
.br
\fIPOS\fP The position where is the element to search 
.RE
.PP
\fBReturns:\fP
.RS 4
the element at the POS-th position in the list L. 
.PP
NULL if POS > |L| or POS <= 0. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_search()\fP 
.PP
\fBgdsl_list_search_max()\fP 
.PP
\fBgdsl_list_search_min()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_search_max (const \fBgdsl_list_t\fP L, \fBgdsl_compare_func_t\fP COMP_F)"
.PP
Search for the greatest element of a list. 
.PP
Search the greatest element of the list L, by using COMP_F to compare L's elements with.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & COMP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to search the element in 
.br
\fICOMP_F\fP The comparison function to use to compare L's element with 
.RE
.PP
\fBReturns:\fP
.RS 4
the highest element of L, by using COMP_F function. 
.PP
NULL if L is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_search()\fP 
.PP
\fBgdsl_list_search_by_position()\fP 
.PP
\fBgdsl_list_search_min()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_search_min (const \fBgdsl_list_t\fP L, \fBgdsl_compare_func_t\fP COMP_F)"
.PP
Search for the lowest element of a list. 
.PP
Search the lowest element of the list L, by using COMP_F to compare L's elements with.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & COMP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to search the element in 
.br
\fICOMP_F\fP The comparison function to use to compare L's element with 
.RE
.PP
\fBReturns:\fP
.RS 4
the lowest element of L, by using COMP_F function. 
.PP
NULL if L is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_search()\fP 
.PP
\fBgdsl_list_search_by_position()\fP 
.PP
\fBgdsl_list_search_max()\fP 
.RE
.PP

.SS "\fBgdsl_list_t\fP gdsl_list_sort (\fBgdsl_list_t\fP L, \fBgdsl_compare_func_t\fP COMP_F)"
.PP
Sort a list. 
.PP
Sort the list L using COMP_F to order L's elements.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| * log( |L| ) ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & COMP_F != NULL & L must not contains elements that are equals 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to sort 
.br
\fICOMP_F\fP The comparison function used to order L's elements 
.RE
.PP
\fBReturns:\fP
.RS 4
the sorted list L. 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_map_forward (const \fBgdsl_list_t\fP L, \fBgdsl_map_func_t\fP MAP_F, void * USER_DATA)"
.PP
Parse a list from head to tail. 
.PP
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 \fBgdsl_list_map_forward()\fP stops and returns its last examinated element.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & MAP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to parse 
.br
\fIMAP_F\fP The map function to apply on each L's element 
.br
\fIUSER_DATA\fP User's datas passed to MAP_F 
.RE
.PP
\fBReturns:\fP
.RS 4
the first element for which MAP_F returns GDSL_MAP_STOP. 
.PP
NULL when the parsing is done. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_map_backward()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_list_map_backward (const \fBgdsl_list_t\fP L, \fBgdsl_map_func_t\fP MAP_F, void * USER_DATA)"
.PP
Parse a list from tail to head. 
.PP
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 \fBgdsl_list_map_backward()\fP stops and returns its last examinated element.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & MAP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to parse 
.br
\fIMAP_F\fP The map function to apply on each L's element 
.br
\fIUSER_DATA\fP User's datas passed to MAP_F 
.RE
.PP
\fBReturns:\fP
.RS 4
the first element for which MAP_F returns GDSL_MAP_STOP. 
.PP
NULL when the parsing is done. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_map_forward()\fP 
.RE
.PP

.SS "void gdsl_list_write (const \fBgdsl_list_t\fP L, \fBgdsl_write_func_t\fP WRITE_F, FILE * OUTPUT_FILE, void * USER_DATA)"
.PP
Write all the elements of a list to a file. 
.PP
Write the elements of the list L to OUTPUT_FILE, using WRITE_F function. Additionnal USER_DATA argument could be passed to WRITE_F.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & OUTPUT_FILE != NULL & WRITE_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to write. 
.br
\fIWRITE_F\fP The write function. 
.br
\fIOUTPUT_FILE\fP The file where to write L's elements. 
.br
\fIUSER_DATA\fP User's datas passed to WRITE_F. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_write_xml()\fP 
.PP
\fBgdsl_list_dump()\fP 
.RE
.PP

.SS "void gdsl_list_write_xml (const \fBgdsl_list_t\fP L, \fBgdsl_write_func_t\fP WRITE_F, FILE * OUTPUT_FILE, void * USER_DATA)"
.PP
Write the content of a list to a file into XML. 
.PP
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.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & OUTPUT_FILE != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to write. 
.br
\fIWRITE_F\fP The write function. 
.br
\fIOUTPUT_FILE\fP The file where to write L's elements. 
.br
\fIUSER_DATA\fP User's datas passed to WRITE_F. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_write()\fP 
.PP
\fBgdsl_list_dump()\fP 
.RE
.PP

.SS "void gdsl_list_dump (const \fBgdsl_list_t\fP L, \fBgdsl_write_func_t\fP WRITE_F, FILE * OUTPUT_FILE, void * USER_DATA)"
.PP
Dump the internal structure of a list to a file. 
.PP
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.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |L| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t & OUTPUT_FILE != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list to write. 
.br
\fIWRITE_F\fP The write function. 
.br
\fIOUTPUT_FILE\fP The file where to write L's elements. 
.br
\fIUSER_DATA\fP User's datas passed to WRITE_F. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_write()\fP 
.PP
\fBgdsl_list_write_xml()\fP 
.RE
.PP

.SS "\fBgdsl_list_cursor_t\fP gdsl_list_cursor_alloc (const \fBgdsl_list_t\fP L)"
.PP
Create a new list cursor. 
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
L must be a valid gdsl_list_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIL\fP The list on wich the cursor is positionned. 
.RE
.PP
\fBReturns:\fP
.RS 4
the newly allocated list cursor in case of success. 
.PP
NULL in case of insufficient memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_cursor_free()\fP 
.RE
.PP

.SS "void gdsl_list_cursor_free (\fBgdsl_list_cursor_t\fP C)"
.PP
Destroy a list cursor. 
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
C must be a valid gdsl_list_cursor_t. 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIC\fP The list cursor to destroy. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_list_cursor_alloc()\fP 
.RE
.PP

.SS "void gdsl_list_cursor_move_to_head (\fBgdsl_list_cursor_t\fP C)"
.PP
Put a cursor on the head of its list. 
.PP
Put the cursor C on the head of C's list. Does nothing if C's list is empty.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
C must be a valid gdsl_list_cursor_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIC\fP The cursor to use 
.RE
.PP