Main Page | Modules | File List | Globals

Stack manipulation module


Typedefs

typedef _gdsl_stack * gdsl_stack_t
 GDSL stack type.


Functions

gdsl_stack_t gdsl_stack_alloc (const char *NAME, gdsl_alloc_func_t ALLOC_F, gdsl_free_func_t FREE_F)
 Create a new stack.

void gdsl_stack_free (gdsl_stack_t S)
 Destroy a stack.

void gdsl_stack_flush (gdsl_stack_t S)
 Flush a stack.

const char * gdsl_stack_get_name (const gdsl_stack_t S)
 Getsthe name of a stack.

ulong gdsl_stack_get_size (const gdsl_stack_t S)
 Get the size of a stack.

ubyte gdsl_stack_get_growing_factor (const gdsl_stack_t S)
 Get the growing factor of a stack.

bool gdsl_stack_is_empty (const gdsl_stack_t S)
 Check if a stack is empty.

gdsl_element_t gdsl_stack_get_top (const gdsl_stack_t S)
 Get the top of a stack.

gdsl_element_t gdsl_stack_get_bottom (const gdsl_stack_t S)
 Get the bottom of a stack.

gdsl_stack_t gdsl_stack_set_name (gdsl_stack_t S, const char *NEW_NAME)
 Set the name of a stack.

void gdsl_stack_set_growing_factor (gdsl_stack_t S, ubyte G)
 Set the growing factor of a stack.

gdsl_element_t gdsl_stack_insert (gdsl_stack_t S, void *VALUE)
 Insert an element in a stack (PUSH).

gdsl_element_t gdsl_stack_remove (gdsl_stack_t S)
 Remove an element from a stack (POP).

gdsl_element_t gdsl_stack_search (const gdsl_stack_t S, gdsl_compare_func_t COMP_F, void *VALUE)
 Search for a particular element in a stack.

gdsl_element_t gdsl_stack_search_by_position (const gdsl_stack_t S, ulong POS)
 Search for an element by its position in a stack.

gdsl_element_t gdsl_stack_map_forward (const gdsl_stack_t S, gdsl_map_func_t MAP_F, void *USER_DATA)
 Parse a stack from bottom to top.

gdsl_element_t gdsl_stack_map_backward (const gdsl_stack_t S, gdsl_map_func_t MAP_F, void *USER_DATA)
 Parse a stack from top to bottom.

void gdsl_stack_write (const gdsl_stack_t S, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write all the elements of a stack to a file.

void gdsl_stack_write_xml (gdsl_stack_t S, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write the content of a stack to a file into XML.

void gdsl_stack_dump (gdsl_stack_t S, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Dump the internal structure of a stack to a file.


Typedef Documentation

typedef struct _gdsl_stack* gdsl_stack_t
 

GDSL stack 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 52 of file gdsl_stack.h.


Function Documentation

gdsl_stack_t gdsl_stack_alloc const char *  NAME,
gdsl_alloc_func_t  ALLOC_F,
gdsl_free_func_t  FREE_F
 

Create a new stack.

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:

  • 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 stack to create
ALLOC_F Function to alloc element when inserting it in a stack
FREE_F Function to free element when deleting it from a stack
Returns:
the newly allocated stack in case of success.

NULL in case of insufficient memory.

See also:
gdsl_stack_free()

gdsl_stack_flush()

void gdsl_stack_dump gdsl_stack_t  S,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA
 

Dump the internal structure of a stack to a file.

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.

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

gdsl_stack_write_xml()

void gdsl_stack_flush gdsl_stack_t  S  ) 
 

Flush a stack.

Deallocate all the elements of the stack S by calling S's FREE_F function passed to gdsl_stack_alloc(). S is not deallocated itself and S's name is not modified.

Note:
Complexity: O( |S| )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to flush
See also:
gdsl_stack_alloc()

gdsl_stack_free()

void gdsl_stack_free gdsl_stack_t  S  ) 
 

Destroy a stack.

Deallocate all the elements of the stack S by calling S's FREE_F function passed to gdsl_stack_alloc(). The name of S is deallocated and S is deallocated itself too.

Note:
Complexity: O( |S| )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to destroy
See also:
gdsl_stack_alloc()

gdsl_stack_flush()

gdsl_element_t gdsl_stack_get_bottom const gdsl_stack_t  S  ) 
 

Get the bottom of a stack.

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to get the bottom from
Returns:
the element contained at the bottom position of the stack S if S is not empty. The returned element is not removed from S.

NULL if the stack S is empty.

See also:
gdsl_stack_get_top()

ubyte gdsl_stack_get_growing_factor const gdsl_stack_t  S  ) 
 

