### Message Timer Example

Source: https://github.com/etlcpp/etl/blob/master/docs/timers/message-timer.md

Demonstrates the setup and usage of the etl::message_timer. It includes defining message types, routers, a message bus, and then registering and starting timers. The example also shows how to handle timer ticks within an interrupt context.

```cpp
//***************************************************************************
// The set of messages.
//***************************************************************************
enum
{
  MESSAGE1,
  MESSAGE2,
  MESSAGE3,
};

enum
{
  ROUTER1 = 1,
};

struct Message1 : public etl::message<MESSAGE1>
{
};

struct Message2 : public etl::message<MESSAGE2>
{
};

struct Message3 : public etl::message<MESSAGE3>
{
};

Message1 message1;
Message2 message2;
Message3 message3;

//***************************************************************************
// Router that handles messages 1, 2, 3
//***************************************************************************
class Router1 : public etl::message_router<Router1, Message1, Message2, Message3>
{
public:

  Router1()
    : message_router(ROUTER1)
  {
 }

  void on_receive(const Message1& msg)
  {
    printf("Message 1 received\n");
  }

  void on_receive(const Message2& msg)
  {
    printf("Message 2 received\n");
  }

  void on_receive(const Message3& msg)
  {
    printf("Message 3 received\n");
  }

  void on_receive_unknown(const etl::imessage& msg)
  {
  }
};
  
//***************************************************************************
// Bus that handles messages.
//***************************************************************************
class Bus1 : public etl::message_bus<1>
{
};

//***************************************************************************
// Router, bus and timer controller.
//***************************************************************************
Router1 router1;
Bus1    bus1;

etl::message_timer<3> timer_controller;

//***************************************************************************
// The main loop.
//***************************************************************************
int main()
{
  bus1.subscribe(router1);

  etl::timer::id::type id1 = timer_controller.register_timer(message1, 
                                                             router1, 
                                                             1000,
                                                             etl::timer::mode::SINGLE_SHOT);

  etl::timer::id::type id2 = timer_controller.register_timer(message2, 
                                                             bus1, 
                                                             100, 
                                                             etl::timer::mode::REPEATING);

  etl::timer::id::type id3 = timer_controller.register_timer(message3, 
                                                             router1, 
                                                             10, 
                                                             etl::timer::mode::REPEATING);

  timer_controller.start(id1);
  timer_controller.start(id2);
  timer_controller.start(id3);

  timer_controller.enable(true);

  // Start timer interrupts here.

  while (true)
  {
    // Loop forever.
  }

  return 0;
}

//***************************************************************************
// The interrupt timer callback.
//***************************************************************************
void timer_interrupt()
{
  const uint32_t TICK = 1;
  static uint32_t nticks = TICK;

  if (timer_controller.tick(nticks))
  {
    nticks = TICK;
  }
  else
  {
    nticks += TICK;
  }
}

```

--------------------------------

### Parameter Pack Usage Example

Source: https://github.com/etlcpp/etl/blob/master/docs/utilities/parameter-pack.md

Demonstrates how to use `parameter_pack` to get the size, find the index of types, and retrieve types by index. Includes examples of static assertions for invalid types or indices.

```cpp
using Pack = etl::parameter_pack<char, short, int>;

constexpr size_t size = Pack::size; // size == 3

size_t indexChar  = Pack::index_of_type_v<char>;   // indexChar  == 0
size_t indexShort = Pack::index_of_type_v<short>;  // indexShort == 1
size_t indexInt   = Pack::index_of_type_v<int>;    // indexInt   == 2
size_t indexLong  = Pack::index_of_type_v<long>;   // Static assert
                                                   // "T is not in parameter pack"

using type0 = typename Pack::type_from_index_t<0>; // type0 = char
using type1 = typename Pack::type_from_index_t<1>; // type1 = short
using type2 = typename Pack::type_from_index_t<2>; // type2 = int
using type3 = typename Pack::type_from_index_t<3>; // Static assert 
                                                   // "Index out of bounds of parameter pack"
```

--------------------------------

### Shared Message Example Setup

Source: https://github.com/etlcpp/etl/blob/master/docs/tutorials/shared-message_tutorial.md

Includes necessary headers for shared messages, message routing, and memory management. Defines message IDs and custom message structures.

```cpp
//*****************************************************************************
// Shared message example
//*****************************************************************************

#include "etl/shared_message.h"
#include "etl/message.h"
#include "etl/reference_counted_message_pool.h"
#include "etl/message_router.h"
#include "etl/message_bus.h"
#include "etl/fixed_sized_memory_block_allocator.h"
#include "etl/queue.h"

#include <iostream>
#include <atomic>
#include <string>

constexpr etl::message_router_id_t RouterId1 = 1U;
constexpr etl::message_router_id_t RouterId2 = 2U;

//*****************************************************************************
// Message1
//*****************************************************************************
struct Message1 : public etl::message<1>
{
  Message1(std::string s_)
    : s(s_)
  {
  }

  std::string s;
};

//*****************************************************************************
// Message2
//*****************************************************************************
struct Message2 : public etl::message<2>
{
  Message2(std::string s_)
    : s(s_)
  {
  }

  std::string s;
  char data[100];
};

//*****************************************************************************
// Message3
//*****************************************************************************
struct Message3 : public etl::message<3>
{
  Message3(std::string s_)
    : s(s_)
  {
  }

  std::string s;
};

```

