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, field shape and value type.

Template Parameters

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

Binary tables can be seen as a sequence of columns made of consecutive fields. Field values are not necessarily simple types: they can be either string, scalar, vector or multidimensional. Yet, all the fields 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 field shape (see below).

The number of values per field, 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	repeat_count()	element_count()	shape
String	std::string	1	> max number of characters	1	{repeat_count()}
Scalar	Not std::string	1	1	1	{1}
Vector	Not std::string	1	> 1	= repeat count	{repeat_count()}
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 element_count() = 1 and repeat_count() > 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> string_info("String", "", 6);
std::string string_data[] = {"ZERO", "ONE", "TWO", "THREE"};
 
ColumnInfo<int> scalar_info("Scalar");
int scalar_data[] = {0, 1, 2, 3};
 
ColumnInfo<int> vector_info("Vector", "", 3);
int vector_data[] = {
    00, 01, 02,
    10, 11, 12,
    20, 21, 22,
    30, 31, 32};
 
ColumnInfo<int, 2> multidim_info("Multidim", "", {3, 2});
int multidim_data[] = {
    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

Examples

EleFitsBintableExample.cpp.

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, Position< N > s)
	Create a column info with given field shape. More...
	ColumnInfo (std::string n="", std::string u="", long r=1)
	Create a column info with given field repeat count. More...
long	element_count () const
	Get the number of elements per field.
long	elementCount () const
long	repeat_count () const
	Get the repeat count.
long	repeatCount () const

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

Related Functions
(Note that these are not member functions.)
template<typename T , typename... Longs>
ColumnInfo< T, sizeof...(Longs)>	make_column_info (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 >	make_column_info (const std::string &name, const std::string &unit="")
	Scalar column specialization.
template<typename T , long N>
bool	operator!= (const ColumnInfo< T, N > &lhs, const ColumnInfo< T, N > &rhs)
	ColumnInfo unequality operator.
template<typename T , long N>
bool	operator== (const ColumnInfo< T, N > &lhs, const ColumnInfo< T, N > &rhs)
	ColumnInfo equality operator.

---

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

• EleFitsData/EleFitsData/ColumnInfo.h