TableIter.h

Go to the documentation of this file.
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
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1