Loading...
Searching...
No Matches
casacore::TableIterator Class Reference
tables package (libcasa_tables) » Tables_module

More...

`#include <TableIter.h>`

## Public Types

enum | Order { Ascending , Descending }
| Define the possible iteration orders. More...
enum | Option { QuickSort , HeapSort , InsSort , ParSort , 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=ParSort)
| Create a table iterator on the given column(s) for the given table.
| TableIterator (const Table &, const Block< String > &columnNames, Order=Ascending, Option=ParSort)
| TableIterator (const Table &, const Block< String > &columnNames, const Block< Int > &orders, Option=ParSort)
| Give the iteration order per column.
| TableIterator (const Table &, const Block< String > &columnNames, const Block< std::shared_ptr< BaseCompare > > &cmpObjs, const Block< Int > &orders, Option=ParSort, bool cacheIterationBoundaries=false)
| 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)
void | copyState (const TableIterator &)
const String & | keyChangeAtLastNext () const
| Report Name of slowest column that changes at end of current iteration.
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. For example, CompareIntervalReal can be used to iterate in intervals over, say, the TIME column by treating a range of values as equal (e.g. iterate in 60 seconds time intervals).

The table is sorted before doing the iteration unless TableIterator::NoSort is given.

### 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;
casacore::Block
simple 1-D array
Definition Block.h:198
casacore::TableIterator::TableIterator
TableIterator()
Create a null TableIterator object (i.e.
casacore::Table
Definition Table.h:157
casacore::Table::nrow
rownr_t nrow() const
Get the number of rows.
Definition Table.h:1187
casacore::Int
int Int
Definition aipstype.h:48

### 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

## Option

enum casacore::TableIterator::Option

Define the possible sorts.

Enumerator
QuickSort |
HeapSort |
InsSort |
ParSort |
NoSort |

Definition at line 122 of file TableIter.h.

## Order

enum casacore::TableIterator::Order

Define the possible iteration orders.

Enumerator
Ascending |
Descending |

Definition at line 120 of file TableIter.h.

## Constructor & Destructor Documentation

## TableIterator() [1/6]

casacore::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.

Referenced by copyState(), operator=(), and TableIterator().

## TableIterator() [2/6]

casacore::TableIterator::TableIterator | ( | const Table & | ,
|  | const String & | columnName,
|  | Order | = Ascending,
|  | Option | = ParSort )

Create a table iterator on the given column(s) for the given table.

Each iteration step results in a Table containing all rows in which the values in each given column is equal. The column vector can be empty, resulting in a single iteration step giving the entire table. 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 ParSort is the fastest, but for a single core machine QuickSort usually performs better. InsSort (insertion sort) should only be used if the input is almost in order. If it is known that the table is already in order, the sort step can be bypassed by giving the option TableIterator::NoSort. The default option is ParSort.

References Ascending, and ParSort.

## TableIterator() [3/6]

casacore::TableIterator::TableIterator | ( | const Table & | ,
|  | const Block< String > & | columnNames,
|  | Order | = Ascending,
|  | Option | = ParSort )

References Ascending, and ParSort.

## TableIterator() [4/6]

casacore::TableIterator::TableIterator | ( | const Table & | ,
|  | const Block< String > & | columnNames,
|  | const Block< Int > & | orders,
|  | Option | = ParSort )

Give the iteration order per column.

Note: If an interval comparison object like CompareIntervalReal is used, the data are sorted on the interval, not on the value; One should consider to do an explicitsort on value and no iteration sort;

References ParSort.

## TableIterator() [5/6]

casacore::TableIterator::TableIterator | ( | const Table & | ,
|  | const Block< String > & | columnNames,
|  | const Block< std::shared_ptr< BaseCompare > > & | cmpObjs,
|  | const Block< Int > & | orders,
|  | Option | = ParSort,
|  | bool | cacheIterationBoundaries = false )

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. If cacheIterationBoundaries is set to true then the iteration boundaries computed at construction time while sorting the table are used when advancing with next(). Otherwise, for each next() call the comparison functions are reevaluated again to get the iteration boundary. This improves performance in general but will break existing applications that change the comparison objects (cmpObjs) between iterations.

References ParSort.

## TableIterator() [6/6]

casacore::TableIterator::TableIterator | ( | const TableIterator & |  | ) |

Copy constructor (copy semantics).

References TableIterator().

## ~TableIterator()

casacore::TableIterator::~TableIterator | ( |  | ) |

## Member Function Documentation

## copyState()

void casacore::TableIterator::copyState | ( | const TableIterator & |  | ) |

References TableIterator().

## isNull()

Bool casacore::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 194 of file TableIter.h.

References tabIterPtr_p.

## keyChangeAtLastNext()

const String & casacore::TableIterator::keyChangeAtLastNext | ( |  | ) | const

Report Name of slowest column that changes at end of current iteration.

## next()

void casacore::TableIterator::next | ( |  | ) |

Go to the next group.

Referenced by operator++(), and operator++().

## operator++() [1/2]

void casacore::TableIterator::operator++ | ( |  | ) |

inline

Definition at line 236 of file TableIter.h.

References next().

## operator++() [2/2]

void casacore::TableIterator::operator++ | ( | int |  | ) |

inline

Definition at line 239 of file TableIter.h.

References next().

## operator=()

TableIterator & casacore::TableIterator::operator= | ( | const TableIterator & |  | ) |

Assignment (copy semantics).

References TableIterator().

## pastEnd()

Bool casacore::TableIterator::pastEnd | ( |  | ) | const

inline

Test if at the end.

Definition at line 230 of file TableIter.h.

References casacore::False, subTable_p, and casacore::True.

## reset()

void casacore::TableIterator::reset | ( |  | ) |

Reset the iterator (i.e.

restart iteration).

## table()

Table casacore::TableIterator::table | ( |  | ) | const

inline

Get the current group.

Definition at line 233 of file TableIter.h.

References subTable_p.

## throwIfNull()

void casacore::TableIterator::throwIfNull | ( |  | ) | const

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

if function isNull() is True.

## Member Data Documentation

## subTable_p

Table casacore::TableIterator::subTable_p

protected

Definition at line 224 of file TableIter.h.

Referenced by pastEnd(), and table().

## tabIterPtr_p

BaseTableIterator* casacore::TableIterator::tabIterPtr_p

protected

Definition at line 223 of file TableIter.h.

Referenced by isNull().

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

- tables/Tables/TableIter.h