C Standard Library Extensions  1.0.5
Functions
Double-ended queue.

Functions

cx_deque * cx_deque_new (void)
 Create a new deque without any elements.
void cx_deque_push_back (cx_deque *d, cxptr data)
 Append data at the end of a deque.
void cx_deque_push_front (cx_deque *d, cxptr data)
 Insert data at the beginning of a deque.
cxptr cx_deque_get (const cx_deque *d, cx_deque_const_iterator indx)
 Retrive an element from the deque.
cx_deque_iterator cx_deque_erase (cx_deque *d, cx_deque_iterator indx, cx_free_func deallocate)
 Erase a deque element.
void cx_deque_insert (cx_deque *d, cx_deque_iterator indx, cxptr data)
 Insert data into a deque at a given iterator position.
cxsize cx_deque_size (const cx_deque *d)
 Get the actual number of deque elements.
void cx_deque_destroy (cx_deque *d, cx_free_func deallocate)
 Destroy a deque and all its elements.
cxbool cx_deque_empty (const cx_deque *d)
 Check whether a deque is empty.
cx_deque_iterator cx_deque_begin (const cx_deque *d)
 Get an iterator for the first deque element.
cx_deque_iterator cx_deque_end (const cx_deque *d)
 Get an iterator for the position after the last deque element.
cx_deque_iterator cx_deque_next (const cx_deque *d, cx_deque_const_iterator i)
 Get an iterator for the next deque element.
void cx_deque_sort (cx_deque *d, cx_deque_compare compare)
 Sort all elements of a deque using the given comparison function.

Detailed Description

The module implements a double-ended queue. This is a linear list for which all insertions and deletions are made at the ends of the list.

Synopsis:
   #include <cxdeque.h>

Function Documentation

cx_deque_iterator cx_deque_begin ( const cx_deque *  d)

Get an iterator for the first deque element.

Parameters:
dA deque.
Returns:
Iterator for the first element in the deque or cx_deque_end() if the deque is empty.

The function returns a handle to the first element of d. The handle cannot be used directly to access the element data, but only through the appropriate functions.

void cx_deque_destroy ( cx_deque *  d,
cx_free_func  deallocate 
)

Destroy a deque and all its elements.

Parameters:
dDeque container to destroy.
deallocateData deallocator.
Returns:
Nothing.

The function deallocates all data objects referenced by the deque using the data deallocation function deallocate and finally deallocates the deque itself.

References cx_free().

cxbool cx_deque_empty ( const cx_deque *  d)

Check whether a deque is empty.

Parameters:
dA deque.
Returns:
The function returns TRUE if the deque is empty, and FALSE otherwise.

The function tests if the deque d contains data.

cx_deque_iterator cx_deque_end ( const cx_deque *  d)

Get an iterator for the position after the last deque element.

Parameters:
dA deque.
Returns:
Iterator for the end of the deque.

The function returns an iterator for the position one past the last element of the deque deque. The handle cannot be used to directly access the element data, but only through the appropriate functions.

cx_deque_iterator cx_deque_erase ( cx_deque *  d,
cx_deque_iterator  indx,
cx_free_func  deallocate 
)

Erase a deque element.

Parameters:
dThe deque to update.
indxDeque iterator position.
deallocateData deallocator.
Returns:
The iterator for the deque position after indx.

The function removes the data object stored at position indx from the deque d. The data object itself is deallocated by calling the data deallocator deallocate.

cxptr cx_deque_get ( const cx_deque *  d,
cx_deque_const_iterator  indx 
)

Retrive an element from the deque.

Parameters:
dThe deque to query.
indxThe position of the element to get.
Returns:
A handle to the data object.

The function returns a reference to the data item stored in the deque d at the iterator position indx.

void cx_deque_insert ( cx_deque *  d,
cx_deque_iterator  indx,
cxptr  data 
)

Insert data into a deque at a given iterator position.

Parameters:
dThe deque to update.
indxList iterator position.
dataData item to insert.
Returns:
Nothing.

The function inserts the data object reference data into the deque d at the position given by the deque iterator indx.

References cx_deque_push_back().

cx_deque* cx_deque_new ( void  )

Create a new deque without any elements.

Returns:
Handle to the newly allocated deque.

The function allocates memory for the deque object and initializes it to an empty deque.

References cx_calloc().

cx_deque_iterator cx_deque_next ( const cx_deque *  d,
cx_deque_const_iterator  i 
)

Get an iterator for the next deque element.

Parameters:
dA deque.
iCurrent iterator position.
Returns:
Iterator for the next deque element.

The function returns an iterator for the next element in the deque d with respect to the current iterator position i. If the deque d is empty or i points to the deque end the function returns cx_deque_end().

void cx_deque_push_back ( cx_deque *  d,
cxptr  data 
)

Append data at the end of a deque.

Parameters:
dThe deque to update.
dataData to append.
Returns:
Nothing.

The data data is inserted into the deque d after the last element, so that it becomes the new deque tail.

It is equivalent to the statement

References cx_calloc(), and cx_free().

Referenced by cx_deque_insert().

void cx_deque_push_front ( cx_deque *  d,
cxptr  data 
)

Insert data at the beginning of a deque.

Parameters:
dThe deque to update.
dataData to add to the deque.
Returns:
Nothing.

The data data is inserted into the deque d before the first element of the deque, so that it becomes the new deque head.

It is equivalent to the statement

References cx_calloc(), and cx_free().

cxsize cx_deque_size ( const cx_deque *  d)

Get the actual number of deque elements.

Parameters:
dA deque.
Returns:
The current number of elements the deque contains, or 0 if the deque is empty.

Retrieves the number of elements currently stored in the deque d.

void cx_deque_sort ( cx_deque *  d,
cx_deque_compare  compare 
)

Sort all elements of a deque using the given comparison function.

Parameters:
dThe deque to sort.
compareFunction comparing the list elements.
Returns:
Nothing.

The input deque d is sorted using the comparison function compare to determine the order of two deque elements. The comparison function compare must return an integer less than, equal or greater than zero if the first argument passed to it is found, respectively, to be less than, match, or be greater than the second argument. This function uses the stdlib function qsort().

References cx_free(), and cx_malloc().