#include <BintableColumns.h>

Class Description

Column-wise reader-writer for the binary table data unit.

For flexibility, this handler class provides many methods to read and write data, but they are really different flavors of the following few services:

Read/write a single column completely;
Read/write a segment (i.e. consecutive rows) of a single column;
Read/write a sequence of columns completely;
Read/write a sequence of column segments (same row interval for all the columns).

For reading, new columns can be either returned, or existing columns can be filled. Columns can be specified either by their name or index; using index is faster because names are internally converted to indices anyway, via a read operation. When filling an existing column, the name of the column can also be used to specify the column to be read.

When writing, if more rows are needed, they are automatically filled with zeros.

In the Fits file, binary tables are written row-wise, i.e. values of a row are contiguous in the file. As of today, in memory, values are stored column-wise (in Column) for convenience, to avoid heterogeneous containers as much as possible. This implies that read and write functions jump from one disk or memory adress to another all the time, which costs a lot of resources. To save on I/Os, an internal buffer is instantiated by CFitsIO. As opposed to methods to read and write a single column, methods to read and write several columns take advantage of the internal buffer. It is therefore much more efficient to use those than to chain several calls to methods for single columns. Depending on the table width, the speed-up can reach several orders of magnitude.

Method to read and write columns conform to the following naming convention:

Start with read or write;
Contain Segment for reading or writing segments;
Contain Seq for reading or writing several columns;
Contain To for filling an existing column. For example, readSegmentSeqTo() is a method to read a sequence of segments into existing Column objects.

For working with segments, two intervals can generally be specified:

That in the binary table, which is specified as a rows or firstRow parameter;
That in the Column object, for example using a PtrColumn as a view of the data container.

For example, assume we want to concatenate rows 11 to 50 of a 3-column binary table into some std::vector. Here is an option:

// Specs
const Segment rows { 11, 50 };
const long columnCount = 3;
const long rowCount = rows.size();
 
// Data container for all columns
std::vector<float> data(rowCount * columnCount);
 
// Contiguous views
PtrColumn<float> one({ "ONE", "", 1 }, rowCount, &data[0]);
PtrColumn<float> two({ "TWO", "", 1 }, rowCount, &data[rowCount]);
PtrColumn<float> three({ "THREE", "", 1 }, rowCount, &data[rowCount * 2]);
 
// In-place reading
columnCount.readSegmentSeqTo(rows, one, two, three);

Public Member Functions
Column metadata.
long	readColumnCount () const
	Get the current number of columns.

long	readRowCount () const
	Get the current number of rows.

long	readBufferRowCount () const
	Get the number of rows in the internal buffer. More...

bool	has (const std::string &name) const
	Check whether the HDU contains a given column. More...

long	readIndex (const std::string &name) const
	Get the index of the column with given name.

std::vector< long >	readIndices (const std::vector< std::string > &names) const
	Get the indices of the columns with given names.

std::string	readName (long index) const
	Get the name of the column with given index.

std::vector< std::string >	readAllNames () const
	Get the names of all the columns.

void	rename (const std::string &name, const std::string &newName) const
	Rename the column with given name. More...

void	rename (long index, const std::string &newName) const
	Rename the column with given index. More...

Read a single column.
template<typename T >
ColumnInfo< T >	readInfo (const std::string &name) const
	Read the info of a column.

template<typename T >
ColumnInfo< T >	readInfo (long index) const
	Read the info of a column. More...

template<typename T >
VecColumn< T >	read (const std::string &name) const
	Read the column with given name. More...

template<typename T >
VecColumn< T >	read (long index) const
	Read the column with given index. More...

template<typename T >
void	readTo (Column< T > &column) const
	Read a column into an existing `Column`. More...

template<typename T >
void	readTo (const std::string &name, Column< T > &column) const
	Read the column with given name into an existing `Column`. More...

template<typename T >
void	readTo (long index, Column< T > &column) const
	Read the column with given index into an existing `Column`. More...

Read a single column segment.
template<typename T >
VecColumn< T >	readSegment (const Segment &rows, const std::string &name) const
	Read the segment of a column specified by its name. More...

template<typename T >
VecColumn< T >	readSegment (const Segment &rows, long index) const
	Read the segment of a column specified by its index. More...

template<typename T >
void	readSegmentTo (FileMemSegments rows, Column< T > &column) const
	Read the segment of a column into an existing `Column`. More...

template<typename T >
void	readSegmentTo (FileMemSegments rows, const std::string &name, Column< T > &column) const
	Read the segment of a column specified by its name into an existing `Column`. More...

template<typename T >
void	readSegmentTo (FileMemSegments rows, long index, Column< T > &column) const
	Read the segment of a column specified by its index into an existing `Column`. More...

