Abstract base class for Column objects. More...

#include <Column.h>

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

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. More...

virtual	~Column ()
	destructor.

template<typename T >
void	addNullValue (T nullVal)
	Set the TNULLn keyword for the column. More...

const String &	dimen () const
	return TDIMn keyword More...

const String &	display () const
	return TDISPn keyword More...

const String &	format () const
	return TFORMn keyword More...

template<typename T >
bool	getNullValue (T *nullVal) const
	Get the value of the TNULLn keyword for the column. More...

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

const String &	name () const
	return name of Column (TTYPEn keyword)

Table *	parent () const
	return a pointer to the Table which owns this Column

template<typename S >
void	read (std::valarray< S > &vals, long first, long last)
	Retrieve data from a scalar column into a std::valarray. More...

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, applying nullValue when relevant. More...

template<typename S >
void	read (std::valarray< S > &vals, long rows)
	return a single row of a vector column into a std::valarray More...

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 More...

template<typename S >
void	read (std::vector< S > &vals, long first, long last)
	Retrieve data from a scalar column into a std::vector. More...

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>, applying nullValue when relevant. More...

template<typename S >
void	read (std::vector< S > &vals, long rows)
	return a single row of a vector column into a std::vector More...

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 More...

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 More...

virtual void	readData (long firstRow, long nelements, long firstElem=1)=0
	Read (or reread) data from the disk into the Column object's internal arrays. More...

size_t	repeat () const
	get the repeat count for the rows

void	resetRead ()
	reset the Column's isRead flag to false More...

int	rows () const
	return the number of rows in the table. More...

double	scale () const
	get TSCALn value More...

virtual void	setDimen ()
	set the TDIMn keyword.

void	setDisplay ()
	set the TDISPn keyword

ValueType	type () const
	returns the data type of the column

const String &	unit () const
	get units of data in Column (TUNITn keyword)

bool	varLength () const
	boolean, set to true if Column has variable length vector rows.

long	width () const
	return column data width

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. More...

template<typename S >
void	write (const std::valarray< S > &indata, long firstRow)
	write a valarray of values into a scalar column starting with firstRow More...

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, replacing elements equal to nullValue with the FITS null value. More...

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. More...

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. More...

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. More...

template<typename S >
void	write (const std::vector< S > &indata, long firstRow)
	write a vector of values into a scalar column starting with firstRow More...

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, replacing elements equal to nullValue with the FITS null value. More...

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 More...

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 More...

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. More...

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 More...

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. More...

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. More...

template<typename S >
void	write (S indata, long nRows, long firstRow, S nullValue)
	write a C array into a scalar Column, processing undefined values. More...

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 More...

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 More...

double	zero () const
	get TZEROn value More...

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 More...

	Column (Table *p=0)
	Simple constructor to be called by subclass reading ctors.

const String &	comment () const
	retrieve comment for Column

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.

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

◆ Column() [1/2]

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.

◆ Column() [2/2]

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.

Member Function Documentation

◆ addNullValue()

template<typename T >

void CCfits::Column::addNullValue ( T nullVal )

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 value is used).

◆ dimen()

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.

◆ display()

const String & CCfits::Column::display ( ) const

inline

return TDISPn keyword

TDISPn is suggested format for output of column data.

◆ format()

const String & CCfits::Column::format ( ) const

inline

return TFORMn keyword

TFORMn specifies data format stored in disk file.

◆ getNullValue()

template<typename T >

bool CCfits::Column::getNullValue ( T * nullVal ) const

Get the value of the TNULLn keyword for the column.

Only relevant for integer valued columns. If the TNULLn keyword is present, its value will be written to *nullVal and the function returns true. If the keyword is not found or its value is undefined, the function returns false and *nullVal is not modified.

Parameters

nullVal A pointer to the variable for storing the TNULLn value.

◆ read() [1/7]

template<typename S >

void CCfits::Column::read	(	std::valarray< S > &	vals,
		long	first,
		long	last
	)

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.

◆ read() [2/7]

template<typename S >

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

Retrieve data from a scalar column into a std::valarray, applying nullValue when relevant.

If both nullValue and *nullValue are not 0, then any undefined values in the file will be converted to *nullValue when copied into the vals valarray. 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 value to be applied to undefined elements.

◆ read() [3/7]

template<typename S >

void CCfits::Column::read	(	std::valarray< S > &	vals,
		long	row
	)

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

Parameters

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

◆ read() [4/7]

template<typename S >

void CCfits::Column::read	(	std::valarray< S > &	vals,
		long	rows,
		S *	nullValue
	)

return a single row of a vector column into a std::valarray, setting undefined values

return a single row of a vector column into a std::vector, setting undefined values

◆ read() [5/7]

template<typename S >

void CCfits::Column::read	(	std::vector< S > &	vals,
		long	first,
		long	last
	)

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.

◆ read() [6/7]

template<typename S >

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

Retrieve data from a scalar column into a std::vector>, applying nullValue when relevant.

If both nullValue and *nullValue are not 0, then any undefined values in the file will be converted to *nullValue when copied into the vals vector. 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 value to be applied to undefined elements.

◆ read() [7/7]

template<typename S >

void CCfits::Column::read	(	std::vector< S > &	vals,
		long	row
	)

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

Parameters

vals	The output vector object
row	The row number to be retrieved (starting at 1).

◆ readArrays() [1/2]

template<typename S >

