RWTIsvSlist< TL > Class Template Reference

Implements intrusive singly-linked lists. More...

#include <rw/tislist.h>

Inherits RWIsvSlist.

Public Member Functions
	RWTIsvSlist ()
	RWTIsvSlist (TL *a)
	RWTIsvSlist (RWTIsvSlist &&lst)
void	append (TL *a)
void	apply (void(*applyFun)(TL *, void *), void *d)
TL *	at (size_t i) const
void	clear ()
void	clearAndDestroy ()
bool	contains (bool(*testFun)(const TL *, void *), void *d) const
bool	containsReference (const TL *a) const
size_t	entries () const
TL *	find (bool(*testFun)(const TL *, void *), void *d) const
TL *	first () const
TL *	get ()
size_t	index (bool(*testFun)(const TL *, void *), void *d) const
void	insert (TL *a)
void	insertAt (size_t i, TL *a)
bool	isEmpty () const
TL *	last () const
size_t	occurrencesOf (bool(*testFun)(const TL *, void *), void *d) const
size_t	occurrencesOfReference (const TL *a) const
RWTIsvSlist &	operator= (RWTIsvSlist &&lst)
void	prepend (TL *a)
TL *	remove (bool(*testFun)(const TL *, void *), void *d)
TL *	removeAt (size_t i)
TL *	removeFirst ()
TL *	removeLast ()
TL *	removeReference (TL *a)
void	swap (RWTIsvSlist< TL > &lst)

Detailed Description

template<class TL>
class RWTIsvSlist< TL >

Class RWTIsvSlist implements intrusive singly-linked lists.

An intrusive list requires that all members of the list inherit from a common base class, in this case RWIsvSlink. The advantage of such a list is that memory and space requirements are minimized. The disadvantage is that the inheritance hierarchy is inflexible, possibly complicating its use with an existing class. Class RWTValSlist is offered as an alternative, non-intrusive, linked list.

This class is not CopyConstructible or CopyAssignable but is MoveConstructible and MoveAssignable.

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.

Synopsis

#include <rw/tislist.h>
RWTIsvSlist<T> list;

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

Constructor & Destructor Documentation

template<class TL>

RWTIsvSlist< TL >::RWTIsvSlist ( )

inline

Constructs an empty list.

template<class TL>

RWTIsvSlist< TL >::RWTIsvSlist ( TL *  a )

inline

Constructs a list containing the single item pointed to by a.

template<class TL>

RWTIsvSlist< TL >::RWTIsvSlist ( RWTIsvSlist< TL > &&  lst )

inline

Move constructor. The constructed RWTIsvDlist takes ownership of the data owned by lst.

Condition:

This method is available only on platforms with rvalue reference support.

Member Function Documentation

template<class TL>

void RWTIsvSlist< TL >::append ( TL *  a )

inline

Appends the item pointed to by a to the end of the list.

template<class TL>

void RWTIsvSlist< TL >::apply	(	void(*)(TL *, void *)	applyFun,
		void *	d
	)

Calls the function pointed to by applyFun to every item in the collection. The item will be passed in as argument item. Client data may be passed through as parameter d.

template<class TL>

TL* RWTIsvSlist< TL >::at ( size_t  i ) const

inline

Returns the item at index i.

Exceptions

RWBoundsErr

Thrown if the index i is not between zero and the number of items in the collection less one.

template<class TL>

void RWTIsvSlist< TL >::clear ( void  )

inline

Removes all items from the list.

template<class TL>

void RWTIsvSlist< TL >::clearAndDestroy

(

)

Removes and calls delete for each item in the list. Note that this assumes that each item was allocated off the heap.

template<class TL>

bool RWTIsvSlist< TL >::contains ( bool(*)(const TL *, void *)  testFun, void *  d  ) const

inline

Returns true if the list contains an item for which the user-defined function pointed to by testFun returns true.

For each item in the list, this function is called with the item as the first argument. Client data may be passed through as parameter d.

template<class TL>

bool RWTIsvSlist< TL >::containsReference ( const TL *  a ) const

inline

Returns true if the list contains an item with the address a.

