List() : head(0), tail(0), length(0)

List(const List<t> &other)

List(const List<t> *other)

List<t> &operator=(const List<t> &other)

List<t> &operator=(const List<t> *other)

~List()

uInt len() const

virtual void added(Link<t> *, Link<t> *)

virtual void removed(Link<t> *, Link<t> *, Link<t> *)

Description

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Synopsis

This group of classes, List and iterators, was designed to allow multiple iterators to manipulate a list at the same time. However, if only one iterator is required the simple example below shows how a simple list can be created and used without complication. The more complete example below demonstrates all of the functionality of the List classes.

Example

    #include <casa/Containers/List.h>
    #include <casa/Containers/ListIO.h>
    
    main() {
                                                 // List, conceptual
                                                 //       cursor = "|"
      ListIter<int> list(new List<int>(),True);  //  |
      list.addRight(12);                         //  | 12
      list.addRight(2);                          //  | 2 12
      list.addRight(89);                         //  | 89 2 12
      list++;                                    //  89 | 2 12
      list.addRight(10);                         //  89 | 10 2 12
      list++;                                    //  89 10 | 2 12
      list.addRight(8);                          //  89 10 | 8 2 12
      list--;                                    //  89 | 10 8 2 12
      list.pos(0);                               //  | 89 10 8 2 12
      list.pos(5);                               //  89 10 8 2 12 |
      list.pos(4);                               //  89 10 8 2 | 12
      list.step(3);                              //  89 | 10 8 2 12
      list.step();                               //  89 10 | 8 2 12
      list.step(-4);                             //  89 10 8 2 | 12
      list.removeRight();                        //  89 10 8 2 |
      cout << list << endl;
    // iterate(list);
      return 0;
    }
    

          len=4 pos=4 89 10 8 2
     

Member Description

List() : head(0), tail(0), length(0)

Creates an empty list.

List(const List<t> &other)
List(const List<t> *other)
List<t> &operator=(const List<t> &other)
List<t> &operator=(const List<t> *other)

Copy Semantics

~List()

Destructs the list.

uInt len() const

Returns the length of the list.

enum

List version

virtual void added(Link<t> *, Link<t> *)
virtual void removed(Link<t> *, Link<t> *, Link<t> *)

Updates the extreme pointers, head or tail under the appropriate conditions

template<class t> class ConstListIter : public NoticeTarget

Interface

ConstListIter(const List<t> *st)

ConstListIter(const List<t> &st) : NoticeTarget((NoticeSource &)st), cur(st.head), prev(0), curPos(0), container_((List<t> *) (&st))

ConstListIter(const ConstListIter<t> &other) : NoticeTarget((NoticeTarget &)other), cur(other.cur), prev(other.prev), curPos(other.curPos), container_(other.container_)

ConstListIter(const ConstListIter<t> *other)

ConstListIter() : NoticeTarget(),cur(0), prev(0), curPos(0), container_(0)

~ConstListIter()

void notify(const Notice &)

Bool atStart() const

Bool atEnd() const

void operator++()

inline void operator++(int)

void operator--()

void operator--(int)

virtual uInt pos(uInt)

uInt pos() const

uInt len() const

inline uInt step(Int offset)

inline uInt step()

const t &getRight() const

virtual ConstListIter<t> &operator=(const List<t> &other)

virtual ConstListIter<t> &operator=(const List<t> *other)

virtual ConstListIter<t> &operator=(const ConstListIter<t> &other)

virtual ConstListIter<t> &operator=(const ConstListIter<t> *other)

void toStart()

void toEnd()

const List<t> *container() const

Description

Synopsis

All of the operations take place to the right of a conceptual cursor. The cursor starts out before the first element of the list and can be incremented past the last element of the list. Going further than the end of the list results in an exception.

Example

    void iterate(ListIter<int> &list) {
                                                // List, conceptual
                                                //       cursor = "|"
      ConstListIter<int> li = list;             //  89 10 8 2 |
      li--;                                     //  89 10 8 | 2
      cout << li.getRight() << " ";             //  89 10 8 | 2
      li--;                                     //  89 10 | 8 2
      li.pos(0);                                //  | 89 10 8 2
      li.pos(3);                                //  89 10 8 | 2
      li.pos(1);                                //  89 | 10 8 2
      li.step();                                //  89 10 | 8 2
      li.pos(0);                                //  | 89 10 8 2
      li.step(-3);                              //  89 10 | 8 2
      cout << li.getRight() << endl;            //  89 10 | 8 2
      cout << li << endl;                       //  89 10 | 8 2
    }
    

         2 8
         len=4 pos=2 89 10 8 2
 

