CCfits::Column Class Reference

Abstract base class for Column objects. More...

#include <Column.h>

Inherited by CCfits::ColumnData< T >, and CCfits::ColumnVectorData< T >.

List of all members.

Classes

class  InsufficientElements
 Exception thrown if the data supplied for a write operation is less than declared. More...
class  InvalidDataType
 Exception thrown for invalid data type inputs. More...
class  InvalidNumberOfRows
 Exception thrown if user enters a non-positive number for the number of rows to write. More...
class  InvalidRowNumber
 Exception thrown on attempting to read a row number beyond the end of a table. More...
class  InvalidRowParameter
 Exception thrown on incorrect row writing request. More...
class  NoNullValue
 Exception thrown if a null value is specified without support from existing column header. More...
class  RangeError
 exception to be thrown for inputs that cause range errors in column read operations. More...
class  WrongColumnType
 Exception thrown on attempting to access a scalar column as vector data. More...

Public Member Functions

 Column (const Column &right)
 copy constructor, used in copying Columns to standard library containers.
virtual ~Column ()
 destructor.
virtual void readData (long firstRow, long nelements, long firstElem=1)=0
 read method.
int rows () const
 return the number of rows in the table.
void setDisplay ()
 set the TDISPn keyword
virtual void setDimen ()
 set the TDIMn keyword.
Tableparent () const
 return a pointer to the Table which owns this Column
int index () const
 get the Column index (the n in TTYPEn etc).
bool isRead () const
 flag set to true if the entire column data has been read from disk
long width () const
 return column data width
size_t repeat () const
 get the repeat count for the rows
bool varLength () const
 boolean, set to true if Column has variable length vector rows.
double scale () const
 get TSCALn value
double zero () const
 get TZEROn value
const String & display () const
 return TDISPn keyword
const String & dimen () const
 return TDIMn keyword
ValueType type () const
 returns the data type of the column
const String & format () const
 return TFORMn keyword
const String & unit () const
 get units of data in Column (TUNITn keyword)
const String & name () const
 return name of Column (TTYPEn keyword)
template<typename S >
void write (const std::vector< S > &indata, long firstRow)
 write a vector of values into a scalar column starting with firstRow
template<typename S >
void write (const std::valarray< S > &indata, long firstRow)
 write a valarray of values into a scalar column starting with firstRow
template<typename S >
void write (S *indata, long nRows, long firstRow)
 write a C array of size nRows into a scalar Column starting with row firstRow.
template<typename S >
void write (const std::vector< S > &indata, long firstRow, S *nullValue)
 write a vector of values into a scalar column starting with firstRow with undefined values set to nullValue.
template<typename S >
void write (const std::valarray< S > &indata, long firstRow, S *nullValue)
 write a valarray of values into a scalar column starting with firstRow with undefined values set to nullValue.
template<typename S >
void write (S *indata, long nRows, long firstRow, S *nullValue)
 write a C array into a scalar Column, processing undefined values.
template<typename S >
void write (const std::valarray< S > &indata, long nRows, long firstRow)
 write a valarray of values into a range of rows of a vector column.
template<typename S >
void write (const std::vector< S > &indata, long nRows, long firstRow)
 write a vector of values into a range of rows of a vector column
template<typename S >
void write (S *indata, long nElements, long nRows, long firstRow)
 write a C array of values into a range of rows of a vector column
template<typename S >
void write (const std::valarray< S > &indata, long nRows, long firstRow, S *nullValue)
 write a valarray of values into a range of rows of a vector column.
template<typename S >
void write (const std::vector< S > &indata, long nRows, long firstRow, S *nullValue)
 write a vector of values into a range of rows of a vector column, processing undefined values
template<typename S >
void write (S *indata, long nElements, long nRows, long firstRow, S *nullValue)
 write a C array of values into a range of rows of a vector column, processing undefined values.
