fitsHeader.hpp

Go to the documentation of this file.

/** \file fitsHeader.hpp
 * \brief Declares and defines a class to work with a FITS header
 * \ingroup fits_processing_files
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 */
 
//***********************************************************************//
// Copyright 2015-2022 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef ioutils_fits__fitsHeader_hpp
#define ioutils_fits__fitsHeader_hpp
 
#include <list>
#include <unordered_map>
#include <iostream>
#include <vector>
#include <optional>
 
#include "fitsHeaderCard.hpp"
 
namespace mx
{
namespace fits
{
 
/// Class to manage a complete fits header
/** Manages tasks such as insertion (avoiding duplicates), and keyword lookup.
 * The \ref fitsHeaderCard "cards" are stored in a std::list to preserve order, but
 * a std::unordered_multimap is used to provide fast keyword lookup.
 *
 * \ingroup fits_processing
 */
class fitsHeader
{
 
  public:
    /// The iterator type for the cards list
    typedef std::list<fitsHeaderCard>::iterator headerIterator;
 
    /// The iterator type for the card map
    typedef std::unordered_multimap<std::string, headerIterator>::iterator mapIterator;
 
  protected:
    /// The storage for the FITS header cards
    /** We use a list,  rather than forward_list, so that append (insert at end) is constant time.
     *
     */
    std::list<fitsHeaderCard> cards;
 
    /// This multimap allows for fast lookup by keyword.
    /** Use unordered_multimap to handle HISTORY and COMMENT properly, and be as efficient as possible.
     */
    std::unordered_multimap<std::string, headerIterator> cardMap;
 
  public:
    /// Default c'tor
    fitsHeader();
 
    /// Copy constructor
    /** Must be explicitly defined to handle creation of new iterators in the cardMap
     */
    fitsHeader( const fitsHeader &head /**< The fitsHeader to copy */ );
 
    /// Destructor
    ~fitsHeader();
 
    /// Assignment
    /** Must be explicitly defined to handle creation of new iterators in the cardMap
     */
    fitsHeader &operator=( const fitsHeader &head /**< The fitsHeader to copy */ );
 
    /// Get iterator to the beginning of the cards list
    headerIterator begin();
 
    /// Get iterator to the end of the cards list
    headerIterator end();
 
    /// Get iterator pointing to a specific element
    headerIterator iterator( const std::string &keyword /**< The keyword to look up*/ );
 
    /// Test whether the header is empty.
    bool empty();
 
    /// Get number of cards currently stored in the header.
    size_t size();
 
    /// Clear all cards from the header
    void clear();
 
    /// Get number of cards with a given keyword
    /** Reeturns the result of the count() method of the header map.
     *
     * \retval the number of cards with  keyword.
     */
    size_t count( const std::string &keyword /**< [in] the keyword to loop up*/ );
 
    /// Erase card by keyword
    /** This can not be used to erase COMMENT or HISTORY cards.
     *
     * \param keyword the keyword of the card to delete
     *
     */
    void erase( const std::string &keyword );
 
    /// Erase card by iterator
    /** This handles COMMENT and HISTORY cards, deleting only the one pointed to by it
     *
     * \param it is a headerIterator pointing to the card to delete.
     *
     */
    void erase( headerIterator it );
 
    /// Erase the standard entries at the top of the header
    /** Erases each entry down to BSCALE.  This is useful for appending
     * a header to a newly created file.
     */
    void eraseStandardTop();
 
    /// Append a fitsHeaderCard to the end of the header
    /**
     * \param card is a fitsHeaderCard already populated
     */
    void append( const fitsHeaderCard & card );
 
    /// Append a card to the end of the header, from the three components of a card.
    /**
     * \tparam typeT is the data type of the value
     *
     * \param k is the keyword string
     * \param v is the value of typeT
     * \param c is the comment string
     */
    template <typename typeT>
    void append( const std::string &k, const typeT &v, const std::string &c );
 
    /// Append a card to the end of the header, from the components of a card with no comment.
    /**
     * \tparam typeT is the data type of the value
     *
     * \param k is the keyword string
     * \param v is the value of typeT
     */
    template <typename typeT>
    void append( const std::string &k, const typeT &v );
 
    /// Append a card to the end of the header, with just a keyword.
    /** Appens a headerCard with unknownType
     *
     * \param k is the keyword string
     */
    void append( const std::string &k );
 
    /// Append a fitsHeader to the end of the header
    /**
     * \param head is a populated fitsHeader
     */
    void append( fitsHeader &head );
 
    /// Insert a card before another card.
    /**
     * \param it points to the element before which to insert
     * \param card contains the card to insert
     */
    void insert_before( headerIterator it, fitsHeaderCard card );
 
    /// Insert a card before another card, specifying the card by its components.
    /**
     * \tparam typeT is the type of the value, which is converted to string for insertion
     *
     * \param it points to the element before which to insert
     * \param k is the keyword
     * \param v is the value
     * \param c is the comment
     *
     */
    template <typename typeT>
    void insert_before( headerIterator it, const std::string &k, typeT v, const std::string &c );
 