--------------------------------

### Install treefmt with Official Script

Source: https://github.com/etlcpp/etl/blob/master/docs/source/source-formatting.md

Install the treefmt Go binary using the official curl-based installation script. This is a quick way to get treefmt on your system.

```bash
curl -fsSL https://raw.githubusercontent.com/numtide/treefmt/main/install.sh | bash
```

--------------------------------

### Hugo Server Output Example

Source: https://github.com/etlcpp/etl/blob/master/DOCUMENTATION.md

An example of the output seen in the terminal when the Hugo development server starts, indicating the URL where the documentation is accessible.

```text
Web Server is available at http://localhost:1313/
```

--------------------------------

### Callback Timer Example

Source: https://github.com/etlcpp/etl/blob/master/docs/timers/callback-timer.md

Demonstrates registering and starting timers with different callback types (member function, free function, function pointer) and modes (single shot, repeating). The timer controller is enabled and started, with a placeholder for interrupt handling.

```cpp
//***************************************************************************
// Class callback via etl::function
//***************************************************************************
class Test
{
public:

  Test()
    : ticks(0)
  {
  }

  void callback()
  {
    ++ticks;
  }

  int ticks;
};
  
Test test;
etl::function_mv<Test, &Test::callback> member_callback(test);

//***************************************************************************
// Free function callback via etl::function
//***************************************************************************
int free_ticks1 = 0;

void free_callback1()
{
  ++free_ticks1;
}

etl::function_fv<free_callback1> free_function_callback;

//***************************************************************************
// Free function callback via function pointer
//***************************************************************************
int free_ticks2 = 0;

void free_callback2()
{
  ++free_ticks2;
}

//***************************************************************************
// Timer controller.
//***************************************************************************
etl::callback_timer<3> timer_controller;

//***************************************************************************
// The main loop.
//***************************************************************************
int main()
{
  etl::timer::id::type id1 = timer_controller.register_timer(member_callback,
                                                             1000,
                                                             etl::timer::mode::SINGLE_SHOT);

  etl::timer::id::type id2 = timer_controller.register_timer(free_function_callback,
                                                             100,
                                                             etl::timer::mode::REPEATING);

  etl::timer::id::type id3 = timer_controller.register_timer(free_callback2,
                                                             10,
                                                             etl::timer::mode::REPEATING);

  timer_controller.start(id1);
  timer_controller.start(id2);
  timer_controller.start(id3);

  timer_controller.enable(true);

  // Start timer interrupts here.

  while (true)
  {
    // Loop forever.
  }

  return 0;
}

//***************************************************************************
// The interrupt timer callback.
//***************************************************************************
void timer_interrupt()
{
  const uint32_t TICK = 1;
  static uint32_t nticks = TICK;

  if (timer_controller.tick(nticks))
  {
    nticks = TICK;
  }
  else
  {
    nticks += TICK;
  }
}

```

--------------------------------

### Example Usage of callback_timer_deferred_locked

Source: https://github.com/etlcpp/etl/blob/master/docs/timers/callback-timer-deferred-locked.md

Demonstrates the setup and usage of etl::callback_timer_deferred_locked with member function and free function callbacks. It shows timer registration, starting, enabling, and the interrupt handling mechanism.

```cpp
//***************************************************************************
// Class callback via etl::function
//***************************************************************************
class Test
{
public:

  Test()
    : ticks(0)
  {
  }

  void callback()
  {
    ++ticks;
  }

  int ticks;
};
  
using callback_type = etl::icallback_timer_locked::callback_type;

callback_type member_callback = callback_type::create<Test, test, &Test::callback>();

//***************************************************************************
// Free function callback via etl::function
//***************************************************************************
int free_ticks1 = 0;

void free_callback1()
{
  ++free_ticks1;
}

callback_type free_function_callback = callback_type::create<free_callback1>();

//***************************************************************************
// Timer controller.
//***************************************************************************
etl::callback_timer_deferred_locked<2, 4> timer_controller;

//***************************************************************************
// The main loop.
//***************************************************************************
int main()
{
  etl::timer::id::type id1 = timer_controller.register_timer(member_callback,
                                                             1000,
                                                             etl::timer::mode::SINGLE_SHOT);

  etl::timer::id::type id2 = timer_controller.register_timer(free_function_callback,
                                                             100,
                                                             etl::timer::mode::REPEATING);

  timer_controller.start(id1);
  timer_controller.start(id2);

  timer_controller.enable(true);

  // Start timer interrupts here.

  while (true)
  {
    // Loop forever.
  }

  return 0;
}

//***************************************************************************
// The interrupt timer callback.
//***************************************************************************
void timer_interrupt()
{
  const uint32_t TICK = 1;
  static uint32_t nticks = TICK;

  if (timer_controller.tick(nticks))
  {
    nticks = TICK;
  }
  else
  {
    nticks += TICK;
  }
}
```

--------------------------------

### Example: Build and Run armhf Test Suite

Source: https://github.com/etlcpp/etl/blob/master/docs/source/testing.md

