gdsl  1.7
Queue manipulation module

Typedefs

typedef struct _gdsl_queue * gdsl_queue_t
 GDSL queue type.

Functions

gdsl_queue_t gdsl_queue_alloc (const char *NAME, gdsl_alloc_func_t ALLOC_F, gdsl_free_func_t FREE_F)
 Create a new queue.
void gdsl_queue_free (gdsl_queue_t Q)
 Destroy a queue.
void gdsl_queue_flush (gdsl_queue_t Q)
 Flush a queue.
const char * gdsl_queue_get_name (const gdsl_queue_t Q)
 Getsthe name of a queue.
ulong gdsl_queue_get_size (const gdsl_queue_t Q)
 Get the size of a queue.
bool gdsl_queue_is_empty (const gdsl_queue_t Q)
 Check if a queue is empty.
gdsl_element_t gdsl_queue_get_head (const gdsl_queue_t Q)
 Get the head of a queue.
gdsl_element_t gdsl_queue_get_tail (const gdsl_queue_t Q)
 Get the tail of a queue.
gdsl_queue_t gdsl_queue_set_name (gdsl_queue_t Q, const char *NEW_NAME)
 Set the name of a queue.
gdsl_element_t gdsl_queue_insert (gdsl_queue_t Q, void *VALUE)
 Insert an element in a queue (PUT).
gdsl_element_t gdsl_queue_remove (gdsl_queue_t Q)
 Remove an element from a queue (GET).
gdsl_element_t gdsl_queue_search (const gdsl_queue_t Q, gdsl_compare_func_t COMP_F, void *VALUE)
 Search for a particular element in a queue.
gdsl_element_t gdsl_queue_search_by_position (const gdsl_queue_t Q, ulong POS)
 Search for an element by its position in a queue.
gdsl_element_t gdsl_queue_map_forward (const gdsl_queue_t Q, gdsl_map_func_t MAP_F, void *USER_DATA)
 Parse a queue from head to tail.
gdsl_element_t gdsl_queue_map_backward (const gdsl_queue_t Q, gdsl_map_func_t MAP_F, void *USER_DATA)
 Parse a queue from tail to head.
