Readmes updated

Author: VioletGiraffe

container/README.md

@@ -1,57 +1,34 @@
-## A collection of algorithms and augmentations for STL-compatible containers
+# Container utilities
 
-### algorithms.hpp
+Algorithms, adapters, and containers for STL-compatible code.
 
-Defines two functions in `ContainerAlgorithms` namespace that are constructed upon the standard algorithms:
-* `void erase_all_occurrences(ContainerType& container, const ArgumentType& item)` deletes every occurrence of the `item` in `container` using the remove-erase idiom.
-* `void void erase_if(ContainerType& container, std::function<bool(const ItemType&)>` deletes every occurrence of the `item` in `container` using the remove-erase idiom.
+## Facilities
 
-### flat_map.hpp
+| Header | Facility |
+|---|---|
+| `algorithms.hpp` | `ContainerAlgorithms::erase_if()` applies the remove/erase idiom to sequence containers. |
+| `flat_map.hpp` | Vector-backed sorted `flat_map` and `flat_set` with heterogeneous lookup, random-access iteration, ordinary insertion/erasure, sorted-range merging, and batched unsorted insertion. |
+| `iterator_helpers.hpp` | `const_forward_iterator_wrapper` retains both an iterator and its parent container, allowing validity and end checks; 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. |
+| `ordered_containers.hpp` | `ordered_container` adds explicit sorting, lower-bound lookup, and unique sorted insertion to sequence containers. |
+| `set_operations.hpp` | Common-prefix, deduplication, difference, three-way diff, and order-insensitive equality algorithms. |
+| `std_container_helpers.hpp` | Begin/end pair macros, transparent `std::set`, and helpers selecting `push_back`/`insert` or member/linear lookup according to container capabilities. |
+| `tracking_allocator.hpp` | Standard allocator wrapper that reports the bytes currently allocated through that allocator instance. |
+| `vector2d.hpp` | Rectangular `vector<vector<T>>` helper with two-dimensional resize, row fill, width, and height. |
 
-Defines `flat_map` and `flat_set`, sorted associative containers backed by vectors. `flat_map` keeps keys and mapped
-values in separate vectors and exposes pair-like proxy iterators with `first`/`second` and `key()`/`value()` access.
-Both containers support ordinary insertion, merging from a sorted range, and batched unsorted appends followed
-by tail sorting and merging. Existing entries and the first newly inserted entry win duplicate keys. Key equality uses
-`operator==` when the compared types provide it, otherwise comparator equivalence. When both operations are available,
-they must define the same equivalence. Batch entries are added with `append_unsorted()`; ordered operations and
-iteration must not be used between `begin_batch()` and `end_batch()`.
-Map dereference returns its proxy by value, so `auto entry` and `const auto& entry` work in range loops but `auto& entry`
-does not. Read-only standard algorithms and construction of ordinary pair containers are supported; algorithms that
-reorder entries are intentionally ill-formed because keys are immutable.
+## Flat associative containers
 
-### iterator_helpers.hpp
+`flat_map` stores keys and mapped values in separate vectors and exposes pair-like proxy iterators with `first`/`second` and `key()`/`value()` access. Map dereference returns its proxy by value: `auto entry` and `const auto& entry` work in range loops, but `auto& entry` does not. Keys remain immutable, so read-only standard algorithms and construction of ordinary pair containers work while algorithms that reorder entries are intentionally ill-formed.
 
