keyword.cpp

Go to the documentation of this file.

/**
 * @file
 * @ingroup daq_ocm_libfits
 * @copyright 2022 ESO - European Southern Observatory
 *
 * @brief Definition of contents from fits/keyword.hpp
 */
#include <daq/fits/keyword.hpp>
 
#include <algorithm>
#include <cstdlib>
#include <iostream>
#include <ostream>
 
#include <boost/algorithm/string/join.hpp>
#include <boost/assert.hpp>
#include <boost/exception/enable_current_exception.hpp>
#include <fmt/format.h>
 
namespace daq::fits {
namespace {
template <class>
inline constexpr bool always_false_v = false;  // NOLINT
template <class T>
char const* TypeStr() noexcept;
template <>
char const* TypeStr<std::uint64_t>() noexcept {
    return "uint64_t";
}
template <>
char const* TypeStr<std::int64_t>() noexcept {
    return "int64_t";
}
template <>
char const* TypeStr<double>() noexcept {
    return "double";
}
 
enum class ParseResult {
    Ok,
    // There are left-over characters after parsing.
    ExtraChars,
    // Not a string
    NotAString,
    // A string but invalid
    InvalidString,
};
/**
 * Escape string "foo's" -> "foo''s"
 */
std::string FitsEscapeString(std::string_view value) {
    std::string new_value;
    new_value.reserve(value.size());
    for (auto c : value) {
        new_value.push_back(c);
        if (c == '\'') {
            new_value.push_back(c);
        }
    }
    return new_value;
}
 
constexpr char const* FMT_VALUEKW_SCALAR = "{:<8}= {:>20}";
constexpr char const* FMT_VALUEKW_STR = "{:<8}= {:<20}";
constexpr char const* FMT_ESOKW = "HIERARCH ESO {} = {}";
// HIERARCH keyword standard follows FITS free-format specified in standard:
// - Value indicator is at least `= `
// - Comment indicator is ` /`
constexpr char const* FMT_ESOKW_PACKED = "HIERARCH ESO {}= {}";
constexpr char const* FMT_ALL_COMMENT = "{} / {}";
constexpr char const* FMT_COMMENTARYKW = "{:<8} {}";
 
LiteralKeyword InternalValueKeywordFormat(std::string_view name,
                                          std::string_view value,
                                          std::string_view comment) {
    auto is_string = value.find('\'') == 0u;
    // Fixed value format
    auto formatted_name_value =
        fmt::format(is_string ? FMT_VALUEKW_STR : FMT_VALUEKW_SCALAR, name, value);
    if (formatted_name_value.size() > constants::RECORD_LENGTH) {
        throw boost::enable_current_exception(InvalidKeyword(
            name,
            fmt::format("formatted name and value does not fit in keyword record. Length: {}, "
                        "Formatted result: '{}'",
                        formatted_name_value.size(),
                        formatted_name_value)));
    }
    auto formatted = fmt::format(FMT_ALL_COMMENT, formatted_name_value, comment);
    auto view = std::string_view(formatted).substr(0u, fits::constants::RECORD_LENGTH);
    return LiteralKeyword(view);
}
 
LiteralKeyword
InternalEsoKeywordFormat(std::string_view name, std::string_view value, std::string_view comment) {
    const bool use_packed_value =
        name.size() + value.size() >= constants::ESO_HIERARCH_NAME_VALUE_PACKED_LIMIT;
    auto formatted_name_value =
        fmt::format(use_packed_value ? FMT_ESOKW_PACKED : FMT_ESOKW, name, value);
    if (formatted_name_value.size() > constants::RECORD_LENGTH) {
        throw boost::enable_current_exception(InvalidKeyword(
            name,
            fmt::format("formatted name and value does not fit in keyword record. Length: {}, "
                        "Formatted result: '{}'",
                        formatted_name_value.size(),
                        formatted_name_value)));
    }
    auto formatted = fmt::format(FMT_ALL_COMMENT, formatted_name_value, comment);
    auto view = std::string_view(formatted).substr(0u, fits::constants::RECORD_LENGTH);
    return LiteralKeyword(view);
}
 
LiteralKeyword InternalCommentaryKeywordFormat(std::string_view name, std::string_view value) {
    auto formatted_name_value = fmt::format(FMT_COMMENTARYKW, name, value);
    if (formatted_name_value.size() > constants::RECORD_LENGTH) {
        throw boost::enable_current_exception(InvalidKeyword(
            name,
            fmt::format("formatted name and value does not fit in keyword record. Length: {}, "
                        "Formatted result: '{}'",
                        formatted_name_value.size(),
                        formatted_name_value)));
    }
    return LiteralKeyword(formatted_name_value);
}
 
/**
 * Validates logical keyword name according to FITS rules.
 * The rules depend on the type of keyword.
 *
 * Common rules:
 *
 * - Trailing whitespace are insignificant.
 * - Valid character set: [A-Z0-9_-]
 *
 * KeywordType::Value and KeywordType::Commentary:
 * - Size: 1-8 (for an all-spaces keyword there must be one ' ')
 *
 * KeywordType::Eso:
 *
 * - Size: 1 - ESO_HIERARCH_MAX_NAME_LENGTH
 *
 * @throws std::invalid_argument on errors
 */
void ValidateKeywordName(KeywordNameView keyword) {
    if (keyword.name.empty()) {
        throw boost::enable_current_exception(InvalidKeyword("", "keyword name cannot be empty"));
    }
    auto max_length = keyword.type == KeywordType::Eso ? constants::ESO_HIERARCH_MAX_NAME_LENGTH
                                                       : constants::KEYWORD_NAME_LENGTH;
    if (keyword.name.size() > max_length) {
        auto msg = fmt::format("keyword name too long. Maximum is {} and provided name '{}' is {}",
                               max_length,
                               keyword.name,
                               keyword.name.size());
        throw boost::enable_current_exception(InvalidKeyword(keyword.name, msg));
    }
    auto is_valid_char = [](char c) -> bool {
        return (c >= '0' && c <= '9') || (c >= 'A' && c <= 'Z') || c == ' ' || c == '_' || c == '-';
    };
 
    if (!std::all_of(std::begin(keyword.name), std::end(keyword.name), is_valid_char)) {
        throw boost::enable_current_exception(InvalidKeyword(
            keyword.name,
            fmt::format(
                "Keyword name '{}' contains illegal character. Valid charset is [A-Z0-9_-].",
                keyword.name)));
    }
}
 
constexpr KeywordType ParseKeywordType(std::string_view record) noexcept {
    if (record.size() >= constants::KEYWORD_NAME_LENGTH + constants::VALUE_INDICATOR.size()) {
        // If bytes 9 and 10 contain the value indicator it must be a value keyword
        if (record.substr(constants::KEYWORD_NAME_LENGTH, constants::VALUE_INDICATOR.size()) ==
            constants::VALUE_INDICATOR) {
            return KeywordType::Value;
        }
        if (record.size() > constants::ESO_HIERARCH_PREFIX.size()) {
            // HIERARCH ESO keyword must start with 'HIERARCH ESO ' and contain '='.
            auto kw = record.substr(0u, constants::ESO_HIERARCH_PREFIX.size());
            auto remainder = record.substr(constants::ESO_HIERARCH_PREFIX.size(), record.npos);
            if (kw == constants::ESO_HIERARCH_PREFIX && remainder.find('=') != kw.npos) {
                return KeywordType::Eso;
            }
        }
    }
    // Everything else are Commentary keywords.
    return KeywordType::Commentary;
}
 
/**
 * Parse the logical category of an ESO hierarchical keyword.
 *
 * Logical category ignores trailing numbers, so logical category of
 * - `DET1` is `DET`
 * - `DET01` is `DET`
 *
 * However, the logical category for
 * - `DET1A` is `DET1A`
 * - `DET1A1` is `DET1A`.
 *
 * @param name Logical keyword name with the first token being the category.
 * @return logical category (first token stripped of trailing numbers)
 */
constexpr std::string_view ParseLogicalCategory(std::string_view name) noexcept {
    using namespace std::literals::string_view_literals;
    // End of category token
    auto end = name.find_first_of(" ="sv);
    // Trim away any trailing numbers
    auto full_category = name.substr(0, end);
    auto logical_end = full_category.find_last_not_of("0123456789"sv);
    if (logical_end != std::string_view::npos) {
        auto view = name.substr(0, logical_end + 1);
        return view;
    }
    return full_category;
}
 
enum class TrimType { Name, Full };
 
constexpr std::string_view TrimLeft(std::string_view str, TrimType trim) {
    auto trim_pos = str.find_first_not_of(constants::BLANK_CHARS);
    if (trim_pos == std::string_view::npos) {
        // All blanks
        return trim == TrimType::Name ? str.substr(0u, 1u) : std::string_view();
    }
    str.remove_prefix(trim_pos);
    return str;
}
 
/**
 * Trim string view.
 * If @a trim is @a Name it will try to keep a single space char in the event of a completely empty
 * string because that is significant in FITS.
 */
constexpr std::string_view TrimBlanks(std::string_view str, TrimType trim) noexcept {
    if (str.empty()) {
        return str;
    }
    str = TrimLeft(str, trim);
    {  // Trim right
        auto trim_pos = str.find_last_not_of(constants::BLANK_CHARS);
        if (trim_pos != std::string_view::npos) {
            str.remove_suffix(str.size() - trim_pos - 1);
        }
    }
    return str;
}
 
/**
 * @returns FITS string token or empty string view.
 */
constexpr std::string_view NextStringToken(std::string_view str, ParseResult& ec) {
    ec = ParseResult::Ok;
    str = TrimLeft(str, TrimType::Full);
    if (str.empty()) {
        return {};
    }
    if (str[0] != '\'') {
        ec = ParseResult::NotAString;
        return {};
    }
    // one-past end of string
    auto str_end = std::string_view::npos;
    bool possible_end = false;
    // valid characters after closed string `'` are the space or comment characters.
    auto break_chars = std::string_view(" /");
    for (str_end = 1; str_end < str.size(); ++str_end) {
        if (possible_end && break_chars.find(str[str_end]) != std::string_view::npos) {
            break;
        } else if (possible_end && str[str_end] == '\'') {
            // Two consecutive ' -> not a possible end any more
            possible_end = false;
        } else if (!possible_end && str[str_end] == '\'') {
            possible_end = true;
        }
    }
    // Did string end without closing?
    if (!possible_end) {
        ec = ParseResult::InvalidString;
        return {};
    } else {
        return str.substr(0, str_end);
    }
}
 
/**
 * Read next token in str up to @a delimiter.
 *
 * @returns Trimmed token and position after delimiter in the input str. If delimiter was not found
 *          the returned string_view iterator will be nullopt.
 */
constexpr std::pair<std::string_view, std::optional<std::string_view::size_type>>
NextToken(std::string_view str, char delimiter, TrimType trim) noexcept {
    auto delimiter_pos = str.find(delimiter);
    std::optional<std::string_view::size_type> ret_pos;
    if (delimiter_pos != std::string_view::npos) {
        // Delimiter found
        ret_pos = delimiter_pos + 1;
        str.remove_suffix(str.size() - delimiter_pos);
    }
    auto trimmed = TrimBlanks(str, trim);
    return {trimmed, ret_pos};
}
 
/**
 * Read FITS value from str
 *
 * Value is either
 * - a string: 'string' (string may contain ' which are escaped as '')
 * - One of the FITS value types.
 *
 * Up to an optional comment delimiter `/` which does not require a space before it.
 *
 * @returns trimmed value and position of comment delmiter `/`, if any.
 */
constexpr std::pair<std::string_view, std::optional<std::string_view::size_type>>
NextValue(std::string_view str, ParseResult& ec) noexcept {
    // Try to find a string
    auto value = NextStringToken(str, ec);
    if (ec == ParseResult::InvalidString) {
        return {};
    }
    // Offset from local string to input str
    auto offset = 0u;
    if (!value.empty()) {
        // Found string -> remove value
        offset = value.end() - str.begin();
        // shrink `str` to exclude value
        str.remove_prefix(offset);
    }
    ec = ParseResult::Ok;
 
    // Find out where comment begins (and value if not a  string)
    auto [alt, end] = NextToken(str, '/', TrimType::Full);
    auto comment_beg = end.has_value() ? *end - 1 : std::string_view::npos;
    if (value.empty()) {
        if (alt.empty()) {
            return {{}, end};
        }
        // Since value from string was not provided we use value up to `/`
        value = alt;
        if (value.find_first_of(constants::BLANK_CHARS) != std::string_view::npos) {
            // there are blank chars in non-string keyword
            ec = ParseResult::ExtraChars;
            return {};
        }
        // shrink `str` to exclude value
        auto shrink_by = value.end() - str.begin();
        str.remove_prefix(shrink_by);
        if (comment_beg != std::string_view::npos) {
            comment_beg -= shrink_by;
        }
    }
 
    // `str` now begins after value
    auto empty = str.substr(0, comment_beg);
    if (empty.find_first_not_of(constants::BLANK_CHARS) != std::string_view::npos) {
        ec = ParseResult::ExtraChars;
        return {};
    }
    if (end) {
        return {value, *end + offset};
    }
    return {value, std::nullopt};
}
 
constexpr LiteralKeyword::Components
ParseValueKeywordComponents(std::array<char, 80> const& record_array) {
    auto record = std::string_view(&record_array[0], record_array.size());
    LiteralKeyword::Components components{};
    components.type = KeywordType::Value;
 
    // Name
    components.name = TrimBlanks(record.substr(0u, constants::KEYWORD_NAME_LENGTH), TrimType::Name);
    record.remove_prefix(constants::KEYWORD_NAME_LENGTH + constants::VALUE_INDICATOR.size());
    // Value
    ParseResult res = ParseResult::Ok;
    auto [value, comment_start] = NextValue(record, res);
    if (res != ParseResult::Ok) {
        throw boost::enable_current_exception(InvalidKeyword(
            components.name, fmt::format("Invalid keyword. Invalid value found: {}", record)));
    }
    components.value = value;
 
    // Optional comment
    if (comment_start.has_value()) {
        record.remove_prefix(*comment_start);
        components.comment = TrimBlanks(record, TrimType::Full);
    } else {
        components.comment = std::string_view();
    }
 
    return components;
}
 
constexpr LiteralKeyword::Components
ParseEsoKeywordComponents(std::array<char, 80> const& record_array) {
    auto record = std::string_view(&record_array[0], record_array.size());
    LiteralKeyword::Components components{};
    components.type = KeywordType::Eso;
    // Name
    record.remove_prefix(constants::ESO_HIERARCH_PREFIX.size());
 
    auto [name, value_start] = NextToken(record, '=', TrimType::Name);
    components.name = name;
    // Value
    if (!value_start.has_value()) {
        throw boost::enable_current_exception(InvalidKeyword(
            name,
            fmt::format("invalid ESO HIERARCH keyword. No '=' value indicator found: {}", record)));
    }
    record.remove_prefix(*value_start);
    ParseResult res = ParseResult::Ok;
    auto [value, comment_start] = NextValue(record, res);
    if (res != ParseResult::Ok) {
        throw boost::enable_current_exception(InvalidKeyword(
            name, fmt::format("Invalid ESO HIERARCH keyword. Invalid value found: {}", record)));
    }
    components.value = value;
    // Optional comment
    if (comment_start.has_value()) {
        record.remove_prefix(*comment_start);
        components.comment = TrimBlanks(record, TrimType::Full);
    } else {
        components.comment = std::string_view();
    }
 
    return components;
}
 
constexpr LiteralKeyword::Components
ParseCommentaryKeywordComponents(std::array<char, 80> const& record_array) {
    auto record = std::string_view(&record_array[0], record_array.size());
    LiteralKeyword::Components components{};
    components.type = KeywordType::Commentary;
 
    // Name
    components.name = TrimBlanks(record.substr(0u, constants::KEYWORD_NAME_LENGTH), TrimType::Name);
    record.remove_prefix(constants::KEYWORD_NAME_LENGTH);
    // Value
    components.value = TrimBlanks(record, TrimType::Full);
 
    // Commentary keywords does not have a comment
    components.comment = std::string_view();
 
    return components;
}
 
[[nodiscard]] constexpr LiteralKeyword::Components
ParseKeywordComponents(std::array<char, 80> const& record) {
    auto sv_record = std::string_view(&record[0], record.size());
    auto type = ParseKeywordType(sv_record);
 
    // Parse name component
    switch (type) {
    case KeywordType::Value:
        return ParseValueKeywordComponents(record);
    case KeywordType::Eso:
        return ParseEsoKeywordComponents(record);
    case KeywordType::Commentary:
        return ParseCommentaryKeywordComponents(record);
    };
    std::cerr << __PRETTY_FUNCTION__ << ": Invalid type: " << type << std::endl;
    std::terminate();
}
 
}  // namespace
 
bool operator<(KeywordNameView lhs, KeywordNameView rhs) noexcept {
    return lhs.name < rhs.name;
}
 
bool operator==(KeywordNameView lhs, KeywordNameView rhs) noexcept {
    return lhs.type == rhs.type && lhs.name == rhs.name;
}
 
bool operator!=(KeywordNameView lhs, KeywordNameView rhs) noexcept {
    return !(lhs == rhs);
}
 
LiteralKeyword::LiteralKeyword() noexcept {
    std::fill(std::begin(m_record), std::end(m_record), ' ');
    // cppcheck-suppress throwInNoexceptFunction
    m_components = ParseKeywordComponents(m_record);
}
 
LiteralKeyword::LiteralKeyword(std::array<char, constants::RECORD_LENGTH> record)
    : m_record(record), m_components(ParseKeywordComponents(m_record)) {
    try {
        ValidateKeywordName(GetName());
    } catch (...) {
        std::throw_with_nested(std::invalid_argument("Failed to construct LiteralKeyword"));
    }
}
 
LiteralKeyword::LiteralKeyword(std::string_view record) : m_record() {
    try {
        if (record.size() > constants::RECORD_LENGTH) {
            throw boost::enable_current_exception(InvalidKeyword(
                record, "literalKeyword: Keyword with record > 80 chars is invalid"));
        }
        std::fill(std::begin(m_record), std::end(m_record), ' ');
        std::copy(std::begin(record), std::end(record), std::begin(m_record));
        m_components = ParseKeywordComponents(m_record);
        ValidateKeywordName(GetName());
    } catch (...) {
        std::throw_with_nested(std::invalid_argument("Failed to construct LiteralKeyword"));
    }
}
 
LiteralKeyword::LiteralKeyword(LiteralKeyword const& other) noexcept {
    *this = other;
}
 
// cppcheck-suppress operatorEqRetRefThis
LiteralKeyword& LiteralKeyword::operator=(LiteralKeyword const& other) noexcept {
    m_record = other.m_record;
    // Reconstruct string_views using same offset, but with base of this->m_record.data()
    auto make_offset = [&](std::string_view sv) -> std::string_view {
        if (sv.empty()) {
            return std::string_view();
        }
        auto start_offset = sv.data() - other.m_record.data();
        return std::string_view(m_record.data() + start_offset, sv.size());
    };
    m_components.name = make_offset(other.m_components.name);
    m_components.value = make_offset(other.m_components.value);
    m_components.comment = make_offset(other.m_components.comment);
    m_components.type = other.m_components.type;
    return *this;
}
 
std::string_view LiteralKeyword::GetRecord() const& noexcept {
    auto full = std::string_view(&m_record[0], m_record.size());
    return TrimBlanks(full, TrimType::Name);
}
 
bool operator<(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator==(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetRecord() == rhs.GetRecord();
}
 
bool operator!=(LiteralKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetRecord() != rhs.GetRecord();
}
 
std::ostream& operator<<(std::ostream& os, LiteralKeyword const& kw) {
    os << kw.GetRecord();
    return os;
}
 
auto operator==(LiteralKeyword::Components const& lhs,
                LiteralKeyword::Components const& rhs) noexcept -> bool {
    return lhs.type == rhs.type && lhs.name == rhs.name && lhs.value == rhs.value &&
           lhs.comment == rhs.comment;
}
 
auto operator!=(LiteralKeyword::Components const& lhs,
                LiteralKeyword::Components const& rhs) noexcept -> bool {
    return !operator==(lhs, rhs);
}
 
// Instantiate the different variants
template struct BasicKeyword<ValueKeywordTraits>;
template struct BasicKeyword<EsoKeywordTraits>;
 
template std::ostream&
operator<< <EsoKeywordTraits>(std::ostream& os, BasicKeyword<EsoKeywordTraits> const& kw);
 
template std::ostream&
operator<< <ValueKeywordTraits>(std::ostream& os, BasicKeyword<ValueKeywordTraits> const& kw);
 
template <class Trait>
BasicKeyword<Trait>::BasicKeyword(std::string name_arg,
                                  char const* string_value,
                                  std::optional<std::string> comment_arg)
    : name(std::move(name_arg)), value(std::string(string_value)), comment(std::move(comment_arg)) {
    ValidateKeywordName(GetName());
}
 
template <class Trait>
BasicKeyword<Trait>::BasicKeyword(std::string name_arg,
                                  ValueType value_arg,
                                  std::optional<std::string> comment_arg)
    : name(std::move(name_arg)), value(std::move(value_arg)), comment(std::move(comment_arg)) {
    ValidateKeywordName(GetName());
}
 
template <class Trait>
bool BasicKeyword<Trait>::operator==(BasicKeyword<Trait> const& rhs) const noexcept {
    return name == rhs.name && value == rhs.value && comment == rhs.comment;
}
 
template <class Trait>
bool BasicKeyword<Trait>::operator!=(BasicKeyword<Trait> const& rhs) const noexcept {
    return !(*this == rhs);
}
 
template <class Trait>
bool BasicKeyword<Trait>::operator<(BasicKeyword<Trait> const& rhs) const noexcept {
    return name < rhs.name;
}
 
bool NameEquals(KeywordVariant const& lhs, KeywordVariant const& rhs) noexcept {
    return std::visit(
        [&](auto const& lhs, auto const& rhs) noexcept -> bool {
            return lhs.GetName() == rhs.GetName();
        },
        lhs,
        rhs);
}
 
KeywordClass GetKeywordClass(std::string_view name) {
    if (name.size() > FLEN_KEYWORD) {
        throw boost::enable_current_exception(InvalidKeyword(name, "keyword too long"));
    }
    char record[FLEN_CARD] = {' '};
    std::copy(name.begin(), name.end(), &record[0]);
 
    return static_cast<KeywordClass>(fits_get_keyclass(record));
}
 
bool operator<(LiteralKeyword const& lhs, EsoKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator<(LiteralKeyword const& lhs, ValueKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
bool operator<(ValueKeyword const& lhs, EsoKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator<(ValueKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
bool operator<(EsoKeyword const& lhs, ValueKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
bool operator<(EsoKeyword const& lhs, LiteralKeyword const& rhs) noexcept {
    return lhs.GetName() < rhs.GetName();
}
 
std::ostream& operator<<(std::ostream& os, BasicKeywordBase::ValueType const& kw) {
    std::visit(
        [&](auto const& var) mutable {
            using T = std::decay_t<decltype(var)>;
            if constexpr (std::is_same_v<T, std::string>) {
                os << "(str)'" << var << "'";
            } else if constexpr (std::is_same_v<T, bool>) {
                os << "(bool)" << (var ? "true" : "false");
            } else {
                os << "(" << TypeStr<T>() << ")" << var;
            }
        },
        kw);
    return os;
}
 
template <class Trait>
std::ostream& operator<<(std::ostream& os, BasicKeyword<Trait> const& kw) {
    os << "name='" << kw.name << "', value=" << kw.value << ", comment=";
    if (kw.comment) {
        os << "'" << *kw.comment << "'";
    } else {
        os << "n/a";
    }
    return os;
}
 
std::ostream& operator<<(std::ostream& os, KeywordVariant const& kw) {
    std::visit([&](auto const& var) mutable { os << var; }, kw);
    return os;
}
 
void UpdateKeywords(KeywordVector& to, KeywordVector const& from, ConflictPolicy policy) {
    for (auto const& kw : from) {
        if (auto it = std::find_if(
                to.begin(), to.end(), [&](auto const& val) { return NameEquals(val, kw); });
            it != to.end()) {
            if (policy == ConflictPolicy::Replace) {
                // Replace existing keyword with same name (and type)
                *it = kw;
            }
        } else {
            // Otherwise append
            to.emplace_back(kw);
        }
    }
}
 
void InsertKeywords(KeywordVector& keywords,
                    KeywordVector::iterator position,
                    KeywordVector::const_iterator from_first,
                    KeywordVector::const_iterator from_last) {
    // Insert in specified position and then delete duplicates from the two ranges before and after
    // inserted elements.
    auto num_elements = std::distance(from_first, from_last);
    auto pred = [&](KeywordVector::value_type const& kw) -> bool {
        return std::find_if(from_first, from_last, [&](auto const& val) {
                   return NameEquals(val, kw);
               }) != from_last;
    };
    auto inserted_first = keywords.insert(position, from_first, from_last);
    auto after_inserted_first = inserted_first;
    std::advance(after_inserted_first, num_elements);
    // Invalidates iterators after_inserted_first -> end (note: inserted_first is still valid)
    keywords.erase(std::remove_if(after_inserted_first, keywords.end(), pred), keywords.end());
    // Invalidates iterators begin -> inserted_first
    // cppcheck-suppress invalidContainer
    keywords.erase(std::remove_if(keywords.begin(), inserted_first, pred), inserted_first);
}
 
std::string FormatFitsValue(KeywordNameView name, BasicKeywordBase::ValueType const& value) {
    using namespace std::string_view_literals;
    return std::visit(
        [&](auto& value) -> std::string {
            using T = std::decay_t<decltype(value)>;
            if constexpr (std::is_same_v<T, std::string>) {
                // Escape `'`
                auto escaped_value = FitsEscapeString(value);
                if (name.type == daq::fits::KeywordType::Value && name.name == "XTENSION"sv) {
                    // FITS requires XTENSION be padded to at least 8 chars (sec 4.2.1)
                    return fmt::format("'{: <8s}'", escaped_value);
                } else {
                    return fmt::format("'{}'", escaped_value);
                }
            } else if constexpr (std::is_same_v<T, bool>) {
                return value ? "T" : "F";
            } else if constexpr (std::is_same_v<T, double>) {
                if (value > 10000) {
                    return fmt::format("{:g}", value);
                } else {
                    return fmt::format("{:.1f}", value);
                }
            } else if constexpr (std::is_same_v<T, std::int64_t>) {
                return fmt::format("{:d}", value);
            } else if constexpr (std::is_same_v<T, std::uint64_t>) {
                return fmt::format("{:d}", value);
            } else {
                static_assert(always_false_v<T>, "non-exhaustive visitor!");
            }
        },
        value);
}
 
LiteralKeyword Format(EsoKeyword const& keyword) {
    // Fixed value format
    auto name = keyword.GetName();
    auto value = FormatFitsValue(name, keyword.value);
    auto comment = keyword.comment.value_or("");
    return InternalEsoKeywordFormat(name.name, value, comment);
}
 
LiteralKeyword Format(ValueKeyword const& keyword) {
    // Fixed value format
    auto name = keyword.GetName();
    auto value = FormatFitsValue(name, keyword.value);
    auto comment = keyword.comment.value_or("");
    return InternalValueKeywordFormat(name.name, value, comment);
}
 
LiteralKeyword Format(LiteralKeyword::Components const& keyword) {
    switch (keyword.type) {
    case KeywordType::Value: {
        return InternalValueKeywordFormat(keyword.name, keyword.value, keyword.comment);
    }
    case KeywordType::Eso: {
        return InternalEsoKeywordFormat(keyword.name, keyword.value, keyword.comment);
    }
    case KeywordType::Commentary: {
        return InternalCommentaryKeywordFormat(keyword.name, keyword.value);
    }
    };
    std::cerr << __PRETTY_FUNCTION__ << ": Invalid type: " << keyword.type << std::endl;
    std::abort();
}
 
LiteralKeyword Format(KeywordVariant const& keyword) {
    return std::visit(
        [&](auto& kw) -> LiteralKeyword {
            using T = std::decay_t<decltype(kw)>;
            if constexpr (std::is_same_v<T, LiteralKeyword>) {
                return Format(kw.GetComponents());
            } else {
                return Format(kw);
            }
        },
        keyword);
}
 
InvalidKeyword::InvalidKeyword(std::string_view name, std::string const& what)
    : InvalidKeyword(name, what.c_str()) {
}
 
InvalidKeyword::InvalidKeyword(std::string_view name, char const* what)
    : std::invalid_argument(fmt::format("Invalid keyword `{}` {}", name, what)) {
}
 
UnknownKeyword::UnknownKeyword(std::string_view name, std::vector<std::string> const& dictionaries)
    : InvalidKeyword(name,
                     fmt::format("keyword not found in any of the dictionaries: {}",
                                 boost::algorithm::join(dictionaries, ", "))) {
}
 
KeywordFormatter::~KeywordFormatter() noexcept {
}
 
auto StandardKeywordFormatter::Format(KeywordVariant const& keyword) const -> LiteralKeyword {
    return daq::fits::Format(keyword);
}
 
LiteralKeyword
UntypedFormat(KeywordNameView name, std::string_view value, std::string_view comment) {
    switch (name.type) {
    case KeywordType::Value:
        return InternalValueKeywordFormat(name.name, value, comment);
    case KeywordType::Eso:
        return InternalEsoKeywordFormat(name.name, value, comment);
    default:
        BOOST_ASSERT_MSG(false, "Invalid keyword type");
    }
}
 
namespace v1 {
namespace {
constexpr bool SortEsoKeywordName(std::string_view lhs, std::string_view rhs) noexcept {
    using namespace std::literals::string_view_literals;
 
    auto lhs_cat = ParseLogicalCategory(lhs);
    auto rhs_cat = ParseLogicalCategory(rhs);
    if (lhs_cat == rhs_cat) {
        /* within same category keyword is sorted by name */
        return lhs < rhs;
    }
    // This determines the custom category sorting order:
    std::array<std::string_view, 8> categories = {
        "DPR"sv, "OBS"sv, "TPL"sv, "GEN"sv, "TEL"sv, "ADA"sv, "INS"sv, "DET"sv};
    auto lhs_idx = std::find(std::begin(categories), std::end(categories), lhs_cat);
    auto rhs_idx = std::find(std::begin(categories), std::end(categories), rhs_cat);
 
    if (lhs_idx != std::end(categories)) {
        if (rhs_idx != std::end(categories)) {
            // Both lhs and rhs are have special case categories. Sort by
            // their relative position (note: same category was handled before).
            return std::distance(lhs_idx, rhs_idx) > 0;
        } else {
            /* rhs is an unknown category, sort last */
            return true;
        }
    } else {
        if (rhs_idx != std::end(categories)) {
            /* Sort rhs before lhs as it has special category*/
            return false;
        } else {
            /* both lhs and rhs are unknown categories -> sort by name */
            return lhs < rhs;
        }
    }
}
}  // namespace
 
bool StandardLess::operator()(LiteralKeyword const& lhs_kw, LiteralKeyword const& rhs_kw) noexcept {
    auto lhs = lhs_kw.GetName();
    auto rhs = rhs_kw.GetName();
 
    switch (lhs.type) {
    case Value:
        switch (rhs.type) {
        case Value:
            /* Value never sorted before other Value (stable sorted) */
            return false;
        case Eso:
            [[fallthrough]];
        case Commentary:
            /* lhs Value type sorted before ESO and Commentary types */
            return true;
        }
    case Eso:
        switch (rhs.type) {
        case Value:
            /* lhs is Eso and is sorted after Value */
            return false;
        case Eso:
            /* Both are ESO keywords so sorted by name */
            return SortEsoKeywordName(lhs.name, rhs.name);
        case Commentary:
            /* Eso before commentary */
            return true;
        };
    case Commentary:
        switch (rhs.type) {
        case Value:
            [[fallthrough]];
        case Eso:
            /* lhs is Commentary so sorted after both Value and Eso */
            return false;
        case Commentary:
            /* Commentary keywords are stable sorted last */
            return lhs.name < rhs.name;
        }
    };
    return false;
}
 
void StandardSort(std::vector<LiteralKeyword>& keywords) {
    std::stable_sort(std::begin(keywords), std::end(keywords), StandardLess{});
}
 
}  // namespace v1
 
#if defined(UNIT_TEST)
// Some compile time checks to also verify parsing function are actually constexp.
static_assert(ParseKeywordType("DATE-OBS= 'date'") == KeywordType::Value);
static_assert(ParseKeywordType("DATE-OBS='date'") == KeywordType::Commentary);
static_assert(NextToken("        ='date'", '=', TrimType::Name) ==
              std::pair<std::string_view, std::optional<std::string_view::size_type>>(" ", 9));
#endif
}  // namespace daq::fits