This example demonstrates how to build and run the test suite specifically for the armhf architecture.

```bash
# Build & run the armhf test suite
.devcontainer/run-tests.sh armhf
```

--------------------------------

### Multi-Range Iteration Example

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/Views/multi-range.md

Demonstrates setting up and iterating through nested multi-ranges with different data types and comparison/step types. Shows how to access values and iterate using start(), completed(), and next().

```cpp
using Iterator = std::forward_list<std::string>::const_iterator;

// Less Than compare type
using LessThanCompare = etl::multi_range<const short*>::less_than_compare;

// Decrementing step type
using DecrementPtr = etl::multi_range<const short*>::reverse_step;

using Outer  = etl::multi_range<int>;          // Incrementing int
using Middle = etl::multi_range<const short*>; // Decrementing const short*
using Inner  = etl::multi_range<Iterator>;     // Incrementing const_iterator

const short data[4] = { 0, 1, 2, 3 };

std::forward_list<std::string> strings =
{
  "zero", "one", "two", "three"
};

LessThanCompare lessThan;
DecrementPtr    decrementPtr;

// Setup the loops.
Outer  outer(0, 4, lessThan);
Middle middle(data + 3, data - 1, decrementPtr);
Inner  inner(strings.begin(), strings.end());

outer.append(middle).append(inner);

size_t n_outer_loops  = outer.number_of_loops();  // == 3
size_t n_middle_loops = middle.number_of_loops(); // == 2
size_t n_inner_loops  = inner.number_of_loops();  // == 1

size_t n_outer_iterations  = outer.number_of_iterations();  // == 64
size_t n_middle_iterations = middle.number_of_iterations(); // == 16
size_t n_inner_iterations  = inner.number_of_iterations();  // == 4

// Create const references to the loop values.
const int&      value_outer  = outer.value();
const short*&   value_middle = middle.value();
const Iterator& value_inner  = inner.value();

// Iterate through the nested loops.
int i = 0;

for (outer.start(); !outer.completed(); outer.next())
{
  std::cout << "Iteration " << i++ << " : "
            << "Outer  = " << value_outer << " : "
            << "Middle = " << *value_middle << " : "
            << "Inner  = " << *value_inner
            << "\n"; 
}

// Just iterate through the two nested loops.
i = 0;

for (middle.start(); !middle.completed(); middle.next())
{
  std::cout << "Iteration " << i++ << " : "
            << "Middle = " << *value_middle << " : "
            << "Inner  = " << *value_inner
            << "\n"; 
}

```

--------------------------------

### Forward List Initialization Example

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/lists/forward-list.md

An example of initializing an etl::forward_list using the C++17 template deduction guide. The list is created with a specified length and populated with initial data.

```cpp
etl::forward_list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
```

--------------------------------

### Install ETL Library using CMake

Source: https://github.com/etlcpp/etl/blob/master/README.md

Steps to clone, checkout a specific version, build, and install the ETL library. Super user rights may be needed for installation on Linux.

```sh
git clone https://github.com/ETLCPP/etl.git
cd etl
git checkout <targetVersion>
cmake -B build .
cmake --install build/
```

--------------------------------

### Initializing Reference Flat Map with Deduction Guide

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/maps/reference-flat-map.md

An example of initializing an etl::reference_flat_map using C++17 template deduction guides. The size is inferred from the number of pairs provided.

```cpp
etl::reference_flat_map data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} };
```

--------------------------------

### Install guardonce Script

Source: https://github.com/etlcpp/etl/blob/master/Converting header guards.txt

Install the necessary Python package for header guard conversion.

```bash
python3 -m pip install guardonce
```

--------------------------------

### start

Source: https://github.com/etlcpp/etl/blob/master/docs/state machines/state-chart.md

Starts the state chart. Optionally calls the on_entry method of the initial state if provided.

```APIDOC
## void start(bool on_entry_initial = true)

### Description
Starts the state chart. If `on_entry_initial` is `true` and the initial state has an `on_entry` method, then this will be called. The function does nothing after the first call.

### Method
`void`

### Parameters
* **on_entry_initial** (bool) - Optional - If `true`, calls the `on_entry` method of the initial state if it exists.
```

--------------------------------

### Check Go Installation

Source: https://github.com/etlcpp/etl/blob/master/docs/getting-started/view-the-docs-locally/install-hugo.md

Verify that Go is installed correctly on your system. This is a prerequisite for Hugo Modules.

```bash
go version
```

--------------------------------

### start

Source: https://github.com/etlcpp/etl/blob/master/docs/timers/callback-timer-atomic.md

Starts a registered timer.

```APIDOC
## start

### Description
Starts the timer with the specified id.
If the timer is already running then the timer Is restarted from the current tick count.
If immediate is `true` then the timer is triggered on the next call to `tick()`. Note: Single shot timers will only trigger once.
If the id does not correspond to a registered timer then returns `false`.

### Parameters
- **id** (etl::timer::id::type) - The ID of the timer to start.
- **immediate** (bool) - Optional. If `true`, the timer is triggered on the next call to `tick()`.

### Return
`true` if the timer was started successfully, `false` otherwise.
```

--------------------------------

### start

