#include <BintableColumns.h>

Detailed 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 just 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:

Starts with read or write;
Contains segment for reading or writing segments;
Contains n for reading or writing several columns;
Contains to for filling an existing column.

For example, read_n_segments_to() is a method to read a sequence of segments into existing Column objects.

For working with segments, row indices are specified as Segments or FileMemSegments.

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 column_count = 3;
const long row_count = rows.size();
 
// Data container for all columns
std::vector<float> data(row_count * column_count);
 
// Contiguous views
PtrColumn<float> one({"ONE", "", 1}, row_count, &data[0]);
PtrColumn<float> two({"TWO", "", 1}, row_count, &data[row_count]);
PtrColumn<float> three({"THREE", "", 1}, row_count, &data[row_count * 2]);
 
// In-place reading
columns.read_n_segments_to(rows, one, two, three);

Examples: EleFitsBintableExample.cpp, and EleFitsTutorial.cpp.

Public Member Functions
Properties

long	read_column_count () const
	Get the current number of columns.

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

long	read_buffer_row_count () 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	read_index (const std::string &name) const
	Get the index of the column with given name.

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

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

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

void	update_name (ColumnKey key, const std::string &name) const
	Rename the column with given name or index. More...

Read a single column
template<typename T , long N = 1>
ColumnInfo< T, N >	read_info (ColumnKey key) const
	Read the info of a column. More...

template<typename T , long N = 1>
VecColumn< T, N >	read (ColumnKey key) const
	Read the column with given name or index. More...

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

template<typename TColumn >
void	read_to (ColumnKey key, TColumn &column) const
	Read the column with given name or index into an existing `Column`. More...

Read a single column segment
template<typename T , long N = 1>
VecColumn< T, N >	read_segment (const Segment &rows, ColumnKey key) const
	Read the segment of a column specified by its name or index. More...

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

template<typename TColumn >
void	read_segment_to (FileMemSegments rows, ColumnKey key, TColumn &column) const
	Read the segment of a column specified by its name or index into an existing `Column`. More...

Read a sequence of columns
template<typename TKey , typename... Ts>
std::tuple< VecColumn< Ts, 1 >... >	read_n (const TypedKey< Ts, TKey > &... keys) const
	Read a tuple of columns with given names or indices. More...

template<typename T , long N = 1>
std::vector< VecColumn< T, N > >	read_n (std::vector< ColumnKey > keys) const
	Read a vector of columns with given names or indices. More...

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

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

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

template<typename... TColumns>
void	read_n_to (std::vector< ColumnKey > keys, TColumns &... columns) const
	Read a sequence of columns with given names or indices into existing `Column`s. More...

Read a sequence of column segments
template<typename TKey , typename... Ts>
std::tuple< VecColumn< Ts, 1 >... >	read_n_segments (Segment rows, const TypedKey< Ts, TKey > &... keys) const
	Read segments of columns specified by their names or indices. More...

template<typename T , long N = 1>
std::vector< VecColumn< T, N > >	read_n_segments (Segment rows, std::vector< ColumnKey > keys) const
	Read segments of columns specified by their names or indices. More...

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

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

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

template<typename... TColumns>
void	read_n_segments_to (FileMemSegments rows, std::vector< ColumnKey > keys, TColumns &... columns) const
	Read segments of columns specified by their names or indices into existing `Column`s. More...

Write a single column
template<typename TColumn >
void	write (const TColumn &column) const
	Write a column.

template<typename TInfo >
void	append_null (const TInfo &info) const
	Append a null-initialized column.

template<typename TColumn >
void	append (const TColumn &column) const
	Append and fill a column.

template<typename TInfo >
void	insert_null (long index, const TInfo &info) const
	Insert a null-initialized column. More...

template<typename TColumn >
void	insert (long index, const TColumn &column) const
	Insert and fill a column.

void	remove (ColumnKey key) const
	Remove a column specified by its name or index.

Write a single column segment
template<typename TColumn >
void	write_segment (FileMemSegments rows, const TColumn &column) const
	Write a column segment. More...

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

template<typename... TColumns>
void	write_n (const TColumns &... columns) const
	Write several columns. More...

template<typename... TInfos>
void	append_n_null (TInfos &&... infos) const
	Append a sequence of null-initialized columns. More...

template<typename TSeq >
void	insert_n_null (long index, TSeq &&infos) const
	Insert a sequence of null-initialized columns. More...

template<typename... TInfos>
void	insert_n_null (long index, const TInfos &... infos) const
	Insert a sequence of null-initialized columns. More...

void	remove_n (std::vector< ColumnKey > keys) const
	Remove a sequence of columns specified by their names or indices.

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

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

Deprecated

long	readColumnCount () const

long	readRowCount () const

long	readBufferRowCount () const

long	readIndex (const std::string &name) const

std::vector< long >	readIndices (const std::vector< std::string > &names) const

std::string	readName (long index) const

std::vector< std::string >	readAllNames () const

template<typename T , long N = 1>
ColumnInfo< T, N >	readInfo (ColumnKey key) const

void	rename (ColumnKey key, const std::string &name) const

template<typename... TArgs>
void	readTo (TArgs &&... args)

template<typename T , long N = 1>
VecColumn< T, N >	readSegment (const Segment &rows, ColumnKey key) const

template<typename... TArgs>
void	readSegmentTo (TArgs &&... args) const

template<typename TKey , typename... Ts>
std::tuple< VecColumn< Ts, 1 >... >	readSeq (const TypedKey< Ts, TKey > &... keys) const

template<typename T , long N = 1>
std::vector< VecColumn< T, N > >	readSeq (std::vector< ColumnKey > keys) const

template<typename... TArgs>
void	readSeqTo (TArgs &... args) const

template<typename TKey , typename... Ts>
std::tuple< VecColumn< Ts, 1 >... >	readSegmentSeq (Segment rows, const TypedKey< Ts, TKey > &... keys) const

template<typename T , long N = 1>
std::vector< VecColumn< T, N > >	readSegmentSeq (Segment rows, const std::vector< ColumnKey > keys) const

template<typename... TArgs>
void	readSegmentSeqTo (TArgs &&... args) const

template<typename TInfo >
void	init (const TInfo &info, long index=-1) const

template<typename TColumn >
void	writeSegment (FileMemSegments rows, const TColumn &column) const

template<typename... TArgs>
void	writeSeq (const TArgs &... args) const

template<typename... TArgs>
void	initSeq (TArgs &&... args) const

void	removeSeq (std::vector< ColumnKey > keys) const

template<typename... TArgs>
void	writeSegmentSeq (TArgs &&... args) const

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

EleFits/EleFits/BintableColumns.h

Detailed Description

Public Member Functions