gdsl_stack.3

书籍上的数据结构源代码

.TH "Stack manipulation module" 3 "22 Jun 2006" "Version 1.4" "gdsl" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Stack manipulation module \- 
.PP
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef _gdsl_stack * \fBgdsl_stack_t\fP"
.br
.RI "\fIGDSL stack type. \fP"
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBgdsl_stack_t\fP \fBgdsl_stack_alloc\fP (const char *NAME, \fBgdsl_alloc_func_t\fP ALLOC_F, \fBgdsl_free_func_t\fP FREE_F)"
.br
.RI "\fICreate a new stack. \fP"
.ti -1c
.RI "void \fBgdsl_stack_free\fP (\fBgdsl_stack_t\fP S)"
.br
.RI "\fIDestroy a stack. \fP"
.ti -1c
.RI "void \fBgdsl_stack_flush\fP (\fBgdsl_stack_t\fP S)"
.br
.RI "\fIFlush a stack. \fP"
.ti -1c
.RI "const char * \fBgdsl_stack_get_name\fP (const \fBgdsl_stack_t\fP S)"
.br
.RI "\fIGetsthe name of a stack. \fP"
.ti -1c
.RI "\fBulong\fP \fBgdsl_stack_get_size\fP (const \fBgdsl_stack_t\fP S)"
.br
.RI "\fIGet the size of a stack. \fP"
.ti -1c
.RI "\fBulong\fP \fBgdsl_stack_get_growing_factor\fP (const \fBgdsl_stack_t\fP S)"
.br
.RI "\fIGet the growing factor of a stack. \fP"
.ti -1c
.RI "\fBbool\fP \fBgdsl_stack_is_empty\fP (const \fBgdsl_stack_t\fP S)"
.br
.RI "\fICheck if a stack is empty. \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_get_top\fP (const \fBgdsl_stack_t\fP S)"
.br
.RI "\fIGet the top of a stack. \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_get_bottom\fP (const \fBgdsl_stack_t\fP S)"
.br
.RI "\fIGet the bottom of a stack. \fP"
.ti -1c
.RI "\fBgdsl_stack_t\fP \fBgdsl_stack_set_name\fP (\fBgdsl_stack_t\fP S, const char *NEW_NAME)"
.br
.RI "\fISet the name of a stack. \fP"
.ti -1c
.RI "void \fBgdsl_stack_set_growing_factor\fP (\fBgdsl_stack_t\fP S, \fBulong\fP G)"
.br
.RI "\fISet the growing factor of a stack. \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_insert\fP (\fBgdsl_stack_t\fP S, void *VALUE)"
.br
.RI "\fIInsert an element in a stack (PUSH). \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_remove\fP (\fBgdsl_stack_t\fP S)"
.br
.RI "\fIRemove an element from a stack (POP). \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_search\fP (const \fBgdsl_stack_t\fP S, \fBgdsl_compare_func_t\fP COMP_F, void *VALUE)"
.br
.RI "\fISearch for a particular element in a stack. \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_search_by_position\fP (const \fBgdsl_stack_t\fP S, \fBulong\fP POS)"
.br
.RI "\fISearch for an element by its position in a stack. \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_map_forward\fP (const \fBgdsl_stack_t\fP S, \fBgdsl_map_func_t\fP MAP_F, void *USER_DATA)"
.br
.RI "\fIParse a stack from bottom to top. \fP"
.ti -1c
.RI "\fBgdsl_element_t\fP \fBgdsl_stack_map_backward\fP (const \fBgdsl_stack_t\fP S, \fBgdsl_map_func_t\fP MAP_F, void *USER_DATA)"
.br
.RI "\fIParse a stack from top to bottom. \fP"
.ti -1c
.RI "void \fBgdsl_stack_write\fP (const \fBgdsl_stack_t\fP S, \fBgdsl_write_func_t\fP WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)"
.br
.RI "\fIWrite all the elements of a stack to a file. \fP"
.ti -1c
.RI "void \fBgdsl_stack_write_xml\fP (\fBgdsl_stack_t\fP S, \fBgdsl_write_func_t\fP WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)"
.br
.RI "\fIWrite the content of a stack to a file into XML. \fP"
.ti -1c
.RI "void \fBgdsl_stack_dump\fP (\fBgdsl_stack_t\fP S, \fBgdsl_write_func_t\fP WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)"
.br
.RI "\fIDump the internal structure of a stack to a file. \fP"
.in -1c
.SH "Typedef Documentation"
.PP 
.SS "typedef struct _gdsl_stack* \fBgdsl_stack_t\fP"
.PP
GDSL stack type. 
.PP
This type is voluntary opaque. Variables of this kind could'nt be directly used, but by the functions of this module. 
.PP
Definition at line 53 of file gdsl_stack.h.
.SH "Function Documentation"
.PP 
.SS "\fBgdsl_stack_t\fP gdsl_stack_alloc (const char * NAME, \fBgdsl_alloc_func_t\fP ALLOC_F, \fBgdsl_free_func_t\fP FREE_F)"
.PP
Create a new stack. 
.PP
Allocate a new stack data structure which name is set to a copy of NAME. The functions pointers ALLOC_F and FREE_F could be used to respectively, alloc and free elements in the stack. These pointers could be set to NULL to use the default ones:
.IP "\(bu" 2
the default ALLOC_F simply returns its argument
.IP "\(bu" 2
the default FREE_F does nothing
.PP
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
nothing. 
.RE
.PP
\fBParameters:\fP
.RS 4
\fINAME\fP The name of the new stack to create 
.br
\fIALLOC_F\fP Function to alloc element when inserting it in a stack 
.br
\fIFREE_F\fP Function to free element when deleting it from a stack 
.RE
.PP
\fBReturns:\fP
.RS 4
the newly allocated stack in case of success. 
.PP
NULL in case of insufficient memory. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_free()\fP 
.PP
\fBgdsl_stack_flush()\fP 
.RE
.PP

