public:

// One received field occurrence. The views refer to container

// storage and are invalidated by mutation.

struct entry {

std::string_view name;

std::string_view value;

};

// Adds a new occurrence at the end of the sequence, keeping any

// existing entries for the name.

void append(std::string_view name, std::string_view value);

// Erases every entry for the name (any case), then appends a

// single entry at the end of the sequence. The first-seen spelling

// of the name is retained.

void replace(std::string_view name, std::string_view value);

// Erases every entry for the name (any case). Returns true iff any

// entry was removed.

bool remove(std::string_view name);

// Earliest received occurrence of the name, or nullopt.

std::optional<std::string_view> first(std::string_view name) const;

// All occurrences of the name in received order; empty span when

// the name is absent.

std::span<const std::string> all(std::string_view name) const;

// Number of occurrences of the name.

std::size_t count(std::string_view name) const;

// The full sequence in insertion (wire) order. Building the cached views

// may allocate; callers performing admission can contain allocation failure.

std::span<const entry> entries() const;

bool empty() const noexcept { return order_.empty(); }

// Total number of field occurrences across all names.

std::size_t size() const noexcept { return order_.size(); }

// Entry-sequence equality: same number of occurrences in the same

// order, with equal (case-insensitive) names and equal values at

// every position.

friend bool operator==(const fields& a, const fields& b);

friend bool operator!=(const fields& a, const fields& b) {

return !(a == b);

}

private:

// The private codec traverses owned occurrences without allocating the entry cache.

friend class httpserver::detail::qpack_encoder;

static constexpr std::size_t npos = static_cast<std::size_t>(-1);

static bool iequals(std::string_view a, std::string_view b) noexcept;

static constexpr char ascii_lower(const char c) noexcept {

const auto u = static_cast<unsigned char>(c);

return (u >= 'A' && u <= 'Z')

? static_cast<char>(u - 'A' + 'a')

: c;

}

std::size_t find_key(std::string_view name) const noexcept;

std::size_t find_or_add_key(std::string_view name);

void erase_order_for(std::size_t key);

void rebuild_cache() const;

// Distinct names in first-seen order (first-seen spelling kept),

// with one value list per name in received order.

std::vector<std::string> name_store_;

std::vector<std::vector<std::string>> value_store_;

// (name key, value index) per occurrence, in insertion order.

std::vector<std::pair<std::size_t, std::size_t>> order_;

// Lazily rebuilt views for entries(); invalidated by mutation.

mutable std::vector<entry> entry_cache_;

mutable bool cache_dirty_ = true;