ColumnInfo< T, N > Struct Template Reference

#include <ColumnInfo.h>

Detailed Description

template<typename T, long N = 1>
struct Euclid::Fits::ColumnInfo< T, N >

Column informations, i.e. name, unit, entry shape and value type.

Template Parameters

T	The value type
N	The dimension (number of axes per entry)

Binary tables can be seen as a sequence of columns made of consecutive entries. Entry values are not necessarily simple types: they can be either string, scalar, vector or multidimensional. Yet, all the entries of one column have the same properties. The column informations consist in:

• The value type as template parameter T;
• The dimension (number of axes) as template parameter N;
• The column name;
• The column unit;
• The entry shape (see below).

The number of values per entry, named repeat count, is the shape size. Here is a table which summarizes the properties of each column type – and more details follow.

Category	T	N	repeatCount()	elementCount()	shape
String	std::string	1	> max number of characters	1	{repeatCount()}
Scalar	Not std::string	1	1	1	{1}
Vector	Not std::string	1	> 1	= repeat count	{repeatCount()}
Multidimensional	Not std::string	-1 or > 1	= shape size	= shape size	Unconstrained

For string columns, the element count differs from the repeat count, in that the element count is the number of std::string objects stored in the column data container, while the repeat count is the number of characters allocated to each string in the FITS file. This results in elementCount() = 1 and repeatCount() > 1 (multidimensional string columns are not supported).

Example

Here is an example of a 4-row table with each column category:

Row	String	Scalar	Vector	Multidim
0	"ZERO"	0	00 01 02	000 001 002 010 011 012
1	"ONE"	1	10 11 12	100 101 102 110 111 112
2	"TWO"	2	20 21 22	200 201 202 210 211 212
3	"THREE"	3	30 31 32	300 301 302 310 311 312

For performance, the values are stored sequentially in a 1D array as follows:

ColumnInfo<std::string> stringInfo("String", "", 6);
std::string stringData[] = {"ZERO", "ONE", "TWO", "THREE"};
 
ColumnInfo<int> scalarInfo("Scalar");
int scalarData[] = {0, 1, 2, 3};
 
ColumnInfo<int> vectorInfo("Vector", "", 3);
int vectorData[] = {
    00, 01, 02,
    10, 11, 12,
    20, 21, 22,
    30, 31, 32};
 
ColumnInfo<int, 2> multidimInfo("Multidim", "", {3, 2});
int multidimData[] = {
    000, 001, 002, 010, 011, 012,
    100, 101, 102, 110, 111, 112,
    200, 201, 202, 210, 211, 212,
    300, 301, 302, 310, 311, 312};

Note

Since the values are stored sequentially even for vector columns, a scalar column can be "fold" into a vector column by just setting a repeat count greater than 1, and vice-versa. This trick allows writing scalar columns as vector columns, which is what CFITSIO recommends for performance. Indeed, with CFITSIO, it is much faster to write 1 row with a repeat count of 10,000 than 10,000 rows with a repeat count of 1. This is because binary tables are written row-wise in the FITS file.

CFITSIO uses an internal buffer, which can be exploited to optimize reading and writing. This is generally handled through the "iterator function" provided by CFITSIO.

Fortunately, this complexity is already embedded in EleFits internals: the buffer is used optimally when reading and writing several columns. In general, it is nearly as fast to read and write scalar columns as vector columns with EleFits. Therefore, users are encouraged to consider the repeat count as a meaningful value, rather than as an optimization trick.

See also

Column

Optimization and good practices

Public Types
using	Value = std::decay_t< T >
	The value decay type.

Static Public Attributes
static constexpr long	Dim = N
	The dimension parameter.

Public Member Functions
	ColumnInfo (std::string n="", std::string u="", long r=1)
	Create a column info with given entry repeat count. More...
	ColumnInfo (std::string n, std::string u, Position< N > s)
	Create a column info with given entry shape. More...
long	repeatCount () const
	Get the repeat count.
long	elementCount () const
	Get the number of elements per entry.

Public Attributes
std::string	name
	The column name.
std::string	unit
	The column unit.
Position< N >	shape
	The shape of one entry.

Related Functions
(Note that these are not member functions.)
template<typename T , long N>
bool	operator== (const ColumnInfo< T, N > &lhs, const ColumnInfo< T, N > &rhs)
	ColumnInfo equality operator.
template<typename T , long N>
bool	operator!= (const ColumnInfo< T, N > &lhs, const ColumnInfo< T, N > &rhs)
	ColumnInfo unequality operator.
template<typename T , typename... Longs>
ColumnInfo< T, sizeof...(Longs)>	makeColumnInfo (const std::string &name, const std::string &unit, Longs... shape)
	Shortcut to create column informations without specifying the dimension template parameters. More...
template<typename T >
ColumnInfo< T >	makeColumnInfo (const std::string &name, const std::string &unit="")
	Scalar column specialization.

---

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

• EleFitsData/EleFitsData/ColumnInfo.h