flat_map: last remaing API bits

Author: VioletGiraffe

container/README.md

@@ -8,7 +8,7 @@ Algorithms, adapters, and containers for STL-compatible code.
 |---|---|
 | `algorithms.hpp` | `ContainerAlgorithms::erase_if()` applies the remove/erase idiom to sequence containers. |
 | `chunked_deque.hpp` | `chunked_deque` holds elements in fixed-size blocks, each with an occupancy bitmask, so an erasure anywhere in the sequence clears a bit instead of relocating anything. Push and pop at both ends, insertion anywhere, and stable references. `operator[]` is linear in the block count: uneven occupancy rules out index arithmetic. `reserve()` pre-allocates blocks and keeps them across a drain. |
-| `flat_map.hpp` | Vector-backed sorted `flat_map` and `flat_set` with heterogeneous lookup, forward and reverse random-access iteration, ordinary insertion/erasure, sorted-range merging, and batched unsorted insertion. |
+| `flat_map.hpp` | Vector-backed sorted `flat_map` and `flat_set` with heterogeneous lookup, forward and reverse random-access iteration, ordinary insertion/erasure, sorted-range merging, batched unsorted insertion, and whole-vector handover in and out. |
 | `iterator_helpers.hpp` | `const_forward_iterator_wrapper` retains both an iterator and its parent container, so `endReached()` needs no second iterator. `isBound()` reports whether a container was supplied, not whether the iterator is still valid. Factories provide wrapped `cbegin`/`cend`. |
 | `multi_index.hpp` | `MultiIndexSet` owns values uniquely by one member and maintains a non-unique secondary-member index with exact and range lookup. |
 | `multimap_helpers.hpp` | `multimap_value_iterator` adapts a multimap iterator to expose only its mapped value while retaining access to the native iterator. |
@@ -24,6 +24,10 @@ Algorithms, adapters, and containers for STL-compatible code.
 
 `keys()` returns the backing key vector as a const reference, and `flat_map::values()` the mapped vector, indexed in lockstep with it and with iteration. Both are const: a write through a mutable handle would break the sort order, or desynchronize the map's two vectors.
 
+Whole vectors also move in and out without an element-by-element pass. `std::move(container).extract()` empties the container and returns its storage with capacity intact: a `containers` aggregate of `keys` and `values` for the map, the key vector itself for the set. `replace()` and the vector constructors take storage back. The `sorted_unique` overloads adopt it untouched and assert the caller's ordering and uniqueness; the untagged ones sort and deduplicate in place. `replace()` keeps the container's comparator, which assigning a whole new container would replace.
+
+`merge()` folds another container of the same type in, moving its entries across in one pass and leaving it empty. Existing entries win the collisions, as they do when a batch ends, and unlike `std::map::merge` the colliding entries are dropped rather than left behind in the source.
+
 Both flat containers support ordinary insertion, merging a sorted range, inserting a range in any order, `append_sorted_unique()`, and batched unsorted appends. Between `begin_batch()` and `end_batch()`, ordered operations and iteration are invalid. Finalization sorts only the appended tail and merges it with the existing prefix. A tail or sorted range starting past the last existing key skips the merge entirely, so growing a container by repeated appends never rebuilds it. Existing entries win conflicts with a batch, and the first batch entry wins duplicates within that batch. `insert(first, last)` and the initializer-list `insert()` sort and merge a range under those same rules, leaving the container unchanged if constructing an element throws. `insert_sorted()` is the cheaper path when the range is known to be ordered. `abort_batch()` instead discards the appended tail and restores the state from before `begin_batch()`; `clear()` ends an open batch by discarding the container. A failed `end_batch()` leaves the batch open, so `abort_batch()` remains available and lookups keep asserting until it runs.
 
 Key equality uses `operator==` when the compared types provide it and comparator equivalence otherwise. When both are available, they must describe the same equivalence relation.

container/flat_map.hpp

