gdsl_stack.3

书籍上的数据结构源代码

.PP

.SS "\fBgdsl_stack_t\fP gdsl_stack_set_name (\fBgdsl_stack_t\fP S, const char * NEW_NAME)"
.PP
Set the name of a stack. 
.PP
Change the previous name of the stack S to a copy of NEW_NAME.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to change the name 
.br
\fINEW_NAME\fP The new name of S 
.RE
.PP
\fBReturns:\fP
.RS 4
the modified stack in case of success. 
.PP
NULL in case of insufficient memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_get_name()\fP 
.RE
.PP

.SS "void gdsl_stack_set_growing_factor (\fBgdsl_stack_t\fP S, \fBulong\fP G)"
.PP
Set the growing factor of a stack. 
.PP
Set the growing factor of the stack S. This value is the amount of cells to reserve for next insertions. For example, if you set this value to 10, each time the number of elements of S reaches 10, then 10 new cells will be reserved for next 10 insertions. It is a way to save time for insertions. To know the actual value of the growing factor, use \fBgdsl_stack_get_growing_factor()\fP
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to get the growing factor from 
.br
\fIG\fP The new growing factor of S. 
.RE
.PP
\fBReturns:\fP
.RS 4
the growing factor of the stack S. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_insert()\fP 
.PP
\fBgdsl_stack_get_growing_factor()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_insert (\fBgdsl_stack_t\fP S, void * VALUE)"
.PP
Insert an element in a stack (PUSH). 
.PP
Allocate a new element E by calling S's ALLOC_F function on VALUE. ALLOC_F is the function pointer passed to \fBgdsl_stack_alloc()\fP. The new element E is the inserted at the top position of the stack S. If the number of elements in S reaches S's growing factor (G), then G new cells are reserved for future insertions into S to save time.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to insert in 
.br
\fIVALUE\fP The value used to make the new element to insert into S 
.RE
.PP
\fBReturns:\fP
.RS 4
the inserted element E in case of success. 
.PP
NULL in case of insufficient memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_set_growing_factor()\fP 
.PP
\fBgdsl_stack_get_growing_factor()\fP 
.PP
\fBgdsl_stack_remove()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_remove (\fBgdsl_stack_t\fP S)"
.PP
Remove an element from a stack (POP). 
.PP
Remove the element at the top position of the stack S.
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to remove the top from 
.RE
.PP
\fBReturns:\fP
.RS 4
the removed element in case of success. 
.PP
NULL in case of S is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_insert()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_search (const \fBgdsl_stack_t\fP S, \fBgdsl_compare_func_t\fP COMP_F, void * VALUE)"
.PP
Search for a particular element in a stack. 
.PP
Search for the first element E equal to VALUE in the stack S, by using COMP_F to compare all S's element with.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & COMP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to search the element in 
.br
\fICOMP_F\fP The comparison function used to compare S's element with VALUE 
.br
\fIVALUE\fP The value to compare S's elements with 
.RE
.PP
\fBReturns:\fP
.RS 4
the first founded element E in case of success. 
.PP
NULL if no element is found. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_search_by_position()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_search_by_position (const \fBgdsl_stack_t\fP S, \fBulong\fP POS)"
.PP
Search for an element by its position in a stack. 
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & POS > 0 & POS <= |S| 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack 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 stack S. 
.PP
NULL if POS > |L| or POS <= 0. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_search()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_map_forward (const \fBgdsl_stack_t\fP S, \fBgdsl_map_func_t\fP MAP_F, void * USER_DATA)"
.PP
Parse a stack from bottom to top. 
.PP
Parse all elements of the stack S from bottom to top. The MAP_F function is called on each S's element with USER_DATA argument. If MAP_F returns GDSL_MAP_STOP, then \fBgdsl_stack_map_forward()\fP stops and returns its last examinated element.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & MAP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to parse 
.br
\fIMAP_F\fP The map function to apply on each S's element 
.br
\fIUSER_DATA\fP User's datas passed to MAP_F Returns the first element for which MAP_F returns GDSL_MAP_STOP. Returns NULL when the parsing is done. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_map_backward()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_map_backward (const \fBgdsl_stack_t\fP S, \fBgdsl_map_func_t\fP MAP_F, void * USER_DATA)"
.PP
Parse a stack from top to bottom. 
.PP
Parse all elements of the stack S from top to bottom. The MAP_F function is called on each S's element with USER_DATA argument. If MAP_F returns GDSL_MAP_STOP, then \fBgdsl_stack_map_backward()\fP stops and returns its last examinated element.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & MAP_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to parse 
.br
\fIMAP_F\fP The map function to apply on each S'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_stack_map_forward()\fP 
.RE
.PP

.SS "void gdsl_stack_write (const \fBgdsl_stack_t\fP S, \fBgdsl_write_func_t\fP WRITE_F, FILE * OUTPUT_FILE, void * USER_DATA)"
.PP
Write all the elements of a stack to a file. 
.PP
Write the elements of the stack S to OUTPUT_FILE, using WRITE_F function. Additionnal USER_DATA argument could be passed to WRITE_F.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & OUTPUT_FILE != NULL & WRITE_F != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to write. 
.br
\fIWRITE_F\fP The write function. 
.br
\fIOUTPUT_FILE\fP The file where to write S's elements. 
.br
\fIUSER_DATA\fP User's datas passed to WRITE_F. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_write_xml()\fP 
.PP
\fBgdsl_stack_dump()\fP 
.RE
.PP

.SS "void gdsl_stack_write_xml (\fBgdsl_stack_t\fP S, \fBgdsl_write_func_t\fP WRITE_F, FILE * OUTPUT_FILE, void * USER_DATA)"
.PP
Write the content of a stack to a file into XML. 
.PP
Write the elements of the stack S to OUTPUT_FILE, into XML language. If WRITE_F != NULL, then uses WRITE_F to write S's elements to OUTPUT_FILE. Additionnal USER_DATA argument could be passed to WRITE_F.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & OUTPUT_FILE != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to write. 
.br
\fIWRITE_F\fP The write function. 
.br
\fIOUTPUT_FILE\fP The file where to write S's elements. 
.br
\fIUSER_DATA\fP User's datas passed to WRITE_F. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_write()\fP 
.PP
\fBgdsl_stack_dump()\fP 
.RE
.PP

.SS "void gdsl_stack_dump (\fBgdsl_stack_t\fP S, \fBgdsl_write_func_t\fP WRITE_F, FILE * OUTPUT_FILE, void * USER_DATA)"
.PP
Dump the internal structure of a stack to a file. 
.PP
Dump the structure of the stack S to OUTPUT_FILE. If WRITE_F != NULL, then uses WRITE_F to write S's elements to OUTPUT_FILE. Additionnal USER_DATA argument could be passed to WRITE_F.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
S must be a valid gdsl_stack_t & OUTPUT_FILE != NULL 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to write. 
.br
\fIWRITE_F\fP The write function. 
.br
\fIOUTPUT_FILE\fP The file where to write S's elements. 
.br
\fIUSER_DATA\fP User's datas passed to WRITE_F. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_write()\fP 
.PP
\fBgdsl_stack_write_xml()\fP 
.RE
.PP