Get the growing factor of a stack.

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 gdsl_stack_set_growing_factor().

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to get the growing factor from
Returns:
the growing factor of the stack S.
See also:
gdsl_stack_insert()

gdsl_stack_set_growing_factor()

const char* gdsl_stack_get_name const gdsl_stack_t  S  ) 
 

Getsthe name of a stack.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_stack_t
Postcondition:
The returned string MUST NOT be freed.
Parameters:
S The stack to get the name from
Returns:
the name of the stack S.
See also:
gdsl_stack_set_name()

ulong gdsl_stack_get_size const gdsl_stack_t  S  ) 
 

Get the size of a stack.

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

gdsl_element_t gdsl_stack_get_top const gdsl_stack_t  S  ) 
 

Get the top of a stack.

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to get the top from
Returns:
the element contained at the top position of the stack S if S is not empty. The returned element is not removed from S.

NULL if the stack S is empty.

See also:
gdsl_stack_get_bottom()

gdsl_element_t gdsl_stack_insert gdsl_stack_t  S,
void *  VALUE
 

Insert an element in a stack (PUSH).

Allocate a new element E by calling S's ALLOC_F function on VALUE. ALLOC_F is the function pointer passed to gdsl_stack_alloc(). 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.

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

NULL in case of insufficient memory.

See also:
gdsl_stack_set_growing_factor()

gdsl_stack_get_growing_factor()

gdsl_stack_remove()

bool gdsl_stack_is_empty const gdsl_stack_t  S  ) 
 

Check if a stack is empty.

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to check
Returns:
TRUE if the stack S is empty.

FALSE if the stack S is not empty.

gdsl_element_t gdsl_stack_map_backward const gdsl_stack_t  S,
gdsl_map_func_t  MAP_F,
void *  USER_DATA
 

Parse a stack from top to bottom.

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 gdsl_stack_map_backward() stops and returns its last examinated element.

Note:
Complexity: O( |S| )
Precondition:
S must be a valid gdsl_stack_t & MAP_F != NULL
Parameters:
S The stack to parse
MAP_F The map function to apply on each S'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_stack_map_forward()

gdsl_element_t gdsl_stack_map_forward const gdsl_stack_t  S,
gdsl_map_func_t  MAP_F,
void *  USER_DATA
 

Parse a stack from bottom to top.

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 gdsl_stack_map_forward() stops and returns its last examinated element.

Note:
Complexity: O( |S| )
Precondition:
S must be a valid gdsl_stack_t & MAP_F != NULL
Parameters:
S The stack to parse
MAP_F The map function to apply on each S's element
USER_DATA 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.
See also:
gdsl_stack_map_backward()

gdsl_element_t gdsl_stack_remove gdsl_stack_t  S  ) 
 

Remove an element from a stack (POP).

Remove the element at the top position of the stack S.

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to remove the top from
Returns:
the removed element in case of success.

NULL in case of S is empty.

See also:
gdsl_stack_insert()

gdsl_element_t gdsl_stack_search const gdsl_stack_t  S,
gdsl_compare_func_t  COMP_F,
void *  VALUE
 

Search for a particular element in a stack.

Search for the first element E equal to VALUE in the stack S, by using COMP_F to compare all S's element with.

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

NULL if no element is found.

See also:
gdsl_stack_search_by_position()

gdsl_element_t gdsl_stack_search_by_position const gdsl_stack_t  S,
ulong  POS
 

Search for an element by its position in a stack.

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t & POS > 0 & POS <= |S|
Parameters:
S The stack to search the element in
POS The position where is the element to search
Returns:
the element at the POS-th position in the stack S.

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

See also:
gdsl_stack_search()

void gdsl_stack_set_growing_factor gdsl_stack_t  S,
ubyte  G
 

Set the growing factor of a stack.

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 gdsl_stack_get_growing_factor()

Note:
Complexity: O( 1 )
Precondition:
S must be a valid gdsl_stack_t
Parameters:
S The stack to get the growing factor from
G The new growing factor of S.
Returns:
the growing factor of the stack S.
See also:
gdsl_stack_insert()

gdsl_stack_get_growing_factor()

gdsl_stack_t gdsl_stack_set_name gdsl_stack_t  S,
const char *  NEW_NAME
 

Set the name of a stack.

Change the previous name of the stack S to a copy of NEW_NAME.

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

NULL in case of insufficient memory.

See also:
gdsl_stack_get_name()

void gdsl_stack_write const gdsl_stack_t  S,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA
 

Write all the elements of a stack to a file.

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

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

gdsl_stack_dump()

void gdsl_stack_write_xml gdsl_stack_t  S,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA
 

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

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.

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

gdsl_stack_dump()


Generated on Fri Oct 1 18:54:53 2004 for GDSL by doxygen 1.3.5