Iterate through a Table. More...

#include <TableIter.h>

Public Types
enum	Order { Ascending, Descending }
	Define the possible iteration orders. More...
enum	Option { QuickSort, HeapSort, InsSort, NoSort }
	Define the possible sorts. More...
Public Member Functions
	TableIterator ()
	Create a null TableIterator object (i.e.
	TableIterator (const Table &, const String &columnName, Order=Ascending, Option=HeapSort)
	Create a table iterator for the given table.
	TableIterator (const Table &, const Block< String > &columnNames, Order=Ascending, Option=HeapSort)
	TableIterator (const Table &, const Block< String > &columnNames, const Block< Int > &orders, Option=HeapSort)
	Give the iteration order per column.
	TableIterator (const Table &, const Block< String > &columnNames, const Block< CountedPtr< BaseCompare > > &, const Block< Int > &orders, Option=HeapSort)
	Give the iteration order per column.
	TableIterator (const TableIterator &)
	Copy constructor (copy semantics).
	~TableIterator ()
TableIterator &	operator= (const TableIterator &)
	Assignment (copy semantics).
Bool	isNull () const
	Test if the object is null, i.e.
void	throwIfNull () const
	Throw an exception if the object is null, i.e.
void	reset ()
	Reset the iterator (i.e.
Bool	pastEnd () const
	Test if at the end.
void	next ()
	Go to the next group.
void	operator++ ()
void	operator++ (int)
Table	table () const
	Get the current group.
Protected Attributes
BaseTableIterator *	tabIterPtr_p
Table	subTable_p

Detailed Description

Iterate through a Table.

Intended use:

Public interface

Review Status

Reviewed By:: UNKNOWN
Date Reviewed:: before2004/08/25

Prerequisite

Table
Sort

Synopsis

TableIterator is a class allowing one to iterate in an arbitrary way through a table. Each iteration step returns a Table containing the result of the iteration step. It is possible to have more than one iterator on a table.

An iteration is defined by giving the columns over which to iterate. For example, take a UV data set with "axes" frequency, baseline and time. Getting all frequencies per time and baseline can be done by iterating over columns time and baseline (as shown in the example). The main iteration column must be given first. It is possible to define an iteration order per column. It is also possible to define a compare object per column. This can, for example, be used to iterate in intervals by treating a range of values as equal (e.g. iterate in 60 seconds time intervals).

Currently the table is sorted before doing the iteration. This may change in the future when, for example, indices are supported.

Example

       // Iterate over time and baseline (by default in ascending order).
       // Time is the main iteration order.
       Table t;
       Table tab ("UV_Table.data");
       Block<String> iv0(2);
       iv0[0] = "time";
       iv0[1] = "baseline";
       // Create the iterator. This will prepare the first subtable.
       TableIterator iter(tab, iv0);
       Int nr = 0;
       while (!iter.pastEnd()) {
         // Get the first subtable.
         // This will contain rows with equal time and baseline.
        t = iter.table();
        cout << t.nrow() << " ";
        nr++;
         // Prepare the next subtable with the next time,baseline value.
        iter.next();
       }
       cout << endl << nr << " iteration steps" << endl;

Motivation

It is sometimes needed to access all data in a table in a grouped way; for example, all frequencies per time and baseline. This can perfectly be done with an iterator.

Definition at line 115 of file TableIter.h.

Member Enumeration Documentation

enum casa::TableIterator::Option

Define the possible sorts.

Enumerator:

QuickSort
HeapSort
InsSort
NoSort

Definition at line 122 of file TableIter.h.

enum casa::TableIterator::Order

Define the possible iteration orders.

Enumerator:

Ascending
Descending

Definition at line 120 of file TableIter.h.

Constructor & Destructor Documentation

casa::TableIterator::TableIterator ( )

Create a null TableIterator object (i.e.

no iterator is attached yet). The sole purpose of this constructor is to allow construction of an array of TableIterator objects. The assignment operator can be used to make a null object reference a column. Note that sort functions, etc. will cause a segmentation fault when operating on a null object. It was felt it was too expensive to test on null over and over again. The user should use the isNull or throwIfNull function in case of doubt.

casa::TableIterator::TableIterator	(	const Table &	,
		const String &	columnName,
		Order	= `Ascending`,
		Option	= `HeapSort`
	)

Create a table iterator for the given table.

Each iteration step results in a Table containing all rows in which the values in each given column is equal. An iteration order can be given; it defaults to Ascending. Per column a compare object can be given to use other compare functions than the standard ones defined in Compare.h. The compare functions are used for both the sort and the iteration. The option argument makes it possible to choose from various sorting algorithms. Usually QuickSort is the fastest, but for some ill-conditioned input HeapSort performs much better. InsSort (insertion sort) should only be used when the input is almost in order. When the table is already in order, the sort step can be bypassed by giving the option TableIterator::NoSort. The default option is HeapSort.

casa::TableIterator::TableIterator	(	const Table &	,
		const Block< String > &	columnNames,
		Order	= `Ascending`,
		Option	= `HeapSort`
	)

casa::TableIterator::TableIterator	(	const Table &	,
		const Block< String > &	columnNames,
		const Block< Int > &	orders,
		Option	= `HeapSort`
	)

Give the iteration order per column.

casa::TableIterator::TableIterator	(	const Table &	,
		const Block< String > &	columnNames,
		const Block< CountedPtr< BaseCompare > > &	,
		const Block< Int > &	orders,
		Option	= `HeapSort`
	)

Give the iteration order per column.

Give an optional compare object per column. A zero pointer means that the default compare function will be used.

casa::TableIterator::TableIterator ( const TableIterator & )

Copy constructor (copy semantics).

casa::TableIterator::~TableIterator ( )

Member Function Documentation

Bool casa::TableIterator::isNull ( ) const [inline]

Test if the object is null, i.e.

does not reference a table yet. This is the case if the default constructor is used.

Definition at line 176 of file TableIter.h.

References casa::False, tabIterPtr_p, and casa::True.

Referenced by casa::TableIterProxy::isNull().

void casa::TableIterator::next ( )

Go to the next group.

Referenced by operator++().

void casa::TableIterator::operator++ ( ) [inline]

Definition at line 213 of file TableIter.h.

References next().

void casa::TableIterator::operator++ ( int ) [inline]

Definition at line 216 of file TableIter.h.

References next().

TableIterator& casa::TableIterator::operator= ( const TableIterator & )

Assignment (copy semantics).

Bool casa::TableIterator::pastEnd ( ) const [inline]

Test if at the end.

Definition at line 207 of file TableIter.h.

References casa::False, casa::Table::nrow(), subTable_p, and casa::True.

Referenced by casa::ROCTIter::pastEnd().

void casa::TableIterator::reset ( )

Reset the iterator (i.e.

restart iteration).

Referenced by casa::ROCTIter::reset().

Table casa::TableIterator::table ( ) const [inline]

Get the current group.

Definition at line 210 of file TableIter.h.

References subTable_p.

Referenced by casa::ROCTIter::nrow(), and casa::ROCTIter::table().

void casa::TableIterator::throwIfNull ( ) const

Throw an exception if the object is null, i.e.

if function isNull() is True.

Member Data Documentation

Table casa::TableIterator::subTable_p [protected]

Definition at line 201 of file TableIter.h.

Referenced by pastEnd(), and table().

BaseTableIterator* casa::TableIterator::tabIterPtr_p [protected]

Definition at line 200 of file TableIter.h.

Referenced by isNull().

The documentation for this class was generated from the following file:

casacore/tables/Tables/TableIter.h

Public Types

Public Member Functions

Protected Attributes