Source: https://github.com/etlcpp/etl/blob/master/docs/state machines/finite-state-machine.md

Starts the FSM. Optionally calls the on_enter_state method for the initial state. This method can only be called once.

```APIDOC
## start(bool call_on_enter_state = true)

### Description
Starts the FSM. If `call_on_enter_state` is `true` then on_enter_state is called for the initial state. Default is `true`. Can only be called once. Subsequent calls will do nothing.

### Method
void
```

--------------------------------

### Delegate Observable Construction Example

Source: https://github.com/etlcpp/etl/blob/master/docs/callbacks/delegate_observable.md

An example demonstrating the construction of an etl::delegate_observable with initial delegates. This shows how to set up the observable with specific delegate instances.

```cpp
etl::delegate<void(int)> delegate1;
etl::delegate<void(int)> delegate2;

etl::delegate_observable observable(int{}, delegate1, delegate2);
```

--------------------------------

### C++ Buffer Descriptors Example

Source: https://github.com/etlcpp/etl/blob/master/docs/IO/buffer_descriptors.md

Demonstrates the setup and usage of etl::buffer_descriptors for DMA operations. Assumes a DMA driver class and a callback function for processing data. Buffers are allocated, linked to DMA, and released upon completion.

```cpp
constexpr size_t BUFFER_SIZE = 256U;
constexpr size_t N_BUFFERS   = 8U;

// Define the buffer descriptors type.
using BD = etl::buffer_descriptors<char, BUFFER_SIZE, N_BUFFERS, std::atomic_char>;

// The buffers to use with it.
char buffers[N_BUFFERS][BUFFER_SIZE];

// The function to call when a buffer is ready.
void Callback(BD::notification notification)
{
  // Process the buffer in the descriptor here.
  ProcessData(notification.get_descriptor().data(), notification.get_count());

  // Finished with the descriptor now, so release it back.
  notification.get_descriptor().release();
}

// Create the buffer_descriptors.
BD bd(&buffers[0][0], BD::callback_type::create<Callback>());

// The current dma descriptor.
BD::descriptor dma_descriptor;

// An object that controls the DMA.
DMA dma;

// Call to start the DMA.
void DMAStart()
{
  // Get a new descriptor.
  dma_descriptor = bd.allocate();

  if (dma_descriptor.is_valid())
  {
    // Link the buffer to the DMA channel.
    dma.Start(dma_descriptor.data());
  }
  else
  {
    // No valid descriptors available.
    LogError("No Descriptor Available");
  }
}

// Called when the DMA has completed (usually an interrupt).
void DMAComplete()
{
  // DMA is complete. Notify the callback.
  bd.notify(BD::notification(dma_descriptor, dma.GetTransferredSize()));
}
```

--------------------------------

### Visitor Example (Arguments by Reference)

Source: https://github.com/etlcpp/etl/blob/master/docs/patterns/visitor.md

Demonstrates the Visitor pattern where arguments to the `visit` methods are passed by reference. This example uses C++03 style visitor type specification.

```cpp
class Square;
class Circle;
class Triangle;

using ShapeVisitor = etl::visitor<Square, Circle, Triangle>;

class Shape : public etl::visitable<ShapeVisitor>
{
  // Shape based objects are visitable by a ShapeVisitor
};

class Square : public Shape
{
};

class Circle : public Shape
{
};

class Triangle : public Shape
{
};

class Visitor : public ShapeVisitor
{
public:

  void visit(Square& s)
  {
    // Square passed by reference
  }

  void visit(Circle& c)
  {
    // Square passed by reference
  }

  void visit(Triangle& t)
  {
    // Square passed by reference
  }
};

Visitor visitor;

Square   square;
Circle   circle;
Triangle triangle;

square.accept(visitor);   // visitor's visit(Square) is called.
circle.accept(visitor);   // visitor's visit(Circle&) is called.
triangle.accept(visitor); // visitor's visit(const Triangle&) is called.
```

--------------------------------

### Example Usage of make_set

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/sets/multiset.md

An example demonstrating how to use the make_set function to create an etl::multiset of integers.

```cpp
auto data = etl::make_set<int>(0, 1, 2, 3, 4, 5, 6, 7);
```

--------------------------------

### C++ divide_round_to_floor examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_to_floor with various positive and negative inputs.

```cpp
.151 / 100 ==  1
.150 / 100 ==  1
.149 / 100 ==  1
..51 / 100 ==  0
..50 / 100 ==  0
..49 / 100 ==  0
.-49 / 100 == -1
.-50 / 100 == -1
.-51 / 100 == -1
-149 / 100 == -2
-150 / 100 == -2
-151 / 100 == -2
```

--------------------------------

### Run cross-compiled tests with custom --run_under

Source: https://github.com/etlcpp/etl/blob/master/docs/source/bazel.md

Example of using the `--run_under` flag directly to execute cross-compiled test binaries under a specific QEMU emulator. This is useful for custom cross-compilation setups.

```sh
bazel test //test:etl_tests --run_under=/usr/bin/qemu-arm-static
```

--------------------------------

### C++ divide_round_to_ceiling examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_to_ceiling with various positive and negative inputs.

