RWTValDlist(3C++) RWTValDlist(3C++)
Name
RWTValDlist<T> - Rogue Wave library class
Synopsis
#include <rw/tvdlist.h>
RWTValDlist<T> list;
Please Note!
If you do not have the Standard C++ Library, use the interface described
here. Otherwise, use the interface to RWTValDlist described in the Class
Reference.
Description
This class maintains a collection of values, implemented as a doubly
linked list. This is a value based list: objects are copied in and out
of the links that make up the list. Unlike intrusive lists (see class
RWTIsvDlist<T>), the objects need not inherit from a link class.
However, this makes the class slightly less efficient than the intrusive
lists because of the need to allocate a new link off the heap with every
insertion and to make a copy of the object in the newly allocated link.
Parameter T represents the type of object to be inserted into the list,
either a class or fundamental type. The class T must have:
A default constructor;
well-defined copy semantics (T::T(const T&) or equivalent);
well-defined assignment semantics (T::operator=(const T&) or
equivalent);
well-defined equality semantics (T::operator==(const T&)).
Persistence
Isomorphic
Example
In this example, a doubly-linked list of user type Dog is exercised.
#include <rw/tvdlist.h>
#include <rw/rstream.h>
#include <string.h>
class Dog {
char* name;
public:
Dog( const char* c = "") {
name = new char[strlen(c)+1];
strcpy(name, c); }
~Dog() { delete name; }
Page 1
RWTValDlist(3C++) RWTValDlist(3C++)
// Define a copy constructor:
Dog(const Dog& dog) {
name = new char[strlen(dog.name)+1];
strcpy(name, dog.name); }
// Define an assignment operator:
void operator=(const Dog& dog) {
if (this!=&dog) {
delete name;
name = new char[strlen(dog.name)+1];
strcpy(name, dog.name);
}
}
// Define an equality test operator:
int operator==(const Dog& dog) const {
return strcmp(name, dog.name)==0;
}
friend ostream& operator<<(ostream& str, const Dog& dog){
str << dog.name;
return str;}
};
main() {
RWTValDlist<Dog> terriers;
terriers.insert("Cairn Terrier"); // automatic type conversion
terriers.insert("Irish Terrier");
terriers.insert("Schnauzer");
cout << "The list "
<< (terriers.contains("Schnauzer") ? "does ":"does not ")
<< "contain a Schnauzer0;
terriers.insertAt(
terriers.index("Irish Terrier"),
"Fox Terrier"
);
while (!terriers.isEmpty())
cout << terriers.get() << endl;
return 0;
}
Program output:
The list does contain a Schnauzer
Cairn Terrier
Fox Terrier
Irish Terrier
Schnauzer
Page 2
RWTValDlist(3C++) RWTValDlist(3C++)
Public Constructors
RWTValDlist<T>();
Construct an empty list.
RWTValDlist<T>(const RWTValDlist<T>& list);
Construct a copy of the list list. Depending on the nature of the copy
constructor of T, this could be relatively expensive because every item
in the list must be copied.
Public Operators
RWTValDlist&
operator=(const RWTValDlist<T>& list);
Sets self to a copy of the list list. Depending on the nature of the
copy constructor of T, this could be relatively expensive because every
item in the list must be copied.
T&
operator[](size_t i);
Returns a reference to the item at index i. The results can be used as
an lvalue. An exception of type RWBoundsError will be thrown if i is not
a valid index. Valid indices are from zero to the number of items in the
list less one.
const T&
operator[](size_t i) const;
Returns a copy of the item at index i. The results cannot be used as an
lvalue. An exception of type RWBoundsError will be thrown if i is not a
valid index. Valid indices are from zero to the number of items in the
list less one.
Public Member Functions
void
append(const T& a);
Adds the item a to the end of the list.
void
apply(void (*applyFun)(T&, void*), void* d);
Applies the user-defined function pointed to by applyFun to every item in
Page 3
RWTValDlist(3C++) RWTValDlist(3C++)
the list. This function must have prototype:
void yourFun(T& a, void* d);
Client data may be passed through as parameter d.
T&
at(size_t i);
Returns a reference to the item at index i. The results can be used as
an lvalue. An exception of type RWBoundsError will be thrown if i is not
a valid index. Valid indices are from zero to the number of items in the
list less one.
const T&
at(size_t i) const;
Returns a copy of the item at index i. The results cannot be used as an
lvalue. An exception of type RWBoundsError will be thrown if i is not a
valid index. Valid indices are from zero to the number of items in the
list less one.
void
clear();
Removes all items from the list. Their destructors (if any) will be
called.
RWBoolean
contains(const T& a) const;
Returns TRUE if the list contains an object that is equal to the object
a. Returns FALSE otherwise. Equality is measured by the class-defined
equality operator.
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 . Returns FALSE
otherwise. The tester function must have the prototype:
Page 4
RWTValDlist(3C++) RWTValDlist(3C++)
RWBoolean yourTester(const T&, 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
entries() const;
Returns the number of items that are currently in the collection.
RWBoolean
find(const T& target, T& k) const;
Returns TRUE if the list contains an object that is equal to the object
target and puts a copy of the matching object into k. Returns FALSE
otherwise and does not touch k. Equality is measured by the class-
defined equality operator. If you do not need a copy of the found
object, use contains() instead.
RWBoolean
find(RWBoolean (*testFun)(const T&, void*), void* d,T& k)
const;
Returns TRUE if the list contains an object for which the user-defined
tester function pointed to by testFun returns TRUE and puts a copy of the
matching object into k. Returns FALSE otherwise and does not touch k.
The tester function must have the prototype:
RWBoolean yourTester(const T&, 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.
If you do not need a copy of the found object, use contains() instead.
T&
first();
const T&
first() const;
Returns (but does not remove) the first item in the list. The behavior
Page 5
RWTValDlist(3C++) RWTValDlist(3C++)
is undefined if the list is empty.
T
get();
Returns and removes the first item in the list. The behavior is
undefined if the list is empty.
size_t
index(const T& a);
Returns the index of the first object that is equal to the object a, or
RW_NPOS if there is no such object. Equality is measured by the class-
defined equality operator.
size_t
index(RWBoolean (*testFun)(const T&, void*), void* d) const;
Returns the index of the first object for which the user-defined tester
function pointed to by testFun returns TRUE, or RW_NPOS if there is no
such object. The tester function must have the prototype:
RWBoolean yourTester(const T&, 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(const T& a);
Adds the item a to the end of the list.
void
insertAt(size_t i, const T& a);
Insert the item 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
RWBoundsError will be thrown.
RWBoolean
isEmpty() const;
Page 6
RWTValDlist(3C++) RWTValDlist(3C++)
Returns TRUE if there are no items in the list, FALSE otherwise.
T&
last();
const T&
last() const;
Returns (but does not remove) the last item in the list. The behavior is
undefined if the list is empty.
size_t
occurrencesOf(const T& a) const;
Returns the number of objects in the list that are equal to the object a.
Equality is measured by the class-defined equality operator.
size_t
occurrencesOf(RWBoolean (*testFun)(const T&, void*),
void* d) const;
Returns the number of objects in the list for which the user-defined
"tester" function pointed to by testFun returns TRUE . The tester
function must have the prototype:
RWBoolean yourTester(const T&, 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
prepend(const T& a);
Adds the item a to the beginning of the list.
RWBoolean
remove(const T& a);
Removes the first object which is equal to the object a and returns TRUE.
Returns FALSE if there is no such object. Equality is measured by the
class-defined equality operator.
Page 7
RWTValDlist(3C++) RWTValDlist(3C++)
RWBoolean
remove(RWBoolean (*testFun)(const T&, void*),void* d);
Removes the first object for which the user-defined tester function
pointed to by testFun returns TRUE, and returns TRUE. Returns FALSE if
there is no such object. The tester function must have the prototype:
RWBoolean yourTester(const T&, 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
removeAll(const T& a);
Removes all objects which are equal to the object a. Returns the number
of objects removed. Equality is measured by the class-defined equality
operator.
size_t
removeAll(RWBoolean (*testFun)(const T&, void*),void* d);
Removes all objects for which the user-defined tester function pointed to
by testFun returns TRUE. Returns the number of objects removed. The
tester function must have the prototype:
RWBoolean yourTester(const T&, 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 object at index i. An exception of type
RWBoundsError will be thrown if i is not a valid index. Valid indices
are from zero to the number of items in the list less one.
Page 8
RWTValDlist(3C++) RWTValDlist(3C++)
T
removeFirst();
Removes and returns the first item in the list. The behavior is
undefined if the list is empty.
T
removeLast();
Removes and returns the last item in the list. The behavior is undefined
if the list is empty.
Related Global Operators
RWvostream&
operator<<(RWvostream& strm, const RWTValDlist<T>& coll);
RWFile&
operator<<(RWFile& strm, const RWTValDlist<T>& coll);
Saves the collection coll onto the output stream strm, or a reference to
it if it has already been saved.
RWvistream&
operator>>(RWvistream& strm, RWTValDlist<T>& coll);
RWFile&
operator>>(RWFile& strm, RWTValDlist<T>& coll);
Restores the contents of the collection coll from the input stream strm.
RWvistream&
operator>>(RWvistream& strm, RWTValDlist<T>*& p);
RWFile&
operator>>(RWFile& strm, RWTValDlist<T>*& p);
Looks at the next object on the input stream strm and either creates a
new collection off the heap and sets p to point to it, or sets p to point
to a previously read instance. If a collection is created off the heap,
then you are responsible for deleting it.
Page 9