As shown above:

pos()

allows for arbitrary positioning of the cursor

step(), operator++(), and operator--()

allow for relative positioning

getRight()

fetches the next element in the list.

atStart(), atEnd(), and pos()

allow querying the position of the cursor

len()

returns the number of elements in the list.

This class uses the Notice classes to implement "dynamic" cursors so that multiple cursors are updated as elements are added and removed from the list.

Member Description

ConstListIter(const List<t> *st)
ConstListIter(const List<t> &st) : NoticeTarget((NoticeSource &)st), cur(st.head), prev(0), curPos(0), container_((List<t> *) (&st))

This constructor creates a "ConstListIter" which tracks the "List" parameter.

ConstListIter(const ConstListIter<t> &other) : NoticeTarget((NoticeTarget &)other), cur(other.cur), prev(other.prev), curPos(other.curPos), container_(other.container_)
ConstListIter(const ConstListIter<t> *other)

This constructor creates a "ConstListIter" which tracks the same list tracked by the "ConstListIter" parameter.

ConstListIter() : NoticeTarget(),cur(0), prev(0), curPos(0), container_(0)

This is the default constructor. It allows one to create an initially invalid empty ConstListIter. The instantiated class will accept assignment and thus become valid later.

~ConstListIter()

Destructor doesn\'t do anything special because all of the "real" information is in the "List".

void notify(const Notice &)

This function is the hook through which iterators are notified of important changes to the underlying list. For advanced users.

Bool atStart() const
Bool atEnd() const

This functions allows one to checked if the cursor is at an extreme list position. "atStart()" checks to see if the cursor is at the beginning of the list, and "atEnd()" checks to see if the cursor is at the end of the list.

void operator++()
inline void operator++(int)

This function is used to step the cursor forward through the list.

void operator--()
void operator--(int)

This function allow for stepping the cursor toward the front of the list.

virtual uInt pos(uInt)
uInt pos() const

"pos()" without arguments returns the current postion of the cursor. "pos()" with an unsigned integer parameter moves the cursor to an absolute position.

uInt len() const

This function returns the number of elements in the list.

inline uInt step(Int offset)
inline uInt step()

"step()" with no parameters advances the cursor forward one element. "step()" with a signed integer parameter moves the cursor (forward or backward) by a relative offset indicated by the parameter.

const t &getRight() const

Returns the element to the right of the cursor.

virtual ConstListIter<t> &operator=(const List<t> &other)
virtual ConstListIter<t> &operator=(const List<t> *other)

This assignment operator substitutes the "List" tracked by this iterator to the "List" passed as an argument.

virtual ConstListIter<t> &operator=(const ConstListIter<t> &other)
virtual ConstListIter<t> &operator=(const ConstListIter<t> *other)

This assignment operator substitutes the "List" tracked by this iterator to the "List" tracked by the passed "ConstListIter" argument.

void toStart()

This function moves the cursor to the beginning of the list.

void toEnd()

This function moves the cursor to the end of the list.

const List<t> *container() const

Get the container over which we are iterating, could be null...

template<class t> class ListIter : virtual public ConstListIter<t>

Interface

ListIter(List<t> *st, Bool OWN = False) : ConstListIter<t>(st), own(OWN)

ListIter(List<t> &st)

ListIter(const ListIter<t> &other)

ListIter(const ListIter<t> *other) : ConstListIter<t>(other), own(False)

ListIter() : ConstListIter<t>()

void addRight(t e)

void removeRight()

virtual void swapRight(ListIter<t> &)

t &getRight()

const t &getRight() const

virtual ListIter<t> &assign(List<t> *other,Bool OWN = False)

virtual ListIter<t> &operator=(List<t> &other)

virtual ListIter<t> &operator=(List<t> *other)

virtual ListIter<t> &operator=(const ListIter<t> &other)

virtual ListIter<t> &operator=(const ListIter<t> *other)

~ListIter()

virtual Link<t> *newLink(t &e, Link<t> *p=0, Link<t> *n=0)

ConstListIter<t> &operator=(const List<t> &)

ConstListIter<t> &operator=(const List<t> *)

ConstListIter<t> &operator=(const ConstListIter<t> &)

ConstListIter<t> &operator=(const ConstListIter<t> *)

Description

The List class above only provides for the list framework. This is one of two classes which allow list iteration, insertion, and removal. This class can be used to modify a list. Unlike ConstListIter, this class can insert and remove elements from a list as well as look at or observe a list. ConstListIter should be used whenever the list is not modified.