```cpp
.151 / 100 ==  2
.150 / 100 ==  2
.149 / 100 ==  2
.51 / 100 ==  1
..50 / 100 ==  1
..49 / 100 ==  1
.-49 / 100 ==  0
.-50 / 100 ==  0
.-51 / 100 ==  0
-149 / 100 == -1
-150 / 100 == -1
-151 / 100 == -1
```

--------------------------------

### C++ divide_round_half_up examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_half_up with various positive and negative inputs.

```cpp
.151 / 100 ==  3
.150 / 100 ==  3
.149 / 100 ==  1
..51 / 100 ==  1
..50 / 100 ==  1
..49 / 100 ==  0
.-49 / 100 ==  0
.-50 / 100 == -1
.-51 / 100 == -1
-149 / 100 == -1
-150 / 100 == -3
-151 / 100 == -3
```

--------------------------------

### C++ divide_round_to_infinity examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_to_infinity with various positive and negative inputs.

```cpp
.151 / 100 ==  2
.150 / 100 ==  2
.149 / 100 ==  2
..51 / 100 ==  1
..50 / 100 ==  1
..49 / 100 ==  1
.-49 / 100 == -1
.-50 / 100 == -1
.-51 / 100 == -1
-149 / 100 == -2
-150 / 100 == -2
-151 / 100 == -2
```

--------------------------------

### Main Function and Example Execution

Source: https://github.com/etlcpp/etl/blob/master/docs/tutorials/visitor-tutorial.md

Sets up the main execution flow, creating shapes, adding them to a list, and applying the draw and serialise visitors.

```cpp
//*****************************************************************
// Main
//*****************************************************************
int main()
{
  // Create some shapes.
  Square   square;
  Circle   circle;
  Triangle triangle;

  // Add them to the vector
  shape_list.push_back(&square);
  shape_list.push_back(&circle);
  shape_list.push_back(&triangle);

  // Apply the visitors.
  Apply(draw_visitor);
  Apply(serialise_visitor);

  return 0;
}

```

--------------------------------

### Tuple Initialization Example

Source: https://github.com/etlcpp/etl/blob/master/docs/types/tuple.md

Demonstrates direct initialization of an etl::tuple with heterogeneous types.

```cpp
etl::tuple tp(1, 2.2, 3, std::string("4"));

```

```cpp
etl::tuple<int, double, int, std::string> t(1, 2.2, 3, std::string("4"));

```

--------------------------------

### Example Usage of message_timer_locked

Source: https://github.com/etlcpp/etl/blob/master/docs/timers/message-timer-locked.md

Demonstrates the setup and usage of etl::message_timer_locked to register, start, and enable timers for message delivery. This includes defining message types, routers, buses, and the main loop for timer processing.

```cpp
//***************************************************************************
// The set of messages.
//***************************************************************************
enum
{
  MESSAGE1,
  MESSAGE2,
  MESSAGE3,
};

enum
{
  ROUTER1 = 1,
};

struct Message1 : public etl::message<MESSAGE1>
{
};

struct Message2 : public etl::message<MESSAGE2>
{
};

struct Message3 : public etl::message<MESSAGE3>
{
};

Message1 message1;
Message2 message2;
Message3 message3;

//***************************************************************************
// Router that handles messages 1, 2, 3
//***************************************************************************
class Router1 : public etl::message_router<Router1, Message1, Message2, Message3>
{
public:

  Router1()
    : message_router(ROUTER1)
  {
 }

  void on_receive(const Message1& msg)
  {
    printf("Message 1 received\n");
  }

  void on_receive(const Message2& msg)
  {
    printf("Message 2 received\n");
  }

  void on_receive(const Message3& msg)
  {
    printf("Message 3 received\n");
  }

  void on_receive_unknown(const etl::imessage& msg)
  {
  }
};
  
//***************************************************************************
// Bus that handles messages.
//***************************************************************************
class Bus1 : public etl::message_bus<1>
{
};

//***************************************************************************
// Router, bus and timer controller.
//***************************************************************************
Router1 router1;
Bus1    bus1;

etl::message_timer_locked<3> timer_controller;

//***************************************************************************
// The main loop.
//***************************************************************************
int main()
{
  bus1.subscribe(router1);

  etl::timer::id::type id1 = timer_controller.register_timer(message1, 
                                                             router1, 
                                                             1000,
                                                             etl::timer::mode::SINGLE_SHOT);

  etl::timer::id::type id2 = timer_controller.register_timer(message2, 
                                                             bus1, 
                                                             100, 
                                                             etl::timer::mode::REPEATING);

  etl::timer::id::type id3 = timer_controller.register_timer(message3, 
                                                             router1, 
                                                             10, 
                                                             etl::timer::mode::REPEATING);

  timer_controller.start(id1);
  timer_controller.start(id2);
  timer_controller.start(id3);

  timer_controller.enable(true);

  // Start timer interrupts here.

  while (true)
  {
    // Loop forever.
  }

  return 0;
}

//***************************************************************************
// The interrupt timer callback.
//***************************************************************************
void timer_interrupt()
{
  const uint32_t TICK = 1;
  static uint32_t nticks = TICK;

  if (timer_controller.tick(nticks))
  {
    nticks = TICK;
  }
  else
  {
    nticks += TICK;
  }
}

```

