Tobante's embedded template library. A STL-like C++ template library designed for embedded devices with limited resources. Supports freestanding and hosted environments.

• Quick Start
• Status
  • Hosted
  • Freestanding
  • Analysis
• Design Goals
  • Error Handling
  • Near Future
  • Far Future
• Project Integration
  • Command Line / Makefile
  • CMake
  • PlatformIO
• Header Overview
• Header Detail

// main.cpp
#include "etl/algorithm.hpp"  // for count_if
#include "etl/array.hpp"      // for array

auto main() -> int
{
  auto const numbers = etl::array{1, 2, 3, 4, 5};
  auto const greater_two = [] (auto const v) { return v > 2; };
  return etl::count_if(begin(numbers), end(numbers), greater_two);
}

g++ -Wall -Wextra -Wpedantic -std=c++20 -I path/to/tetl/include main.cpp

For examples look at the examples subdirectory or the test files in tests. The API reference is currently work in progress. I'm switching from doxygen to standardese, which still has some bugs, so some parts of the docs may still be missing.

License	Lines of Code	Progress	Documentation
		Spreadsheet	API Reference

Platform	Status	Notes
Linux		GCC 11/12 & Clang 12/13/14/15/16
macOS		AppleClang 14
Windows		Visual Studio 2022

Platform	Status	Notes
ARM		GCC 12
AVR		GCC 12
MSP430		GCC 12

Type	Status	Notes
Coverage		GCC 11
Sanitizers		Clang 16
Clang-Tidy		Clang 16
Clang -Weverything		Clang 16

NOTE: All test are compiled in debug and release mode with at least -Wall -Wextra -Wpedantic -Werror or /W3 /WX. The full list of warning flags can be found in the CMake configuration: cmake/compiler_warnings.cmake. Hosted platforms run all tests & examples, while freestanding builds only compile (ARM & AVR) and link (AVR) the example files.

• 100% portable (no STL headers required, minimum of C headers)
• Header only
• C++20 and beyond (freestanding or hosted)
• Similar API to the STL
• No dynamic memory
• constexpr all the things
• Minimize undefined behavoir. See Error Handling
• Easy desktop development (cmake)

It all started when I wanted to have a vector without dynamic memory. At that time I didn't know that proposals like github.com/gnzlbg/static_vector where in the making. My actual goal has turned into a mammoth project. A standard library for microcontrollers and other embedded environments. The API is, as far as it is technically feasible, identical to the STL. All algorithms work identically, pair and friend are available and containers like set, map and vector are also implemented, but with different names.

All containers work only with memory on the stack. This means that their size must be known at compile time. Furthermore I assume an environment in which exceptions and RTTI migth be disabled. This results in the problem that not all members of a container can be implemented the same way as they are in the STL. Any function that returns a reference to a sequence element has the ability to throw exceptions in a normal hosted environment if the index is out of bounds. If exceptions are disabled, this is not possible. For now, my solution to this problem is to delegate to the user. Unsafe methods like etl::static_vector::operator[] are still available (with asserts in debug builds), while throwing methods like etl::static_vector::at are not implemented. This is currently subject to change. See Error Handling for more details.

Unlike LLVMs SmallVector, etl::static_vector & friends do not have a base class which they can slice to. My plan is to add mutable view-like non-owning types for each container. A etl::static_vector we would have a vector_ref which would work mostly like a span, but would also provide the vector interface. I don't want to name the types *_view, since the word view implies non-mutable in standard containers like string_view. None of the container_ref types have been implemented yet.

The headers etl/algorithm.hpp and etl/numeric.hpp provide all algorithms from the standard. Unlike implementations found in libstdc++ or libc++, mine are primarily optimized for code size and not runtime performance. Overloads with an ExecutionPolicy are not implemented.

Headers like etl/chrono.hpp and etl/mutex.hpp only provide classes & functions that can be implemented in a portable way. Platform specific functionality like steady_clock or mutex can be provided by the user. The user provided types should meet the requirements listed in Named Requirements to work seamlessly with the types provided in the etl namespace.

The etl/experimental subdirectory includes libraries that use etl as their foundation. It can be thought of as a mini boost-like library collection. Everything is work in progress.