All of the operations take place to the right of a conceptual cursor. The cursor starts out before the first element of the list and can be incremented past the last element of the list. Going further than the end of the list results in an exception. All additions and deletions occur to the right of this conceptual cursor. In addition, this class uses the Notice class to ensure that multiple iterators which are observing the same list are updated as the list changes. This is important when multiple iterators are used.

Example

    #include <casa/Containers/List.h>
    #include <casa/Containers/ListIO.h>
    
    main() {
                                                // The conceptual cursors are:
                                                //   |  for one
                                                //   ^  for two
                                                //   _  for three
        ListIter<int> one(new List<int>,True);
        ListIter<int> three, two = one;
        one.addRight(12);                       //  |^ 12
        one.addRight(2);                        //  |^ 2 12
        one.addRight(89);                       //  |^ 89 2 12
        cout << one.getRight() << " " 
             << two.getRight() << endl;
        two.addRight(21);                       //  |^ 21 89 2 12
        cout << one.getRight() << " " 
             << two.getRight() << endl;
        one++; two++; two++;                    //   21 | 89 ^ 2 12
        three = one;                            //   21 |_ 89 ^ 2 12
        one.removeRight();                      //   21 |^_ 2 12
        cout << one.getRight() << " " 
             << two.getRight() << " "
             << three.getRight() << endl;
        three.addRight(17);                     //   21 |^_ 17 2 12
    
        cout << one.getRight() << " " 
             << two.getRight() << " "
             << three.getRight() << endl;
    
        one.toEnd();                            //   21 ^_ 17 2 12 |
        one.addRight(18);                       //   21 ^_ 17 2 12 | 18
        two.pos(3);                             //   21 _ 17 2 ^ 12 | 18
        three--;                                //   _ 21 17 2 ^ 12 | 18
        two.step();                             //   _ 21 17 2 12 ^| 18
        one.step(4);                            //   _ 21 17 | 2 12 ^ 18
        cout << "one:   " << one << endl;
        cout << "two:   " << two << endl;
        cout << "three: " << three << endl;
    
        return 0;
    }
    

           89 89
           21 21
           2 2 2
           17 2 17
           one:   len=5 pos=2 21 17 2 12 18
           two:   len=5 pos=4 21 17 2 12 18
           three: len=5 pos=0 21 17 2 12 18
     

This class uses the "Notice" classes to implement "dynamic" cursors so that multiple cursors are updated as elements are added and removed from the list.

Member Description

ListIter(List<t> *st, Bool OWN = False) : ConstListIter<t>(st), own(OWN)

This constructor allows one to construct a ListIter and attach it to the List parameter. The own flag can be set to indicate that the List should be destroyed when the ListIter is deleted.

ListIter(List<t> &st)

This constructor allows one to construct a ListIter and attach it to the List parameter.

ListIter(const ListIter<t> &other)
ListIter(const ListIter<t> *other) : ConstListIter<t>(other), own(False)

These constructors allow for the creation of a ListIter from another ListIter. This will attach this ListIter to the List tracked by the ListIter parameter at the time of construction.

ListIter() : ConstListIter<t>()

This is the default constructor. It allows one to create an initially invalid empty ListIter. The instantiated class will accept assignment and thus become valid later.

void addRight(t e)

This function adds the element to the right of the current cursor position.

void removeRight()

This function removes the element to the right of the current cursor position.

virtual void swapRight(ListIter<t> &)

This function swaps the list section after the current position of the list with the right section of the list of another iterator. This can be particularly useful for "remembering" the position of a cursor in a list.

t &getRight()
const t &getRight() const

Returns the element to the right of the cursor.

virtual ListIter<t> &assign(List<t> *other,Bool OWN = False)

This function changes the List which this ListIter tracks and specifies that the List should be deleted when this iterator is deleted.

virtual ListIter<t> &operator=(List<t> &other)
virtual ListIter<t> &operator=(List<t> *other)

This assignment operator changes the List which this iterator tracks to the List parameter.

virtual ListIter<t> &operator=(const ListIter<t> &other)
virtual ListIter<t> &operator=(const ListIter<t> *other)

These assignment operators allow one to change the List to which this iterator tracks to the List currently associated with the argument ListIter.

~ListIter()

virtual Link<t> *newLink(t &e, Link<t> *p=0, Link<t> *n=0)

This function creates a new link. By separating link creation out into "newLink", the "addRight(t)" functionality can be performed in the base class.

ConstListIter<t> &operator=(const List<t> &)
ConstListIter<t> &operator=(const List<t> *)
ConstListIter<t> &operator=(const ConstListIter<t> &)
ConstListIter<t> &operator=(const ConstListIter<t> *)