    /// Insert a card before another card, specifying the card by its components.
    /**
     * \tparam typeT is the type of the value, which is converted to string for insertion
     *
     * \param it points to the element before which to insert
     * \param k is the keyword
     * \param v is the value
     *
     */
    template <typename typeT>
    void insert_before( headerIterator it, const std::string &k, typeT v );
 
    /// Insert a card after another card.
    /**
     * \param it points to the element after which to insert
     * \param card contains the card to insert
     */
    void insert_after( headerIterator it, fitsHeaderCard card );
 
    /// Insert a card after another card, specifying the card by its components.
    /**
      * \tparam typeT is the type of the value, which is converted to string for insertion
      *
      * \param it points to the element after which to insert
      * \param k is the keyword
      * \param v is the value
      * \param c is the comment
      *
 
      */
    template <typename typeT>
    void insert_after( headerIterator it, const std::string &k, typeT v, const std::string &c );
 
    /// Insert a card after another card, specifying the card by its components.
    /**
     * \tparam typeT is the type of the value, which is converted to string for insertion
     *
     * \param it points to the element after which to insert
     * \param k is the keyword
     * \param v is the value
     *
     */
    template <typename typeT>
    void insert_after( headerIterator it, const std::string &k, typeT v );
 
    /// Card access by keyword operator
    /** Looks up the card by its keyword, and returns a reference to it.
     *
     * \param keyword is the header keyword to look up
     *
     * \retval fitsHeaderCard& reference to the \ref fitsHeaderCard
     */
    fitsHeaderCard &operator[]( const std::string &keyword );
 
    /// Card access by keyword operator (const version)
    /** Looks up the card by its keyword, and returns a reference to it.
     *
     * \param keyword is the header keyword to look up
     *
     * \retval fitsHeaderCard& const reference to the \ref fitsHeaderCard
     */
    const fitsHeaderCard &operator[]( const std::string &keyword ) const;
 
}; // fitsHeader
 
template <typename typeT>
void fitsHeader::append( const std::string &k, const typeT &v, const std::string &c )
{
    append( fitsHeaderCard( k, v, c ) );
}
 
template <typename typeT>
void fitsHeader::append( const std::string &k, const typeT &v )
{
    append( fitsHeaderCard( k, v ) );
}
 
template <typename typeT>
void fitsHeader::insert_before( headerIterator it, const std::string &k, typeT v, const std::string &c )
{
    insert_before( it, fitsHeaderCard( k, v, c ) );
}
 
template <typename typeT>
void fitsHeader::insert_before( headerIterator it, const std::string &k, typeT v )
{
    insert_before( it, fitsHeaderCard( k, v ) );
}
 
template <typename typeT>
void fitsHeader::insert_after( headerIterator it, const std::string &k, typeT v, const std::string &c )
{
    insert_after( it, fitsHeaderCard( k, v, c ) );
}
 
template <typename typeT>
void fitsHeader::insert_after( headerIterator it, const std::string &k, typeT v )
{
    insert_after( it, fitsHeaderCard( k, v ) );
}
 
/** \addtogroup fits_utils
 * @{
 */
 
/// Convert the values in a std::vector of \ref fitsHeader "fits headers" into a std::vector of values.
/** Resizes the vector of the appropriate type.
 *
 * \tparam dataT is the type of the header value
 *
 * \param[out] v will contain the converted values
 * \param[in] heads contains the headers
 * \param[in] keyw contains the keyword designating which value to convert
 * 
 * \returns an optional which, if true, contains a vector of the indices of \p heads for which 
 *          the extraction of a value for \p keyw failed
 *
 */
template <typename dataT>
std::optional<std::vector<size_t>> headersToValues( std::vector<dataT> &v, std::vector<fitsHeader> &heads, const std::string &keyw )
{
    v.resize( heads.size() );
    std::vector<size_t> bad;
    for( size_t i = 0; i < heads.size(); ++i )
    {
        try
        {
            v[i] = heads[i][keyw].value<dataT>(); // convertFromString<dataT>(heads[i][keyw].value);
        }
        catch(...)
        {
            bad.push_back(i);
            v[i] = std::numeric_limits<dataT>::max();
        }
    }
 
    if(bad.size() > 0) 
    {
        return bad;
    }
    else 
    {
        return {};
    }
 
}
 
/// Write the status of a Git repository to HISTORY in a FITS header.
/**
 * \param [in,out] head the HISTORY cards will be appended to this header
 * \param [in] repoName the name of the repository
 * \param [in] sha1 is the SHA-1 hash string of the repository
 * \param [in] modified whether or not the repository has been modified after the
 *                      commit referred to by sha1
 */
void fitsHeaderGitStatus( fitsHeader &head, const std::string &repoName, const char *sha1, int modified );
 
///@}
 
} // namespace fits
} // namespace mx
 
#endif // ioutils_fits__fitsHeader_hpp