void CCfits::Column::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

Parameters

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

◆ readArrays() [2/2]

template<typename S >

void CCfits::Column::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

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

◆ readData()

void CCfits::Column::readData	(	long	firstRow = `1`,
		long	nelements = `1`,
		long	firstElem = `1`
	)

pure virtual

Read (or reread) data from the disk into the Column object's internal arrays.

This function normally does not need to be called. See the resetRead function for an alternative way of performing a reread from disk.

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)

◆ resetRead()

void CCfits::Column::resetRead ( )

inline

reset the Column's isRead flag to false

This forces the data to be reread from the disk the next time a read command is called on the Column, rather than simply retrieving the data already stored in the Column object's internal arrays. This may be useful for example if trying to reread a Column using a different nullValue argument than for an earlier read.

◆ rows()

int CCfits::Column::rows ( ) const

return the number of rows in the table.

return number of rows in the Column

◆ scale()

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.

◆ write() [1/15]

template<typename S >

void CCfits::Column::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.

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.

◆ write() [2/15]

template<typename S >

void CCfits::Column::write	(	const std::valarray< S > &	indata,
		long	firstRow
	)

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

◆ write() [3/15]

template<typename S >

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

write a valarray of values into a scalar column starting with firstRow, replacing elements equal to nullValue with the FITS null value.

If nullValue is not 0, the appropriate FITS null value will be substituted for all elements of indata equal to *nullValue. For integer type columns there must be a pre-existing TNULLn keyword to define the FITS null value, otherwise a FitsError exception is thrown. For floating point columns, the FITS null is the IEEE NaN (Not-a-Number) value. See the cfitsio fits_write_colnull function documentation for more details.

Parameters

indata	The data to be written.
firstRow	The first row to be written
nullValue	Pointer to the value for which equivalent indata elements will be replaced in the file with the appropriate FITS null value.

◆ write() [4/15]

template<typename S >

void CCfits::Column::write	(	const std::valarray< S > &	indata,
		long	nRows,
		long	firstRow
	)

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

◆ write() [5/15]

template<typename S >

void CCfits::Column::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.

see version without undefined processing for details.

◆ write() [6/15]

template<typename S >

void CCfits::Column::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.

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.

◆ write() [7/15]

template<typename S >

void CCfits::Column::write	(	const std::vector< S > &	indata,
		long	firstRow
	)

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

◆ write() [8/15]

template<typename S >

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

write a vector of values into a scalar column starting with firstRow, replacing elements equal to nullValue with the FITS null value.

If nullValue is not 0, the appropriate FITS null value will be substituted for all elements of indata equal to *nullValue. For integer type columns there must be a pre-existing TNULLn keyword to define the FITS null value, otherwise a FitsError exception is thrown. For floating point columns, the FITS null is the IEEE NaN (Not-a-Number) value. See the cfitsio fits_write_colnull function documentation for more details.

Parameters

indata	The data to be written.
firstRow	The first row to be written
nullValue	Pointer to the value for which equivalent indata elements will be replaced in the file with the appropriate FITS null value.

◆ write() [9/15]

template<typename S >

void CCfits::Column::write	(	const std::vector< S > &	indata,
		long	nRows,
		long	firstRow
	)

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

◆ write() [10/15]

template<typename S >

void CCfits::Column::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

see version without undefined processing for details.

◆ write() [11/15]

template<typename S >

void CCfits::Column::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.

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.

◆ write() [12/15]

template<typename S >

void CCfits::Column::write	(	S *	indata,
		long	nElements,
		long	nRows,
		long	firstRow
	)

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

◆ write() [13/15]

template<typename S >

void CCfits::Column::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.

see version without undefined processing for details.

◆ write() [14/15]

template<typename S >

void CCfits::Column::write	(	S *	indata,
		long	nRows,
		long	firstRow
	)

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

◆ write() [15/15]

template<typename S >

void CCfits::Column::write	(	S *	indata,
		long	nRows,
		long	firstRow,
		S *	nullValue
	)

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

◆ writeArrays() [1/2]

template<typename S >

void CCfits::Column::writeArrays	(	const std::vector< std::valarray< S > > &	indata,
		long	firstRow
	)

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.

◆ writeArrays() [2/2]

template<typename S >

void CCfits::Column::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

see version without undefined processing for details.

◆ zero()

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:

Column.h
Column.cxx
ColumnT.h

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Column() [1/2]

◆ Column() [2/2]

Member Function Documentation

◆ addNullValue()

◆ dimen()

◆ display()

◆ format()

◆ getNullValue()

◆ read() [1/7]

◆ read() [2/7]

◆ read() [3/7]

◆ read() [4/7]

◆ read() [5/7]

◆ read() [6/7]

◆ read() [7/7]

◆ readArrays() [1/2]

◆ readArrays() [2/2]

◆ readData()

◆ resetRead()

◆ rows()

◆ scale()

◆ write() [1/15]

◆ write() [2/15]

◆ write() [3/15]

◆ write() [4/15]

◆ write() [5/15]

◆ write() [6/15]

◆ write() [7/15]

◆ write() [8/15]

◆ write() [9/15]

◆ write() [10/15]

◆ write() [11/15]

◆ write() [12/15]

◆ write() [13/15]

◆ write() [14/15]

◆ write() [15/15]

◆ writeArrays() [1/2]

◆ writeArrays() [2/2]

◆ zero()