• Networking (buffers, ntoh, ...)
• Strong types
• STM32 HAL
• DSP DSL
• FreeRTOS Abstraction
  • Stubs for unittests run on desktop machines

Since I assume that you might have exceptions disabled, I need a different way of reporting exceptional cases to you which occured deep inside the library. To keep the behavior of my library and actual STL implementations as close as possible, I've chosen to add a global assert/exception handler functions, which can be overriden by enabling the TETL_ENABLE_CUSTOM_ASSERT_HANDLER macro.

TODO

• ASSERT macro for debug checks
• EXCEPTION macro for debug & release checks

For more details about the global assertion handler etl::tetl_assert_handler & the assertion macro TETL_ASSERT see the examples/cassert.cpp file.

• Switch from doxygen to standardese as the documentation generator
• Fix map, tuple, variant & format
• Improve number <-> string conversions
• Add fuzzing tests to CI
  • Check that etl and std implementations produce the same output

• Replace Catch2 with custom unit testing library
  • This depends on a working implementation of format for reporting errors.
• Run unit test & examples on hardware or QEMU emulations.
  • Depends on the custom unit test library, since Catch2 is to big to fit onto most MCUs

The following steps explain how to add etl to your project. Embedded or desktop.

cd path/to/your/project
mkdir 3rd_party
git submodule add https://github.com/tobanteEmbedded/tetl.git 3rd_party/tetl

CXXFLAGS += -std=c++20 -I3rd_party/tetl

Add tetl as a git submodule, then add these lines to your CMakeLists.txt:

# tetl::etl is an interface target, so you can use it even if you
# have a custom toolchain in your CMake configuration. The target only sets the
# include path. No static library is created.

add_subdirectory(3rd_party/tetl/include EXCLUDE_FROM_ALL)
target_link_libraries(${YOUR_TARGET} tetl::etl)

Add tetl as a git submodule, then add these lines to your platformio.ini:

; Most Arduino code does not compile unless you have GNU extensions enabled.
[env:yourenv]
build_unflags = -std=gnu++11
build_flags = -std=gnu++20 -Wno-register -I 3rd_party/tetl

• Library: Algorithms
• Include: etl/algorithm.hpp
• Example: algorithm.cpp
• Implementation Progress: algorithm
• Changes:
  • Implementations are optimize for code size. See etl::search vs. libstdc++ (godbolt.org) as an example.
  • All overloads using an execution policy are not implemented.

• Library: Containers
• Include: etl/array.hpp
• Example: array.cpp
• Implementation Progress: array
• Changes:
  • None

• Library: Numeric
• Include: etl/bit.hpp
• Example: bit.cpp
• Implementation Progress: bit
• Changes:
  • None

• Library: Utility
• Include: etl/bitset.hpp
• Example: bitset.cpp
• Implementation Progress: bitset
• Changes:
  • TODO

• Library: Utility / Error Handling
• Include: etl/cassert.hpp
• Example: cassert.cpp
• Implementation Progress: cassert
• Changes:
  • Added custom assertion macro TETL_ASSERT. The behavoir can be customized. The macro get's called every time an exceptional case has occurred inside the library. See the example file for more details.

• Library: Strings
• Include: etl/cctype.hpp
• Example: TODO
• Implementation Progress: cctype
• Changes:
  • Locale independent

• Library: Utility / Numeric Limits
• Include: etl/cfloat.hpp
• Example: TODO
• Implementation Progress: cfloat
• Changes:
  • None

• Library: Strings
• Include: etl/charconv.hpp
• Example: TODO
• Implementation Progress: charconv
• Changes:
  • None

• Library: Utility
• Include: etl/chrono.hpp
• Example: chrono.cpp
• Implementation Progress: chrono
• Changes:
  • No clocks are implemented. You have to provide your own, which must at least meet the requirements of Clock.

• Library: Utility / Numeric Limits
• Include: etl/climits.hpp
• Example: TODO
• Implementation Progress: climits
• Changes:
  • None

• Library: Numeric
• Include: etl/cmath.hpp
• Example: TODO
• Implementation Progress: cmath
• Changes:
  • None

