//# ArrayColumn.h: access to an array table column with arbitrary data type //# Copyright (C) 1994,1995,1996,1997,1998,2001 //# Associated Universities, Inc. Washington DC, USA. //# //# This library is free software; you can redistribute it and/or modify it //# under the terms of the GNU Library General Public License as published by //# the Free Software Foundation; either version 2 of the License, or (at your //# option) any later version. //# //# This library is distributed in the hope that it will be useful, but WITHOUT //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public //# License for more details. //# //# You should have received a copy of the GNU Library General Public License //# along with this library; if not, write to the Free Software Foundation, //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA. //# //# Correspondence concerning AIPS++ should be addressed as follows: //# Internet email: aips2-request@nrao.edu. //# Postal address: AIPS++ Project Office //# National Radio Astronomy Observatory //# 520 Edgemont Road //# Charlottesville, VA 22903-2475 USA //# //# $Id: ArrayColumn.h 21521 2014-12-10 08:06:42Z gervandiepen $ #ifndef TABLES_ARRAYCOLUMN_H #define TABLES_ARRAYCOLUMN_H //# Includes #include #include #include #include namespace casacore { //# NAMESPACE CASACORE - BEGIN //# Forward Declarations class ColumnSlicer; // // Read and write access to an array table column with arbitrary data type // // // // // //
  • Table //
  • ArrayColumnBase // // // ArrayColumn gives read and write access to an column in a table // containing an array with data type T. // // // The class ArrayColumn allows readonly access to a column // containing arrays with an arbitrary data type. It can handle direct // as well as indirect arrays. // It is possible to get the data in an individual cell (i.e. table row); // either the whole array or a slice of the array can be accessed. // It is also possible to get the column as a whole if the arrays // in all cells of the column have the same shape (which is always true // for direct arrays). As in the case of individual cells it is possible // to get the entire arrays or a slice of the arrays. // // A default constructor is defined to allow construction of an array // of ArrayColumn objects. However, this constructs an object not // referencing a column. Functions like get, etc. will fail (i.e. result // in a segmentation fault) when used on such objects. The functions // isNull and throwIfNull can be used to test on this. // The functions attach and reference can fill in the object. // // The assignment operator is not defined for this class, because it was // felt it would be too confusing. Instead the function reference can // be used to do assignment with reference semantics. An assignment // with copy semantics makes no sense for a readonly column. // // //
  • Default constructor //
  • Copy constructor //
  • Assignment operator // // // See module Tables. // template class ArrayColumn : public ArrayColumnBase { public: // The default constructor creates a null object, i.e. it // does not reference a table column. // The sole purpose of this constructor is to allow construction // of an array of ArrayColumn objects. // The functions reference and attach can be used to make a null object // reference a column. // Note that get 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. ArrayColumn(); // Construct for the given column in the given table. ArrayColumn (const Table&, const String& columnName); // Construct from the given table column. // This constructor is useful if first a table column was constructed, // its type is determined and thereafter used to construct the // correct column object. explicit ArrayColumn (const TableColumn&); // Copy constructor (reference semantics). ArrayColumn (const ArrayColumn&); ~ArrayColumn(); // Clone the object. virtual TableColumn* clone() const; // Assignment uses reference semantics, thus works the same // as function reference. ArrayColumn& operator= (const ArrayColumn&); // Change the reference to another column. // This is in fact an assignment operator with reference semantics. // It removes the reference to the current column and creates // a reference to the column referenced in the other object. // It will handle null objects correctly. void reference (const ArrayColumn&); // Attach a column to the object. // This is in fact only a shorthand for //
    reference (ArrayColumn (table, columnName)); void attach (const Table& table, const String& columnName) { reference (ArrayColumn (table, columnName)); } // Get the #dimensions of an array in a particular cell. // If the cell does not contain an array, 0 is returned. // Use the function isDefined to test if the cell contains an array. uInt ndim (rownr_t rownr) const { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->ndim (rownr); } // Get the shape of an array in a particular cell. // If the cell does not contain an array, a 0-dim shape is returned. // Use the function isDefined to test if the cell contains an array. IPosition shape (rownr_t rownr) const { TABLECOLUMNCHECKROW(rownr); return baseColPtr_p->shape (rownr); } // Get the array value in a particular cell (i.e. table row). // The row numbers count from 0 until #rows-1. // // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the table array shape. // However, if the resize flag is set the destination array will be // resized if not conforming. void get (rownr_t rownr, Array& array, Bool resize = False) const; Array get (rownr_t rownr) const; Array operator() (rownr_t rownr) const; // // Get a slice of an N-dimensional array in a particular cell // (i.e. table row). // The row numbers count from 0 until #rows-1. // The dimensionality of the slice must match the dimensionality // of the table array and the slice definition should not exceed // the shape of the table array. // // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the shape of the // table array slice. // However, if the resize flag is set the destination array will be // resized if not conforming. void getSlice (rownr_t rownr, const Slicer& arraySection, Array& array, Bool resize = False) const; Array getSlice (rownr_t rownr, const Slicer& arraySection) const; // // Get an irregular slice of an N-dimensional array in a particular cell // (i.e. table row) as given by the vectors of Slice objects. // The outer vector represents the array axes. // A missing or empty axis means the entire axis. // The inner vector represents the slices to take for each axis. // For example, to get slices from 2-dim arrays: // // Vector > slices(2); // 2-dim // slices[1].resize (3); // 3 slices in 2nd dim // slices[1][0] = Slice(100,20); // slices[1][1] = Slice(200,18); // slices[1][2] = Slice(538,30,2); // // Get data. Vector of first axis is empty, thus entire axis is read. // Array data = dataCol.getColumn (slices); // // If the column contains n-dim arrays, the resulting array is (n+1)-dim. // with the last dimension representing the number of rows and the // other dimensions representing the shape of the slice. // The arrays in the column must have the same shape in all cells. // // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the resulting (n+1)-dim // array. // However, if the resize flag is set the destination array will be // resized if not conforming. void getSlice (rownr_t rownr, const Vector >& arraySlices, Array& arr, Bool resize = False) const; Array getSlice (rownr_t rownr, const Vector >& arraySlices) const; // // Get the array of all values in a column. // If the column contains n-dim arrays, the resulting array is (n+1)-dim // with the last dimension representing the number of rows. // The arrays in the column must have the same shape in all cells. // // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the resulting (n+1)-dim // array. // However, if the resize flag is set the destination array will be // resized if not conforming. void getColumn (Array& array, Bool resize = False) const; Array getColumn() const; // // Get regular slices from all arrays in the column. // If the column contains n-dim arrays, the resulting array is (n+1)-dim. // with the last dimension representing the number of rows and the // other dimensions representing the shape of the slice. // The arrays in the column must have the same shape in all cells. // // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the resulting (n+1)-dim // array. // However, if the resize flag is set the destination array will be // resized if not conforming. void getColumn (const Slicer& arraySection, Array& array, Bool resize = False) const; Array getColumn (const Slicer& arraySection) const; // // Get irregular slices from all arrays in the column as given by the // vectors of Slice objects. The outer vector represents the array axes. // A missing or empty axis means the entire axis. // The inner vector represents the slices to take for each axis. // For example, to get slices from 2-dim arrays: // // Vector > slices(2); // 2-dim // slices[1].resize (3); // 3 slices in 2nd dim // slices[1][0] = Slice(100,20); // slices[1][1] = Slice(200,18); // slices[1][2] = Slice(538,30,2); // // Get data. Vector of first axis is empty, thus entire axis is read. // Array data = dataCol.getColumn (slices); // // If the column contains n-dim arrays, the resulting array is (n+1)-dim. // with the last dimension representing the number of rows and the // other dimensions representing the shape of the slice. // The arrays in the column must have the same shape in all cells. // // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the resulting (n+1)-dim // array. // However, if the resize flag is set the destination array will be // resized if not conforming. void getColumn (const Vector >& arraySection, Array& array, Bool resize = False) const; Array getColumn (const Vector >& arraySection) const; // // Get the array of some values in a column. // The Slicer object can be used to specify start, end (or length), // and stride of the rows to get. // If the column contains n-dim arrays, the resulting array is (n+1)-dim // with the last dimension representing the number of rows in the slicer. // The arrays in the column must have the same shape in all those cells. // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the resulting (n+1)-dim // array. // However, if the resize flag is set the destination array will be // resized if not conforming. // void getColumnRange (const Slicer& rowRange, Array& arr, Bool resize = False) const; Array getColumnRange (const Slicer& rowRange) const; void getColumnCells (const RefRows& rownrs, Array& arr, Bool resize = False) const; Array getColumnCells (const RefRows& rownrs) const; // // Get slices from some arrays in a column. // The first Slicer object can be used to specify start, end (or length), // and stride of the rows to get. The second Slicer object can be // used to specify the slice to take from each array. // If the column contains n-dim arrays, the resulting array is (n+1)-dim // with the last dimension representing the number of rows in the slicer. // The arrays in the column must have the same shape in all those cells. // According to the assignment rules of class Array, the destination // array must be empty or its shape must conform the resulting (n+1)-dim // array. // However, if the resize flag is set the destination array will be // resized if not conforming. // void getColumnRange (const Slicer& rowRange, const Slicer& arraySection, Array& arr, Bool resize = False) const; Array getColumnRange (const Slicer& rowRange, const Slicer& arraySection) const; void getColumnCells (const RefRows& rownrs, const Slicer& arraySection, Array& arr, Bool resize = False) const; Array getColumnCells (const RefRows& rownrs, const Slicer& arraySection) const; // // Similar to getColumn (arraySlices, arr, resize) except it // gets the slices for the given rows instead of all rows. void getColumnCells (const RefRows& rows, const ColumnSlicer & slicerSet, Array& destination, Bool resize = False) const; // Set the shape of the array in the given row. // Setting the shape is needed if the array is put in slices, // otherwise the table system would not know the shape. // void setShape (rownr_t rownr, const IPosition& shape); // Try to store the array in a tiled way using the given tile shape. void setShape (rownr_t rownr, const IPosition& shape, const IPosition& tileShape); // // Put the array in a particular cell (i.e. table row). // The row numbers count from 0 until #rows-1. // If the shape of the table array in that cell has not already been // defined, it will be defined implicitly. void put (rownr_t rownr, const Array& array); // Copy the value of a cell of that column to a cell of this column. // This function uses a generic TableColumn object as input. // The data types of both columns must be the same, otherwise an // exception is thrown. // // Use the same row numbers for both cells. void put (rownr_t rownr, const TableColumn& that, Bool preserveTileShape=False) { put (rownr, that, rownr, preserveTileShape); } // Use possibly different row numbers for that (i.e. input) and // and this (i.e. output) cell. void put (rownr_t thisRownr, const TableColumn& that, rownr_t thatRownr, Bool preserveTileShape=False); // For backward compatibility (otherwise ambigious with put taking Bool). void put (uInt thisRownr, const TableColumn& that, uInt thatRownr, Bool preserveTileShape=False) { put (rownr_t(thisRownr), that, rownr_t(thatRownr), preserveTileShape); } // // Put into a slice of an N-dimensional array in a particular cell. // The row numbers count from 0 until #rows-1. // The shape of the table array must have been defined. // The dimensionality of the slice must match the dimensionality // of the table array and the slice definition should not exceed // the shape of the table array. void putSlice (rownr_t rownr, const Slicer& arraySection, const Array& array); void putSlice (rownr_t rownr, const Vector >& arraySlices, const Array& arr); // Put the array of all values in the column. // If the column contains n-dim arrays, the source array must be (n+1)-dim // with the last dimension representing the number of rows. void putColumn (const Array& array); // Put into subsections of the table arrays in the entire column. // If the column contains n-dim arrays, the source array is (n+1)-dim // with the last dimension representing the number of rows and // other dimensions representing the shape of the slice. // The dimensionality of the slice must match the dimensionality // of the table array, thus must be n-dim. Also the slice definition // should not exceed the shape of the table arrays. void putColumn (const Slicer& arraySection, const Array& array); void putColumn (const Vector >& arraySlices, const Array& arr); // Put the array of some values in the column. // The Slicer object can be used to specify start, end (or length), // and stride of the rows to put. // If the column contains n-dim arrays, the source array must be (n+1)-dim // with the last dimension representing the number of rows in the slicer. // void putColumnRange (const Slicer& rowRange, const Array& arr); void putColumnCells (const RefRows& rownrs, const Array& arr); // // Put into subsection of the table arrays in some rows of the column. // The first Slicer object can be used to specify start, end (or length), // and stride of the rows to put. The second Slicer object can be // used to specify the slice to take from each array. // If the column contains n-dim arrays, the source array must be (n+1)-dim // with the last dimension representing the number of rows in the slicer. // void putColumnRange (const Slicer& rowRange, const Slicer& arraySection, const Array& arr); void putColumnCells (const RefRows& rownrs, const Slicer& arraySection, const Array& arr); // // Same as putColumn(arraySlices, arr) except that it puts for the given // rows instead of all rows. // void putColumnCells (const RefRows& rows, const Vector >& arraySlices, const Array& arr); void putSliceFromRows (const RefRows& rows, const Vector >& arraySlices, const Array& source) { putColumnCells (rows, arraySlices, source); } void putColumnCells (const RefRows& rows, const ColumnSlicer & columnSlicer, const Array& source); // // Put the same value in all cells of the column. void fillColumn (const Array& value); // Put the contents of a column with the same data type into this column. // To put the contents of a column with a different data type into // this column, the function TableColumn::putColumn can be used // (provided the data type promotion is possible). // In fact, this function is an assignment operator with copy semantics. void putColumn (const ArrayColumn& that); private: // Check if the data type matches the column data type. void checkDataType() const; }; //# Explicitly instantiate these templates in ArrayColumn_tmpl.cc extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; extern template class ArrayColumn; } //# NAMESPACE CASACORE - END //# Make old name ROArrayColumn still available. #define ROArrayColumn ArrayColumn #ifndef CASACORE_NO_AUTO_TEMPLATES #include #endif //# CASACORE_NO_AUTO_TEMPLATES #endif