RWTPtrDlist(3C++) RWTPtrDlist(3C++)
Name
RWTPtrDlist<T> - Rogue Wave library class
Synopsis
#include <rw/tpdlist.h>
RWTPtrDlist<T> list;
Please Note!
If you do not have the Standard C++ Library, use the interface described
here. Otherwise, use the interface to RWTPtrDlist described in the Class
Reference.
Description
This class maintains a collection of pointers to type T, implemented as a
doubly linked list. This is a pointer based list: pointers to objects
are copied in and out of the links that make up the list. Parameter T
represents the type of object to be inserted into the list, either a
class or fundamental type. The class T must have:
well-defined equality semantics (T::operator==(const T&)).
Persistence
Isomorphic
Example
In this example, a doubly-linked list of pointers to the user type Dog is
exercised. Contrast this approach with the example given under
RWTValDlist<T>.
#include <rw/tpdlist.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; }
// 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) {
Page 1
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
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() {
RWTPtrDlist<Dog> terriers;
terriers.insert(new Dog("Cairn Terrier"));
terriers.insert(new Dog("Irish Terrier"));
terriers.insert(new Dog("Schnauzer"));
Dog key1("Schnauzer");
cout << "The list "
<< (terriers.contains(&key1) ? "does " : "does not ")
<< "contain a Schnauzer0;
Dog key2("Irish Terrier");
terriers.insertAt(
terriers.index(&key2),
new Dog("Fox Terrier")
);
Dog* d;
while (!terriers.isEmpty()) {
d = terriers.get();
cout << *d << endl;
delete d;
}
return 0;
}
Program output:
The list does contain a Schnauzer
Cairn Terrier
Fox Terrier
Irish Terrier
Schnauzer
Public Constructors
RWTPtrDlist<T>();
Constructs an empty list.
Page 2
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
RWTPtrDlist<T>(const RWTPtrDlist<T>& c);
Constructs a new doubly-linked list as a shallow copy of c. After
construction, pointers will be shared between the two collections.
Public Operators
RWTPtrDlist&
operator=(const RWTPtrDlist<T>& c);
Sets self to a shallow copy of c. Afterwards, pointers will be shared
between the two collections.
T*&
operator[](size_t i);
T* const&
operator[](size_t i) const;
Returns a pointer to the ith value in the list. The first variant can be
used as an lvalue, the second cannot. The index i must be between zero
and the number of items in the collection less one, or an exception of
type RWBoundsError will be thrown.
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);
Applies the user-defined function pointed to by applyFun to every item in
the list. This function must have the prototype:
void yourFun(T* a, void* d);
This function will be called for each item in the list, with a pointer to
the item as the first argument. Client data may be passed through as
parameter d.
T*&
at(size_t i);
T* const&
Page 3
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
at(size_t i) const;
Returns a pointer to the ith value in the list. The first variant can be
used as an lvalue, the second cannot. The index i must be between zero
and the number of items in the collection less one, or an exception of
type RWBoundsError will be thrown.
void
clear();
Removes all items from the collection.
void
clearAndDestroy();
Removes all items from the collection and deletes them.
RWBoolean
contains(const T* a) const;
Returns TRUE if the list contains an object that is equal to the object
pointed to by a, FALSE otherwise. Equality is measured by the class-
defined equality operator for type T.
RWBoolean
contains(RWBoolean (*testFun)(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:
RWBoolean yourTester(T*, void* d);
This function will be called for each item in the list, with a pointer to
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.
Page 4
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
T*
find(const T* target) const;
Returns a pointer to the first object encountered which is equal to the
object pointed to by target, or nil if no such object can be found.
Equality is measured by the class-defined equality operator for type T.
T*
find(RWBoolean (*testFun)(T*, void*),void* d,) const;
Returns a pointer to the first object encountered for which the user-
defined tester function pointed to by testFun returns TRUE, or nil if no
such object can be found. The tester function must have the prototype:
RWBoolean yourTester(T*, void* d);
This function will be called for each item in the list, with a pointer to
the item as the first argument. Client data may be passed through as
parameter d.
T*&
first();
T* const&
first() const;
Returns a pointer to the first item in the list. The behavior is
undefined if the list is empty.
T*
get();
Returns a pointer to the first item in the list and removes the item.
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 pointed
to by a, or RW_NPOS if there is no such object. Equality is measured by
the class-defined equality operator for type T.
Page 5
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
size_t
index(RWBoolean (*testFun)(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(T*, void* d);
This function will be called for each item in the list, with a pointer to
the item as the first argument. Client data may be passed through as
parameter d.
void
insert(T* a);
Adds the object pointed to by a to the end of the list.
void
insertAt(size_t i, T* a);
Adds the object 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 RWBoundsError will be thrown.
RWBoolean
isEmpty() const;
Returns TRUE if there are no items in the list, FALSE otherwise.
T*&
last();
T* const&
last() const;
Returns a pointer to 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
Page 6
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
pointed to by a. Equality is measured by the class-defined equality
operator for type T.
size_t
occurrencesOf(RWBoolean (*testFun)(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(T*, void* d);
This function will be called for each item in the list, with a pointer to
the item as the first argument. Client data may be passed through as
parameter d.
void
prepend(T* a);
Adds the item pointed to by a to the beginning of the list.
T*
remove(const T* a);
Removes the first object which is equal to the object pointed to by a and
returns a pointer to it, or nil if no such object could be found.
Equality is measured by the class-defined equality operator for type T.
T*
remove(RWBoolean (*testFun)(T*, void*),void* d);
Removes the first object for which the user-defined tester function
pointed to by testFun returns TRUE and returns a pointer to it, or nil if
there is no such object. The tester function must have the prototype:
RWBoolean yourTester(T*, void* d);
This function will be called for each item in the list, with a pointer to
the item as the first argument. Client data may be passed through as
parameter d.
Page 7
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
size_t
removeAll(const T* a);
Removes all objects which are equal to the object pointed to by a.
Returns the number of objects removed. Equality is measured by the
class-defined equality operator for type T.
size_t
removeAll(RWBoolean (*testFun)(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(T*, void* d);
This function will be called for each item in the list, with a pointer to
the item as the first argument. Client data may be passed through as
parameter d.
T*
removeAt(size_t i);
Removes the object at index i and returns a pointer to it. 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.
T*
removeFirst();
Removes the first item in the list and returns a pointer to it. The
behavior is undefined if the list is empty.
T*
removeLast();
Removes the last item in the list and returns a pointer to it. The
behavior is undefined if the list is empty.
Related Global Operators
RWvostream&
operator<<(RWvostream& strm, const RWTPtrDlist<T>& coll);
RWFile&
Page 8
RWTPtrDlist(3C++) RWTPtrDlist(3C++)
operator<<(RWFile& strm, const RWTPtrDlist<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, RWTPtrDlist<T>& coll);
RWFile&
operator>>(RWFile& strm, RWTPtrDlist<T>& coll);
Restores the contents of the collection coll from the input stream strm.
RWvistream&
operator>>(RWvistream& strm, RWTPtrDlist<T>*& p);
RWFile&
operator>>(RWFile& strm, RWTPtrDlist<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