--------------------------------

### Minimal CMake Build Example

Source: https://github.com/etlcpp/etl/blob/master/docs/source/testing.md

Builds the test suite with C++20 standard and then runs the tests. Ensure you are in the 'test' directory and have a 'build' subdirectory.

```bash
cd test
mkdir build && cd build
cmake -DBUILD_TESTS=ON -DNO_STL=OFF -DETL_CXX_STANDARD=20 ..
cmake --build . -j$(nproc)
ctest -V
```

--------------------------------

### Example Usage of Multimax Algorithms (C++)

Source: https://github.com/etlcpp/etl/blob/master/docs/utilities/algorithms.md

Demonstrates how to use multimax, multimax_compare, multimax_iter, and multimax_iter_compare with different comparison strategies.

```cpp
int maximum;

maximum = etl::multimax(1, 2, 3, 4, 5, 6, 7, 8));
maximum = etl::multimax_compare(std::less<int>(), 1, 2, 3, 4, 5, 6, 7, 8));
maximum = etl::multimax_compare(std::greater<int>(), 1, 2, 3, 4, 5, 6, 7, 8));

int i[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };

int* p_maximum;

p_maximum = etl::multimax_iter(&i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7]));
p_maximum = etl::multimax_iter_compare(std::less<int>(), 
                                       &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7]));
p_maximum = etl::multimax_iter_compare(std::greater<int>(), 
                                       &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7]));
```

--------------------------------

### C++ divide_round_half_odd examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_half_odd with various positive and negative inputs.

```cpp
.151 / 100 ==  2
.150 / 100 ==  1
.149 / 100 ==  1
..51 / 100 ==  1
..50 / 100 ==  1
..49 / 100 ==  0
.-49 / 100 ==  0
.-50 / 100 == -1
.-51 / 100 == -1
-149 / 100 == -1
-150 / 100 == -1
-151 / 100 == -2
```

--------------------------------

### Start FSM

Source: https://github.com/etlcpp/etl/blob/master/docs/state machines/finite-state-machine.md

Starts the FSM. Optionally calls on_enter_state for the initial state. This method can only be called once; subsequent calls have no effect.

```cpp
void start(bool call_on_enter_state = true)
```

--------------------------------

### Select Compiler for Meson Build

Source: https://github.com/etlcpp/etl/blob/master/docs/source/meson.md

Demonstrates how to specify the C and C++ compilers for Meson configuration using environment variables.

```bash
# GCC
CC=gcc CXX=g++ meson setup builddir

# Clang
CC=clang CXX=clang++ meson setup builddir

# Specific versions
CC=gcc-14 CXX=g++-14 meson setup builddir
CC=clang-18 CXX=clang++-18 meson setup builddir
```

--------------------------------

### Install Hugo Extended on Linux

Source: https://github.com/etlcpp/etl/blob/master/DOCUMENTATION.md

Download and install the latest extended release of Hugo on Linux. This method is recommended to ensure you get the extended version.

```bash
tar -xzf hugo_extended_x.x.x_linux-amd64.tar.gz
   sudo mv hugo /usr/local/bin/
```

--------------------------------

### Install Hugo Extended via Snap (Linux)

Source: https://github.com/etlcpp/etl/blob/master/docs/getting-started/view-the-docs-locally/install-hugo.md

Install the extended version of Hugo using Snap on Linux. This method ensures you get the latest stable extended build.

```bash
sudo snap install hugo --channel=extended/stable --classic
```

--------------------------------

### Multimin Example (C++)

Source: https://github.com/etlcpp/etl/blob/master/docs/utilities/algorithms.md

Demonstrates the usage of ETL's multimin and multimin_compare functions for finding minimum values and iterators from variable argument lists.

```cpp
int minimum;

minimum = etl::multimin(1, 2, 3, 4, 5, 6, 7, 8));
minimum = etl::multimin_compare(std::less<int>(), 1, 2, 3, 4, 5, 6, 7, 8));
minimum = etl::multimin_compare(std::greater<int>(), 1, 2, 3, 4, 5, 6, 7, 8));

int i[8] = { 1, 2, 3, 4, 5, 6, 7, 8 };

int* p_minimum;

p_minimum = etl::multimin_iter(&i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7]));
p_minimum = etl::multimin_iter_compare(std::less<int>(), 
                                       &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7]));
p_minimum = etl::multimin_iter_compare(std::greater<int>(), 
                                       &i[0], &i[1], &i[2], &i[3], &i[4], &i[5], &i[6], &i[7]));

```

--------------------------------

### Make Multimap Usage Example

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/maps/multimap.md

Shows how to use the make_multimap helper function to create and initialize an etl::multimap.

```cpp
auto data = etl::make_multimap<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
                                    etl::pair{4, 5}, etl::pair{6, 7});
```

--------------------------------

### C++ divide_round_half_down examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_half_down with various positive and negative inputs.

```cpp
.151 / 100 ==  3
.150 / 100 ==  2
.149 / 100 ==  1
..51 / 100 ==  1
..50 / 100 ==  0
..49 / 100 ==  0
.-49 / 100 ==  0
.-50 / 100 ==  0
.-51 / 100 == -1
-149 / 100 == -1
-150 / 100 == -2
-151 / 100 == -3
```

