RWTIsvSlist<T>

Click on the banner to return to the Class Reference home page.

RWTIsvSlist<T>

Synopsis

Descripton

Example

Public Constructors

Public Member Functions

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] = '\0'; }
};

void printem(Symbol* s, void*) { cout << s->name << endl; }
main(){

  RWTIsvSlist<Symbol> list;
  list.insert( new Symbol("one") );
  list.insert( new Symbol("two") );
  list.prepend( new Symbol("zero") );

  list.apply(printem, 0);

  list.clearAndDestroy();  // Deletes the items inserted into 
                           // the list
  return 0;
}

Program Output:

zero
one
two

Public Constructors

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);

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.

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);

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.

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 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.