• Library: Numeric
• Include: etl/complex.hpp
• Example: TODO
• Implementation Progress: complex
• Changes:
  • None

• Library: Concepts
• Include: etl/concepts.hpp
• Example: TODO
• Implementation Progress: concepts
• Changes:
  • None

• Library: Utility
• Include: etl/cstdarg.hpp
• Example: TODO
• Implementation Progress: cstdarg
• Changes:
  • None

• Library: Utility
• Include: etl/cstddef.hpp
• Example: TODO
• Implementation Progress: cstddef
• Changes:
  • None

• Library: Utility / Numeric Limits
• Include: etl/cstdint.hpp
• Example: TODO
• Implementation Progress: cstdint
• Changes:
  • None

• Library: Input/Output
• Include: etl/cstdio.hpp
• Example: TODO
• Implementation Progress: cstdio
• Changes:
  • TODO

• Library: Utility
• Include: etl/cstdlib.hpp
• Example: TODO
• Implementation Progress: cstdlib
• Changes:
  • None

• Library: Strings
• Include: etl/cstring.hpp
• Example: TODO
• Implementation Progress: cstring
• Changes:
  • TODO

• Library: Utility
• Include: etl/ctime.hpp
• Example: TODO
• Implementation Progress: ctime
• Changes:
  • TODO

• Library: Strings
• Include: etl/cwchar.hpp
• Example: TODO
• Implementation Progress: cwchar
• Changes:
  • TODO

• Library: Error handling
• Include: etl/exception.hpp
• Example: TODO
• Implementation Progress: exception
• Changes:
  • TODO

• Library: Utility / Error Handling
• Include: etl/expected.hpp
• Example: TODO
• Implementation Progress: expected
• Changes:
  • TODO

• Library: Strings
• Include: etl/format.hpp
• Example: TODO
• Implementation Progress: format
• Changes:
  • WIP. Don't use.

• Library: Utility
• Include: etl/functional.hpp
• Example: TODO
• Implementation Progress: functional
• Changes:
  • TODO

• Library: Input/Output
• Include: etl/ios.hpp
• Example: TODO
• Implementation Progress: ios
• Changes:
  • TODO

• Library: Iterator
• Include: etl/iterator.hpp
• Example: TODO
• Implementation Progress: iterator
• Changes:
  • TODO

• Library: Utility / Numeric Limits
• Include: etl/limits.hpp
• Example: TODO
• Implementation Progress: limits
• Changes:
  • None

• Library: Containers
• Include: etl/map.hpp
• Example: map.cpp
• Implementation Progress: map
• Changes:
  • Renamed map to static_map. Fixed compile-time capacity.

• Library: Utility / Dynamic Memory
• Include: etl/memory.hpp
• Example: memory.cpp
• Implementation Progress: memory
• Changes:
  • Non-standard class templates small_ptr (compressed pointer) & pointer_int_pair (pointer + integer) are provided.

• Library: Thread
• Include: etl/mutex.hpp
• Example: mutex.cpp
• Implementation Progress: mutex
• Changes:
  • Only RAII lock types are implemented. You have to provide a mutex type that at least meets the BasicLockable requirements.

• Library: Utility / Dynamic Memory
• Include: etl/new.hpp
• Example: TODO
• Implementation Progress: new
• Changes:
  • None
  • If the standard <new> is availble it is used to define the global placement new functions to avoid ODR violations when mixing std & etl headers.

• Library: Numeric
• Include: etl/numbers.hpp
• Example: TODO
• Implementation Progress: numbers
• Changes:
  • None

• Library: Numeric
• Include: etl/numeric.hpp
• Example: numeric.cpp
• Implementation Progress: numeric
• Changes:
  • Implementations are optimize for code size. See etl::search vs. libstdc++ (godbolt.org) as an example.
  • All overloads using an execution policy are not implemented.

• Library: Utility
• Include: etl/optional.hpp
• Example: optional.cpp
• Implementation Progress: optional
• Changes:
  • TODO

• Library: Random Number
• Include: etl/random.hpp
• Example: random.cpp
• Implementation Progress: random
• Changes:
  • Added basic_xorshift32 and basic_xorshift64 (Non-standard)