-Defines two classes `const_forward_iterator_wrapper` and `forward_iterator_wrapper` that encapsulate an std (or std-compatible) iterator together with a reference to the container this iterator points to. This allows using these iterators as any other normal iterator while also being able to get the parent container from them.
+Both flat containers support ordinary insertion, merging a sorted range, `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. Existing entries win conflicts with a batch, and the first batch entry wins duplicates within that batch.
 
-### ordered_containers.hpp
+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.
 
-Defines `ordered_container` class that wraps an STL-compatible container. It is intended for use with containers that aren't sorted by nature (e. g. vector or list as opposed to map or set), and provides three extra methods: `sort()`, `find(value)` and `insert_into_sorted(value)`. The `find` and `insert_into_sorted` methods require that container is sorted, and for such a container they provide optimized implementation using `std::lower_bound`. The `insert_into_sorted` method returns `std::pair<iterator, bool>` similar to the standard ordered containers.
+## Set operations
 
-### set_operations.hpp
-
-Defines a number of algorithms on containers in `SetOperations` namespace:
-* `OrderedSetType longestCommonStart(SupersetType<OrderedSetType> const & superset)` takes a set of ordered containers and returns the longest common starting sequence of items between all of these ordered containers.
-Example 1: `longestCommonStart(std::vector{std::vector<int>{1, 2, 3, 4, 5}, std::vector<int>{1, 2, 3, 10, 20}})` -> `std::vector{1, 2}`
-Example 2: `longestCommonStart(std::vector{std::string("Hello"), std::string("Heat"), std::string("Home")})` -> `std::string("H")`
-* `template <class ContainerType> ContainerType uniqueElements(const ContainerType& c)` returns only the unique items from `c`. This function is stable (item order is preserved). Has no-op overloads for `set` and `map` which may only contain unique items by definition.
-* `setTheoreticDifference` takes two containers `a` and `b` and an optional comparator, and returns a container of all the elements from `a` that are not in `b`.
-Example: `setTheoreticDifference<std::list>(std::vector<int> {1, 2, 3}, std::deque<int> {3, 1})` -> `std::list<int> {2}`
-It is assumed that the containers are unordered because for ordered containers `std::set_difference` can be called directly.
-* `calculateDiff` takes two containers `a` and `b` and an optional template argument specifying the output container type. It returns the following structure:
-    ```template <class OutputContainerType>
-    struct Diff
-    {
-        OutputContainerType common_elements;
-        OutputContainerType elements_from_a_not_in_b;
-        OutputContainerType elements_from_b_not_in_a;
-    };
-
-### std_container_helpers.hpp
-
-Defines two functions that behave differently depending on what container they're called with:
-* `void add_item(Container& container, const ItemType& item)` calls `push_back(item)` for containers that have push_back (ordered containers), and `insert(item)` for other (unordered) containers.
-* `auto container_aware_find(Container& container, const ItemType& item)` calls `container.find(item)` for containers that have a member function `find`, calls `std::find` otherwise.
-
-### string_helpers.hpp
-
-Defines `bool operator==(const std::string str, const char ch)` and `bool operator==(const char ch, const std::string str)` for comparing a string with to a single character.
+- `longestCommonStart()` returns the longest shared prefix of a container of ordered containers: `std::vector<std::string>{"Hello", "Heat", "Home"}` produces `"H"`.
+- `uniqueElements<ItemOrder>()` removes duplicates, optionally retaining the first or last occurrence order. The `std::set` overload is a no-op reference return.
+- `setTheoreticDifference<OutputContainer>()` sorts copies of two unordered inputs and returns the elements present only in the first.
+- `calculateDiff()` returns `common_elements`, `elements_from_a_not_in_b`, and `elements_from_b_not_in_a`.
+- `is_equal_sets()` compares compatible containers without regard to order; it sorts non-`std::set` inputs in place.

hash/README.md

@@ -0,0 +1,11 @@
+# Hash utilities
+
+Compile-time and runtime non-cryptographic hashing helpers. These functions are suitable for hash tables, identifiers, partitioning, and checks against accidental changes; they are not authentication or password-hashing primitives.
+
+| Header | Facility |
+|---|---|
+| `hash_consteval.hpp` | `murmur3_32_consteval()` computes seedable MurmurHash3 x86-32 for a `std::string_view` during constant evaluation. Byte assembly is explicitly little-endian, so results are stable across host architectures. |
+| `mixers.h` | `mix_moremur()` avalanches one 64-bit integer, useful for finalizing or decorrelating an already assembled key. |
+| `wheathash.hpp` | `wheathash64()` hashes a byte range with a fixed or caller-supplied seed; `wheathash32()` truncates it to 32 bits, and `wheathash64v()` hashes an object's in-memory representation. |
+
+`wheathash64v()` includes padding and uses the host object representation. Its result may therefore vary with compiler, ABI, byte order, or uninitialized padding; use the byte-range overload with an explicitly serialized representation when hashes must persist or cross process/platform boundaries.

