Queue containers maintain an ordered collection of data that's retrieved in the order in which the data was entered into the queue. The queue class is implemented as a templated class, allowing the use of any data type as the queue data.
A second template parameter specifies the storage class used to implement the queue; the WCValSList, WCIsvSList and WCPtrSList classes are appropriate for this.
wcqueue.h
The WCQueue<Type,FType> class is a templated class used to create objects that maintain data in a queue.
In the description of each member function, the text Type is used to indicate the template parameter defining the type of the elements stored in the queue. The text FType is used to indicate the template parameter defining the storage class used to maintain the queue.
For example, to create a queue of integers, the WCQueue<int,WCValSList<int> > class can be used. The WCQueue<int *,WCPtrSList<int> > class creates a queue of pointers to integers. To create an intrusive queue of objects of type isv_link (derived from the WCSLink class), the WCQueue<isv_link*,WCIsvSList<isv_link> > class can be used.
The WCExcept class is a base class of the WCQueue<Type,FType> class, and provides the exceptions() member function. This member function controls the exceptions that can be thrown by the WCQueue<Type,FType> object. No exceptions are enabled unless they are set by the exceptions() member function.
Type must provide any constructors and/or operators required by the FType class.
The following member functions are declared in the public interface:
WCQueue(); WCQueue( void *(*)( size_t ), void (*)( void *, size_t ) ); ~WCQueue(); void clear(); int entries() const; Type first() const; Type get(); int insert( const Type & ); int isEmpty() const; Type last() const;
#include <wcqueue.h>
#include <iostream.h>
main() {
WCQueue<int,WCValSList<int> > queue;
queue.insert( 7 );
queue.insert( 8 );
queue.insert( 9 );
queue.insert( 10 );
cout << "\nNumber of queue entries: " <<
queue.entries() << "\n";
cout << "First entry = [" << queue.first() << "]\n";
cout << "Last entry = [" << queue.last() << "]\n";
while( !queue.isEmpty() ) {
cout << queue.get() << "\n";
};
cout.flush();
}
create a WCQueue<Type,FType> object
#include <wcqueue.h> public: WCQueue(); WCQueue( void *(*allocator)( size_t ), void (*deallocator)( void *, size_t ) );
There are two forms of the public WCQueue<Type,FType> constructor:
If FType is either the WCValSList or WCPtrSList class, then the allocator function is registered to perform all memory allocations of the queue elements, and the deallocator function to perform all freeing of the queue elements' memory.
The allocator and deallocator functions are ignored if FType is the WCIsvSList class.
These functions provide the ability to control how the allocation and freeing of memory is performed, allowing for more efficient memory handling than the general purpose global operator new() and operator delete() can provide. Memory management optimizations may potentially be made through the allocator and deallocator functions, but aren't recommended before you understand memory management, and determine it to be worthwhile.
The allocator function shall return a pointer to allocated memory of at least the size given by the argument, or zero(0) if the allocation can't be performed. Initialization of the memory returned is performed by the WCQueue<Type,FType> class.
The WCQueue<Type,FType> class calls the deallocator function only on memory allocated by the allocator function. The deallocator shall free the memory pointed to by the first argument which is of the size given by the second argument. The size passed to the deallocator function is guaranteed to be the same size passed to the allocator function when the memory was allocated.
The allocator and deallocator functions may assume that for a list object instance, the allocator is always called with the same first argument (the size of the memory to be allocated). If FType is the WCValSList<Type> class, then the WCValSListItemSize( Type ) macro returns the size of the elements that are allocated by the allocator function. Similarly, the WCPtrSListItemSize ( Type ) macro returns the size of WCPtrSList<Type> elements.
The FType storage class constructor performs the initialization of the queue.
The public WCQueue<Type,FType> constructor creates an initialized WCQueue<Type,FType> object.
WCQueue<Type,FType>::~WCQueue()
destroy a WCQueue<Type,FType> object
#include <wcqueue.h> public: virtual ~WCQueue();
The public WCQueue<Type,FType> destructor destroys the WCQueue<Type,FType> object. The FType storage class destructor performs the destruction. The call to this destructor is inserted implicitly by the compiler at the point where the WCQueue<Type,FType> object goes out of scope.
If the queue isn't empty of queue elements and the not_empty exception is enabled, the exception is thrown.
The WCQueue<Type,FType> object is destroyed.
WCExcept::not_empty, WCQueue<Type,FType>::WCQueue(), WCQueue<Type,FType>::clear()
clear the queue object
#include <wcqueue.h> public: void clear();
The clear() public member function is used to clear the queue object and set it to the state it was in just after its initial construction. The queue object isn't destroyed and re-created by this operator, so the object destructor isn't invoked. The queue elements aren't cleared by the queue class. However, the class used to maintain the queue, FType, may clear the items as part of the clear() function for that class. If it doesn't clear the items, any queue items still in the list are lost unless pointed to by some pointer object in the program code.
The clear() public member function resets the queue object to the state it was in immediately after its initial construction.
WCQueue<Type,FType>::~WCQueue(), WCQueue<Type,FType>::isEmpty()
count the elements in the queue
#include <wcqueue.h> public: int entries() const;
The entries() public member function is used to determine the number of queue elements contained in the list object.
The number of elements in the queue is returned.
WCQueue<Type,FType>::isEmpty()
return the first element in the queue
#include <wcqueue.h> public: Type first() const;
The first() public member function returns a queue element from the beginning of the queue object. The queue element isn't removed from the queue.
If the queue is empty, one of two exceptions can be thrown:
The first queue element is returned. If there are no elements in the queue, the return value is determined by the find() member function of the FType class.
WCExcept::empty_container, WCExcept::index_range, Ftype::find(), WCQueue<Type,FType>::get(), WCQueue<Type,FType>::isEmpty(), WCQueue<Type,FType>::last()
get the first element that was put into the queue
#include <wcqueue.h> public: Type get();
The get() public member function returns the queue element that was first inserted into the queue object. The queue element is removed from the queue.
If the queue is empty, one of two exceptions can be thrown:
The first element in the queue is removed and returned. If there are no elements in the queue, the return value is determined by the get() member function of the FType class.
WCExcept::empty_container, WCExcept::index_range, Ftype::get(), WCQueue<Type,FType>::first(), WCQueue<Type,FType>::insert(), WCQueue<Type,FType>::isEmpty()
add an element to the end of the queue
#include <wcqueue.h> public: int insert( const Type & );
The insert() public member function is used to insert the data into the queue. It's the last element in the queue, and the last to be retrieved.
If the insertion fails, the out_of_memory exception is thrown, if enabled. The queue remains unchanged.
The queue element is inserted at the end of the queue. A TRUE value (non-zero) is returned if the insertion is successful; FALSE (zero) is returned if it fails.
WCExcept::out_of_memory, WCQueue<Type,FType>::get()
determine whether or not the queue is empty
#include <wcqueue.h> public: int isEmpty() const;
The isEmpty() public member function is used to determine if a queue object has any queue elements in it.
A TRUE value (non-zero) is returned if the queue object doesn't have any queue elements in it; FALSE (zero) is returned if the queue contains at least one element.
WCQueue<Type,FType>::entries()
return the last element in the queue
#include <wcqueue.h> public: Type last() const;
The last() public member function returns a queue element from the end of the queue object. The queue element isn't removed from the queue.
If the queue is empty, one of two exceptions can be thrown:
The last queue element is returned. If there are no elements in the queue, the return value is determined by the find() member function of the FType class.
WCExcept::empty_container, WCExcept::index_range, Ftype::find(), WCQueue<Type,FType>::first(), WCQueue<Type,FType>::get(), WCQueue<Type,FType>::isEmpty()