From 4550c7d3f5a898a3daf15ef0b28e6c9c60128663 Mon Sep 17 00:00:00 2001 From: mph2 Date: Mon, 18 Mar 2002 16:12:24 +0000 Subject: updating docs --- ace/Containers_T.h | 38 +++++++++++++++++++++++++++++++++++++- ace/Unbounded_Queue.h | 40 +++++++++++++++++++++++++++++++++++++++- ace/Unbounded_Set.h | 35 ++++++++++++++++++++++++++++++++++- 3 files changed, 110 insertions(+), 3 deletions(-) diff --git a/ace/Containers_T.h b/ace/Containers_T.h index 04352e9b7c9..088d9776cac 100644 --- a/ace/Containers_T.h +++ b/ace/Containers_T.h @@ -289,6 +289,8 @@ private: }; +/* MATT UPDATE */ + /** * @class ACE_Unbounded_Stack * @@ -298,7 +300,8 @@ private: * If you use the or methods you should keep * in mind that duplicate entries aren't allowed. In general, * therefore, you should avoid the use of these methods since - * they aren't really part of the ADT stack. + * they aren't really part of the ADT stack. The stack is implemented + * as a doubly linked list. */ template class ACE_Unbounded_Stack @@ -312,19 +315,34 @@ public: // = Initialization, assignment, and termination methods. /// Initialize a new stack so that it is empty. Use user defined /// allocation strategy if specified. + /** + * Initialize an empty stack using the user specified allocation strategy + * if provided. + */ ACE_Unbounded_Stack (ACE_Allocator *alloc = 0); /// The copy constructor (performs initialization). + /** + * Initialize this stack to be an exact copy of . + */ ACE_Unbounded_Stack (const ACE_Unbounded_Stack &s); /// Assignment operator (performs assignment). + /** + * Perform a deep copy of the rhs into the lhs. + */ void operator= (const ACE_Unbounded_Stack &s); /// Perform actions needed when stack goes out of scope. + /** + * Destroy the underlying list for the stack. + */ ~ACE_Unbounded_Stack (void); // = Classic Stack operations. + + ///Push an element onto the top of stack. /** * Place a new item on top of the stack. Returns -1 if the stack * is already full, 0 if the stack is not already full, and -1 if @@ -332,6 +350,7 @@ public: */ int push (const T &new_item); + ///Pop the top element of the stack. /** * Remove and return the top stack item. Returns -1 if the stack is * already empty, 0 if the stack is not already empty, and -1 if @@ -339,6 +358,7 @@ public: */ int pop (T &item); + ///Examine the top of the stack. /** * Return top stack item without removing it. Returns -1 if the * stack is already empty, 0 if the stack is not already empty, and @@ -349,13 +369,20 @@ public: // = Check boundary conditions. /// Returns 1 if the container is empty, otherwise returns 0. + /** + * Constant time check to see if the stack is empty. + */ int is_empty (void) const; /// Returns 1 if the container is full, otherwise returns 0. + /** + * Always resturns 0 since the stack is unbounded. + */ int is_full (void) const; // = Auxiliary methods (not strictly part of the Stack ADT). + ///Linear Insert of an item. /** * Insert into the Stack at the head (but doesn't allow * duplicates). Returns -1 if failures occur, 1 if item is already @@ -365,12 +392,21 @@ public: /// Remove from the Stack. Returns 0 if it removes the item, /// -1 if it can't find the item, and -1 if a failure occurs. + /** + * Linear remove operation. + */ int remove (const T &item); /// Finds if occurs the set. Returns 0 if finds, else -1. + /** + * Linear find operation. + */ int find (const T &item) const; /// The number of items in the stack. + /** + * Constant time access to the current stack size. + */ size_t size (void) const; /// Dump the state of an object. diff --git a/ace/Unbounded_Queue.h b/ace/Unbounded_Queue.h index e245ecc4738..52b378e43fc 100644 --- a/ace/Unbounded_Queue.h +++ b/ace/Unbounded_Queue.h @@ -137,49 +137,84 @@ public: // = Initialization and termination methods. /// construction. Use user specified allocation strategy /// if specified. + /** + * Initialize an empty queue using the strategy provided. + */ ACE_Unbounded_Queue (ACE_Allocator *alloc = 0); /// Copy constructor. + /** + * Initialize the queue to be a copy of the provided queue. + */ ACE_Unbounded_Queue (const ACE_Unbounded_Queue &); /// Assignment operator. + /** + * Perform a deep copy of rhs. + */ void operator= (const ACE_Unbounded_Queue &); /// Destructor. + /** + * Clean up the memory for the queue. + */ ~ACE_Unbounded_Queue (void); // = Check boundary conditions. /// Returns 1 if the container is empty, otherwise returns 0. + /** + * Constant time check to see if the queue is empty. + */ int is_empty (void) const; - /// Returns 1 if the container is full, otherwise returns 0. + /// Returns 0. + /** + * The queue cannot be full, so it always returns 0. + */ int is_full (void) const; // = Classic queue operations. /// Adds to the tail of the queue. Returns 0 on success, /// -1 on failure. + /** + * Insert an item at the end of the queue. + */ int enqueue_tail (const T &new_item); /// Adds to the head of the queue. Returns 0 on success, /// -1 on failure. + /** + * Insert an item at the head of the queue. + */ int enqueue_head (const T &new_item); /// Removes and returns the first on the queue. Returns 0 on /// success, -1 if the queue was empty. + /** + * Remove an item from the head of the queue. + */ int dequeue_head (T &item); // = Additional utility methods. /// Reset the to be empty and release all its /// dynamically allocated resources. + /** + * Delete the queue nodes. + */ void reset (void); /// Get the th element in the set. Returns -1 if the element /// isn't in the range {0.. - 1}, else 0. + /** + * Find the item in the queue between 0 and the provided index of the + * queue. + */ int get (T *&item, size_t slot = 0) const; + ///Set the th element of the queue to . /** * Set the th element in the set. Will pad out the set with * empty nodes if is beyond the range {0.. - 1}. @@ -189,6 +224,9 @@ public: int set (const T &item, size_t slot); /// The number of items in the queue. + /** + * Return the size of the queue. + */ size_t size (void) const; /// Dump the state of an object. diff --git a/ace/Unbounded_Set.h b/ace/Unbounded_Set.h index 71eb5bb300d..a5595214370 100644 --- a/ace/Unbounded_Set.h +++ b/ace/Unbounded_Set.h @@ -165,27 +165,47 @@ public: // = Initialization and termination methods. /// Constructor. Use user specified allocation strategy /// if specified. + /** + * Initialize an empty set using the allocation strategy of the user if + * provided. + */ ACE_Unbounded_Set (ACE_Allocator *alloc = 0); /// Copy constructor. + /** + * Initialize this set to be an exact copy of the set provided. + */ ACE_Unbounded_Set (const ACE_Unbounded_Set &); /// Assignment operator. + /** + * Perform a deep copy of the rhs into the lhs. + */ void operator= (const ACE_Unbounded_Set &); /// Destructor. + /** + * Destroy the nodes of the set. + */ ~ACE_Unbounded_Set (void); // = Check boundary conditions. /// Returns 1 if the container is empty, otherwise returns 0. + /** + * Constant time is_empty check. + */ int is_empty (void) const; - /// Returns 1 if the container is full, otherwise returns 0. + /// Returns 0. + /** + * Always returns 0 since the set can never fill up. + */ int is_full (void) const; // = Classic unordered set operations. + ///Linear insertion of an item. /** * Insert into the set (doesn't allow duplicates). * Returns -1 if failures occur, 1 if item is already present, else @@ -195,8 +215,12 @@ public: /// Insert at the tail of the set (doesn't check for /// duplicates). + /** + * Constant time insert at the end of the set. + */ int insert_tail (const T &item); + ///Linear remove operation. /** * Remove first occurrence of from the set. Returns 0 if * it removes the item, -1 if it can't find the item, and -1 if a @@ -206,15 +230,24 @@ public: /// Finds if occurs in the set. Returns 0 if find succeeds, /// else -1. + /** + * Performs a linear find operation. + */ int find (const T &item) const; /// Size of the set. + /** + * Access the size of the set. + */ size_t size (void) const; /// Dump the state of an object. void dump (void) const; /// Reset the to be empty. + /** + * Delete the nodes of the set. + */ void reset (void); // = STL-styled unidirectional iterator factory. -- cgit v1.2.1