--------------------------------

### C++ divide_round_to_zero examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_to_zero with various positive and negative inputs.

```cpp
.151 / 100 ==  1
.150 / 100 ==  1
.149 / 100 ==  1
..51 / 100 ==  0
..50 / 100 ==  0
..49 / 100 ==  0
.-49 / 100 ==  0
.-50 / 100 ==  0
.-51 / 100 ==  0
-149 / 100 == -1
-150 / 100 == -1
-151 / 100 == -1
```

--------------------------------

### Singleton Usage Example

Source: https://github.com/etlcpp/etl/blob/master/docs/patterns/singleton.md

Demonstrates the lifecycle of a singleton, including checking validity, creating with parameters, accessing the instance, and destroying it.

```cpp
class MyType;
using MySingleton = etl::singleton<MyType>;
bool is_valid;

is_valid = MySingleton::is_valid();    // false

MyType& mt1 = MySingleton::instance(); // Raises ETL_ASSERT etl::singleton_not_created

MySingleton::create(1, "Hello World"); // Construct with parameters
is_valid = MySingleton::is_valid();    // true

MyType& mt2 = MySingleton::instance(); // Get the instance
is_valid = MySingleton::is_valid();    // true

MySingleton::destroy();                // Destruct the instance
is_valid = MySingleton::is_valid();    // false
```

--------------------------------

### Get Buffer Data Pointer

Source: https://github.com/etlcpp/etl/blob/master/docs/IO/buffer_descriptors.md

Returns a constant pointer to the start of the buffer's data.

```cpp
ETL_CONSTEXPR pointer data() const
```

--------------------------------

### Start Hugo Development Server

Source: https://github.com/etlcpp/etl/blob/master/DOCUMENTATION.md

Initiates the Hugo local web server to serve the documentation. Changes to documentation files will be reflected automatically in the browser.

```bash
hugo server
```

--------------------------------

### etl::multimap Constructor (Template Deduction Guides)

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/maps/multimap.md

Demonstrates how to construct an etl::multimap using C++17 template deduction guides by providing a list of pairs.

```APIDOC
## etl::multimap Constructor (Template Deduction Guides)

### Description
C++17 and above allow for template argument deduction for multimap constructors when pairs are provided.

### Template Deduction Guides
```cpp
template <typename... TPairs>
etl::multimap(TPairs...)
```

### Example
```cpp
etl::multimap data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} }
```
Defines data as an multimap of `int`/`int` pairs, of length 4, containing the supplied data.
```

--------------------------------

### Singleton Creation and Access

Source: https://github.com/etlcpp/etl/blob/master/docs/patterns/singleton.md

Demonstrates how to create, access, and check the validity of a singleton instance.

```APIDOC
## etl::singleton<T>

### Description
Provides a non-intrusive way to create a singleton with deterministic construction and destruction.

### Template Parameters
* **T** - The type to use as a singleton.

### Static Functions

#### `static void create()`
Creates the singleton, default constructing the instance and setting it to the valid state. Only the first call is effective. Must be called before `instance()`.

#### `template <typename T1> static void create(const T1& p1)`
Constructs the singleton from 1 parameter.

#### `template <typename T1, typename T2> static void create(const T1& p1, const T2& p2)`
Constructs the singleton from 2 parameters.

#### `template <typename T1, typename T2, typename T3> static void create(const T1& p1, const T2& p2, const T3& p3)`
Constructs the singleton from 3 parameters.

#### `template <typename T1, typename T2, typename T3, typename T4> static void create(const T1& p1, const T2& p2, const T3& p3, const T4& p4)`
Constructs the singleton from 4 parameters.

#### `template <typename... TArgs> static void create(TArgs&&... args)` (C++11 and above)
Creates the singleton and constructs the type using the supplied parameters. Sets the singleton to the valid state. Only the first successful call is effective. Does nothing if the singleton is already valid. Must be called before `instance()`.

#### `static T& instance()`
Returns a reference to the one instance of `T`. Asserts `etl::singleton_not_created` if `create` has not been called.

#### `static void destroy()`
Calls the destructor of the instance and sets the singleton to the invalid state. Only the first successful call is effective. Does nothing if the singleton is already invalid.

#### `static bool is_valid()`
Returns `true` if the instance is valid, `false` otherwise (before `create` or after `destroy`).

### Example
```cpp
class MyType;
using MySingleton = etl::singleton<MyType>;
bool is_valid;

is_valid = MySingleton::is_valid();    // false

// MyType& mt1 = MySingleton::instance(); // Raises ETL_ASSERT etl::singleton_not_created

MySingleton::create(1, "Hello World"); // Construct with parameters
is_valid = MySingleton::is_valid();    // true

MyType& mt2 = MySingleton::instance(); // Get the instance
is_valid = MySingleton::is_valid();    // true

MySingleton::destroy();                // Destruct the instance
is_valid = MySingleton::is_valid();    // false
```
```

--------------------------------

### Example of etl::list Initialization with Template Deduction

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/lists/list.md

This example illustrates using the C++17 template deduction guide to initialize an etl::list. The list infers its type and size from the provided initializer list.

