From 27ce9364ec15431acf4f6c17f286a0b97ba5b5c8 Mon Sep 17 00:00:00 2001 From: Sergei Date: Sun, 27 Sep 2026 11:42:34 +0300 Subject: [PATCH 1/8] Add docs and tutorial for etl::intrusive_avl_tree (#1608) * Add docs and tutorial for etl::intrusive_avl_tree Documents the intrusive AVL tree added in PR #1425: a full API reference page under Containers/Trees, and a tutorial demonstrating ordered access to intrusively-linked objects with unpredictable lifetimes, including move support and destructor-driven automatic removal from the tree. Co-Authored-By: Claude Sonnet 5 * Add complexity shortcode and document its usage Introduces a {{< complexity >}} Hugo shortcode (with light/dark styling for constant/logarithmic/linear/linearithmic/polynomial/exponential classes) for rendering Big-O complexity inline, applies it throughout the intrusive_avl_tree API reference in place of raw "O(...)" text, and documents the Description/Complexity structure and supported classes in DOCUMENTATION.md. Co-Authored-By: Claude Sonnet 5 * Fix issues found by @CodeRabbit * Put complexity notes on their own lines in intrusive_avl_tree docs Move the complexity shortcode from the inline "**Complexity:**" label to its own line under a "**Complexity**" label. Notes that give several alternatives (e.g. amortized vs. worst-case) now show each one on a separate line. Update the guideline in DOCUMENTATION.md to match. * Update complexity examples in DOCUMENTATION.md Add the hard line break after the "**Complexity**" label in the example, and rewrite the list of supported complexity classes in the new two-line format, including an example with several alternatives. * Add logarithmic complexity example to DOCUMENTATION.md --------- Co-authored-by: Claude Sonnet 5 Co-authored-by: John Wellbelove --- DOCUMENTATION.md | 32 + docs/containers/trees/_index.md | 6 + docs/containers/trees/intrusive-avl-tree.md | 560 ++++++++++++++++++ docs/tutorials/_index.md | 5 + docs/tutorials/intrusive-avl-tree-tutorial.md | 210 +++++++ docs/utilities/intrusive-links.md | 2 + hugo/assets/css/custom.css | 76 +++ hugo/layouts/shortcodes/complexity.html | 3 + 8 files changed, 894 insertions(+) create mode 100644 docs/containers/trees/_index.md create mode 100644 docs/containers/trees/intrusive-avl-tree.md create mode 100644 docs/tutorials/intrusive-avl-tree-tutorial.md create mode 100644 hugo/layouts/shortcodes/complexity.html diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 2da43c6b..3b2c2ca6 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -120,6 +120,38 @@ The documentation is written in [Goldmark](https://github.com/teekennedy/goldmar Hugo uses [Goldmark](https://github.com/teekennedy/goldmark-markdown) as its default Markdown processor for versions 0.60.0 and newer. It is built into Hugo, providing high-performance and fully [CommonMark](https://commonmark.org/)-compliant rendering, along with support for [GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) Markdown. +### Documenting Algorithmic Complexity + +When documenting the complexity of an operation, use the `complexity` shortcode instead of writing raw Big-O text. +Place it on its own `**Complexity**` lines, right after the `**Description**` line/paragraph, for example: + +```markdown +**Description** +Returns the number of linked items. + +**Complexity** +{{< complexity "constant" "1" >}} +``` + +The shortcode takes two arguments: a complexity class (used to color and label it) and the expression to show +inside `O(...)`. The supported classes are: + +```markdown +**Complexity** +{{< complexity "constant" "1" >}} +**Complexity** +{{< complexity "linear" "N" >}}, where N is number of items in the tree, and assuming comparator is {{< complexity "constant" "1" >}}. +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where N is number of items in the tree. +**Complexity** +{{< complexity "linearithmic" "N log N" >}}, where N is number of items in the tree. +**Complexity** +{{< complexity "polynomial" "N²" >}}, where N is number of items in the tree. +**Complexity** +{{< complexity "constant" "1" >}} when something, or +{{< complexity "exponential" "2ᴺ" >}} some alternative, where N is number of items in the tree. +``` + ### Starting a New Page A template file is provided at `docs/page-template.md` to use as a starting point. Copy it to the diff --git a/docs/containers/trees/_index.md b/docs/containers/trees/_index.md new file mode 100644 index 00000000..c7bd6cc9 --- /dev/null +++ b/docs/containers/trees/_index.md @@ -0,0 +1,6 @@ +--- +title: "Trees" +weight: 100 +--- + +Tree like containers. diff --git a/docs/containers/trees/intrusive-avl-tree.md b/docs/containers/trees/intrusive-avl-tree.md new file mode 100644 index 00000000..ce52af92 --- /dev/null +++ b/docs/containers/trees/intrusive-avl-tree.md @@ -0,0 +1,560 @@ +--- +title: "intrusive_avl_tree" +weight: 1 +--- + +{{< callout type="info">}} + Header: `intrusive_avl_tree.h` + Similar to: `std::set` / `std::map` (ordering only, no ownership) +{{< /callout >}} + +An intrusive, self-balancing AVL tree. + +```cpp +template +etl::intrusive_avl_tree +``` + +`TValue` is the type that contains the actual values. It must derive from +`etl::intrusive_avl_tree_base::link_type`, exposed as the tree's own +`link_type`. Unlike `etl::intrusive_list`/`etl::intrusive_forward_list`, +which are templated directly on a link type and expect the node to derive +from it publicly, `intrusive_avl_tree` is templated only on `TValue` and an +`ID_`. Its `link_type` is a deliberately opaque wrapper around +`etl::tree_link` that exposes almost nothing as public (or even +protected) API, by design, so that inheriting from it imposes as little +"intrusive"-ness as possible, avoids name conflicts, and hides implementation +details. + +As with the other intrusive containers, an object may inherit multiple +`link_type`s with different `ID_` values to be a member of several trees (or +lists) at once: + +```cpp +typedef etl::intrusive_avl_tree_base<0>::link_type FirstLink; +typedef etl::intrusive_avl_tree_base<1>::link_type SecondLink; + +struct Item : public FirstLink, public SecondLink +{ + int value; +}; + +etl::intrusive_avl_tree tree0; +etl::intrusive_avl_tree tree1; +``` + +See also: +[Intrusive Links]({{% relref "../../utilities/intrusive-links.md" %}}) +[intrusive_list]({{% relref "../lists/intrusive-list.md" %}}) +[intrusive_forward_list]({{% relref "../lists/intrusive-forward-list.md" %}}) + +There is no class-level comparator template parameter. Every ordering +operation instead takes its own comparator functor at the call site. +Lookup functions (`find`, `lower_bound`, `upper_bound`, `find_or_insert`) +take a unary comparator accepting a single `const value_type&` and returning +an `int`: `>0` if the search target is "greater" than the argument, `0` if +found, `<0` if "smaller". The range constructor takes a binary comparator +`int(const value_type& lhs, const value_type& rhs)`; `etl::compare::cmp` +can be used directly if `value_type` defines `<`. + +## Member types + +```cpp +link_type (nested, inherited from etl::intrusive_avl_tree_base) +value_type TValue +pointer value_type* +const_pointer const value_type* +reference value_type& +const_reference const value_type& +size_type size_t +rvalue_reference value_type&& // C++11 +``` + +## The link type + +`TValue` must derive from `link_type`. It has its own set of special member +functions that a node author relies on. + +```cpp +link_type() +``` +**Description** +Default constructor. Leaves the item unlinked. + +--- + +```cpp +link_type(link_type&& other) +``` +**Description** +C++11. Constructs a new item by moving `other` into `this`. After +construction, `this` replaces `other` in the same tree position that +`other` occupied, so no tree balancing is needed. `other` becomes unlinked. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +link_type& operator=(link_type&& other) +``` +**Description** +C++11. Assigns `other` by moving it into `this`. Does nothing on +self-assignment. After assignment, `this` replaces `other` in the same tree +position that `other` occupied; `other` becomes unlinked. `this` might end +up in a different tree than it started in. + +**Complexity** +{{< complexity "logarithmic" "log N" >}} if `this` is already linked to a tree (it has to be erased first, with rebalancing), or +{{< complexity "constant" "1" >}} if `this` is not linked, where `N` is number of items in the tree. + +--- + +```cpp +link_type(const link_type&) = delete; +link_type& operator=(const link_type&) = delete; +``` +**Description** +C++11. Copy construction and assignment are disabled. + +--- + +```cpp +~link_type() +``` +**Description** +Might rotate the tree as necessary to keep it balanced. The tree is not the +real owner of its nodes' memory - the node's actual owner may destroy it at +any time, with or without a prior explicit `erase`. If the link is still +linked to a tree when it's destroyed, the destructor unlinks it +automatically; otherwise the node's former parent and children would keep +dangling pointers to it, breaking the tree and leading to undefined +behaviour. This is what makes it safe to embed a tree node in an object +whose lifetime is managed elsewhere. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree. + +## Constructors + +```cpp +etl::intrusive_avl_tree() +``` +**Description** +Default constructor. Constructs an empty tree. + +--- + +```cpp +template +etl::intrusive_avl_tree(TIterator first, TIterator last, TBinaryCompare binary_comp) +``` +**Description** +Constructs the tree from the range [`first`, `last`) of items, using +`binary_comp` to order them. All items in the range must be unlinked +initially; if any item is already linked to some other tree, throws +`etl::intrusive_avl_tree_value_is_already_linked`, and any items already +inserted are unlinked again - it's all or nothing. +If duplicates should be kept, `binary_comp` should return a non-zero result +even for "equal" items - `<0` prepends a duplicate, `>0` appends one. +Returning `0` for equal items keeps only the first of each run of duplicates +in the range; the rest are left unlinked. `etl::compare::cmp` +can be used directly as `binary_comp`. + +**Complexity** +{{< complexity "linearithmic" "N log N" >}}, where `N` is number of items in the range. + +--- + +```cpp +intrusive_avl_tree(intrusive_avl_tree&&) = default; +``` +**Description** +C++11. Move constructor. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +intrusive_avl_tree(const intrusive_avl_tree&) = delete; +``` +**Description** +C++11. Copy construction is disabled. + +--- + +```cpp +~intrusive_avl_tree() +``` +**Description** +Every remaining node is unlinked; none of the value objects are destroyed, +since the tree never owns their memory. + +**Complexity** +{{< complexity "linear" "N" >}}, where `N` is number of items in the tree. + +## Assignment + +```cpp +intrusive_avl_tree& operator=(intrusive_avl_tree&&) = default; +``` +**Description** +C++11. Move assignment. Does nothing on self-assignment. All of `this` +tree's former items have to be unlinked. + +**Complexity** +{{< complexity "linear" "N" >}}, where `N` is the size of `this` tree before assignment. + +--- + +```cpp +intrusive_avl_tree& operator=(const intrusive_avl_tree&) = delete; +``` +**Description** +C++11. Copy assignment is disabled. + +## Capacity + +```cpp +bool empty() const +``` +**Description** +Returns `true` if the tree has no linked items. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +size_t size() const +``` +**Description** +Returns the number of linked items. + +**Complexity** +{{< complexity "constant" "1" >}} + +## Iterators + +Only bidirectional `iterator`/`const_iterator` are provided; there is no +`reverse_iterator` (use `visit_in_order` with `is_reverse = true` instead). +An iterator may be in one of three logical states: it references a real +node (`has_value() == true`), it is the terminal sentinel (`it == end()`), +or it is "valueless" (`!has_value() && it != end()` - e.g. a +default-constructed iterator, or the result of `get_parent()`/`get_child()` +when there is no such node). + +```cpp +iterator begin() +const_iterator begin() const +const_iterator cbegin() const +``` +**Description** +Returns an iterator to the smallest item. Returns `end()` if the tree is +empty. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +iterator end() +const_iterator end() const +const_iterator cend() const +``` +**Description** +Returns an iterator to the terminal sentinel. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +iterator min() +const_iterator min() const +``` +**Description** +Equivalent to `begin()`. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +iterator max() +const_iterator max() const +``` +**Description** +Equivalent to `--end()`. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +iterator& operator++() +iterator operator++(int) +``` +**Description** +Advances the iterator to the next ("greater") item. + +**Complexity** +{{< complexity "constant" "1" >}} amortized, +{{< complexity "logarithmic" "log N" >}} worst-case, where `N` is number of items in the tree. + +--- + +```cpp +iterator& operator--() +iterator operator--(int) +``` +**Description** +Moves the iterator to the previous ("smaller") item. + +**Complexity** +{{< complexity "constant" "1" >}} amortized, +{{< complexity "logarithmic" "log N" >}} worst-case, where `N` is number of items in the tree. + +--- + +```cpp +reference operator*() const +pointer operator->() const +pointer get() const +``` +**Description** +Dereferences an iterator that has a value. `operator*`/`operator->` throw +`etl::intrusive_avl_tree_iterator_exception` if `has_value()` is `false`. +`get()` returns `nullptr` instead of throwing. + +--- + +```cpp +bool has_value() const +explicit operator bool() const +``` +**Description** +Returns `true` if the iterator references a real node. + +## Advanced traversal + +These are normally only needed for advanced traversal. + +```cpp +iterator get_root() +const_iterator get_root() const +``` +**Description** +Returns an iterator to the root node. Valueless (`has_value() == false`) if +the tree is empty. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +int_fast8_t get_balance_factor() const +``` +**Description** +Returns the node's AVL balance factor: `-1`, `0` or `+1`. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +iterator get_parent() const +``` +**Description** +Returns an iterator to the node's parent. Valueless if there is no parent. + +**Complexity** +{{< complexity "constant" "1" >}} + +--- + +```cpp +iterator get_child(bool is_right) const +``` +**Description** +Returns an iterator to the node's left (`is_right == false`) or right +(`is_right == true`) child. Valueless if there is no such child. + +**Complexity** +{{< complexity "constant" "1" >}} + +## Lookup + +```cpp +template +iterator find(TCompare comp) +template +const_iterator find(TCompare comp) const +``` +**Description** +Finds an item using the unary comparator `comp`. Returns `end()` if there +is no matching item. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree, +and assuming `comp` is {{< complexity "constant" "1" >}}. + +--- + +```cpp +template +iterator lower_bound(TCompare comp) +template +const_iterator lower_bound(TCompare comp) const +``` +**Description** +Returns an iterator to the first item that compares as "not less" than the +target of `comp`. Returns `end()` if no such item exists. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree, +and assuming `comp` is {{< complexity "constant" "1" >}}. + +--- + +```cpp +template +iterator upper_bound(TCompare comp) +template +const_iterator upper_bound(TCompare comp) const +``` +**Description** +Returns an iterator to the first item that compares as "greater" than the +target of `comp`. Returns `end()` if no such item exists. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree, +and assuming `comp` is {{< complexity "constant" "1" >}}. + +## Modifiers + +```cpp +template +etl::pair find_or_insert(TCompare comp, TFactory factory) +``` +**Description** +Finds an existing item using the unary comparator `comp`; if not found, +calls `factory()` (no arguments) and inserts the item it returns at the +position where the search stopped. This operation never invalidates +existing iterators, though depending on where the new item was linked, +existing iterators may skip over it. +`factory` must return the address of the new value (castable to +`link_type*`). If it returns `nullptr`, the tree is left unmodified and the +result iterator is valueless. If the returned value is already linked to +any tree, throws `etl::intrusive_avl_tree_value_is_already_linked`. +Returns a pair of: an iterator to the found or inserted item (never `end()`, +but may be valueless), and a `bool` that is `true` if the tree was modified. +If duplicates are wanted, `comp` should return a non-zero result even for +"equal" items - `+1` appends after existing duplicates, `-1` prepends +before them. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree, +and assuming `comp` and `factory` are {{< complexity "constant" "1" >}}. + +--- + +```cpp +iterator erase(iterator position) +iterator erase(const_iterator position) +``` +**Description** +Erases the item at `position`, including tree rebalancing. `position` must +reference a real item (asserts/throws +`etl::intrusive_avl_tree_iterator_exception` otherwise) and must originate +from this tree instance. Invalidates any existing iterator to the erased +item, but no others. Returns an iterator to the next node. +Use `clear()` instead if every item needs to be erased - no rebalancing is +involved. + +**Complexity** +{{< complexity "logarithmic" "log N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +void clear() +``` +**Description** +Unlinks every item, leaving the tree empty. Invalidates all existing +iterators. This is cheaper than calling `erase` on every item, which would +cost {{< complexity "linearithmic" "N log N" >}} once intermediate +rebalancing is taken into account. + +**Complexity** +{{< complexity "linear" "N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +void swap(intrusive_avl_tree& other) +friend void swap(intrusive_avl_tree& lhs, intrusive_avl_tree& rhs) +``` +**Description** +Swaps the contents of two trees. Does nothing on self-swap. + +**Complexity** +{{< complexity "constant" "1" >}} + +## Traversal + +Each of these visits every item exactly once, without recursion, and has a +`const` overload. The visitor must not modify the tree during visitation. + +```cpp +template +void visit_in_order(bool is_reverse, Visitor visitor) +``` +**Description** +Visits every item in sorted order. `is_reverse` selects ascending (`false`) +or descending (`true`) order. + +**Complexity** +{{< complexity "linear" "N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +template +void visit_pre_order(bool is_reverse, Visitor visitor) +``` +**Description** +Visits every item in pre-order (parent before children). + +**Complexity** +{{< complexity "linear" "N" >}}, where `N` is number of items in the tree. + +--- + +```cpp +template +void visit_post_order(bool is_reverse, Visitor visitor) +``` +**Description** +Visits every item in post-order (children before parent). + +**Complexity** +{{< complexity "linear" "N" >}}, where `N` is number of items in the tree. + +## Exceptions + +```cpp +intrusive_avl_tree_exception // base exception +intrusive_avl_tree_iterator_exception // invalid iterator use +intrusive_avl_tree_value_is_already_linked // item already linked to a tree +``` diff --git a/docs/tutorials/_index.md b/docs/tutorials/_index.md index 43e6530f..d41ac916 100644 --- a/docs/tutorials/_index.md +++ b/docs/tutorials/_index.md @@ -13,6 +13,11 @@ A quick introduction to containers. --- +[Intrusive AVL Tree](./intrusive-avl-tree-tutorial) +Ordering objects that already exist, without a second container. + +--- + [observer](./observer-tutorial) A templated set of classes to allow easier implementation of the observer pattern. diff --git a/docs/tutorials/intrusive-avl-tree-tutorial.md b/docs/tutorials/intrusive-avl-tree-tutorial.md new file mode 100644 index 00000000..033ff380 --- /dev/null +++ b/docs/tutorials/intrusive-avl-tree-tutorial.md @@ -0,0 +1,210 @@ +--- +title: "Intrusive AVL Tree" +--- + +A tutorial on how `etl::intrusive_avl_tree` can give ordered, +{{< complexity "logarithmic" "log N" >}} access to objects that already +exist elsewhere, without a second container to track them. + +## Overview + +Imagine a set of driver/sensor tasks, each owned by its own subsystem. They +are created and destroyed at unpredictable times as modules attach and +detach, so there is no compile-time upper bound on how many exist at once. +A scheduler needs to visit the tasks that are currently due, in ascending +deadline order, on every tick. + +A normal fixed-capacity ordered container (`etl::set`/`etl::map`) would need +a second, separately-sized place to store pointers to these tasks. Instead, +embedding an `etl::intrusive_avl_tree` link directly into each task object +gives the scheduler ordered, {{< complexity "logarithmic" "log N" >}} +access to exactly the tasks that exist right now - nothing more is +allocated, and nothing needs to be kept in sync by hand. That's the payoff of "intrusive": the tree links the +objects that already exist, rather than storing copies of them. + +The example below also demonstrates two things that fall out of the design +for free: +- **Move support.** When the `std::vector` that owns the tasks reallocates, + every task is moved into new storage - and each move takes over its + task's exact tree position, with no rebalancing and no code of its own. +- **Safe removal without an explicit `erase()` call.** Removing a task's + owning object removes it from the schedule too, with no dangling entry + left behind - whether that's because the object is destroyed while still + linked (`link_type`'s destructor unlinks it automatically), or, as in + this example, because `std::vector::erase` move-assigns another task over + it (`link_type`'s move assignment unlinks `this` before taking over the + moved-from tree position). + +## Example + +```cpp +#include "etl/intrusive_avl_tree.h" + +#include +#include +#include +#include + +// A driver/sensor task that already exists as a long-lived object owned by +// its own subsystem. Inheriting from the tree's link_type is all it takes +// to make it schedulable - no separate fixed-capacity container is needed +// to track which tasks exist. +class SensorTask : public etl::intrusive_avl_tree_base<0>::link_type +{ +public: + SensorTask(uint32_t id_, uint32_t deadline_, uint32_t period_) + : id(id_), deadline(deadline_), period(period_) + { + } + + // Orders primarily by deadline; ties are broken by id so two tasks due + // on the same tick still occupy distinct tree positions. + struct Locate + { + uint32_t target_deadline; + uint32_t target_id; + + int operator()(const SensorTask& node) const + { + if (target_deadline != node.deadline) + { + return (target_deadline < node.deadline) ? -1 : 1; + } + if (target_id != node.id) + { + return (target_id < node.id) ? -1 : 1; + } + return 0; + } + }; + + uint32_t id; + uint32_t deadline; // next tick at which this task must be serviced + uint32_t period; +}; + +typedef etl::intrusive_avl_tree Schedule; + +// The only place a task gets linked - called whenever a module attaches, +// or whenever a task is rescheduled after being serviced. +void schedule_task(Schedule& schedule, SensorTask& task) +{ + schedule.find_or_insert(SensorTask::Locate{ task.deadline, task.id }, + [&task] { return &task; }); +} + +// Visits every currently-due task in ascending deadline order, services it, +// then reschedules it at its next deadline. +void service_due_tasks(Schedule& schedule, uint32_t now) +{ + for (auto it = schedule.begin(); (it != schedule.end()) && (it->deadline <= now); ) + { + SensorTask& task = *it; + it = schedule.erase(it); // O(log N), rebalances + + std::cout << "servicing task " << task.id << " (was due at " << task.deadline << ")\n"; + + task.deadline = now + task.period; + schedule_task(schedule, task); // reschedule at the new deadline + } +} + +void print_schedule(const Schedule& schedule) +{ + for (auto it = schedule.begin(); it != schedule.end(); ++it) + { + std::cout << " task " << it->id << " due at " << it->deadline << "\n"; + } +} + +int main() +{ + Schedule schedule; + + // Driver registry: a plain std::vector that a subsystem uses to own its + // tasks for whatever reason it already needs to - the tree does not + // require this vector to exist, it's just a stand-in for "wherever the + // real owner happens to keep the object". + std::vector driver_registry; + driver_registry.reserve(2); + + driver_registry.emplace_back(1, 100, 1000); + schedule_task(schedule, driver_registry.back()); + + driver_registry.emplace_back(2, 300, 1000); + schedule_task(schedule, driver_registry.back()); + + std::cout << "Initial schedule (ascending deadline):\n"; + print_schedule(schedule); + + std::cout << "\nschedule.size() before growth: " << schedule.size() << "\n"; + + // driver_registry.reserve()'d capacity was 2; this emplace_back forces a + // reallocation. std::vector move-constructs every existing SensorTask + // into the new storage. Each move steals its task's exact tree position + // (O(1), no rebalancing) - the tree needs no code of its own to survive + // the underlying storage moving. + driver_registry.emplace_back(3, 200, 1100); + schedule_task(schedule, driver_registry.back()); + + std::cout << "schedule.size() after growth: " << schedule.size() << "\n\n"; + + std::cout << "Schedule after growth (still correctly ordered):\n"; + print_schedule(schedule); + + std::cout << "\nServicing due tasks at tick 250:\n"; + service_due_tasks(schedule, 250); + + std::cout << "\nSchedule after servicing:\n"; + print_schedule(schedule); + + // Unplugging a module removes its SensorTask from driver_registry. Task 2 + // isn't the last element, so std::vector::erase() doesn't just destroy it + // in place: it move-assigns the following element (task 3) into task 2's + // slot, then destroys the now-duplicate last slot. That move-assignment + // is SensorTask's (implicitly-generated) one, which calls + // link_type::operator=(link_type&&): it first unlinks *this* - task 2's + // slot, still linked at deadline 300 - from the tree, then takes over + // task 3's tree position. The destructor that runs afterwards, on the + // vacated last slot, fires on an already-unlinked, moved-from object, so + // it has nothing left to do - no explicit schedule.erase() call is made + // here, and no dangling entry is left behind. + std::cout << "\nschedule.size() before unplugging task 2: " << schedule.size() << "\n"; + + auto pos = std::find_if(driver_registry.begin(), driver_registry.end(), + [](const SensorTask& t) { return t.id == 2; }); + driver_registry.erase(pos); // move-assigns task 3 over task 2, unlinking task 2 + + std::cout << "schedule.size() after unplugging task 2: " << schedule.size() << "\n"; + + return 0; +} +``` + +## Program output + +``` +Initial schedule (ascending deadline): + task 1 due at 100 + task 2 due at 300 + +schedule.size() before growth: 2 +schedule.size() after growth: 3 + +Schedule after growth (still correctly ordered): + task 1 due at 100 + task 3 due at 200 + task 2 due at 300 + +Servicing due tasks at tick 250: +servicing task 1 (was due at 100) +servicing task 3 (was due at 200) + +Schedule after servicing: + task 2 due at 300 + task 1 due at 1250 + task 3 due at 1350 + +schedule.size() before unplugging task 2: 3 +schedule.size() after unplugging task 2: 2 +``` diff --git a/docs/utilities/intrusive-links.md b/docs/utilities/intrusive-links.md index 6ee73e3f..ac16e511 100644 --- a/docs/utilities/intrusive-links.md +++ b/docs/utilities/intrusive-links.md @@ -297,6 +297,8 @@ template struct tree_link ``` +`etl::intrusive_avl_tree` is built on top of `tree_link` - see [intrusive_avl_tree]({{% relref "../containers/trees/intrusive-avl-tree.md" %}}). + ### Template parameters ```cpp const size_t ID_ diff --git a/hugo/assets/css/custom.css b/hugo/assets/css/custom.css index e23c0ebf..ee5b7e09 100644 --- a/hugo/assets/css/custom.css +++ b/hugo/assets/css/custom.css @@ -420,4 +420,80 @@ tr td code{ font-size: 0.8rem !important; } +.complexity { + padding: 3px 6px; + border-radius: 999px; + font-weight: 600; + letter-spacing: 0.04em; + border: 1px solid transparent; +} +html.dark .complexity { + &.constant { + color: #7CFFB2; + background: rgba(0,255,120,0.08); + border-color: rgba(0,255,120,0.25); + } + &.logarithmic { + color: #7CE7FF; + background: rgba(0,200,255,0.08); + border-color: rgba(0,200,255,0.18); + } + &.linear { + color: #6AB7FF; + background: rgba(80,140,255,0.08); + border-color: rgba(80,140,255,0.18); + } + &.linearithmic { + color: #B78CFF; + background: rgba(140,80,255,0.08); + border-color: rgba(140,80,255,0.18); + } + &.polynomial { + color: #FFD36A; + background: rgba(255,190,0,0.08); + border-color: rgba(255,190,0,0.18); + } + &.exponential { + color: #ff7d9c; + background: rgba(255,0,80,0.08); + border-color: rgba(255,0,80,0.2); + } +} +html:not(.dark) .complexity { + &.constant { + color: #15803D; + background: rgba(34,197,94,0.10); + border-color: rgba(34,197,94,0.22); + } + + &.logarithmic { + color: #0E7490; + background: rgba(6,182,212,0.10); + border-color: rgba(6,182,212,0.22); + } + + &.linear { + color: #2563EB; + background: rgba(59,130,246,0.10); + border-color: rgba(59,130,246,0.22); + } + + &.linearithmic { + color: #7C3AED; + background: rgba(139,92,246,0.10); + border-color: rgba(139,92,246,0.22); + } + + &.polynomial { + color: #CA8A04; + background: rgba(234,179,8,0.12); + border-color: rgba(234,179,8,0.24); + } + + &.exponential { + color: #DC2626; + background: rgba(239,68,68,0.10); + border-color: rgba(239,68,68,0.22); + } +} diff --git a/hugo/layouts/shortcodes/complexity.html b/hugo/layouts/shortcodes/complexity.html new file mode 100644 index 00000000..644440ab --- /dev/null +++ b/hugo/layouts/shortcodes/complexity.html @@ -0,0 +1,3 @@ + + 𝐎({{ .Get 1 }}) + From 3f329f1ca46e22e3fcfb7bcd8f269488a51900b8 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Mon, 28 Sep 2026 10:38:08 +0100 Subject: [PATCH 2/8] Updated sponsors pages --- docs/business-and-financial-case-for-commercial-sponsorship.md | 2 +- docs/sponsors.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/business-and-financial-case-for-commercial-sponsorship.md b/docs/business-and-financial-case-for-commercial-sponsorship.md index aa7683f4..956bbea3 100644 --- a/docs/business-and-financial-case-for-commercial-sponsorship.md +++ b/docs/business-and-financial-case-for-commercial-sponsorship.md @@ -2,7 +2,7 @@ title: "Why CFOs should care about Open Source" description: "The business and financial case for commercially sponsoring the Embedded Template Library (ETL)." date: 2026-09-12 -weight: 3003 +weight: 2 --- If your engineering team is using the **Embedded Template Library (ETL)** in commercial products, your company is benefiting from a critical piece of software infrastructure. diff --git a/docs/sponsors.md b/docs/sponsors.md index 25d7fb00..77be5bbc 100644 --- a/docs/sponsors.md +++ b/docs/sponsors.md @@ -1,6 +1,6 @@ --- title: "Sponsors of the ETL" -weight: 3002 +weight: 3 --- A special thank you to all of our past and current sponsors. Your generosity directly funds the continuous development and maintenance of the ETL. From 912e83e789395688f75d4c4554e354113ce362ab Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Mon, 28 Sep 2026 09:57:31 +0100 Subject: [PATCH 3/8] Refactor the documentation css to group styles for light and dark themes --- hugo/assets/css/custom.css | 679 ++++++++++++++++++++----------------- 1 file changed, 373 insertions(+), 306 deletions(-) diff --git a/hugo/assets/css/custom.css b/hugo/assets/css/custom.css index ee5b7e09..bbddd9ab 100644 --- a/hugo/assets/css/custom.css +++ b/hugo/assets/css/custom.css @@ -1,222 +1,6 @@ -/* Definitions for light mode */ -html:not(.dark) .highlight .chroma .c1 -{ - color: forestgreen !important; -} - -html:not(.dark) .highlight .chroma .cp, -html:not(.dark) .highlight .chroma .cpf { - color: mediumslateblue !important; -} - -html:not(.dark) h1 { - color: white !important; - width: 100%; - background-color: coral !important; - border: width 0.15rem solid rgb(163, 81, 51) !important; - padding: 0.5rem 0.5rem !important; -} - -html:not(.dark) h2 { - color: royalblue !important; - border-bottom: 3px solid black !important; -} - -html:not(.dark) h3, -html:not(.dark) h4 -{ - color: darkgoldenrod !important; - border-bottom: 2px solid darkgrey !important; -} - -html:not(.dark) p { - color: black !important; -} - -html:not(.dark) dl, -html:not(.dark) dl dt code, -html:not(.dark) dl dd { - color: black !important; - background-color: #eeeeee !important; -} - -html:not(.dark) code, -html:not(.dark) pre, -html:not(.dark) pre code { - color: black !important; - background-color: #eeeeee !important; -} - -html:not(.dark) hr { - background-color: #eeeeee !important; -} - -html:not(.dark) .hx\:font-extrabold { - font-family: Roboto, sans-serif !important; - font-size: 1.6rem !important; - color: royalblue !important; -} - -/* inactive */ -html:not(.dark) .hx\:text-gray-500 { - color: black !important; -} - -/* active */ -html:not(.dark) .hextra-sidebar-active-item { - color: black !important; -} - -html:not(.dark) .content p.label-text { - color: darkgoldenrod !important; -} - -/* Regular item hover */ -html:not(.dark) .hextra-sidebar-item a:hover, -html:not(.dark) .hextra-sidebar-item a:hover span { - background-color: rgb(250, 195, 175) !important; - color: black !important; -} - -/* Active item default + hover - must come AFTER regular hover */ -html:not(.dark) .hextra-sidebar-item[data-active="true"] a, -html:not(.dark) .hextra-sidebar-item[data-active="true"] a span, -html:not(.dark) .hextra-sidebar-item[data-active="true"] a:hover, -html:not(.dark) .hextra-sidebar-item[data-active="true"] a:hover span { - background-color: coral !important; - color: white !important; -} - - -/* Definitions for dark mode */ -html.dark .highlight .chroma .c1 -{ - color: lightgreen !important; -} - -html.dark .highlight .chroma .cp, -html.dark.highlight .chroma .cpf { - color: lightsteelblue !important; -} - -html.dark body { - background-color: #1e1e1e !important; -} - -html.dark main { - background-color: #252525 !important; -} - -html.dark .hx\:dark\:shadow-\[0_-12px_16px_\#111\] { - box-shadow: 0 -12px 16px #1e1e1e !important; -} - -html.dark .hx\:dark\:bg-dark { - background-color: #1e1e1e !important; - border-color: grey !important; -} - -html.dark h1 -{ - color: white !important; - width: 100%; - background-color: rgb(177, 87, 54) !important; - padding: 0.5rem 0.5rem !important; -} - -html.dark h2 { - color: #7099c7 !important; - border-bottom: 2px solid #c0c0c0 !important; -} - -html.dark h3, -html.dark h4 { - color: lightgreen !important; - border-bottom: 2px solid #505050 !important; -} - -html.dark p { - color: #c0c0c0 !important; -} - -html.dark p strong { - color: #c4c3a6; -} - -html.dark dl, -html.dark dl dt code, -html.dark dl dd { - color: #c0c0c0 !important; - background-color: #444444 !important; -} - -html.dark code, -html.dark pre, -html.dark pre code { - color: #c0c0c0 !important; - background-color: #444444 !important; -} - -html.dark hr { - background-color: #505050 !important; -} - -html.dark .hx\:font-extrabold { - font-family: Roboto, sans-serif !important; - font-size: 1.6rem !important; - color: #7099c7 !important; -} - -/* inactive */ -html.dark .hx\:text-gray-500 { - color: #c0c0c0 !important; -} - -/* active */ -html.dark .hextra-sidebar-active-item { - color: #c0c0c0 !important; -} - -html.dark .hextra-code-block .highlight .chroma span.p { - color: #c0c0c0; -} - -html.dark .content p.label-text { - color: salmon !important; -} - -/* Regular item hover */ -html.dark .hextra-sidebar-item a:hover, -html.dark .hextra-sidebar-item a:hover span { - background-color: rgb(250, 195, 175) !important; - color: black !important; -} - -/* Active item default + hover - must come AFTER regular hover */ -html.dark .hextra-sidebar-item[data-active="true"] a, -html.dark .hextra-sidebar-item[data-active="true"] a span, -html.dark .hextra-sidebar-item[data-active="true"] a:hover, -html.dark .hextra-sidebar-item[data-active="true"] a:hover span { - background-color: rgb(177, 87, 54) !important; - color: #e0e0e0 !important; -} - -/* Common definitions */ - -@font-face { - font-family: Roboto; - src: url('/fonts/roboto-v51-latin-regular.woff2') format('woff2'); - font-weight:500; - font-style: normal; -} - -@font-face { - font-family: 'Roboto Mono'; - src: url('/fonts/roboto-mono-v31-latin-500.woff2') format('woff2'); - font-weight: nornal; - font-style: normal; -} - +/**********************/ +/* .highlight .chroma */ +/**********************/ .highlight .chroma .k, .highlight .chroma .kc, .highlight .chroma .kd, @@ -233,64 +17,21 @@ html.dark .hextra-sidebar-item[data-active="true"] a:hover span { font-style: normal !important; } -.hx\:mb-0 { - display: block; - width: 100%; +html.dark .highlight .chroma .cp, +html.dark.highlight .chroma .cpf { + color: lightgreen !important; + color: lightsteelblue !important; } -.hextra-code-block { - margin-top: 0.5rem !important; - -} - -/* .highlight .chroma .c1 -{ +html:not(.dark) .highlight .chroma .cp, +html:not(.dark) .highlight .chroma .cpf { color: forestgreen !important; -} - -.highlight .chroma .cp, -.highlight .chroma .cpf { color: mediumslateblue !important; -} */ - -html.dark .hextra-code-block .highlight .chroma .cs, -html.dark .hextra-code-block .highlight .chroma .cp, -html.dark .hextra-code-block .highlight .chroma .cpf { - font-weight: normal; -} - -.badges { - display: flex; - flex-wrap: wrap; - gap: 4px; - justify-content: flex-start; - margin-top: 1rem; -} - -.badges p { - display: contents; - margin: 0; -} - -.badges div { - width: 100%; - display: flex; - flex-wrap: wrap; - gap: 4px; -} - -.content ul li { - font-family: Roboto, sans-serif !important; - font-style: normal !important; - font-weight: normal !important; - font-size: 1.1rem !important; -} - -.err { - background-color: transparent !important; - color: inherit !important; } +/***********************/ +/* h1 */ +/***********************/ h1 { font-family: Roboto, sans-serif !important; font-style: i !important; @@ -301,6 +42,25 @@ h1 { border-radius: 0.5rem !important; } +html.dark h1 +{ + color: white !important; + width: 100%; + background-color: rgb(177, 87, 54) !important; + padding: 0.5rem 0.5rem !important; +} + +html:not(.dark) h1 { + color: white !important; + width: 100%; + background-color: coral !important; + border: width 0.15rem solid rgb(163, 81, 51) !important; + padding: 0.5rem 0.5rem !important; +} + +/***********************/ +/* h2 */ +/***********************/ h2 { font-family: Roboto, sans-serif !important; font-style: normal !important; @@ -310,6 +70,19 @@ h2 { margin-bottom: 0.5em !important; } +html.dark h2 { + color: #7099c7 !important; + border-bottom: 2px solid #c0c0c0 !important; +} + +html:not(.dark) h2 { + color: royalblue !important; + border-bottom: 3px solid black !important; +} + +/***********************/ +/* h3 */ +/***********************/ h3 { font-family: Roboto, sans-serif !important; font-style: normal !important; @@ -321,6 +94,20 @@ h3 { #display: inline-block; } +html.dark h3 { + color: lightgreen !important; + border-bottom: 2px solid #505050 !important; +} + +html:not(.dark) h3 +{ + color: darkgoldenrod !important; + border-bottom: 2px solid darkgrey !important; +} + +/***********************/ +/* h4 */ +/***********************/ h4 { font-family: Roboto, sans-serif !important; font-style: normal !important; @@ -331,6 +118,43 @@ h4 { display: inline-block; } +html.dark h4 { + color: lightgreen !important; + border-bottom: 2px solid #505050 !important; +} + +html:not(.dark) h4 +{ + color: darkgoldenrod !important; + border-bottom: 2px solid darkgrey !important; +} + +/***********************/ +/* p */ +/***********************/ +p { + font-family: Roboto, sans-serif !important; + font-style: normal !important; + font-weight: normal !important; + font-size: 1.1rem !important; + margin-top: 0.5em !important; +} + +html.dark p { + color: #c0c0c0 !important; +} + +html.dark p strong { + color: #c4c3a6; +} + +html:not(.dark) p { + color: black !important; +} + +/***********************/ +/* dl */ +/***********************/ dl { font-family: 'Roboto Mono', monospace !important; font-style: normal !important; @@ -352,27 +176,23 @@ dl dd { font-size: 1rem !important; } -ol { - font-family: 'Roboto Mono', monospace !important; - font-style: normal !important; - font-weight: normal !important; - font-size: 1rem !important; +html.dark dl, +html.dark dl dt code, +html.dark dl dd { + color: #c0c0c0 !important; + background-color: #444444 !important; } -ol li { - font-family: Roboto, sans-serif !important; - font-style: normal !important; - font-weight: normal !important; - font-size: 1rem !important; -} - -ol li code { - font-family: 'Roboto Mono', monospace !important; - font-style: normal !important; - font-weight: normal !important; - font-size: 1rem !important; +html:not(.dark) dl, +html:not(.dark) dl dt code, +html:not(.dark) dl dd { + color: black !important; + background-color: #eeeeee !important; } +/***********************/ +/* pre & code */ +/***********************/ code { font-family: 'Roboto Mono', monospace !important; font-weight: normal !important; @@ -381,15 +201,6 @@ code { border: none !important; } -pre code { - font-family: 'Roboto Mono', monospace !important; - font-style: normal !important; - font-weight: normal !important; - font-size: 0.9rem !important; - margin-left: 0 !important; - border: none !important; -} - pre { font-family: 'Roboto Mono', monospace !important; font-size: 0.9rem !important; @@ -400,6 +211,32 @@ pre { border: none !important; } +pre code { + font-family: 'Roboto Mono', monospace !important; + font-style: normal !important; + font-weight: normal !important; + font-size: 0.9rem !important; + margin-left: 0 !important; + border: none !important; +} + +html.dark code, +html.dark pre, +html.dark pre code { + color: #c0c0c0 !important; + background-color: #444444 !important; +} + +html:not(.dark) code, +html:not(.dark) pre, +html:not(.dark) pre code { + color: black !important; + background-color: #eeeeee !important; +} + +/***********************/ +/* hr */ +/***********************/ hr { height: 2px !important; border: none !important; @@ -407,23 +244,154 @@ hr { margin-bottom: 1em !important; } -p { +html.dark hr { + background-color: #505050 !important; +} + +html:not(.dark) hr { + background-color: #eeeeee !important; +} + +/***********************/ +/* body */ +/***********************/ +html.dark body { + background-color: #1e1e1e !important; +} + +/***********************/ +/* .hx\:font-extrabold */ +/***********************/ +html.dark .hx\:font-extrabold { font-family: Roboto, sans-serif !important; - font-style: normal !important; - font-weight: normal !important; - font-size: 1.1rem !important; - margin-top: 0.5em !important; + font-size: 1.6rem !important; + color: #7099c7 !important; } -tr td code{ - font-family: 'Roboto Mono', monospace !important; - font-size: 0.8rem !important; +html:not(.dark) .hx\:font-extrabold { + font-family: Roboto, sans-serif !important; + font-size: 1.6rem !important; + color: royalblue !important; } +/***********************/ +/* .hx\:text-gray-500 */ +/* inactive */ +/***********************/ +html.dark .hx\:text-gray-500 { + color: #c0c0c0 !important; +} + +html:not(.dark) .hx\:text-gray-500 { + color: black !important; +} + +/*******************************/ +/* .hextra-sidebar-active-item */ +/* active */ +/*******************************/ +html.dark .hextra-sidebar-active-item { + color: #c0c0c0 !important; +} + +html:not(.dark) .hextra-sidebar-active-item { + color: black !important; +} + +/*************************/ +/* .content p.label-text */ +/*************************/ +html.dark .content p.label-text { + color: salmon !important; +} + +html:not(.dark) .content p.label-text { + color: darkgoldenrod !important; +} + +/********************************/ +/* .hextra-sidebar-item a:hover */ +/********************************/ +html.dark .hextra-sidebar-item a:hover, +html.dark .hextra-sidebar-item a:hover span { + background-color: rgb(250, 195, 175) !important; + color: black !important; +} + +html:not(.dark) .hextra-sidebar-item a:hover, +html:not(.dark) .hextra-sidebar-item a:hover span { + background-color: rgb(250, 195, 175) !important; + color: black !important; +} + +/*********************************/ +/* .hextra-sidebar-item */ +/* Active item default + hover */ +/* Must come AFTER regular hover */ +/*********************************/ +html.dark .hextra-sidebar-item[data-active="true"] a, +html.dark .hextra-sidebar-item[data-active="true"] a span, +html.dark .hextra-sidebar-item[data-active="true"] a:hover, +html.dark .hextra-sidebar-item[data-active="true"] a:hover span { + background-color: rgb(177, 87, 54) !important; + color: #e0e0e0 !important; +} + +html:not(.dark) .hextra-sidebar-item[data-active="true"] a, +html:not(.dark) .hextra-sidebar-item[data-active="true"] a span, +html:not(.dark) .hextra-sidebar-item[data-active="true"] a:hover, +html:not(.dark) .hextra-sidebar-item[data-active="true"] a:hover span { + background-color: coral !important; + color: white !important; +} + +/***********************/ +/* main */ +/***********************/ +html.dark main { + background-color: #252525 !important; +} + +/***********************/ +/* .hx\:dark\:shadow */ +/***********************/ +html.dark .hx\:dark\:shadow-\[0_-12px_16px_\#111\] { + box-shadow: 0 -12px 16px #1e1e1e !important; +} + +/***********************/ +/* .hx\:dark\:bg-dark */ +/***********************/ +html.dark .hx\:dark\:bg-dark { + background-color: #1e1e1e !important; + border-color: grey !important; +} + +/***********************/ +/* hextra-code-block */ +/***********************/ +.hextra-code-block { + margin-top: 0.5rem !important; +} + +html.dark .hextra-code-block .highlight .chroma span.p { + color: #c0c0c0; +} + +html.dark .hextra-code-block .highlight .chroma .cs, +html.dark .hextra-code-block .highlight .chroma .cp, +html.dark .hextra-code-block .highlight .chroma .cpf { + font-weight: normal; +} + +/***********************/ +/* complexity */ +/***********************/ .complexity { padding: 3px 6px; - border-radius: 999px; + border-radius: 0.5rem !important; font-weight: 600; + font-size: 0.9rem !important; letter-spacing: 0.04em; border: 1px solid transparent; } @@ -460,6 +428,7 @@ html.dark .complexity { border-color: rgba(255,0,80,0.2); } } + html:not(.dark) .complexity { &.constant { color: #15803D; @@ -497,3 +466,101 @@ html:not(.dark) .complexity { border-color: rgba(239,68,68,0.22); } } + +/***********************/ +/* font-face */ +/***********************/ +@font-face { + font-family: Roboto; + src: url('/fonts/roboto-v51-latin-regular.woff2') format('woff2'); + font-weight:500; + font-style: normal; +} + +@font-face { + font-family: 'Roboto Mono'; + src: url('/fonts/roboto-mono-v31-latin-500.woff2') format('woff2'); + font-weight: nornal; + font-style: normal; +} + +/***********************/ +/* .hx\:mb */ +/***********************/ +.hx\:mb-0 { + display: block; + width: 100%; +} + +/***********************/ +/* .badges */ +/***********************/ +.badges { + display: flex; + flex-wrap: wrap; + gap: 4px; + justify-content: flex-start; + margin-top: 1rem; +} + +.badges p { + display: contents; + margin: 0; +} + +.badges div { + width: 100%; + display: flex; + flex-wrap: wrap; + gap: 4px; +} + +/***********************/ +/* .content */ +/***********************/ +.content ul li { + font-family: Roboto, sans-serif !important; + font-style: normal !important; + font-weight: normal !important; + font-size: 1.1rem !important; +} + +/***********************/ +/* .err */ +/***********************/ +.err { + background-color: transparent !important; + color: inherit !important; +} + +/***********************/ +/* ol */ +/***********************/ +ol { + font-family: 'Roboto Mono', monospace !important; + font-style: normal !important; + font-weight: normal !important; + font-size: 1rem !important; +} + +ol li { + font-family: Roboto, sans-serif !important; + font-style: normal !important; + font-weight: normal !important; + font-size: 1rem !important; +} + +ol li code { + font-family: 'Roboto Mono', monospace !important; + font-style: normal !important; + font-weight: normal !important; + font-size: 1rem !important; +} + +/***********************/ +/* tr */ +/***********************/ +tr td code{ + font-family: 'Roboto Mono', monospace !important; + font-size: 0.8rem !important; +} From 2bea749ef30205632846fed7fed5662e20631cf7 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Tue, 29 Sep 2026 12:34:42 +0100 Subject: [PATCH 4/8] Update Codacy badge in README.md Updated Codacy badge link to reflect new project status. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d66d2037..5b3a50cc 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ ![CI](https://github.com/ETLCPP/etl/actions/workflows/clang-c++26.yml/badge.svg?branch=master) ![CI](https://github.com/ETLCPP/etl/actions/workflows/clang-syntax-checks.yml/badge.svg?branch=master) -[![Codacy Badge](https://api.codacy.com/project/badge/Grade/3c14cd918ccf40008d0bcd7b083d5946)](https://www.codacy.com/manual/jwellbelove/etl?utm_source=github.com&utm_medium=referral&utm_content=ETLCPP/etl&utm_campaign=Badge_Grade) +[![Codacy Badge](https://app.codacy.com/project/badge/Grade/c0c29f7b84554166b577e8a98fc18d0b)](https://app.codacy.com/gh/ETLCPP/etl/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade) [![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/ETLCPP) From 3a3b5124bd89f3f50ae8658cdee6c4b6fa6396cd Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Tue, 29 Sep 2026 12:37:27 +0100 Subject: [PATCH 5/8] Fix Codacy badge display --- docs/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_index.md b/docs/_index.md index 472fb0ac..dc6fde75 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -40,7 +40,7 @@ type: hextra-home
coverage - Codacy +Codacy Badge
From ea54954c54bd0bb3ecb01515a54ed2a81bdca2a2 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Sun, 4 Oct 2026 10:16:44 +0100 Subject: [PATCH 6/8] refresh codacy integration status From 5fe4a6cbd01f2f6ffe0cff839bbad168a668329f Mon Sep 17 00:00:00 2001 From: Eden Frosst Date: Fri, 16 Oct 2026 06:55:25 -0400 Subject: [PATCH 7/8] Expose more Zephyr Kconfigs for error handling (#1622) * zephyr: make `ETL_DEBUG` default to on if Zephyr assertions are enabled this is the more appropriate default: ETL_DEBUG controls some container assertions, so it should follow the Zephyr assertions by default * zephyr: expose new error-checking configs * zephyr: add Kconfig choices for error handling --- zephyr/CMakeLists.txt | 12 +++++++- zephyr/Kconfig | 72 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 80 insertions(+), 4 deletions(-) diff --git a/zephyr/CMakeLists.txt b/zephyr/CMakeLists.txt index 60e5c2fb..4c360584 100644 --- a/zephyr/CMakeLists.txt +++ b/zephyr/CMakeLists.txt @@ -3,6 +3,16 @@ if(CONFIG_ETL) zephyr_link_libraries(etl::etl) zephyr_compile_definitions_ifdef(CONFIG_ETL_DEBUG ETL_DEBUG) - zephyr_compile_definitions_ifdef(CONFIG_ETL_CHECK_PUSH_POP ETL_CHECK_PUSH_POP) + zephyr_compile_definitions_ifdef(CONFIG_ETL_LOG_ERRORS ETL_LOG_ERRORS) + zephyr_compile_definitions_ifdef(CONFIG_ETL_USE_ASSERT_FUNCTION ETL_USE_ASSERT_FUNCTION) + zephyr_compile_definitions_ifdef(CONFIG_ETL_THROW_EXCEPTIONS ETL_THROW_EXCEPTIONS) + zephyr_compile_definitions_ifdef(CONFIG_ETL_NO_CHECKS ETL_NO_CHECKS) + + zephyr_compile_definitions_ifdef(CONFIG_ETL_VERBOSE_ERRORS ETL_VERBOSE_ERRORS) + zephyr_compile_definitions_ifdef(CONFIG_ETL_MINIMAL_ERRORS ETL_MINIMAL_ERRORS) + + zephyr_compile_definitions_ifdef(CONFIG_ETL_CHECK_PUSH_POP ETL_CHECK_PUSH_POP) + zephyr_compile_definitions_ifdef(CONFIG_ETL_CHECK_INDEX_OPERATOR ETL_CHECK_INDEX_OPERATOR) + zephyr_compile_definitions_ifdef(CONFIG_ETL_CHECK_EXTRA ETL_CHECK_EXTRA) endif() diff --git a/zephyr/Kconfig b/zephyr/Kconfig index ad8cd12d..b5ac8b47 100644 --- a/zephyr/Kconfig +++ b/zephyr/Kconfig @@ -8,12 +8,78 @@ if ETL config ETL_DEBUG bool "Build ETL with debugging checks" - default y if DEBUG + default y if ASSERT + +choice ETL_ERROR_MODE + prompt "ETL error handling mode" + help + What ETL does when one of its checks fails. + +config ETL_ASSERT_ERRORS + bool "Assert in ETL_DEBUG builds, otherwise ignore" + help + With ETL_DEBUG, a failed check calls assert(). Without it, nothing + is reported, but checks that guard an operation still skip it. + With ETL_LOG_ERRORS, a failed check calls the error handler instead, + with or without ETL_DEBUG. + +config ETL_USE_ASSERT_FUNCTION + bool "Call a user assert function" + help + A failed check calls the function registered with + etl::set_assert_function(), and checks that guard an operation + still skip it. Until one is registered, it calls assert(false). + +config ETL_THROW_EXCEPTIONS + bool "Throw an exception" + depends on CPP_EXCEPTIONS + help + A failed check throws an etl::exception. + +config ETL_NO_CHECKS + bool "No checks" + help + Check conditions are not evaluated. + +endchoice # ETL_ERROR_MODE + +config ETL_LOG_ERRORS + bool "Call the ETL error handler" + depends on !ETL_USE_ASSERT_FUNCTION && !ETL_NO_CHECKS + help + A failed check calls the callback registered with + etl::error_handler::set_callback(). With ETL_THROW_EXCEPTIONS it + then throws; otherwise, checks that guard an operation still skip + it. With no callback registered, errors are discarded. + +choice ETL_ERROR_DETAIL + prompt "ETL error detail level" + help + What information the etl::exception for a failed check carries, + whether it is thrown or passed to the error handler or assert + function. Unused when a failed check calls plain assert(). + +config ETL_TERSE_ERRORS + bool "Short error code only" + +config ETL_VERBOSE_ERRORS + bool "Message, file and line" + +config ETL_MINIMAL_ERRORS + bool "Nothing" + +endchoice # ETL_ERROR_DETAIL config ETL_CHECK_PUSH_POP bool "Enable push/pop checks in ETL" + depends on !ETL_NO_CHECKS -config ETL_LOG_ERRORS - bool "Call ETL error handler instead of assert" +config ETL_CHECK_INDEX_OPERATOR + bool "Enable bounds checks on ETL operator[]" + depends on !ETL_NO_CHECKS + +config ETL_CHECK_EXTRA + bool "Enable extra bounds and empty checks in ETL containers" + depends on !ETL_NO_CHECKS endif # ETL From 606eea614f847edb8689d82e93dbfc4d5f65748c Mon Sep 17 00:00:00 2001 From: AlvyneZ Date: Tue, 20 Oct 2026 18:20:01 +0300 Subject: [PATCH 8/8] Fix indirect_vector range overloads matching integral arguments Calls such as indirect_vector::insert(position, 2, 7), assign(5, 7) and the constructor indirect_vector(5, 7) chose the iterator range templates, because two ints deduce TIterator = int exactly. They then failed to compile inside the template, for example at etl::distance(int, int). Constrain the range versions of assign, insert and the indirect_vector and indirect_vector_ext constructors with etl::enable_if, as etl::vector does, so that integral arguments select the (count, value) overloads. Add tests for each case. --- include/etl/indirect_vector.h | 9 ++--- test/test_indirect_vector.cpp | 36 +++++++++++++++++++ test/test_indirect_vector_external_buffer.cpp | 16 +++++++++ 3 files changed, 57 insertions(+), 4 deletions(-) diff --git a/include/etl/indirect_vector.h b/include/etl/indirect_vector.h index 2fcac9ba..217e6380 100644 --- a/include/etl/indirect_vector.h +++ b/include/etl/indirect_vector.h @@ -724,7 +724,7 @@ namespace etl ///\param last The iterator to the last element + 1. //********************************************************************* template - void assign(TIterator first, TIterator last) + typename etl::enable_if::value, void>::type assign(TIterator first, TIterator last) { ETL_STATIC_ASSERT((etl::is_same::type, typename etl::remove_cv< typename etl::iterator_traits< TIterator>::value_type>::type>::value), @@ -1071,7 +1071,7 @@ namespace etl ///\param last The last + 1 element to add. //********************************************************************* template - iterator insert(const_iterator position, TIterator first, TIterator last) + typename etl::enable_if::value, iterator>::type insert(const_iterator position, TIterator first, TIterator last) { size_t count = size_t(etl::distance(first, last)); @@ -1462,7 +1462,7 @@ namespace etl ///\param last The iterator to the last element + 1. //************************************************************************* template - indirect_vector(TIterator first, TIterator last) + indirect_vector(TIterator first, TIterator last, typename etl::enable_if::value, int>::type = 0) : etl::iindirect_vector(lookup_vector, storage_pool) { this->assign(first, last); @@ -1613,7 +1613,8 @@ namespace etl ///\param last The iterator to the last element + 1. //************************************************************************* template - indirect_vector_ext(TIterator first, TIterator last, etl::ivector& lookup_, etl::ipool& pool_) + indirect_vector_ext(TIterator first, TIterator last, etl::ivector& lookup_, etl::ipool& pool_, + typename etl::enable_if::value, int>::type = 0) : etl::iindirect_vector(lookup_, pool_) { ETL_ASSERT(lookup_.capacity() <= pool_.capacity(), ETL_ERROR(indirect_vector_buffer_missmatch)); diff --git a/test/test_indirect_vector.cpp b/test/test_indirect_vector.cpp index f9973441..75dc1293 100644 --- a/test/test_indirect_vector.cpp +++ b/test/test_indirect_vector.cpp @@ -1201,6 +1201,42 @@ namespace CHECK_THROW(data.insert(data.begin() + static_cast(offset), INSERT_SIZE, INITIAL_VALUE), etl::vector_full); } + //************************************************************************* + TEST(test_constructor_two_parameter_same_type_not_iterator) + { + std::vector compare_data(5, 7); + etl::indirect_vector data(5, 7); + + CHECK_EQUAL(compare_data.size(), data.size()); + CHECK(std::equal(data.begin(), data.end(), compare_data.begin())); + } + + //************************************************************************* + TEST(test_assign_two_parameter_same_type_not_iterator) + { + std::vector compare_data; + etl::indirect_vector data; + + compare_data.assign(5, 7); + data.assign(5, 7); + + CHECK_EQUAL(compare_data.size(), data.size()); + CHECK(std::equal(data.begin(), data.end(), compare_data.begin())); + } + + //************************************************************************* + TEST(test_insert_three_parameter_same_type_not_iterator) + { + std::vector compare_data(3UL, 1); + etl::indirect_vector data(3UL, 1); + + compare_data.insert(compare_data.begin(), 2, 7); + data.insert(data.begin(), 2, 7); + + CHECK_EQUAL(compare_data.size(), data.size()); + CHECK(std::equal(data.begin(), data.end(), compare_data.begin())); + } + //************************************************************************* TEST_FIXTURE(SetupFixture, test_insert_position_range) { diff --git a/test/test_indirect_vector_external_buffer.cpp b/test/test_indirect_vector_external_buffer.cpp index a699834a..0223f7ee 100644 --- a/test/test_indirect_vector_external_buffer.cpp +++ b/test/test_indirect_vector_external_buffer.cpp @@ -335,6 +335,22 @@ namespace CHECK_EQUAL(4U, *data2[3]); } + //************************************************************************* + TEST(test_constructor_two_parameter_same_type_not_iterator) + { + LookupInt lookup; + PoolInt pool; + + etl::indirect_vector_ext data(5, 7, lookup, pool); + + CHECK_EQUAL(5U, data.size()); + CHECK_EQUAL(7, data[0]); + CHECK_EQUAL(7, data[1]); + CHECK_EQUAL(7, data[2]); + CHECK_EQUAL(7, data[3]); + CHECK_EQUAL(7, data[4]); + } + //************************************************************************* TEST_FIXTURE(SetupFixture, test_assignment) {