template<class verboseT = verbose::d>
class mx::fits::fitsHeader< verboseT >

Class to manage a FITS file metadata header and provide fast access to the cards by keyword.

Manages tasks such as insertion (avoiding duplicates), and keyword lookup.

The cards are stored in a std::list to preserve order, but a std::unordered_multimap is used to provide fast keyword lookup into the list.

Template Parameters

verboseT sets the error reporting verbosity

Definition at line 80 of file fitsHeader.hpp.

#include <ioutils/fits/fitsHeader.hpp>

Public Types
typedef std::list< fitsHeaderCard< verboseT > >	cardListT
	The list type.
typedef cardListT::iterator	headerIteratorT
	The iterator type for the cards list.
typedef std::unordered_multimap< std::string, headerIteratorT >	cardMapT
	The map type.
typedef cardMapT::value_type	cardMapValueT
	The value type for the card map.
typedef cardMapT::iterator	mapIteratorT
	The iterator type for the card map.

Public Member Functions
	fitsHeader ()
	Default c'tor.
	fitsHeader (const fitsHeader &head)
	Copy constructor.
	~fitsHeader ()
	Destructor.
fitsHeader &	operator= (const fitsHeader &head)
	Assignment operator.
headerIteratorT	begin ()
	Get iterator to the beginning of the cards list.
headerIteratorT	end ()
	Get iterator to the end of the cards list.
headerIteratorT	iterator (const std::string &keyword)
	Get iterator pointing to a specific element.
bool	empty ()
	Test whether the header is empty.
size_t	size ()
	Get number of cards currently stored in the header.
error_t	clear ()
	Clear all cards from the header.
size_t	count (const std::string &keyword)
	Get number of cards with a given keyword.
error_t	erase (const std::string &keyword)
	Erase card by keyword.
error_t	erase (headerIteratorT it)
	Erase card by iterator.
error_t	eraseStandardTop ()
	Erase the standard entries at the top of the header.
error_t	append (const fitsHeaderCard< verboseT > &card)
	Append a fitsHeaderCard to the end of the header.
error_t	append (const std::string &k, const char *v, const std::string &c)
	Append a string card to the end of the header, from the three components of a card.
template<typename typeT>
error_t	append (const std::string &k, const typeT &v, const std::string &c)
	Append a card to the end of the header, from the three components of a card.
template<typename typeT>
error_t	append (const std::string &k, const typeT &v)
	Append a card to the end of the header, from the components of a card with no comment.
error_t	append (const std::string &k)
	Append a card to the end of the header, with just a keyword.
error_t	append (fitsHeader &head)
	Append a fitsHeader to the end of the header.
error_t	insert_before (headerIteratorT it, fitsHeaderCard< verboseT > card)
	Insert a card before another card.
template<typename typeT>
error_t	insert_before (headerIteratorT it, const std::string &k, typeT v, const std::string &c)
	Insert a card before another card, specifying the card by its components.
template<typename typeT>
error_t	insert_before (headerIteratorT it, const std::string &k, typeT v)
	Insert a card before another card, specifying the card by its components.
error_t	insert_after (headerIteratorT it, fitsHeaderCard< verboseT > card)
	Insert a card after another card.
template<typename typeT>
error_t	insert_after (headerIteratorT it, const std::string &k, typeT v, const std::string &c)
	Insert a card after another card, specifying the card by its components.
template<typename typeT>
error_t	insert_after (headerIteratorT it, const std::string &k, typeT v)
	Insert a card after another card, specifying the card by its components.
fitsHeaderCard< verboseT > &	operator[] (const std::string &keyword)
	Card access by keyword operator.
const fitsHeaderCard< verboseT > &	operator[] (const std::string &keyword) const
	Card access by keyword operator (const version).

Protected Attributes
cardListT	m_cardList
	The storage for the FITS header cards.
cardMapT	m_cardMap
	This multimap allows for fast lookup by keyword.
fitsHeaderCard< verboseT >	m_emptyCard
	Card with empty keyword used as an error sentinel.

Member Typedef Documentation

◆ cardListT