template<typename S >
void write (const std::valarray< S > &indata, const std::vector< long > &vectorLengths, long firstRow)
 write a valarray of values into a column with specified number of entries written per row.
template<typename S >
void write (const std::vector< S > &indata, const std::vector< long > &vectorLengths, long firstRow)
 write a vector of values into a column with specified number of entries written per row.
template<typename S >
void write (S *indata, long nElements, const std::vector< long > &vectorLengths, long firstRow)
 write a C-array of values of size nElements into a vector column with specified number of entries written per row.
template<typename S >
void writeArrays (const std::vector< std::valarray< S > > &indata, long firstRow)
 write a vector of valarray objects to the column, starting at row firstRow >= 1
template<typename S >
void writeArrays (const std::vector< std::valarray< S > > &indata, long firstRow, S *nullValue)
 write a vector of valarray objects to the column, starting at row firstRow >= 1, processing undefined values
template<typename S >
void read (std::vector< S > &vals, long first, long last)
 Retrieve data from a scalar column into a std::vector.
template<typename S >
void read (std::valarray< S > &vals, long first, long last)
 Retrieve data from a scalar column into a std::valarray.
template<typename S >
void read (std::valarray< S > &vals, long rows)
 return a single row of a vector column into a std::valarray
template<typename S >
void readArrays (std::vector< std::valarray< S > > &vals, long first, long last)
 return a set of rows of a vector column into a vector of valarrays
template<typename S >
void read (std::vector< S > &vals, long first, long last, S *nullValue)
 Retrieve data from a scalar column into a std::vector, setting nullvalue.
template<typename S >
void read (std::valarray< S > &vals, long first, long last, S *nullValue)
 Retrieve data from a scalar column into a std::valarray, setting undefined values.
template<typename S >
void read (std::valarray< S > &vals, long rows, S *nullValue)
 return a single row of a vector column into a std::valarray, setting undefined values
template<typename S >
void readArrays (std::vector< std::valarray< S > > &vals, long first, long last, S *nullValue)
 return a set of rows of a vector column into a container, setting undefined values
template<typename T >
void addNullValue (T nullVal)
 Set the TNULLn keyword for the column.

Protected Member Functions

 Column (int columnIndex, const String &columnName, ValueType type, const String &format, const String &unit, Table *p, int rpt=1, long w=1, const String &comment="")
 new column creation constructor
 Column (Table *p=0)
 Simple constructor to be called by subclass reading ctors.
fitsfile * fitsPointer ()
 fits pointer corresponding to fits file containing column data.
void makeHDUCurrent ()
 make HDU containing this the current HDU of the fits file.
virtual std::ostream & put (std::ostream &s) const
 internal implementation of << operator.
const String & comment () const
 retrieve comment for Column


Detailed Description

Abstract base class for Column objects.

