RWTIsvSlist(3C++) RWTIsvSlist(3C++)
Name
RWTIsvSlist<T> - Rogue Wave library class
Synopsis
#include <rw/tislist.h>
RWTIsvSlist<T> list;
Descripton
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> 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 <rw/tislist.h>
#include <rw/rstream.h>
#include <string.h>
struct Symbol : public RWIsvSlink
{ char name[10];
Symbol( const char* cs)
{ strncpy(name, cs, sizeof(name)); name[9] = ' '; }
};
void printem(Symbol* s, void*) { cout << s->name << endl; }
main(){
RWTIsvSlist<Symbol> list;
list.insert( new Symbol("one") );
list.insert( new Symbol("two") );
Page 1
RWTIsvSlist(3C++) RWTIsvSlist(3C++)
list.prepend( new Symbol("zero") );
list.apply(printem, 0);
list.clearAndDestroy(); // Deletes the items inserted into
// the list
return 0;
}
Program Output:
zero
one
Public Constructors
two
RWTIsvSlist();
Constructs an empty list.
RWTIsvSlist(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);
Page 2
RWTIsvSlist(3C++) RWTIsvSlist(3C++)
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.
RWBoolean
contains(RWBoolean (*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:
RWBoolean 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.
RWBoolean
containsReference(const T* a) const;
Returns TRUE if the list contains an item with the address a.
Page 3
RWTIsvSlist(3C++) RWTIsvSlist(3C++)
size_t
entries() const;
Returns the number of items currently in the list.
T*
find(RWBoolean (*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:
RWBoolean 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(RWBoolean (*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:
RWBoolean yourTester(const T* item, void* d);
Page 4
RWTIsvSlist(3C++) RWTIsvSlist(3C++)
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.
RWBoolean
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(RWBoolean (*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:
RWBoolean 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.
Page 5
RWTIsvSlist(3C++) RWTIsvSlist(3C++)
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(RWBoolean (*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:
RWBoolean 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
Page 6
RWTIsvSlist(3C++) RWTIsvSlist(3C++)
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.
Page 7