template<class verboseT = verbose::d>

typedef std::list<fitsHeaderCard<verboseT> > mx::fits::fitsHeader< verboseT >::cardListT

The list type.

We use a list, rather than forward_list, so that append (insert at end) is constant time.

Definition at line 87 of file fitsHeader.hpp.

◆ cardMapT

template<class verboseT = verbose::d>

typedef std::unordered_multimap<std::string, headerIteratorT> mx::fits::fitsHeader< verboseT >::cardMapT

The map type.

Use unordered_multimap to allow multiple HISTORY and COMMENT properly, but be as efficient as possible.

Definition at line 95 of file fitsHeader.hpp.

◆ cardMapValueT

template<class verboseT = verbose::d>

typedef cardMapT::value_type mx::fits::fitsHeader< verboseT >::cardMapValueT

The value type for the card map.

Definition at line 98 of file fitsHeader.hpp.

◆ headerIteratorT

template<class verboseT = verbose::d>

typedef cardListT::iterator mx::fits::fitsHeader< verboseT >::headerIteratorT

The iterator type for the cards list.

Definition at line 90 of file fitsHeader.hpp.

◆ mapIteratorT

template<class verboseT = verbose::d>

typedef cardMapT::iterator mx::fits::fitsHeader< verboseT >::mapIteratorT

The iterator type for the card map.

Definition at line 101 of file fitsHeader.hpp.

Constructor & Destructor Documentation

◆ fitsHeader() [1/2]

template<class verboseT>

mx::fits::fitsHeader< verboseT >::fitsHeader ( )

Default c'tor.

Definition at line 297 of file fitsHeader.hpp.

Referenced by fitsHeader(), append(), and operator=().

◆ fitsHeader() [2/2]

template<class verboseT>

mx::fits::fitsHeader< verboseT >::fitsHeader ( const fitsHeader< verboseT > & head )

Copy constructor.

Parameters

head	The fitsHeader to copy

Definition at line 302 of file fitsHeader.hpp.

References fitsHeader(), and operator=().

◆ ~fitsHeader()

template<class verboseT>

mx::fits::fitsHeader< verboseT >::~fitsHeader ( )

Destructor.

Definition at line 308 of file fitsHeader.hpp.

References clear().

Member Function Documentation

◆ append() [1/6]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::append ( const fitsHeaderCard< verboseT > & card )

Append a fitsHeaderCard to the end of the header.

Parameters

[in] card the card to append

Definition at line 477 of file fitsHeader.hpp.

References mx::fits::fitsType(), mx::invalidarg, mx::fits::fitsHeaderCard< verboseT >::keyword(), m_cardList, m_cardMap, mx::internal::mxlib_error_report(), mx::noerror, mx::std_bad_alloc, mx::std_exception, and mx::fits::fitsHeaderCard< verboseT >::type().

◆ append() [2/6]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::append ( const std::string & k )

Append a card to the end of the header, with just a keyword.

Appends a headerCard with unknownType

Parameters

[in] k the keyword of the new card

Definition at line 604 of file fitsHeader.hpp.

References append(), and mxlib_error_return.

◆ append() [3/6]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::append	(	const std::string &	k,
		const char *	v,
		const std::string &	c )

Append a string card to the end of the header, from the three components of a card.

Parameters

[in]	k	the keyword of the new card
[in]	v	the value of the new card
[in]	c	the comment of the new card

Definition at line 610 of file fitsHeader.hpp.

References append(), and mxlib_error_return.

◆ append() [4/6]

template<class verboseT>

template<typename typeT>

error_t mx::fits::fitsHeader< verboseT >::append	(	const std::string &	k,
		const typeT &	v )

Append a card to the end of the header, from the components of a card with no comment.

Template Parameters

typeT is the data type of the value

Parameters

[in]	k	the keyword of the new card
[in]	v	the value of the new card

Definition at line 624 of file fitsHeader.hpp.

References append(), and mxlib_error_return.

◆ append() [5/6]

template<class verboseT>

template<typename typeT>

error_t mx::fits::fitsHeader< verboseT >::append	(	const std::string &	k,
		const typeT &	v,
		const std::string &	c )