Read a sequence of columns.
template<typename... Ts>
std::tuple< VecColumn< Ts >... >	readSeq (const Named< Ts > &... names) const
	Read the columns with given names. More...

template<typename... Ts>
std::tuple< VecColumn< Ts >... >	readSeq (const Indexed< Ts > &... indices) const
	Read the columns with given indices. More...

template<typename TSeq >
void	readSeqTo (TSeq &&columns) const
	Read a sequence of columns into existing `Column`s. More...

template<typename... Ts>
void	readSeqTo (Column< Ts > &... columns) const
	Read a sequence of columns into existing `Column`s. More...

template<typename TSeq >
void	readSeqTo (const std::vector< std::string > &names, TSeq &&columns) const
	Read a sequence of columns with given names into existing `Column`s. More...

template<typename... Ts>
void	readSeqTo (const std::vector< std::string > &names, Column< Ts > &... columns) const
	Read a sequence of columns with given names into existing `Column`s. More...

template<typename TSeq >
void	readSeqTo (const std::vector< long > &indices, TSeq &&columns) const
	Read a sequence of columns with given indices into existing `Column`s. More...

template<typename... Ts>
void	readSeqTo (const std::vector< long > &indices, Column< Ts > &... columns) const
	Read a sequence of columns with given indices into existing `Column`s. More...

Read a sequence of column segments.
template<typename... Ts>
std::tuple< VecColumn< Ts >... >	readSegmentSeq (const Segment &rows, const Named< Ts > &... names) const
	Read segments of columns specified by their names. More...

template<typename... Ts>
std::tuple< VecColumn< Ts >... >	readSegmentSeq (const Segment &rows, const Indexed< Ts > &... indices) const
	Read segments of columns specified by their indices. More...

template<typename TSeq >
void	readSegmentSeqTo (FileMemSegments rows, TSeq &&columns) const
	Read segments of columns into existing `Column`s. More...

template<typename... Ts>
void	readSegmentSeqTo (FileMemSegments rows, Column< Ts > &... columns) const
	Read segments of columns into existing `Column`s. More...

template<typename TSeq >
void	readSegmentSeqTo (FileMemSegments rows, const std::vector< std::string > &names, TSeq &&columns) const
	Read segments of columns specified by their names into existing `Column`s. More...

template<typename... Ts>
void	readSegmentSeqTo (FileMemSegments rows, const std::vector< std::string > &names, Column< Ts > &... columns) const
	Read segments of columns specified by their names into existing `Column`s. More...

template<typename TSeq >
void	readSegmentSeqTo (FileMemSegments rows, const std::vector< long > &indices, TSeq &&columns) const
	Read segments of columns specified by their indices into existing `Column`s. More...

template<typename... Ts>
void	readSegmentSeqTo (FileMemSegments rows, const std::vector< long > &indices, Column< Ts > &... columns) const
	Read segments of columns specified by their indices into existing `Column`s. More...

Write a single column.
template<typename T >
void	write (const Column< T > &column) const
	Write a column. More...

template<typename T >
void	init (const ColumnInfo< T > &info, long index=-1) const
	Append or insert a column, which was not previously initialized. More...

void	remove (const std::string &name) const
	Remove a column specified by its name.

void	remove (long index) const
	Remove a column specified by its index.

Write a single column segment.
template<typename T >
void	writeSegment (FileMemSegments rows, const Column< T > &column) const
	Write a column segment. More...

Write a sequence of columns.
template<typename TSeq >
void	writeSeq (TSeq &&columns) const
	Write several columns.

template<typename... Ts>
void	writeSeq (const Column< Ts > &... columns) const
	Write several columns. More...

template<typename TSeq >
void	initSeq (long index, TSeq &&infos) const
	Append or insert a sequence of columns, which were not previously initialized. More...

template<typename... Ts>
void	initSeq (long index, const ColumnInfo< Ts > &... infos) const
	Append or insert a sequence of columns, which were not previously initialized. More...

void	removeSeq (const std::vector< std::string > &names) const
	Remove a sequence of columns specified by their names.

void	removeSeq (const std::vector< long > &indices) const
	Remove a sequence of columns specified by their indices.

Write a sequence of column segments.
template<typename TSeq >
void	writeSegmentSeq (FileMemSegments rows, TSeq &&columns) const
	Write a sequence of segments. More...

template<typename... Ts>
void	writeSegmentSeq (FileMemSegments rows, const Column< Ts > &... columns) const
	Write a sequence of segments. More...

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

EleFits/EleFits/BintableColumns.h

Class Description

Public Member Functions