math/README.md

@@ -1,14 +1,13 @@
-## A collection of arithmetic convenience functions
+# Math utilities
 
-### math.hpp
+`math.hpp` provides small arithmetic templates in namespace `Math`.
 
-Defines a number of template functions for mathematical and arithmetical operations in the `Math` namespace.
-
-* `round` and `floor` functions that accept a second parameter - the number of digits after the decimal point to round or floor to.
-* `round`, `floor` and `ceil` functions that accept an extra template parameter for the output type which can be integer or floating-point.
-* `abs` function suitable both for integer and floating-point values. For integer values, it takes in to account that the opposite value for `std::numeric_limits<T>::min()` is not representable in the same type, so it truncates it to `::max()`.
-* `clamp(T min, T value, T max)` function template.
-* `signum` function template (returns -1 for negative value, 0 for zero and 1 for positive).
-* `squared` function template that accepts an output type that can be larger than the inputtype  to fit the result reliably.
-* `bool isInRange(const T value, const T lowerBound, const T upperBound)` function template.
-* `arithmeticMean`, `geometricMean`: function templates that take a parameter pack and return the mean value of the values in the pack. Can be used to conveniently calculate the mean of 3-4-5 values.
+| Facility | Description |
+|---|---|
+| `round`, `floor`, `ceil` | Decimal-place rounding/flooring and typed numeric conversions for integral and floating-point inputs. |
+| `abs` | Integral and floating absolute value; the unrepresentable magnitude of the signed minimum is saturated to the type's maximum. |
+| `clamp`, `signum`, `squared`, `isInRange` | Bounds, sign, optionally widened square, and inclusive range helpers. |
+| `arithmeticMean`, `geometricMean` | Mean of a short value parameter pack, returned as the explicitly selected result type. |
+| `pow2` | Computes powers of two for positive exponents. |
+| `reduce` | Maps a 32-bit value into `[0, range)` using the high half of a multiply. |
+| `FastMod32` | Precomputes a non-zero divisor's reciprocal data so repeated 32-bit modulo operations avoid division. |

parameter_pack/README.md

@@ -1,15 +1,22 @@
-## Helper templates for accessing and manipulating template parameter packs
+# Parameter-pack utilities
 
-### parameter_pack_helpers.hpp
+`parameter_pack_helpers.hpp` provides compile-time type lookup and iteration in namespace `pack`, plus the `type_pack` facade.
 
-* `template <typename T, typename... Args> constexpr size_t index_for_type_v` defines the index (position) of *type* T in the `Args...` pack. Results in compilation error if the type is not found.
+| Facility | Description |
+|---|---|
+| `type_by_index<I, Args...>` | Type at index `I`. |
+| `index_for_type<T, Args...>()` | Optional compile-time index of the first `T`; `index_for_type_v` is the strict form that fails compilation when absent. |
+| `has_type_v<T, Args...>`, `type_count<T, Args...>()` | Tests for a type and counts its occurrences. |
+| `first_type<Args...>` | First type in a pack. |
+| `value_by_index<I>(args...)` | Value at index `I`, selected during constant evaluation. |
+| `for_value(f, args...)` | Calls `f(value)` for every value in order. |
+| `for_type<Args...>(f)` | Calls `f.template operator()<T>()` once for every type. |
+| `type_pack<Args...>` | Exposes pack size and indexed types, finds type indices, appends types, constructs another variadic template, or converts the pack to `std::tuple`. |
 