Columns are the data containers used in FITS tables. Columns of scalar type (one entry per cell) are implemented by the template subclass ColumnData<T>. Columns of vector type (vector and variable rows) are implemented with the template subclass ColumnVectorData<T>. AsciiTables may only contain Columns of type ColumnData<T>, where T is an implemented FITS data type (see the CCfits.h header for a complete list. This requirement is enforced by ensuring that AsciiTable's addColumn method may only create an AsciiTable compatible column. The ColumnData<T> class stores its data in a std::vector<T> object.

BinTables may contain either ColumnData<T> or ColumnVectorData<T>. For ColumnVectorData, T must be a numeric type: string vectors are handled by ColumnData<T>; string arrays are not supported. The internal representation of the data is a std::vector<std::valarray<T> > object. The std::valarray class is designed for efficient numeric processing and has many vectorized numeric and transcendental functions defined on it.

Member template functions for read/write operations are provided in multiple overloads as the interface to data operations. Implicit data type conversions are supported but where they are required make the operations less efficient. Reading numeric column data as character arrays, supported by cfitsio, is not supported by CCfits.

As a base class, Column provides protected accessor/mutator inline functions to allow only its subclasses to access data members.


Constructor & Destructor Documentation

CCfits::Column::Column ( const Column right  ) 

copy constructor, used in copying Columns to standard library containers.

The copy constructor is for internal use only: it does not affect the disk fits file associated with the object.

CCfits::Column::Column ( int  columnIndex,
const String &  columnName,
ValueType  type,
const String &  format,
const String &  unit,
Table p,
int  rpt = 1,
long  w = 1,
const String &  comment = "" 
) [protected]

new column creation constructor

This constructor allows the specification of:

Parameters:
columnIndex The column number
columnName The column name, keyword TTYPEn
type used for determining class of T in ColumnData<T>, ColumnVectorData<T>
format the column data format, TFORMn keyword
unit the column data unit, TUNITn keyword
p the Table pointer
rpt (optional) repeat count for the row ( == 1 for AsciiTables)
w the row width
comment comment to be added to the header.

References setDimen(), and setDisplay().


Member Function Documentation

template<typename T >
void CCfits::Column::addNullValue ( nullVal  )  [inline]

Set the TNULLn keyword for the column.

Only relevant for integer valued columns, TNULLn is the value used by cfitsio in undefined processing. All entries in the table equal to an input "null value" are set equal to the value of TNULLn. (For floating point columns a system NaN values is used).

References fitsPointer(), index(), CCfits::ExtHDU::makeThisCurrent(), parent(), and type().

const String & CCfits::Column::dimen (  )  const [inline]

return TDIMn keyword

represents dimensions of data arrays in vector columns. for scalar columns, returns a default value.

const String & CCfits::Column::display (  )  const [inline]

return TDISPn keyword

TDISPn is suggested format for output of column data.

const String & CCfits::Column::format (  )  const [inline]

return TFORMn keyword

TFORMn specifies data format stored in disk file.

Referenced by put().

template<typename S >
void CCfits::Column::read ( std::valarray< S > &  vals,
long  first,
long  last,
S *  nullValue 
) [inline]

Retrieve data from a scalar column into a std::valarray, setting undefined values.

If the column is of integer type, then any column value that equals this null value is set equal to the value of the TNULLn keyword. An exception is thrown if TNULLn is not specified. See cfitsio documentation for further details

Parameters:
vals The output container. The function will resize this as necessary
first,last the span of row numbers to read.
nullValue pointer to integer value regarded as undefined

References isRead(), CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::read ( std::vector< S > &  vals,
long  first,
long  last,
S *  nullValue 
) [inline]

Retrieve data from a scalar column into a std::vector, setting nullvalue.

If the column is of integer type, then any column value that equals this null value is set equal to the value of the TNULLn keyword. An exception is thrown if TNULLn is not specified. See cfitsio documentation for further details

Parameters:
vals The output container. The function will resize this as necessary
first,last the span of row numbers to read.
nullValue pointer to integer value regarded as undefined

References isRead(), CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::read ( std::valarray< S > &  vals,
long  rows 
) [inline]

return a single row of a vector column into a std::valarray

Parameters:
vals The output valarray object
rows The row number to be retrieved (starting at 1).

References read().

template<typename S >
void CCfits::Column::read ( std::valarray< S > &  vals,
long  first,
long  last 
) [inline]

Retrieve data from a scalar column into a std::valarray.

Parameters:
vals The output container. The function will resize this as necessary
first,last the span of row numbers to read.

References read().

template<typename S >
void CCfits::Column::read ( std::vector< S > &  vals,
long  first,
long  last 
) [inline]

Retrieve data from a scalar column into a std::vector.

This and the following functions perform implicit data conversions. An exception will be thrown if no conversion exists.

Parameters:
vals The output container. The function will resize this as necessary
first,last the span of row numbers to read.

Referenced by read().

template<typename S >
void CCfits::Column::readArrays ( std::vector< std::valarray< S > > &  vals,
long  first,
long  last,
S *  nullValue 
) [inline]

return a set of rows of a vector column into a container, setting undefined values

Parameters:
vals The output container. The function will resize this as necessary
first,last the span of row numbers to read.
nullValue pointer to integer value regarded as undefined

References isRead(), CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::readArrays ( std::vector< std::valarray< S > > &  vals,
long  first,
long  last 
) [inline]

return a set of rows of a vector column into a vector of valarrays

Parameters:
vals The output container. The function will resize this as necessary
first,last the span of row numbers to read.

void CCfits::Column::readData ( long  firstRow = 1,
long  nelements = 1,
long  firstElem = 1 
) [pure virtual]

read method.

Parameters:
firstRow The first row to be read
nelements The number of elements to read
firstElem The number of the element on the first row to start at (ignored for scalar columns)

Referenced by CCfits::BinTable::readData(), and CCfits::AsciiTable::readData().

int CCfits::Column::rows (  )  const

return the number of rows in the table.

return number of rows in the Column

References CCfits::Table::rows().

Referenced by read().

double CCfits::Column::scale (  )  const [inline]

get TSCALn value

TSCALn is used to convert a data array represented on disk in integer format as floating. Useful for compact storage of digitized data.

template<typename S >
void CCfits::Column::write ( S *  indata,
long  nElements,
const std::vector< long > &  vectorLengths,
long  firstRow 
) [inline]

write a C-array of values of size nElements into a vector column with specified number of entries written per row.

Intended for writing a varying number of elements to multiple rows in a vector column, this may be used for either variable or fixed-width columns. See the indata valarray version of this function for a complete description.

References write().

template<typename S >
void CCfits::Column::write ( const std::vector< S > &  indata,
const std::vector< long > &  vectorLengths,
long  firstRow 
) [inline]

write a vector of values into a column with specified number of entries written per row.

Intended for writing a varying number of elements to multiple rows in a vector column, this may be used for either variable or fixed-width columns. See the indata valarray version of this function for a complete description.

References write().

template<typename S >
void CCfits::Column::write ( const std::valarray< S > &  indata,
const std::vector< long > &  vectorLengths,
long  firstRow 
) [inline]

write a valarray of values into a column with specified number of entries written per row.

Data are written into vectorLengths.size() rows, with vectorLength[n] elements written to row n+firstRow -1. Although primarily intended for wrapping calls to multiple variable-width vector column rows, it may also be used to write a variable number of elements to fixed-width column rows.

When writing to fixed-width column rows, if the number of elements sent to a particular row are fewer than the column's repeat value, the remaining elements in the row will not be modified.

Since cfitsio does not support null value processing for variable width columns this function and its variants do not have version which process undefined values

Parameters:
indata The data to be written
vectorLengths the number of elements to write to each successive row.
firstRow the first row to be written.

References CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::write ( S *  indata,
long  nElements,
long  nRows,
long  firstRow,
S *  nullValue 
) [inline]

write a C array of values into a range of rows of a vector column, processing undefined values.

see version without undefined processing for details.

References write().

template<typename S >
void CCfits::Column::write ( const std::vector< S > &  indata,
long  nRows,
long  firstRow,
S *  nullValue 
) [inline]

write a vector of values into a range of rows of a vector column, processing undefined values

see version without undefined processing for details.

References write().

template<typename S >
void CCfits::Column::write ( const std::valarray< S > &  indata,
long  nRows,
long  firstRow,
S *  nullValue 
) [inline]

write a valarray of values into a range of rows of a vector column.

see version without undefined processing for details.

References CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::write ( S *  indata,
long  nElements,
long  nRows,
long  firstRow 
) [inline]

write a C array of values into a range of rows of a vector column

Details are as for vector input; only difference is the need to supply the size of the C-array.

Parameters:
indata The data to be written.
nElements The size of indata
nRows the number of rows to which to write the data.
firstRow The first row to be written

References write().

template<typename S >
void CCfits::Column::write ( const std::vector< S > &  indata,
long  nRows,
long  firstRow 
) [inline]

write a vector of values into a range of rows of a vector column

The primary use of this is for fixed width columns, in which case Column's repeat attribute is used to determine how many elements are written to each row; if indata.size() is too small an exception will be thrown. If the column is variable width, the call will write indata.size()/nRows elements to each row.

Parameters:
indata The data to be written.
nRows the number of rows to which to write the data.
firstRow The first row to be written

References write().

template<typename S >
void CCfits::Column::write ( const std::valarray< S > &  indata,
long  nRows,
long  firstRow 
) [inline]

write a valarray of values into a range of rows of a vector column.

The primary use of this is for fixed width columns, in which case Column's repeat attribute is used to determine how many elements are written to each row; if indata.size() is too small an exception will be thrown. If the column is variable width, the call will write indata.size()/nRows elements to each row.

Parameters:
indata The data to be written.
nRows the number of rows to which to write the data.
firstRow The first row to be written

References write().

template<typename S >
void CCfits::Column::write ( S *  indata,
long  nRows,
long  firstRow,
S *  nullValue 
) [inline]

write a C array into a scalar Column, processing undefined values.

Parameters:
indata The data to be written.
nRows The size of the data array to be written
firstRow The first row to be written
nullValue Pointer to the value in the input array to be set to undefined values

References write().

template<typename S >
void CCfits::Column::write ( const std::valarray< S > &  indata,
long  firstRow,
S *  nullValue 
) [inline]

write a valarray of values into a scalar column starting with firstRow with undefined values set to nullValue.

Parameters:
indata The data to be written.
firstRow The first row to be written
nullValue Pointer to the value in the input array to be set to undefined values

References write().

template<typename S >
void CCfits::Column::write ( const std::vector< S > &  indata,
long  firstRow,
S *  nullValue 
) [inline]

write a vector of values into a scalar column starting with firstRow with undefined values set to nullValue.

Parameters:
indata The data to be written.
firstRow The first row to be written
nullValue Pointer to the value in the input array to be set to undefined values

References CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::write ( S *  indata,
long  nRows,
long  firstRow 
) [inline]

write a C array of size nRows into a scalar Column starting with row firstRow.

Parameters:
indata The data to be written.
nRows The size of the data array to be written
firstRow The first row to be written

References write().

template<typename S >
void CCfits::Column::write ( const std::valarray< S > &  indata,
long  firstRow 
) [inline]

write a valarray of values into a scalar column starting with firstRow

Parameters:
indata The data to be written.
firstRow The first row to be written

References write().

template<typename S >
void CCfits::Column::write ( const std::vector< S > &  indata,
long  firstRow 
) [inline]

write a vector of values into a scalar column starting with firstRow

Parameters:
indata The data to be written.
firstRow The first row to be written

Referenced by write().

template<typename S >
void CCfits::Column::writeArrays ( const std::vector< std::valarray< S > > &  indata,
long  firstRow,
S *  nullValue 
) [inline]

write a vector of valarray objects to the column, starting at row firstRow >= 1, processing undefined values

see version without undefined processing for details.

References CCfits::ExtHDU::makeThisCurrent(), name(), parent(), and type().

template<typename S >
void CCfits::Column::writeArrays ( const std::vector< std::valarray< S > > &  indata,
long  firstRow 
) [inline]

write a vector of valarray objects to the column, starting at row firstRow >= 1

Intended for writing a varying number of elements to multiple rows in a vector column, this may be used for either variable or fixed-width columns. When writing to fixed-width column rows, if the number of elements sent to a particular row are fewer than the column's repeat value, the remaining elements in the row will not be modified.

Parameters:
indata The data to be written
firstRow the first row to be written.

double CCfits::Column::zero (  )  const [inline]

get TZEROn value

TZEROn is an integer offset used in the implementation of unsigned data


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

Generated on Mon Dec 15 11:39:46 2008 for CCfits by  doxygen 1.5.7.1