00001 //# TableIter.h: Iterate through a Table 00002 //# Copyright (C) 1994,1995,1996,1997,1999,2000 00003 //# Associated Universities, Inc. Washington DC, USA. 00004 //# 00005 //# This library is free software; you can redistribute it and/or modify it 00006 //# under the terms of the GNU Library General Public License as published by 00007 //# the Free Software Foundation; either version 2 of the License, or (at your 00008 //# option) any later version. 00009 //# 00010 //# This library is distributed in the hope that it will be useful, but WITHOUT 00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 00012 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public 00013 //# License for more details. 00014 //# 00015 //# You should have received a copy of the GNU Library General Public License 00016 //# along with this library; if not, write to the Free Software Foundation, 00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. 00018 //# 00019 //# Correspondence concerning AIPS++ should be addressed as follows: 00020 //# Internet email: aips2-request@nrao.edu. 00021 //# Postal address: AIPS++ Project Office 00022 //# National Radio Astronomy Observatory 00023 //# 520 Edgemont Road 00024 //# Charlottesville, VA 22903-2475 USA 00025 //# 00026 //# $Id$ 00027 00028 #ifndef TABLES_TABLEITER_H 00029 #define TABLES_TABLEITER_H 00030 00031 //# Includes 00032 #include <casacore/casa/aips.h> 00033 #include <casacore/tables/Tables/Table.h> 00034 #include <casacore/casa/Utilities/Sort.h> 00035 #include <casacore/casa/Utilities/Compare.h> 00036 00037 namespace casacore { //# NAMESPACE CASACORE - BEGIN 00038 00039 //# Forward Declarations 00040 class BaseTableIterator; 00041 class String; 00042 template<class T> class Block; 00043 00044 00045 // <summary> 00046 // Iterate through a Table 00047 // </summary> 00048 00049 // <use visibility=export> 00050 00051 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests=""> 00052 // </reviewed> 00053 00054 // <prerequisite> 00055 //# Classes you should understand before using this one. 00056 // <li> Table 00057 // <li> Sort 00058 // </prerequisite> 00059 00060 // <synopsis> 00061 // TableIterator is a class allowing one to iterate in an arbitrary 00062 // way through a table. Each iteration step returns a Table 00063 // containing the result of the iteration step. 00064 // It is possible to have more than one iterator on a table. 00065 // 00066 // An iteration is defined by giving the columns over which to iterate. 00067 // For example, take a UV data set with "axes" frequency, baseline and 00068 // time. Getting all frequencies per time and baseline can be done 00069 // by iterating over columns time and baseline (as shown in the example). 00070 // The main iteration column must be given first. 00071 // It is possible to define an iteration order per column. 00072 // <br>It is also possible to define a compare object per column. 00073 // For example, CompareIntervalReal can be used to iterate in intervals 00074 // over, say, the TIME column by treating a range of values as equal 00075 // (e.g. iterate in 60 seconds time intervals). 00076 // 00077 // The table is sorted before doing the iteration unless TableIterator::NoSort 00078 // is given. 00079 // </synopsis> 00080 00081 // <example> 00082 // <srcblock> 00083 // // Iterate over time and baseline (by default in ascending order). 00084 // // Time is the main iteration order. 00085 // Table t; 00086 // Table tab ("UV_Table.data"); 00087 // Block<String> iv0(2); 00088 // iv0[0] = "time"; 00089 // iv0[1] = "baseline"; 00090 // // Create the iterator. This will prepare the first subtable. 00091 // TableIterator iter(tab, iv0); 00092 // Int nr = 0; 00093 // while (!iter.pastEnd()) { 00094 // // Get the first subtable. 00095 // // This will contain rows with equal time and baseline. 00096 // t = iter.table(); 00097 // cout << t.nrow() << " "; 00098 // nr++; 00099 // // Prepare the next subtable with the next time,baseline value. 00100 // iter.next(); 00101 // } 00102 // cout << endl << nr << " iteration steps" << endl; 00103 // </srcblock> 00104 // </example> 00105 00106 // <motivation> 00107 // It is sometimes needed to access all data in a table in a grouped 00108 // way; for example, all frequencies per time and baseline. 00109 // This can perfectly be done with an iterator. 00110 // </motivation> 00111 00112 //# <todo asof="$DATE:$"> 00113 //# A List of bugs, limitations, extensions or planned refinements. 00114 //# </todo> 00115 00116 00117 class TableIterator 00118 { 00119 public: 00120 00121 // Define the possible iteration orders. 00122 enum Order {Ascending=Sort::Ascending, Descending=Sort::Descending}; 00123 // Define the possible sorts. 00124 enum Option {QuickSort= Sort::QuickSort, 00125 HeapSort = Sort::HeapSort, 00126 InsSort = Sort::InsSort, 00127 ParSort = Sort::ParSort, 00128 NoSort = 64}; 00129 00130 // Create a null TableIterator object (i.e. no iterator is attached yet). 00131 // The sole purpose of this constructor is to allow construction 00132 // of an array of TableIterator objects. 00133 // The assignment operator can be used to make a null object 00134 // reference a column. 00135 // Note that sort functions, etc. will cause a segmentation fault 00136 // when operating on a null object. It was felt it was too expensive 00137 // to test on null over and over again. The user should use the isNull 00138 // or throwIfNull function in case of doubt. 00139 TableIterator(); 00140 00141 // Create a table iterator for the given table. 00142 // Each iteration step results in a Table containing all 00143 // rows in which the values in each given column is equal. 00144 // An iteration order can be given; it defaults to Ascending. 00145 // Per column a compare object can be given to use other compare 00146 // functions than the standard ones defined in Compare.h. 00147 // The compare functions are used for both the sort and the iteration. 00148 // The option argument makes it possible to choose from various 00149 // sorting algorithms. Usually ParSort is the fastest, but for 00150 // a single core machine QuickSort usually performs better. 00151 // InsSort (insertion sort) should only be used if the input 00152 // is almost in order. 00153 // If it is known that the table is already in order, the sort step can be 00154 // bypassed by giving the option TableIterator::NoSort. 00155 // The default option is ParSort. 00156 // <group> 00157 TableIterator (const Table&, const String& columnName, 00158 Order = Ascending, Option = ParSort); 00159 TableIterator (const Table&, const Block<String>& columnNames, 00160 Order = Ascending, Option = ParSort); 00161 // Give the iteration order per column. 00162 // <note>If an interval comparison object like CompareIntervalReal 00163 // is used, the data are sorted on the interval, not on the value. 00164 // One should consider to do an explicitsort on value and no iteration sort. 00165 // </note> 00166 TableIterator (const Table&, const Block<String>& columnNames, 00167 const Block<Int>& orders, Option = ParSort); 00168 // Give the iteration order per column. 00169 // Give an optional compare object per column. 00170 // A zero pointer means that the default compare function will be used. 00171 TableIterator (const Table&, const Block<String>& columnNames, 00172 const Block<CountedPtr<BaseCompare> >&, 00173 const Block<Int>& orders, Option = ParSort); 00174 // </group> 00175 00176 // Copy constructor (copy semantics). 00177 TableIterator (const TableIterator&); 00178 00179 ~TableIterator(); 00180 00181 // Assignment (copy semantics). 00182 TableIterator& operator= (const TableIterator&); 00183 00184 // Test if the object is null, i.e. does not reference a table yet. 00185 // This is the case if the default constructor is used. 00186 Bool isNull() const 00187 { return (tabIterPtr_p == 0 ? True : False); } 00188 00189 // Throw an exception if the object is null, i.e. 00190 // if function isNull() is True. 00191 void throwIfNull() const; 00192 00193 // Reset the iterator (i.e. restart iteration). 00194 void reset(); 00195 00196 // Test if at the end. 00197 Bool pastEnd() const; 00198 00199 // Go to the next group. 00200 // <group> 00201 void next(); 00202 void operator++(); 00203 void operator++(int); 00204 // </group> 00205 00206 // Get the current group. 00207 Table table() const; 00208 00209 protected: 00210 BaseTableIterator* tabIterPtr_p; 00211 Table subTable_p; 00212 }; 00213 00214 00215 00216 //# Iterator is at the end if the subtable is empty. 00217 inline Bool TableIterator::pastEnd() const 00218 { return (subTable_p.nrow() == 0 ? True : False); } 00219 00220 inline Table TableIterator::table() const 00221 { return subTable_p; } 00222 00223 inline void TableIterator::operator++() 00224 { next(); } 00225 00226 inline void TableIterator::operator++(int) 00227 { next(); } 00228 00229 00230 00231 00232 00233 } //# NAMESPACE CASACORE - END 00234 00235 #endif