RWTIsvSlist<T>
Module: Essential Tools Module Group: Traditional Collection Classes
Does not inherit
Local Index
Members
Synopsis
#include <rw/tislist.h> RWTIsvSlist<T> list;
Description
Class RWTIsvSlist<T> is a class that implements intrusive singly-linked lists.
An intrusive list is one where the member of the list must inherit from a common base class, in this case RWIsvSlink. The advantage of such a list is that memory and space requirements are kept to a minimum. The disadvantage is that the inheritance hierarchy is inflexible, making it slightly more difficult to use with an existing class. Class RWTValSlist<T,A> is offered as an alternative, non-intrusive, linked list.
See Stroustrup (1991; Section 8.3.1) for more information about intrusive lists.
Note that when you insert an item into an intrusive list, the actual item (not a copy) is inserted. Because each item carries only one link field, the same item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.
Example
#include <iostream>
#include <rw/cstring.h>
#include <rw/tislist.h>
struct MySymbol : public RWIsvSlink
{
MySymbol (const char* s) : s_ (s) { }
const RWCString& name () const {
return s_;
}
private:
RWCString s_;
};
void printem(MySymbol* s, void*)
{
std::cout << s->name () << std::endl;
}
int main ()
{
RWTIsvSlist<MySymbol> list;
list.insert ( new MySymbol("one") );
list.insert ( new MySymbol("two") );
list.prepend( new MySymbol("zero") );
list.apply (printem, 0);
list.clearAndDestroy(); // Deletes the items inserted into the list
return 0;
}
Program Output:
zero one two
Public Constructors
RWTIsvSlist<T>();
Constructs an empty list.
RWTIsvSlist<T>(T* a);
Constructs a list with the single item pointed to by a in it.
Public Member Functions
void append(T* a);
Appends the item pointed to by a to the end of the list.
void apply(void (*applyFun)(T*, void*), void* d);
Calls the function pointed to by applyFun to every item in the collection. This must have the prototype:
void yourFun(T* item, void* d);
The item will be passed in as argument item. Client data may be passed through as parameter d.
T* at(size_t i) const;
Returns the item at index i. The index i must be between zero and the number of items in the collection less one, or an exception of type TOOL_INDEX will be thrown.
void clear();
Removes all items from the list.
void clearAndDestroy();
Removes and calls delete for each item in the list. Note that this assumes that each item was allocated off the heap.
bool
contains(bool (*testFun)(const T*, void*), void* d)
const;
Returns true if the list contains an item for which the user-defined "tester" function pointed to by testFun returns true. The tester function must have the prototype:
bool yourTester(const T* item, void* d);
For each item in the list this function will be called with the item as the first argument. Client data may be passed through as parameter d.
bool containsReference(const T* a) const;
Returns true if the list contains an item with the address a.
size_t entries() const;
Returns the number of items currently in the list.
T* find(bool (*testFun)(const T*, void*),void* d) const;
Returns the first item in the list for which the user-defined "tester" function pointed to by testFun returns true. If there is no such item, then returns nil. The tester function must have the prototype:
bool yourTester(const T* item, void* d);
For each item in the list this function will be called with the item as the first argument. Client data may be passed through as parameter d.
T* first() const;
Returns (but does not remove) the first item in the list, or nil if the list is empty.
T* get();
Returns and removes the first item in the list, or nil if the list is empty.
size_t index(bool (*testFun)(const T*, void*),void* d) const;
Returns the index of the first item in the list for which the user-defined "tester" function pointed to by testFun returns true. If there is no such item, then returns RW_NPOS. The tester function must have the prototype:
bool yourTester(const T* item, void* d);
For each item in the list this function will be called with the item as the first argument. Client data may be passed through as parameter d.
void insert(T* a);
Appends the item pointed to by a to the end of the list. This item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.
void insertAt(size_t i, T* a);
Insert the item pointed to by a at the index position i. This position must be between zero and the number of items in the list, or an exception of type TOOL_INDEX will be thrown. The item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.
bool isEmpty() const;
Returns true if there are no items in the list, false otherwise.
T* last() const;
Returns (but does not remove) the last item in the list, or nil if the list is empty.
size_t
occurrencesOf(bool (*testFun)(const T*, void*),
void* d) const;
Traverses the list and returns the number of times for which the user-defined "tester" function pointed to by testFun returned true. The tester function must have the prototype:
bool yourTester(const T* item, void* d);
For each item in the list this function will be called with the item as the first argument. Client data may be passed through as parameter d.
size_t occurrencesOfReference(const T* a) const;
Returns the number of times which the item pointed to by a occurs in the list. Because items cannot be inserted into a list more than once, this function can only return zero or one.
void prepend(T* a);
Prepends the item pointed to by a to the beginning of the list.
T* remove(bool (*testFun)(const T*, void*),void* d);
Removes and returns the first item for which the user-defined tester function pointed to by testFun returns true, or nil if there is no such item. The tester function must have the prototype:
bool yourTester(const T* item, void* d);
For each item in the list this function will be called with the item as the first argument. Client data may be passed through as parameter d.
T* removeAt(size_t i);
Removes and returns the item at index i. The index i must be between zero and the number of items in the collection less one or an exception of type TOOL_INDEX will be thrown.
T* removeFirst();
Removes and returns the first item in the list, or nil if there are no items in the list.
T* removeLast();
Removes and returns the last item in the list, or nil if there are no items in the list. This function is relatively slow because removing the last link in a singly-linked list necessitates access to the next-to-the-last link, requiring the whole list to be searched.
T* removeReference(T* a);
Removes and returns the link with address a. The link must be in the list. In a singly-linked list this function is not very efficient.
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.