Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
Mac and OpenDoc are trademarks of Apple Computer, Inc.
Introduction
The OpenDoc Utilities include rudimentary C++ collection classes and iterators which may be used by part editors for such things as storing lists of display frames. Nevertheless, part editors are free to use their own collection classes.
The classes are not template-based. The OrderedCollection class implements an ordered collection of elements of type void*. The LinkedList class is a fairly low-level class used in the implementation of the OrderedCollection class, but may be used directly by subclassing class Link for new element types.
OrderedCollection
The OrderedCollection class implements a collection of elements whose order is determined externally (i.e. by the way they are inserted). The elements are not accessible by a key, but methods are provided to access the first and last element, as well as the element before and after a given element. The elements are of type ElementType, which is define as a void*. The collection is implemented as a linked list.
Constructors and Destructors
Two constructors are provided. The second one allows the client to specify a memory heap for allocating the internal memory of the collection:
OrderedCollection();
// Constructs an empty collection
OrderedCollection(ODMemoryHeapID where);
// Constructs an empty collection. Will allocate memory from the specified memory heap.
virtual ~OrderedCollection();
// Destructs the collection, deleting the links, but not the elements themselves.
Adding elements
ODVMethod void AddFirst(ElementType element);
// Adds an element to the beginning of the collection.
// Returns the element before the specified one, or kODNULL.
ODVMethod ElementType First() const;
// Returns the first element
ODVMethod ElementType Last() const;
// Returns the last element
Removing elements
ODVMethod ElementType RemoveFirst();
// Removes the first element
ODVMethod ElementType RemoveLast();
// Removes the last element
ODVMethod void RemoveAll();
// Called from the destructor. Removes all elements, deleting the links
// Does not delete the elements themselves
ODVMethod void DeleteAll();
// Removes and deletes all links and elements.
Note: Since ElementType is void*, no element destructor will be called. Clients could iterate over the elements to free element contents, and then call RemoveAll, rather than DeleteAll.
ODVMethod ODBoolean Remove(ElementType existing);
// Removes an existing element. Returns true if an element was actually removed.
// A protected method to compare elements for equality. Does a pointer comparison by default.
OrderedCollectionIterator
The OrderedCollectionIterator class provides a way to enumerate the elements of the collection in either order. If the collection is modified while iterating, a kODErrIteratorOutOfSync error will be thrown. However, it is possible to remove the current element provide this is done using the iterator's RemoveCurrent method is used.
// Construct an iterator for the specified collection.
~OrderedCollectionIterator();
// Destruct the iterator
ElementType First();
// Return the first element in the collection.
ElementType Next();
// Return the next element in the collection, or the first element if First() has never been called.
ElementType Last();
// Returns the last element in the collection.
ElementType Previous();
// Returns the previous element in the collection, or the last element if Last() was never called.
ODBoolean IsNotComplete();
// Returns kODTrue if there are additional elements to iterate over.
void RemoveCurrent();
// Remove the current element from the collection
Example 1:
OrderedCollectionIterator iter(fContentFrames);
for (ODFrame* aFrame = (ODFrame*)iter.First();
iter.IsNotComplete();
aFrame = (ODFrame*)iter.Next())
{
// Do something with aFrame
}
Example 2:
ODFrame* aFrame = kODNULL;
while ((aFrame = (ODFrame*) iter.Next()) != kODNULL)
{
// Do something with aFrame
}
LinkedList
The Link, LinkedList, and LinkedListIterator classes are used in the implementation of OrderedCollection and OrderedCollectionIterator, but they can be used directly, by subclassing Link for new element types. The client is responsible for memory management of Links - LinkedList just strings them together.
In order to do anything useful with a LinkedList, the Link class must be subclassed to add a data member for the element. See ValueLink in OrdColl.h. The Link class is not document here, since its methods are called by LinkedList.
Constructors and Destructors
LinkedList();
// Construct an empty LinkedList
~LinkedList();
// Destruct the list
Adding elements
void AddBefore(Link& existing, Link* link);
// Adds a link before a specified link
void AddAfter(Link& existing, Link* link);
// Adds a link after a specified link
void AddFirst(Link* link);
// Adds a link at the beginning.
void AddLast(Link* link);
// Adds a link at the end
void AddLast( LinkedList &list );
// Append the contents of another list, emptying the other list.
void AddLastUnique( LinkedList &list );
// Append the contents of another list, eliminating duplicates
Accessing Elements
ODBoolean Includes( const Link* ) const;
// Return kODTrue if the list contains the specified Link
Link* After(const Link& link) const;
// Return the link after the specified one
Link* Before(const Link& link) const;
// Return the link before the specified one
Link* First() const;
// Return the first link
Link* Last() const;
// Return the last link
Removing Elements
void Remove(Link&);
// Remove the specified link
void RemoveAll();
// Remove all links. Deleting links is the responsibility of the client.
void DeleteAllLinks();
// Removes and deletes all the links
Link* RemoveFirst();
// Removes the first link.
Link* RemoveLast();
// Removes the last link
Miscellaneous
ODBoolean IsEmpty( ) const;
// Return kODTrue if there are no elements in the list
ODULong Count() const;
// Return the number of elements in the list
LinkedListIterator
LinkedListIterator(LinkedList* list);
// Construct an iterator for the specified linked list
~LinkedListIterator();
// Destruct the linked list
Link* First();
// Return the first link
Link* Next();
// Return the next link, or the first link if First was never called
Link* Last();
// Return the last link
Link* Previous();
// Return the next link (going backwards), or the last link if Last() was never called
Link* Current();
// Return the current link
ODBoolean IsNotComplete();
// Returns kODTrue if there are additional elements to iterate over.
void RemoveCurrent();
// Remove the current link
Node and NodeTraverser
The Node and NodeTraverser classes were not really intended for use by developers, but you might find them interesting. Much like LinkedList, they are implementation classes which could be used to implement higher-level classes for managing hierarchical data.
DictList
The DictList class is primarily intended for use within OpenDoc. Each element in the list is a pair of void* values.