Append a card to the end of the header, from the three components of a card.

Template Parameters

typeT is the data type of the value

Parameters

[in]	k	the keyword of the new card
[in]	v	the value of the new card
[in]	c	the comment of the new card

Definition at line 617 of file fitsHeader.hpp.

References append(), and mxlib_error_return.

◆ append() [6/6]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::append ( fitsHeader< verboseT > & head )

Append a fitsHeader to the end of the header.

Parameters

[in] head the fitsHeader to append

Definition at line 585 of file fitsHeader.hpp.

References fitsHeader(), append(), begin(), end(), mxlib_error_check, and mx::noerror.

◆ begin()

template<class verboseT>

fitsHeader< verboseT >::headerIteratorT mx::fits::fitsHeader< verboseT >::begin ( )

Get iterator to the beginning of the cards list.

Definition at line 331 of file fitsHeader.hpp.

References m_cardList.

Referenced by append(), eraseStandardTop(), mx::fits::fitsFile< dataT, verboseT >::readHeader(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::fits::fitsFile< dataT, verboseT >::write().

◆ clear()

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::clear ( )

Clear all cards from the header.

Definition at line 367 of file fitsHeader.hpp.

References m_cardList, m_cardMap, and mx::noerror.

Referenced by ~fitsHeader(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ count()

template<class verboseT>

size_t mx::fits::fitsHeader< verboseT >::count ( const std::string & keyword )

Get number of cards with a given keyword.

Returns the result of the count() method of the header map.

Return values

the	number of cards with keyword.

Parameters

[in] keyword the keyword to look up

Definition at line 376 of file fitsHeader.hpp.

References m_cardMap.

Referenced by mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ empty()

template<class verboseT>

bool mx::fits::fitsHeader< verboseT >::empty ( )

Test whether the header is empty.

Definition at line 355 of file fitsHeader.hpp.

References m_cardList.

Referenced by mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ end()

template<class verboseT>

fitsHeader< verboseT >::headerIteratorT mx::fits::fitsHeader< verboseT >::end ( )

Get iterator to the end of the cards list.

Definition at line 337 of file fitsHeader.hpp.

References m_cardList.

Referenced by append(), eraseStandardTop(), mx::fits::fitsFile< dataT, verboseT >::readHeader(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::fits::fitsFile< dataT, verboseT >::write().

◆ erase() [1/2]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::erase ( const std::string & keyword )

Erase card by keyword.

This can not be used to erase COMMENT or HISTORY cards.

Parameters

[in] keyword the keyword of the card to delete

Definition at line 382 of file fitsHeader.hpp.

References mx::invalidarg, m_cardList, m_cardMap, mx::internal::mxlib_error_report(), mx::noerror, and mx::notfound.

Referenced by eraseStandardTop(), mx::fits::fitsFile< dataT, verboseT >::readHeader(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ erase() [2/2]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::erase ( headerIteratorT it )

Erase card by iterator.

This handles COMMENT and HISTORY cards, deleting only the one pointed to by it using all the contents of the card (not just the keyword)

Parameters

[in] it iterator pointing to the card to delete.

Definition at line 409 of file fitsHeader.hpp.

References mx::invalidarg, m_cardList, m_cardMap, mx::internal::mxlib_error_report(), and mx::noerror.

◆ eraseStandardTop()

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::eraseStandardTop ( )

Erase the standard entries at the top of the header.

Erases each entry down to BSCALE. This is useful for appending a header from a previous image to a newly created file. Also erases boilerplate comments, such as for long string.

Definition at line 435 of file fitsHeader.hpp.

References begin(), end(), erase(), mxlib_error_check, and mx::noerror.

Referenced by mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ insert_after() [1/3]

template<class verboseT>

template<typename typeT>

error_t mx::fits::fitsHeader< verboseT >::insert_after	(	headerIteratorT	it,
		const std::string &	k,
		typeT	v )

Insert a card after another card, specifying the card by its components.

Template Parameters

typeT is the type of the value, which is converted to string for insertion

Parameters

[in]	it	interator pointing to the element after which to insert
[in]	k	the keyword of the new card
[in]	v	the value of the new card

Definition at line 843 of file fitsHeader.hpp.

References insert_after(), and mxlib_error_return.

◆ insert_after() [2/3]

template<class verboseT>

template<typename typeT>

error_t mx::fits::fitsHeader< verboseT >::insert_after	(	headerIteratorT	it,
		const std::string &	k,
		typeT	v,
		const std::string &	c )

Insert a card after another card, specifying the card by its components.

Template Parameters

typeT is the type of the value, which is converted to string for insertion

Parameters

[in]	it	iterator pointing to the element after which to insert
[in]	k	the keyword of the new card
[in]	v	the value of the new card
[in]	c	the comment of the new card

Definition at line 738 of file fitsHeader.hpp.

References insert_after(), and mxlib_error_return.

◆ insert_after() [3/3]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::insert_after	(	headerIteratorT	it,
		fitsHeaderCard< verboseT >	card )

Insert a card after another card.

Parameters

[in]	it	iterator pointing to the element after which to insert
[in]	card	the card to insert

Definition at line 744 of file fitsHeader.hpp.

References mx::fits::fitsType(), mx::invalidarg, mx::fits::fitsHeaderCard< verboseT >::keyword(), m_cardList, m_cardMap, mx::internal::mxlib_error_report(), mx::noerror, mx::std_bad_alloc, mx::std_exception, and mx::fits::fitsHeaderCard< verboseT >::type().

Referenced by insert_after(), insert_after(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ insert_before() [1/3]

template<class verboseT>

template<typename typeT>

error_t mx::fits::fitsHeader< verboseT >::insert_before	(	headerIteratorT	it,
		const std::string &	k,
		typeT	v )

Insert a card before another card, specifying the card by its components.

Template Parameters

typeT is the type of the value, which is converted to string for insertion

Parameters

[in]	it	iterator pointing to the element before which to insert
[in]	k	the keyword of the new card
[in]	v	the value of the new card

Definition at line 731 of file fitsHeader.hpp.

References insert_before(), and mxlib_error_return.

◆ insert_before() [2/3]

template<class verboseT>

template<typename typeT>

error_t mx::fits::fitsHeader< verboseT >::insert_before	(	headerIteratorT	it,
		const std::string &	k,
		typeT	v,
		const std::string &	c )

Insert a card before another card, specifying the card by its components.

Template Parameters

typeT is the type of the value, which is converted to string for insertion

Parameters

[in]	it	iterator pointing to the element before which to insert
[in]	k	the keyword of the new card
[in]	v	the value of the new card
[in]	c	the comment of the new card

Definition at line 724 of file fitsHeader.hpp.

References insert_before(), and mxlib_error_return.

◆ insert_before() [3/3]

template<class verboseT>

error_t mx::fits::fitsHeader< verboseT >::insert_before	(	headerIteratorT	it,
		fitsHeaderCard< verboseT >	card )

Insert a card before another card.

Parameters

[in]	it	iterator pointing to the element before which to insert
[in]	card	the card to insert

Definition at line 630 of file fitsHeader.hpp.

References mx::fits::fitsType(), mx::invalidarg, mx::fits::fitsHeaderCard< verboseT >::keyword(), m_cardList, m_cardMap, mx::internal::mxlib_error_report(), mx::noerror, mx::std_bad_alloc, mx::std_exception, and mx::fits::fitsHeaderCard< verboseT >::type().

Referenced by insert_before(), insert_before(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ iterator()

template<class verboseT>

fitsHeader< verboseT >::headerIteratorT mx::fits::fitsHeader< verboseT >::iterator ( const std::string & keyword )

Get iterator pointing to a specific element.

Parameters

keyword The keyword to look up

Definition at line 343 of file fitsHeader.hpp.

References m_cardList, and m_cardMap.

Referenced by mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

◆ operator=()

template<class verboseT>

fitsHeader< verboseT > & mx::fits::fitsHeader< verboseT >::operator= ( const fitsHeader< verboseT > & head )

Assignment operator.

Parameters

head	The fitsHeader to copy

Definition at line 314 of file fitsHeader.hpp.

References fitsHeader(), m_cardList, and m_cardMap.

Referenced by fitsHeader().

◆ operator[]() [1/2]

template<class verboseT>

fitsHeaderCard< verboseT > & mx::fits::fitsHeader< verboseT >::operator[] ( const std::string & keyword )

Card access by keyword operator.

Looks up the card by its keyword, and returns a reference to it.

Returns: on success: fitsHeaderCard& reference to the fitsHeaderCard; on error: a fitsHeaderCard& to a card with an empty keyword

Parameters

[in] keyword the header keyword to look up

Definition at line 849 of file fitsHeader.hpp.

References append(), m_cardMap, m_emptyCard, mx::internal::mxlib_error_report(), and mx::noerror.

◆ operator[]() [2/2]

template<class verboseT>

const fitsHeaderCard< verboseT > & mx::fits::fitsHeader< verboseT >::operator[] ( const std::string & keyword ) const

Card access by keyword operator (const version).

Looks up the card by its keyword, and returns a reference to it.

Returns: on success: fitsHeaderCard& reference to the fitsHeaderCard; on error: a fitsHeaderCard& to a card with an empty keyword

Parameters

[in] keyword the header keyword to look up

Definition at line 876 of file fitsHeader.hpp.

References m_cardMap, m_emptyCard, mx::internal::mxlib_error_report(), and mx::notfound.

◆ size()

template<class verboseT>

size_t mx::fits::fitsHeader< verboseT >::size ( )

Get number of cards currently stored in the header.

Definition at line 361 of file fitsHeader.hpp.

References m_cardList.

Referenced by mx::fits::fitsFile< dataT, verboseT >::readHeader(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE(), and mx::unitTest::fitsTest::fitsHeaderTest::TEST_CASE().

Member Data Documentation

◆ m_cardList

template<class verboseT = verbose::d>

cardListT mx::fits::fitsHeader< verboseT >::m_cardList

protected

The storage for the FITS header cards.

Definition at line 105 of file fitsHeader.hpp.

Referenced by append(), begin(), clear(), empty(), end(), erase(), erase(), insert_after(), insert_before(), iterator(), operator=(), and size().

◆ m_cardMap

template<class verboseT = verbose::d>

cardMapT mx::fits::fitsHeader< verboseT >::m_cardMap

protected

This multimap allows for fast lookup by keyword.

Definition at line 108 of file fitsHeader.hpp.

Referenced by append(), clear(), count(), erase(), erase(), insert_after(), insert_before(), iterator(), operator=(), operator[](), and operator[]().

◆ m_emptyCard

template<class verboseT = verbose::d>

fitsHeaderCard<verboseT> mx::fits::fitsHeader< verboseT >::m_emptyCard

mutableprotected

Card with empty keyword used as an error sentinel.

Definition at line 111 of file fitsHeader.hpp.

Referenced by operator[](), and operator[]().

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

ioutils/fits/fitsHeader.hpp

Public Types

Public Member Functions

Protected Attributes

Member Typedef Documentation

◆ cardListT

◆ cardMapT

◆ cardMapValueT

◆ headerIteratorT

◆ mapIteratorT

Constructor & Destructor Documentation

◆ fitsHeader() [1/2]

◆ fitsHeader() [2/2]

◆ ~fitsHeader()

Member Function Documentation

◆ append() [1/6]

◆ append() [2/6]

◆ append() [3/6]

◆ append() [4/6]

◆ append() [5/6]

◆ append() [6/6]

◆ begin()

◆ clear()

◆ count()

◆ empty()

◆ end()

◆ erase() [1/2]

◆ erase() [2/2]

◆ eraseStandardTop()

◆ insert_after() [1/3]

◆ insert_after() [2/3]

◆ insert_after() [3/3]

◆ insert_before() [1/3]

◆ insert_before() [2/3]

◆ insert_before() [3/3]

◆ iterator()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ size()

Member Data Documentation

◆ m_cardList

◆ m_cardMap

◆ m_emptyCard