@@ -39,6 +39,14 @@ namespace FlatContainerInternal {
 			return !compare(query, stored_key); // lower_bound already established !(stored_key < query)
 	}
 
+	template <typename Key, typename Compare>
+	[[nodiscard]] bool sorted_and_unique(const std::vector<Key>& keys, const Compare& compare)
+	{
+		return std::is_sorted(keys.begin(), keys.end(), compare)
+			&& std::adjacent_find(keys.begin(), keys.end(),
+				[&](const Key& left, const Key& right) { return sorted_keys_equal(left, right, compare); }) == keys.end();
+	}
+
 	template <typename T>
 	concept SynthThreeWayComparable = std::three_way_comparable<T> || requires(const T& left, const T& right) {
 		{ left < right } -> std::convertible_to<bool>;
@@ -116,6 +124,10 @@ namespace FlatContainerInternal {
 
 } // namespace FlatContainerInternal
 
+// Marks the overloads that adopt a caller's vectors as they are: ordered by the container's comparator, no duplicate keys
+struct sorted_unique_t { explicit sorted_unique_t() = default; };
+inline constexpr sorted_unique_t sorted_unique{};
+
 template <typename Key, typename Mapped, typename Compare = std::less<>>
 class flat_map
 {
@@ -240,6 +252,13 @@ class flat_map
 	using reference = typename iterator::reference;
 	using const_reference = typename const_iterator::reference;
 
+	// The storage extract() hands over and replace() takes back, index-aligned as keys() and values() are
+	struct containers
+	{
+		std::vector<Key> keys;
+		std::vector<Mapped> values;
+	};
+
 	flat_map() = default;
 	explicit flat_map(Compare compare): _compare(std::move(compare)) {}
 
@@ -248,6 +267,22 @@ class flat_map
 
 	flat_map(std::initializer_list<value_type> values, Compare compare = {}): _compare(std::move(compare)) { insert(values); }
 
+	// Adopts the vectors untouched: the caller's ordering and uniqueness are asserted, never established
+	flat_map(sorted_unique_t, std::vector<Key> keys, std::vector<Mapped> values, Compare compare = {})
+		: _keys(std::move(keys)), _values(std::move(values)), _compare(std::move(compare))
+	{
+		assert(_keys.size() == _values.size());
+		assert(FlatContainerInternal::sorted_and_unique(_keys, _compare));
+	}
+
+	// Sorts and deduplicates in place: the entries never leave the vectors handed in
+	flat_map(std::vector<Key> keys, std::vector<Mapped> values, Compare compare = {})
+		: _keys(std::move(keys)), _values(std::move(values)), _compare(std::move(compare))
+	{
+		assert(_keys.size() == _values.size());
+		merge_appended_tail(0);
+	}
+
 	[[nodiscard]] bool empty() const noexcept { return _keys.empty(); }
 	[[nodiscard]] size_type size() const noexcept { return _keys.size(); }
 	[[nodiscard]] bool batch_open() const noexcept { return _batch_start != no_batch; }
@@ -307,6 +342,49 @@ class flat_map
 	[[nodiscard]] const std::vector<Key>& keys() const noexcept { assert_not_batching(); return _keys; }
 	[[nodiscard]] const std::vector<Mapped>& values() const noexcept { assert_not_batching(); return _values; }
 
+	// Empties the container: the vectors leave with their capacity, ready to be reworked and handed back
+	[[nodiscard]] containers extract() &&
+	{
+		assert_not_batching();
+		containers extracted{ std::move(_keys), std::move(_values) };
+		clear();
+		return extracted;
+	}
+
+	// Keeps this container's comparator, which assigning a whole new container would replace
+	void replace(sorted_unique_t, std::vector<Key>&& keys, std::vector<Mapped>&& values)
+	{
+		assert_not_batching();
+		assert(keys.size() == values.size());
+		assert(FlatContainerInternal::sorted_and_unique(keys, _compare));
+		_keys = std::move(keys);
+		_values = std::move(values);
+	}
+
+	void replace(std::vector<Key>&& keys, std::vector<Mapped>&& values)
+	{
+		assert_not_batching();
+		assert(keys.size() == values.size());
+		_keys = std::move(keys);
+		_values = std::move(values);
+		// The whole container is the batch: a throw from the comparator then leaves it open for abort_batch()
+		_batch_start = 0;
+		end_batch();
+	}
+
+	// Consumes other entirely: a colliding entry is dropped, not left behind as std::map::merge leaves it
+	// Entries already here win a collision, as they do when a batch ends
+	void merge(flat_map&& other)
+	{
+		assert(this != &other);
+		assert_not_batching();
+		other.assert_not_batching();
+		assert(FlatContainerInternal::sorted_and_unique(other._keys, _compare));
+		// Emptying other up front keeps it empty even when the merge throws partway through moving the entries out
+		auto [keys, values] = std::move(other).extract();
+		merge_sorted(std::move(keys), std::move(values));
+	}
+
 	// Ends an open batch as well
 	void clear() noexcept
 	{
@@ -873,6 +951,18 @@ class flat_set
 
 	flat_set(std::initializer_list<Key> values, Compare compare = {}): _compare(std::move(compare)) { insert(values); }
 
+	// Adopts the vector untouched: the caller's ordering and uniqueness are asserted, never established
+	flat_set(sorted_unique_t, std::vector<Key> keys, Compare compare = {}): _keys(std::move(keys)), _compare(std::move(compare))
+	{
+		assert(FlatContainerInternal::sorted_and_unique(_keys, _compare));
+	}
+
+	// Sorts and deduplicates in place: the keys never leave the vector handed in
+	explicit flat_set(std::vector<Key> keys, Compare compare = {}): _keys(std::move(keys)), _compare(std::move(compare))
+	{
+		merge_appended_tail(0);
+	}
+
 	[[nodiscard]] bool empty() const noexcept { return _keys.empty(); }
 	[[nodiscard]] size_type size() const noexcept { return _keys.size(); }
 	[[nodiscard]] bool batch_open() const noexcept { return _batch_start != no_batch; }
@@ -914,6 +1004,44 @@ class flat_set
 	// Const only: a write through a mutable handle could break the sort order
 	[[nodiscard]] const std::vector<Key>& keys() const noexcept { assert_not_batching(); return _keys; }
 
+	// Empties the container: the vector leaves with its capacity, ready to be reworked and handed back
+	[[nodiscard]] std::vector<Key> extract() &&
+	{
+		assert_not_batching();
+		auto extracted = std::move(_keys);
+		clear();
+		return extracted;
+	}
+
+	// Keeps this container's comparator, which assigning a whole new container would replace
+	void replace(sorted_unique_t, std::vector<Key>&& keys)
+	{
+		assert_not_batching();
+		assert(FlatContainerInternal::sorted_and_unique(keys, _compare));
+		_keys = std::move(keys);
+	}
+
+	void replace(std::vector<Key>&& keys)
+	{
+		assert_not_batching();
+		_keys = std::move(keys);
+		// The whole container is the batch: a throw from the comparator then leaves it open for abort_batch()
+		_batch_start = 0;
+		end_batch();
+	}
+
+	// Consumes other entirely: a colliding key is dropped, not left behind as std::set::merge leaves it
+	// Keys already here win a collision, as they do when a batch ends
+	void merge(flat_set&& other)
+	{
+		assert(this != &other);
+		assert_not_batching();
+		other.assert_not_batching();
+		assert(FlatContainerInternal::sorted_and_unique(other._keys, _compare));
+		// Emptying other up front keeps it empty even when the merge throws partway through moving the keys out
+		merge_sorted(std::move(other).extract());
+	}
+
 	// Ends an open batch as well
 	void clear() noexcept { _keys.clear(); _batch_start = no_batch; }
 	void reserve(size_type count) { _keys.reserve(count); }