.SS "void gdsl_stack_free (\fBgdsl_stack_t\fP S)"
.PP
Destroy a stack. 
.PP
Deallocate all the elements of the stack S by calling S's FREE_F function passed to \fBgdsl_stack_alloc()\fP. The name of S is deallocated and S is deallocated itself too.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.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 destroy 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_alloc()\fP 
.PP
\fBgdsl_stack_flush()\fP 
.RE
.PP

.SS "void gdsl_stack_flush (\fBgdsl_stack_t\fP S)"
.PP
Flush a stack. 
.PP
Deallocate all the elements of the stack S by calling S's FREE_F function passed to \fBgdsl_stack_alloc()\fP. S is not deallocated itself and S's name is not modified.
.PP
\fBNote:\fP
.RS 4
Complexity: O( |S| ) 
.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 flush 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_alloc()\fP 
.PP
\fBgdsl_stack_free()\fP 
.RE
.PP

.SS "const char* gdsl_stack_get_name (const \fBgdsl_stack_t\fP S)"
.PP
Getsthe name of a stack. 
.PP
\fBNote:\fP
.RS 4
Complexity: O( 1 ) 
.RE
.PP
\fBPrecondition:\fP
.RS 4
Q must be a valid gdsl_stack_t 
.RE
.PP
\fBPostcondition:\fP
.RS 4
The returned string MUST NOT be freed. 
.RE
.PP
\fBParameters:\fP
.RS 4
\fIS\fP The stack to get the name from 
.RE
.PP
\fBReturns:\fP
.RS 4
the name of the stack S. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_set_name()\fP 
.RE
.PP

.SS "\fBulong\fP gdsl_stack_get_size (const \fBgdsl_stack_t\fP S)"
.PP
Get the size of a stack. 
.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 size from 
.RE
.PP
\fBReturns:\fP
.RS 4
the number of elements of the stack S (noted |S|). 
.RE
.PP

.SS "\fBulong\fP gdsl_stack_get_growing_factor (const \fBgdsl_stack_t\fP S)"
.PP
Get the growing factor of a stack. 
.PP
Get 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. This value is 1 by default and can be modified with \fBgdsl_stack_set_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 
.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_set_growing_factor()\fP 
.RE
.PP

.SS "\fBbool\fP gdsl_stack_is_empty (const \fBgdsl_stack_t\fP S)"
.PP
Check if a stack is empty. 
.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 check 
.RE
.PP
\fBReturns:\fP
.RS 4
TRUE if the stack S is empty. 
.PP
FALSE if the stack S is not empty. 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_get_top (const \fBgdsl_stack_t\fP S)"
.PP
Get the top of a stack. 
.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 top from 
.RE
.PP
\fBReturns:\fP
.RS 4
the element contained at the top position of the stack S if S is not empty. The returned element is not removed from S. 
.PP
NULL if the stack S is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_get_bottom()\fP 
.RE
.PP

.SS "\fBgdsl_element_t\fP gdsl_stack_get_bottom (const \fBgdsl_stack_t\fP S)"
.PP
Get the bottom of a stack. 
.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 bottom from 
.RE
.PP
\fBReturns:\fP
.RS 4
the element contained at the bottom position of the stack S if S is not empty. The returned element is not removed from S. 
.PP
NULL if the stack S is empty. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBgdsl_stack_get_top()\fP 
.RE