layout.hpp

// SPDX-FileCopyrightText: 2006-2026, Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2026, Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
#include <array>       // for array
#include <concepts>    // for derived_from
#include <cstddef>     // for size_t
#include <cstdint>     // for uint8_t
#include <format>      // for formatter, format_error, format_to, format
#include <functional>  // for function
#include <iosfwd>      // for ostream, istream
#include <optional>    // for optional
#include <string>      // for string
#include <string_view> // for string_view
#include <vector>      // for operator==, vector
 
#include <hibf/layout/prefixes.hpp> // for layout_fullest_technical_bin_idx, layout_header, layout_lower_level
#include <hibf/platform.hpp>
 
namespace seqan::hibf
{
 
struct config;
 
} // namespace seqan::hibf
 
namespace seqan::hibf::layout
{
 
struct layout
{
    struct max_bin
    {
        std::vector<size_t> previous_TB_indices{}; // identifies the IBF based on upper levels
        size_t id{};                               // the technical bin id that has the maximum kmer content
 
        friend auto operator<=>(max_bin const &, max_bin const &) = default;
 
        // needs a template (instead of using std::ostream directly) to be able to only include <iosfwd>
        template <typename stream_type>
            requires std::derived_from<stream_type, std::ostream>
        friend stream_type & operator<<(stream_type & stream, max_bin const & object)
        {
            stream << prefix::layout_header << prefix::layout_lower_level << '_';
            auto it = object.previous_TB_indices.begin();
            auto end = object.previous_TB_indices.end();
            // If not empty, we join with ';'
            if (it != end)
            {
                stream << *it;
                while (++it != end)
                    stream << ';' << *it;
            }
            stream << " " << prefix::layout_fullest_technical_bin_idx << object.id;
 
            return stream;
        }
    };
 
    struct user_bin
    {
        std::vector<size_t> previous_TB_indices{}; // previous technical bin indices which refer to merged bin indices.
        size_t storage_TB_id{};                    // id of the technical bin that the user bin is actuallly stored in
        size_t number_of_technical_bins{};         // 1 == single bin, >1 == split_bin
        size_t idx{};                              // The index of the user bin corresponding to the order in data
 
        friend auto operator<=>(user_bin const &, user_bin const &) = default;
 
        // needs a template (instead of using std::ostream directly) to be able to only include <iosfwd>
        template <typename stream_type>
            requires std::derived_from<stream_type, std::ostream>
        friend stream_type & operator<<(stream_type & stream, user_bin const & object)
        {
            stream << object.idx << '\t';
            for (auto bin : object.previous_TB_indices)
                stream << bin << ';';
            stream << object.storage_TB_id << '\t';
            for ([[maybe_unused]] auto && elem : object.previous_TB_indices) // number of bins per merged level is 1
                stream << "1;";
            stream << object.number_of_technical_bins;
 
            return stream;
        }
    };
 
    void read_from(std::istream & stream);
    void write_to(std::ostream & stream) const;
 
    void clear();
 
    [[nodiscard]] size_t number_of_levels() const;
 
    struct diagnostic
    {
        enum class severity : uint8_t
        {
            note,
            warning,
            error
        };
 
        enum class code : uint8_t
        {
            // errors
            empty_layout,               
            no_technical_bins,          
            technical_bin_overflow,     
            user_bin_out_of_range,      
            duplicate_user_bin,         
            missing_user_bin,           
            overlapping_technical_bins, 
            top_level_max_bin_entry,    
            max_bin_without_ibf,        
            duplicate_max_bin,          
            invalid_max_bin,            
            max_bin_exceeds_root,       
            missing_max_bin,            
            // warnings
            technical_bin_exceeds_tmax, 
            single_bin_ibf,             
            unexpected_empty_bins,      
            // notes
            empty_technical_bins, 
        };
 
        severity level{}; 
        code what{};      
        std::optional<std::vector<size_t>> ibf{};
        std::optional<size_t> user_bin{};      
        std::optional<size_t> technical_bin{}; 
        std::string message{};                 
 
        // needs a template (instead of using std::ostream directly) to be able to only include <iosfwd>
        // `diagnostic_t` is always `diagnostic`. As a template parameter, it defers the check of the format string
        // until std::formatter<diagnostic>, which can only be specialised after this class, is known.
        template <typename stream_type, std::same_as<diagnostic> diagnostic_t>
            requires std::derived_from<stream_type, std::ostream>
        friend stream_type & operator<<(stream_type & stream, diagnostic_t const & object)
        {
            stream << std::format("{}", object);
            return stream;
        }
    };
 
    using diagnostic_handler = std::function<void(diagnostic const &)>;
 
    static void throw_on_error(diagnostic const & finding);
 
    bool validate(config const & config, diagnostic_handler const & handler = throw_on_error) const;
 
    size_t top_level_max_bin_id{};
    std::vector<max_bin> max_bins{};
    std::vector<user_bin> user_bins{};
 
    bool operator==(layout const &) const = default;
};
 
} // namespace seqan::hibf::layout
 
template <>
struct std::formatter<seqan::hibf::layout::layout::diagnostic>
{
    constexpr formatter() = default;                              
    constexpr formatter(formatter const &) = default;             
    constexpr formatter & operator=(formatter const &) = default; 
    constexpr formatter(formatter &&) = default;                  
    constexpr formatter & operator=(formatter &&) = default;      
    constexpr ~formatter() = default;                             
 
    template <typename parse_context_t>
    constexpr auto parse(parse_context_t & context)
    {
        auto const it = context.begin();
        if (it != context.end() && *it != '}')
            throw std::format_error{"seqan::hibf::layout::layout::diagnostic does not support format specifications."};
        return it;
    }
 
    template <typename format_context_t>
    auto format(seqan::hibf::layout::layout::diagnostic const & diagnostic, format_context_t & context) const
    {
        using severity = seqan::hibf::layout::layout::diagnostic::severity;
        if (diagnostic.level > severity::error)
            throw std::format_error{"Invalid seqan::hibf::layout::layout::diagnostic::severity."};
 
        constexpr std::array<std::string_view, 3> names{"NOTE", "WARNING", "ERROR"};
        return std::format_to(context.out(),
                              "[HIBF LAYOUT {}] {}",
                              names[static_cast<size_t>(diagnostic.level)],
                              diagnostic.message);
    }
};