keyword.hpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_ocm_libfits
 * @copyright 2021 ESO - European Southern Observatory
 *
 * @brief Contains data structure for FITS keywords
 */
#ifndef DAQ_OCM_DAQ_FITS_KEYWORD_HPP_
#define DAQ_OCM_DAQ_FITS_KEYWORD_HPP_
 
 
#include <array>
 
#include <optional>
#include <string>
#include <variant>
#include <vector>
#include <iosfwd>
 
 
namespace daq::fits {
 
/**
 * Non template base class that is purely used to avoid type-deduction issues of ValueType.
 */
struct BasicKeywordBase {
    // Possible value types that can be carried in a keyword
    using ValueType = std::variant<std::string, int64_t, uint64_t, double, bool>;
};
 
/**
 * A type safe version of FormattedKeyword that consist of the three basic components of a FITS
 * keyword keyword record: name, value and optional comment.
 *
 * @note name should be used for the logical keyword name, not the keyword name according to FITS
 * standard. E.g. the ESO hiearchical keywords all have the keyword name HIERARCH according to the
 * standard, but this structure should instead use the logical fields where e.g. "HIERARCH ESO DPR
 * CATG" is the logical keyword name.
 *
 * It does not model any specific unit, only the value type. Therefore it is not strictly necessary
 * to have all possible types represented in ValueType (e.g. both singel and double precision
 * floats).
 *
 * The idea is that the unit, formatting and ranges is provided provided by dictionaries.
 *
 * It also typically requires a dictionary to be able to understand how to parse @c value.
 *
 * @ingroup daq_ocm_libfits
 */
template <class Trait>
struct BasicKeyword final : BasicKeywordBase {
    BasicKeyword() = default;
    BasicKeyword(BasicKeyword const&) = default;
    BasicKeyword(BasicKeyword&&) noexcept = default;
    BasicKeyword(std::string name,
                 char const* string_value,
                 std::optional<std::string> comment = std::nullopt);
    BasicKeyword(std::string name,
                 ValueType value,
                 std::optional<std::string> comment = std::nullopt) noexcept;
 
    BasicKeyword& operator=(BasicKeyword&& rhs) noexcept = default;
    BasicKeyword& operator=(BasicKeyword const& rhs) = default;
 
    /**
     * Compares all members for equality.
     */
    bool operator==(BasicKeyword const& rhs) const noexcept;
    /**
     * Compares all members for inequality.
     */
    bool operator!=(BasicKeyword const& rhs) const noexcept;
    /**
     * Uses @a name property as the sorting index.
     */
    bool operator<(BasicKeyword const& rhs) const noexcept;
 
 
    std::string name;
    ValueType value;
    std::optional<std::string> comment;
};
 
struct ValueKeywordTraits {};
struct EsoKeywordTraits {};
 
/**
 * Standard FITS value keyword.
 *
 * @ingroup daq_ocm_libfits
 */
using ValueKeyword = BasicKeyword<ValueKeywordTraits>;
 
/**
 * ESO hiearchical keyword.
 *
 * @ingroup daq_ocm_libfits
 */
using EsoKeyword = BasicKeyword<EsoKeywordTraits>;
 
/**
 * EsoKeyword is sorted after ValueKeyword.
 *
 * @ingroup daq_ocm_libfits
 */
constexpr bool operator<(ValueKeyword const&, EsoKeyword const&) noexcept {
    return true;
}
 
/**
 * EsoKeyword is sorted after ValueKeyword.
 *
 * @ingroup daq_ocm_libfits
 */
constexpr bool operator<(EsoKeyword const&, ValueKeyword const&) noexcept {
    return false;
}
 
template <class Trait>
std::ostream& operator<<(std::ostream& os, BasicKeyword<Trait> const& kw);
 
template <class Trait>
std::ostream& operator<<(std::ostream& os, BasicKeywordBase::ValueType const& kw);
 
 
/**
 * The different variants of keywords that are supported.
 *
 * @ingroup daq_ocm_libfits
 */
using KeywordVariant = std::variant<ValueKeyword, EsoKeyword>;
 
/**
 * Vector of keywords.
 *
 * @ingroup daq_ocm_libfits
 */
using KeywordVector = std::vector<KeywordVariant>;
 
/**
 * Ostream formatting of keywords.
 *
 * @ingroup daq_ocm_libfits
 */
std::ostream& operator<<(std::ostream& os, KeywordVariant const& kw);
 
/**
 * Compare keyword names of keyword of the same type.
 *
 * Comparing names only is useful to e.g. look up keyword by name, to modify it.
 *
 * @param lhs value to compare
 * @param rhs value to compare
 * @returns true iff lhs and rhs are the same type and their name property compares equal.
 *
 * @ingroup daq_ocm_libfits
 */
bool NameEquals(KeywordVariant const& lhs, KeywordVariant const& rhs) noexcept;
 
/**
 * Updates @a a with keywords from @a b.
 *
 * New keywords are inserted at the end. Existing keywords will be updated with new value if
 * keyword type and name is the same.
 *
 * @param to Keywords to update to.
 * @param from Keywords to update from.
 *
 * @ingroup daq_ocm_libfits
 */
void UpdateKeywords(KeywordVector& to, KeywordVector const& from);
 
}  // namespace daq::fits
#endif  // #ifndef DAQ_OCM_DAQ_KEYWORD_HPP_