• Library: Numeric
• Include: etl/ratio.hpp
• Example: ratio.cpp
• Implementation Progress: ratio
• Changes:
  • None

• Library: Utility
• Include: etl/scope.hpp
• Example: TODO
• Implementation Progress: TODO
• Reference: en.cppreference.com/w/cpp/experimental/scope_exit
• Changes:
  • Based on p0052r8
  • Only provides scope_exit

• Library: Utility
• Include: etl/source_location.hpp
• Example: source_location.cpp
• Implementation Progress: TODO
• Changes:
  • None

• Library: Containers
• Include: etl/set.hpp
• Example: set.cpp
• Implementation Progress: set
• Changes:
  • Renamed set to static_set. Fixed compile-time capacity.
  • If is_trivial_v<T>, then is_trivially_copyable_v<static_set<T, Capacity>>
  • If is_trivial_v<T>, then is_trivially_destructible_v<static_set<T, Capacity>>

• Library: Containers
• Include: etl/span.hpp
• Example: TODO
• Implementation Progress: span

• Library: Containers
• Include: etl/stack.hpp
• Example: TODO
• Implementation Progress: stack
• Changes:
  • None. Works with static_vector.

• Library: Error handling
• Include: etl/stdexcept.hpp
• Example: TODO
• Implementation Progress: stdexcept
• Changes:
  • TODO

• Library: Strings
• Include: etl/string.hpp
• Example: string.cpp
• Implementation Progress: string
• Changes:
  • Only implemeted for type char at the moment.
  • Renamed basic_string to basic_static_string. Fixed compile-time capacity.

• Library: Strings
• Include: etl/string_view.hpp
• Example: string_view.cpp
• Implementation Progress: string_view
• Changes:
  • None
  • Only implemeted for type char at the moment.

• Library: Utility / Error Handling
• Include: etl/system_error.hpp
• Example: TODO
• Implementation Progress: system_error
• Changes:
  • Only provides errc enum and helper traits.

• Library: Utility
• Include: etl/tuple.hpp
• Example: tuple.cpp
• Implementation Progress: tuple
• Changes:
  • Broken at the moment.

• Library: Utility
• Include: etl/type_traits.hpp
• Example: type_traits.cpp
• Implementation Progress: type_traits
• Changes:
  • None

• Library: Utility
• Include: etl/utility.hpp
• Example: utility.cpp
• Implementation Progress: utility
• Changes:
  • None

• Library: Utility
• Include: etl/variant.hpp
• Example: TODO
• Implementation Progress: variant
• Changes:
  • Broken at the moment.

• Library: Containers
• Include: etl/vector.hpp
• Example: vector.cpp
• Implementation Progress: vector
• Changes:
  • Renamed vector to static_vector. Fixed compile-time capacity.
  • Based on P0843r3 and the reference implementation from github.com/gnzlbg/static_vector.
  • If is_trivial_v<T>, then is_trivially_copyable_v<static_vector<T, Capacity>>
  • If is_trivial_v<T>, then is_trivially_destructible_v<static_vector<T, Capacity>>

• Library: Utility
• Include: etl/version.hpp

Get access to all intrinsic macros & library version macro and constants. This header also include <version> from C++20 if it is available.

#include "etl/version.hpp"

#include <stdio.h>

auto main() -> int
{
  puts(TETL_VERSION_STRING);  // Print current library version

  // Detect compiler
#if defined(TETL_MSVC)
  puts("msvc");
#if defined(TETL_GCC)
  puts("gcc");
#if defined(TETL_CLANG)
  puts("clang");
#else
  puts("other compiler");
#endif

  // Detect C++ standard
  if (etl::current_standard == language_standard::cpp_20) { puts("using C++20"); }
  if (etl::current_standard == language_standard::cpp_23) { puts("using C++23"); }

  return 0;
}

• Library: Utility
• Include: etl/warning.hpp

#include "etl/warning.hpp"

auto main(int argc, char** argv) -> int
{
  // Explicitly ignore unused arguments or variables.
  etl::ignore_unused(argc, argv);
  return 0;
}