```cpp
etl::list data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
```

--------------------------------

### C++ divide_round_half_even examples

Source: https://github.com/etlcpp/etl/blob/master/docs/maths/rounded-integral-division.md

Examples demonstrating the behavior of divide_round_half_even (Banker's rounding) with various positive and negative inputs.

```cpp
.151 / 100 ==  2
.150 / 100 ==  2
.149 / 100 ==  1
..51 / 100 ==  1
..50 / 100 ==  0
..49 / 100 ==  0
.-49 / 100 ==  0
.-50 / 100 ==  0
.-51 / 100 == -1
-149 / 100 == -1
-150 / 100 == -2
-151 / 100 == -2
```

--------------------------------

### Getting Iterator to Beginning (begin)

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/Views/array-wrapper.md

Returns an iterator pointing to the first element of the array. Used for iterating through the array from the start.

```cpp
ETL_CONSTEXPR iterator begin()
```

```cpp
ETL_CONSTEXPR const_iterator begin() const
ETL_CONSTEXPR const_iterator cbegin() const
```

--------------------------------

### Example Usage

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/Views/multi-range.md

Demonstrates how to set up and iterate through nested multi-ranges with different comparison types and step types.

```APIDOC
## Example

```cpp
using Iterator = std::forward_list<std::string>::const_iterator;

// Less Than compare type
using LessThanCompare = etl::multi_range<const short*>::less_than_compare;

// Decrementing step type
using DecrementPtr = etl::multi_range<const short*>::reverse_step;

using Outer  = etl::multi_range<int>;          // Incrementing int
using Middle = etl::multi_range<const short*>; // Decrementing const short*
using Inner  = etl::multi_range<Iterator>;     // Incrementing const_iterator

const short data[4] = { 0, 1, 2, 3 };

std::forward_list<std::string> strings =
{
  "zero", "one", "two", "three"
};

LessThanCompare lessThan;
DecrementPtr    decrementPtr;

// Setup the loops.
Outer  outer(0, 4, lessThan);
Middle middle(data + 3, data - 1, decrementPtr);
Inner  inner(strings.begin(), strings.end());

outer.append(middle).append(inner);

size_t n_outer_loops  = outer.number_of_loops();  // == 3
size_t n_middle_loops = middle.number_of_loops(); // == 2
size_t n_inner_loops  = inner.number_of_loops();  // == 1

size_t n_outer_iterations  = outer.number_of_iterations();  // == 64
size_t n_middle_iterations = middle.number_of_iterations(); // == 16
size_t n_inner_iterations  = inner.number_of_iterations();  // == 4

// Create const references to the loop values.
const int&      value_outer  = outer.value();
const short*&   value_middle = middle.value();
const Iterator& value_inner  = inner.value();

// Iterate through the nested loops.
int i = 0;

for (outer.start(); !outer.completed(); outer.next())
{
  std::cout << "Iteration " << i++ << " : "
            << "Outer  = " << value_outer << " : "
            << "Middle = " << *value_middle << " : "
            << "Inner  = " << *value_inner
            << "\n"; 
}

// Just iterate through the two nested loops.
i = 0;

for (middle.start(); !middle.completed(); middle.next())
{
  std::cout << "Iteration " << i++ << " : "
            << "Middle = " << *value_middle << " : "
            << "Inner  = " << *value_inner
            << "\n"; 
}
```
```

--------------------------------

### Get Iterator to Beginning of Span

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/Views/poly-span.md

Returns an iterator pointing to the first element of the span. Use when you need to start iterating from the beginning.

```cpp
ETL_NODISCARD ETL_CONSTEXPR iterator begin() const ETL_NOEXCEPT
```

--------------------------------

### Get Number of Ranges

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/Views/multi-range.md

Returns the count of linked ranges starting from the current one. For a chain A -> B -> C, B.number_of_ranges() returns 2.

```cpp
size_t number_of_ranges() const
```

--------------------------------

### Separate Build Directories per Compiler

Source: https://github.com/etlcpp/etl/blob/master/docs/source/meson.md

Example of setting up separate build directories for different compiler configurations.

```bash
CC=gcc CXX=g++ meson setup build-gcc
CC=clang CXX=clang++ meson setup build-clang
```

--------------------------------

### Constructing flat_multimap with Initializer List

Source: https://github.com/etlcpp/etl/blob/master/docs/containers/maps/flat-multimap.md

Example of constructing an etl::flat_multimap using C++17 template deduction guides with an initializer list of pairs.

```cpp
etl::flat_multimap data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl::pair{6, 7} };
```

--------------------------------

### String View Hashing Example

Source: https://github.com/etlcpp/etl/blob/master/docs/strings/string-view.md

Demonstrates how to create a string view, print its content, and calculate its hash value using etl::hash. Requires including the necessary headers for string and string_view.

```cpp
etl::string<10> greeting("Hello World");

using View = etl::string_view;

View view(greeting.begin() + 2, greeting.size() - 4);

void Print(const View& view)
{
  std::cout << std::string(view.begin(), view.end());
}

Print(view); // Prints "llo Wo"

size_t hashvalue = etl::hash<View>()(view);
```