-* `template <size_t index, typename... Args> using type_by_index` defines the *type* at `index` in `Args...`.
+```cpp
+pack::for_value([](const auto& value) { std::cout << value << '\n'; }, 0, -1.0f, "text");
 
-* `template <size_t index, typename... Args> constexpr auto value_by_index(Args&&... args) noexcept` returns the *value* at position `index` from `args`.
-
-* `template <typename Functor, class... Args> void apply(Functor&& f, Args&&... args)` iterates the pack `args` and calls functor `f` with each *value* in the pack.
-<br>Example: `apply([](auto&& value){std::cout << value << std::endl;}, 0, -1.0f, "text");`
-
-* `template <typename... Args, typename Functor> void for_type(Functor&& f)` calls functor `f` for each *type* in the argument pack. The type is passed using `type_wrapper` helper template defined in `utils/template_magic.hpp`. 
-<br>Example: `for_type<int, float, std::string> ([](auto&& t){ using Type = typename decltype(t)::type; });`
+pack::for_type<int, float, std::string>([]<typename T> {
+    static_assert(sizeof(T) > 0);
+});
+```

random/README.md

@@ -1,6 +1,11 @@
-## Helper class for wrapping generator and distribution inside a single class.
+# Random-number utilities
 
-### randomnumbergenerator.h
+`randomnumbergenerator.h` combines a standard random engine and distribution behind a small integral interface.
 
- I find it annoying to have to explicitly declare both the generator and the distribution, so I wrapped it up in a class. Templated on value type, distribution type and generator type; has reasonable default distribution `std::uniform_int_distribution` and generator `std::mt19937_64`.
- 
+| Facility | Description |
+|---|---|
+| `RandomNumberGenerator<IntType, DistributionT, GeneratorT>` | Owns one generator and distribution and returns the next value through `rand()`. Defaults to `std::mt19937_64`, `std::uniform_int_distribution`, the full `IntType` range, and deterministic seed `0`. |
+| `RNG<IntType, minValue, maxValue, ...>` | Static `next()` facade backed by one thread-local generator per specialization. Each thread starts from seed `0`. |
+| `RandomChar` | `RNG<int16_t, 33, 126>` specialization for printable ASCII code points. |
+
+Supply a varying seed to `RandomNumberGenerator` when reproducible output is not desired. `RNG` intentionally exposes no reseeding API.

tuple/README.md

@@ -1,9 +1,15 @@
-## Helper templates for working specifically with std::tuple
+# Tuple utilities
 
-### tuple_helpers.hpp
+`tuple_helpers.hpp` provides compile-time inspection and value iteration in namespace `tuple`.
 
-Defines namespace `tuple`, containing the following templates:
-* `constexpr size_t tuple_size_v_omnivorous` is analogous to `std::tuple_size_v` but accepts types with any cv and ref qualifiers.
-* `indexForType` returns the index of type `T` in the given tuple; results in compilation error if type not present.
-* `visit` implements runtime indexing of a tuple - calls a functor the value at specified index (that need not be known at compile time) as the functor's argument. The argument can be a non-const reference for a non-const tuple, so it can mutate the tuple's items.
-* `for_each` calls a functor with each value from the tuple. Supports both `const` and non-`const` tuples. The argument can be a non-const reference for a non-const tuple, so it can mutate the tuple's items.
+| Facility | Description |
+|---|---|
+| `tuple_size_v_omnivorous<Tuple>` | `std::tuple_size_v` after removing reference qualifiers, accepting const and reference forms. |
+| `indexForType<T>(tuple)` | Compile-time index of `T`; fails compilation when the type is absent. |
+| `size(tuple)` | Compile-time tuple element count. |
+| `for_each(tuple, f)` | Calls `f` with every element in order, preserving tuple and element cv/ref qualifiers so a mutable tuple can be modified. |
+
+```cpp
+std::tuple values{1, 2.0};
+tuple::for_each(values, []<typename T>(T& value) { value += value; });
+```