summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ace/Containers_T.h38
-rw-r--r--ace/Unbounded_Queue.h40
-rw-r--r--ace/Unbounded_Set.h35
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 <insert> or <remove> 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 T>
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 <s>.
+ */
ACE_Unbounded_Stack (const ACE_Unbounded_Stack<T> &s);
/// Assignment operator (performs assignment).
+ /**
+ * Perform a deep copy of the rhs into the lhs.
+ */
void operator= (const ACE_Unbounded_Stack<T> &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 <new_item> 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 <item> 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 <item> 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<T> &);
/// Assignment operator.
+ /**
+ * Perform a deep copy of rhs.
+ */
void operator= (const ACE_Unbounded_Queue<T> &);
/// 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 <new_item> 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 <new_item> 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 <item> 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 <ACE_Unbounded_Queue> to be empty and release all its
/// dynamically allocated resources.
+ /**
+ * Delete the queue nodes.
+ */
void reset (void);
/// Get the <slot>th element in the set. Returns -1 if the element
/// isn't in the range {0..<size> - 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 <slot>th element of the queue to <item>.
/**
* Set the <slot>th element in the set. Will pad out the set with
* empty nodes if <slot> is beyond the range {0..<size> - 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<T> &);
/// Assignment operator.
+ /**
+ * Perform a deep copy of the rhs into the lhs.
+ */
void operator= (const ACE_Unbounded_Set<T> &);
/// 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 <new_item> 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 <item> 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 <item> 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 <item> 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 <ACE_Unbounded_Set> to be empty.
+ /**
+ * Delete the nodes of the set.
+ */
void reset (void);
// = STL-styled unidirectional iterator factory.