template<class TL>

size_t RWTIsvSlist< TL >::entries ( void  ) const

inline

Returns the number of items currently in the list.

template<class TL>

TL* RWTIsvSlist< TL >::find	(	bool(*)(const TL *, void *)	testFun,
		void *	d
	)		const

Returns the first item in the list for which the user-defined function pointed to by testFun returns true. If there is no such item, then returns rwnil.

For each item in the list, this function is called with the item as the first argument. Client data may be passed through as parameter d.

template<class TL>

TL* RWTIsvSlist< TL >::first ( void  ) const

inline

Returns (but does not remove) the first item in the list, or rwnil if the list is empty.

template<class TL>

TL* RWTIsvSlist< TL >::get ( void  )

inline

Returns and removes the first item in the list, or rwnil if the list is empty.

template<class TL>

size_t RWTIsvSlist< TL >::index	(	bool(*)(const TL *, void *)	testFun,
		void *	d
	)		const

Returns the index of the first item in the list for which the user-defined function pointed to by testFun returns true. If there is no such item, then returns RW_NPOS.

For each item in the list, this function is called with the item as the first argument. Client data may be passed through as parameter d.

template<class TL>

void RWTIsvSlist< TL >::insert ( TL *  a )

inline

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.

template<class TL>

void RWTIsvSlist< TL >::insertAt ( size_t  i, TL *  a  )

inline

Inserts the item pointed to by a at the index position i.

The item cannot be inserted into more than one list, nor can it be inserted into the same list more than once.

Exceptions

RWBoundsErr

Thrown if the index i is not between zero and the number of items in the list.

template<class TL>

bool RWTIsvSlist< TL >::isEmpty ( ) const

inline

Returns true if there are no items in the list, false otherwise.

template<class TL>

TL* RWTIsvSlist< TL >::last ( void  ) const

inline

Returns (but does not remove) the last item in the list, or rwnil if the list is empty.

template<class TL>

size_t RWTIsvSlist< TL >::occurrencesOf	(	bool(*)(const TL *, void *)	testFun,
		void *	d
	)		const

Traverses the list and returns the number of times for which the user-defined function pointed to by testFun returned true.

For each item in the list, this function is called with the item as the first argument. Client data may be passed through as parameter d.

template<class TL>

size_t RWTIsvSlist< TL >::occurrencesOfReference ( const TL *  a ) const

inline

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 return only zero or one.

template<class TL>

RWTIsvSlist& RWTIsvSlist< TL >::operator= ( RWTIsvSlist< TL > &&  lst )

inline

Move assignment. Self takes ownership of the data owned by lst.

Condition:

This method is available only on platforms with rvalue reference support.

template<class TL>

void RWTIsvSlist< TL >::prepend ( TL *  a )

inline

Prepends the item pointed to by a to the beginning of the list.

template<class TL>

TL* RWTIsvSlist< TL >::remove	(	bool(*)(const TL *, void *)	testFun,
		void *	d
	)

Removes and returns the first item for which the user-defined function pointed to by testFun returns true, or rwnil if there is no such item.

For each item in the list, this function is called with the item as the first argument. Client data may be passed through as parameter d.

template<class TL>

TL* RWTIsvSlist< TL >::removeAt ( size_t  i )

inline

Removes and returns the item at index i.

Exceptions

RWBoundsErr

Thrown if the index i is not between zero and the number of items in the collection less one.

template<class TL>

TL* RWTIsvSlist< TL >::removeFirst ( )

inline

Removes and returns the first item in the list, or rwnil if there are no items in the list.

template<class TL>

TL* RWTIsvSlist< TL >::removeLast ( )

inline

Removes and returns the last item in the list, or rwnil if there are no items in the list. Note that this function is relatively slow because the enter list must be searched in order to remove of the last link in a singly-linked list.

template<class TL>

TL* RWTIsvSlist< TL >::removeReference ( TL *  a )

inline

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.

template<class TL>

void RWTIsvSlist< TL >::swap ( RWTIsvSlist< TL > &  lst )

inline

Swaps the data owned by self with the data owned by lst.