void gdsl_queue_write (const gdsl_queue_t Q, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write all the elements of a queue to a file.
void gdsl_queue_write_xml (const gdsl_queue_t Q, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Write the content of a queue to a file into XML.
void gdsl_queue_dump (const gdsl_queue_t Q, gdsl_write_func_t WRITE_F, FILE *OUTPUT_FILE, void *USER_DATA)
 Dump the internal structure of a queue to a file.

Typedef Documentation

typedef struct _gdsl_queue* gdsl_queue_t

GDSL queue 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 54 of file gdsl_queue.h.


Function Documentation

gdsl_queue_t gdsl_queue_alloc ( const char *  NAME,
gdsl_alloc_func_t  ALLOC_F,
gdsl_free_func_t  FREE_F 
)

Create a new queue.

Allocate a new queue 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 queue. 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:
NAMEThe name of the new queue to create
ALLOC_FFunction to alloc element when inserting it in a queue
FREE_FFunction to free element when deleting it from a queue
Returns:
the newly allocated queue in case of success.
NULL in case of insufficient memory.
See also:
gdsl_queue_free()
gdsl_queue_flush()

Destroy a queue.

Deallocate all the elements of the queue Q by calling Q's FREE_F function passed to gdsl_queue_alloc(). The name of Q is deallocated and Q is deallocated itself too.

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to destroy
See also:
gdsl_queue_alloc()
gdsl_queue_flush()

Flush a queue.

Deallocate all the elements of the queue Q by calling Q's FREE_F function passed to gdsl_queue_allocc(). Q is not deallocated itself and Q's name is not modified.

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to flush
See also:
gdsl_queue_alloc()
gdsl_queue_free()
const char* gdsl_queue_get_name ( const gdsl_queue_t  Q)

Getsthe name of a queue.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Postcondition:
The returned string MUST NOT be freed.
Parameters:
QThe queue to get the name from
Returns:
the name of the queue Q.
See also:
gdsl_queue_set_name()

Get the size of a queue.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to get the size from
Returns:
the number of elements of Q (noted |Q|).

Check if a queue is empty.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to check
Returns:
TRUE if the queue Q is empty.
FALSE if the queue Q is not empty.

Get the head of a queue.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to get the head from
Returns:
the element contained at the header position of the queue Q if Q is not empty. The returned element is not removed from Q.
NULL if the queue Q is empty.
See also:
gdsl_queue_get_tail()

Get the tail of a queue.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to get the tail from
Returns:
the element contained at the footer position of the queue Q if Q is not empty. The returned element is not removed from Q.
NULL if the queue Q is empty.
See also:
gdsl_queue_get_head()
gdsl_queue_t gdsl_queue_set_name ( gdsl_queue_t  Q,
const char *  NEW_NAME 
)

Set the name of a queue.

Change the previous name of the queue Q to a copy of NEW_NAME.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to change the name
NEW_NAMEThe new name of Q
Returns:
the modified queue in case of success.
NULL in case of insufficient memory.
See also:
gdsl_queue_get_name()
gdsl_element_t gdsl_queue_insert ( gdsl_queue_t  Q,
void *  VALUE 
)

Insert an element in a queue (PUT).

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

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to insert in
VALUEThe value used to make the new element to insert into Q
Returns:
the inserted element E in case of success.
NULL in case of insufficient memory.
See also:
gdsl_queue_remove()

Remove an element from a queue (GET).

Remove the element at the footer position of the queue Q.

Note:
Complexity: O( 1 )
Precondition:
Q must be a valid gdsl_queue_t
Parameters:
QThe queue to remove the tail from
Returns:
the removed element in case of success.
NULL in case of Q is empty.
See also:
gdsl_queue_insert()
gdsl_element_t gdsl_queue_search ( const gdsl_queue_t  Q,
gdsl_compare_func_t  COMP_F,
void *  VALUE 
)

Search for a particular element in a queue.

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

Note:
Complexity: O( |Q| / 2 )
Precondition:
Q must be a valid gdsl_queue_t & COMP_F != NULL
Parameters:
QThe queue to search the element in
COMP_FThe comparison function used to compare Q's element with VALUE
VALUEThe value to compare Q's elements with
Returns:
the first founded element E in case of success.
NULL in case the searched element E was not found.
See also:
gdsl_queue_search_by_position

Search for an element by its position in a queue.

Note:
Complexity: O( |Q| / 2 )
Precondition:
Q must be a valid gdsl_queue_t & POS > 0 & POS <= |Q|
Parameters:
QThe queue to search the element in
POSThe position where is the element to search
Returns:
the element at the POS-th position in the queue Q.
NULL if POS > |L| or POS <= 0.
See also:
gdsl_queue_search()
gdsl_element_t gdsl_queue_map_forward ( const gdsl_queue_t  Q,
gdsl_map_func_t  MAP_F,
void *  USER_DATA 
)

Parse a queue from head to tail.

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

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t & MAP_F != NULL
Parameters:
QThe queue to parse
MAP_FThe map function to apply on each Q's element
USER_DATAUser'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_queue_map_backward()
gdsl_element_t gdsl_queue_map_backward ( const gdsl_queue_t  Q,
gdsl_map_func_t  MAP_F,
void *  USER_DATA 
)

Parse a queue from tail to head.

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

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t & MAP_F != NULL
Parameters:
QThe queue to parse
MAP_FThe map function to apply on each Q's element
USER_DATAUser'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_queue_map_forward()
void gdsl_queue_write ( const gdsl_queue_t  Q,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA 
)

Write all the elements of a queue to a file.

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

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t & OUTPUT_FILE != NULL & WRITE_F != NULL
Parameters:
QThe queue to write.
WRITE_FThe write function.
OUTPUT_FILEThe file where to write Q's elements.
USER_DATAUser's datas passed to WRITE_F.
See also:
gdsl_queue_write_xml()
gdsl_queue_dump()
void gdsl_queue_write_xml ( const gdsl_queue_t  Q,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA 
)

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

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

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t & OUTPUT_FILE != NULL
Parameters:
QThe queue to write.
WRITE_FThe write function.
OUTPUT_FILEThe file where to write Q's elements.
USER_DATAUser's datas passed to WRITE_F.
See also:
gdsl_queue_write()
gdsl_queue_dump()
void gdsl_queue_dump ( const gdsl_queue_t  Q,
gdsl_write_func_t  WRITE_F,
FILE *  OUTPUT_FILE,
void *  USER_DATA 
)

Dump the internal structure of a queue to a file.

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

Note:
Complexity: O( |Q| )
Precondition:
Q must be a valid gdsl_queue_t & OUTPUT_FILE != NULL
Parameters:
QThe queue to write.
WRITE_FThe write function.
OUTPUT_FILEThe file where to write Q's elements.
USER_DATAUser's datas passed to WRITE_F.
See also:
gdsl_queue_write()
gdsl_queue_write_xml()