From a8ebe338f80ee25fcc79d53cdbc8140bf208fae1 Mon Sep 17 00:00:00 2001 From: Roland Reichwein Date: Fri, 6 Mar 2026 11:11:46 +0100 Subject: [PATCH 1/7] Fix etl::rotate (#1327) Per the C++ standard, std::rotate returns first + (last - middle): * When first == middle, return last * When middle == last, return first --- include/etl/algorithm.h | 28 +++++++++-- test/iterators_for_unit_tests.h | 6 +++ test/test_algorithm.cpp | 87 +++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+), 4 deletions(-) diff --git a/include/etl/algorithm.h b/include/etl/algorithm.h index 74fbb8ed..8ee795a8 100644 --- a/include/etl/algorithm.h +++ b/include/etl/algorithm.h @@ -1193,7 +1193,12 @@ namespace etl typename etl::enable_if::value, TIterator>::type rotate_general(TIterator first, TIterator middle, TIterator last) { - if (first == middle || middle == last) + if (first == middle) + { + return last; + } + + if (middle == last) { return first; } @@ -1242,7 +1247,12 @@ namespace etl typename etl::enable_if::value, TIterator>::type rotate_general(TIterator first, TIterator middle, TIterator last) { - if (first == middle || middle == last) + if (first == middle) + { + return last; + } + + if (middle == last) { return first; } @@ -1292,7 +1302,12 @@ namespace etl typename etl::enable_if::value, TIterator>::type rotate_general(TIterator first, TIterator middle, TIterator last) { - if (first == middle || middle == last) + if (first == middle) + { + return last; + } + + if (middle == last) { return first; } @@ -1314,7 +1329,12 @@ namespace etl typename etl::enable_if::value, TIterator>::type rotate_general(TIterator first, TIterator middle, TIterator last) { - if (first == middle || middle == last) + if (first == middle) + { + return last; + } + + if (middle == last) { return first; } diff --git a/test/iterators_for_unit_tests.h b/test/iterators_for_unit_tests.h index 16085f87..82d28c6c 100644 --- a/test/iterators_for_unit_tests.h +++ b/test/iterators_for_unit_tests.h @@ -113,6 +113,12 @@ struct non_random_iterator : public etl::iterator +bool operator ==(const non_random_iterator& lhs, const non_random_iterator& rhs) +{ + return lhs.ptr == rhs.ptr; +} + template bool operator !=(const non_random_iterator& lhs, const non_random_iterator& rhs) { diff --git a/test/test_algorithm.cpp b/test/test_algorithm.cpp index abdab9d5..4dd01e9f 100644 --- a/test/test_algorithm.cpp +++ b/test/test_algorithm.cpp @@ -1236,6 +1236,93 @@ namespace } } + //************************************************************************* + TEST(rotate_return_value) + { + // Verify that etl::rotate returns the same iterator as std::rotate + // in all cases, including the degenerate first==middle and middle==last cases. + std::vector initial_data = { 1, 2, 3, 4, 5 }; + + for (size_t i = 0UL; i <= initial_data.size(); ++i) + { + std::vector data1(initial_data); + std::vector data2(initial_data); + + auto std_result = std::rotate(data1.data(), data1.data() + i, data1.data() + data1.size()); + auto etl_result = etl::rotate(data2.data(), data2.data() + i, data2.data() + data2.size()); + + // Check that the return value offset matches + ptrdiff_t std_offset = std_result - data1.data(); + ptrdiff_t etl_offset = etl_result - data2.data(); + CHECK_EQUAL(std_offset, etl_offset); + } + + // Explicitly test first == middle (empty left half): should return last + { + std::vector data = { 1, 2, 3 }; + auto result = etl::rotate(data.data(), data.data(), data.data() + data.size()); + CHECK(result == data.data() + data.size()); + } + + // Explicitly test middle == last (empty right half): should return first + { + std::vector data = { 1, 2, 3 }; + auto result = etl::rotate(data.data(), data.data() + data.size(), data.data() + data.size()); + CHECK(result == data.data()); + } + } + + //************************************************************************* + TEST(rotate_return_value_non_random_iterator) + { + // Verify that etl::rotate returns the correct iterator when called with + // non-random (bidirectional) iterators, exercising rotate_general for + // bidirectional iterators rather than the random-access overload. + std::vector initial_data = { 1, 2, 3, 4, 5 }; + + for (size_t i = 0UL; i <= initial_data.size(); ++i) + { + std::vector data1(initial_data); + std::vector data2(initial_data); + + auto std_result = std::rotate(data1.data(), data1.data() + i, data1.data() + data1.size()); + + non_random_iterator nr_first(data2.data()); + non_random_iterator nr_middle(data2.data() + i); + non_random_iterator nr_last(data2.data() + data2.size()); + auto etl_result = etl::rotate(nr_first, nr_middle, nr_last); + + // Check that the data was rotated correctly + bool isEqual = std::equal(std::begin(data1), std::end(data1), std::begin(data2)); + CHECK(isEqual); + + // Check that the return value offset matches + ptrdiff_t std_offset = std_result - data1.data(); + ptrdiff_t etl_offset = etl_result.ptr - data2.data(); + CHECK_EQUAL(std_offset, etl_offset); + } + + // Explicitly test first == middle (empty left half): should return last + { + std::vector data = { 1, 2, 3 }; + non_random_iterator nr_first(data.data()); + non_random_iterator nr_middle(data.data()); + non_random_iterator nr_last(data.data() + data.size()); + auto result = etl::rotate(nr_first, nr_middle, nr_last); + CHECK(result.ptr == data.data() + data.size()); + } + + // Explicitly test middle == last (empty right half): should return first + { + std::vector data = { 1, 2, 3 }; + non_random_iterator nr_first(data.data()); + non_random_iterator nr_middle(data.data() + data.size()); + non_random_iterator nr_last(data.data() + data.size()); + auto result = etl::rotate(nr_first, nr_middle, nr_last); + CHECK(result.ptr == data.data()); + } + } + //************************************************************************* TEST(any_of) { From f96510bd79dca27c7a9445b56d3625d85e219843 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Mon, 2 Mar 2026 09:59:08 +0000 Subject: [PATCH 2/7] Added missing files from VS2022 project --- test/vs2022/etl.vcxproj | 2 ++ 1 file changed, 2 insertions(+) diff --git a/test/vs2022/etl.vcxproj b/test/vs2022/etl.vcxproj index 6396b761..2b069673 100644 --- a/test/vs2022/etl.vcxproj +++ b/test/vs2022/etl.vcxproj @@ -3552,6 +3552,7 @@ + @@ -10362,6 +10363,7 @@ + From 4ad6126ec5fdd7c27ed359ee09de2482e922bebb Mon Sep 17 00:00:00 2001 From: Roland Reichwein Date: Fri, 6 Mar 2026 21:08:31 +0100 Subject: [PATCH 3/7] Fix greater_equal and less_equal (#1331) --- include/etl/functional.h | 10 +++--- test/test_functional.cpp | 70 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 5 deletions(-) diff --git a/include/etl/functional.h b/include/etl/functional.h index 0f0172ec..73b1685b 100644 --- a/include/etl/functional.h +++ b/include/etl/functional.h @@ -224,9 +224,9 @@ namespace etl typedef int is_transparent; template - constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(lhs) < static_cast(rhs)) + constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(!(static_cast(rhs) < static_cast(lhs))) { - return !(static_cast(lhs) < static_cast(rhs)); + return !(static_cast(rhs) < static_cast(lhs)); } }; #endif @@ -250,7 +250,7 @@ namespace etl typedef int is_transparent; template - constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(lhs) < static_cast(rhs)) + constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(rhs) < static_cast(lhs)) { return static_cast(rhs) < static_cast(lhs); } @@ -276,9 +276,9 @@ namespace etl typedef int is_transparent; template - constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(lhs) < static_cast(rhs)) + constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(!(static_cast(lhs) < static_cast(rhs))) { - return static_cast(rhs) < static_cast(lhs); + return !(static_cast(lhs) < static_cast(rhs)); } }; #endif diff --git a/test/test_functional.cpp b/test/test_functional.cpp index 1204d330..5bbe6beb 100644 --- a/test/test_functional.cpp +++ b/test/test_functional.cpp @@ -85,6 +85,24 @@ namespace mutable std::string result; }; +#if ETL_USING_CPP11 + // Lightweight type used to verify transparent heterogeneous comparison. + // Only operator<(int, Wrapper) is defined; operator<(Wrapper, int) is + // intentionally absent. less_equal is implemented as + // !(rhs < lhs), so less_equal{}(Wrapper, int) needs + // operator<(int, Wrapper) which IS provided. + struct Wrapper + { + int value; + constexpr explicit Wrapper(int v) : value(v) {} + }; + + // int < Wrapper -- defined + constexpr bool operator<(int lhs, const Wrapper& rhs) { return lhs < rhs.value; } + + // Wrapper < int -- intentionally NOT defined +#endif + SUITE(test_functional) { //************************************************************************* @@ -101,6 +119,32 @@ namespace CHECK((compare>(1, 2))); CHECK(!(compare>(2, 1))); CHECK((compare>(1, 1))); + +#if ETL_USING_CPP11 + CHECK((compare>(1, 2))); + CHECK(!(compare>(2, 1))); + CHECK((compare>(1, 1))); +#endif + } + + //************************************************************************* + TEST(test_less_equal_void_heterogeneous) + { +#if ETL_USING_CPP11 + // less_equal{}(lhs, rhs) is !(rhs < lhs). + // With only operator<(int, Wrapper) defined, we can call + // less_equal{}(Wrapper, int) because the implementation + // evaluates !(int < Wrapper). + + // Wrapper(1) <= 2 → !(2 < Wrapper(1)) → !(2 < 1) → !false → true + CHECK((etl::less_equal{}(Wrapper(1), 2))); + + // Wrapper(2) <= 1 → !(1 < Wrapper(2)) → !(1 < 2) → !true → false + CHECK(!(etl::less_equal{}(Wrapper(2), 1))); + + // Wrapper(3) <= 3 → !(3 < Wrapper(3)) → !(3 < 3) → !false → true + CHECK((etl::less_equal{}(Wrapper(3), 3))); +#endif } //************************************************************************* @@ -117,6 +161,32 @@ namespace CHECK(!(compare>(1, 2))); CHECK((compare>(2, 1))); CHECK((compare>(1, 1))); + +#if ETL_USING_CPP11 + CHECK(!(compare>(1, 2))); + CHECK((compare>(2, 1))); + CHECK((compare>(1, 1))); +#endif + } + + //************************************************************************* + TEST(test_greater_equal_void_heterogeneous) + { +#if ETL_USING_CPP11 + // greater_equal{}(lhs, rhs) is !(lhs < rhs). + // With only operator<(int, Wrapper) defined, we can call + // greater_equal{}(int, Wrapper) because the implementation + // evaluates !(int < Wrapper). + + // 2 >= Wrapper(1) → !(2 < Wrapper(1)) → !(2 < 1) → !false → true + CHECK((etl::greater_equal{}(2, Wrapper(1)))); + + // 1 >= Wrapper(2) → !(1 < Wrapper(2)) → !(1 < 2) → !true → false + CHECK(!(etl::greater_equal{}(1, Wrapper(2)))); + + // 3 >= Wrapper(3) → !(3 < Wrapper(3)) → !(3 < 3) → !false → true + CHECK((etl::greater_equal{}(3, Wrapper(3)))); +#endif } //************************************************************************* From 7329efc7dfde1116de974899558be5345ec0e5c2 Mon Sep 17 00:00:00 2001 From: Roland Reichwein Date: Fri, 6 Mar 2026 21:29:58 +0100 Subject: [PATCH 4/7] Align comparison operators (#1330) In functional.h, the comparison operators for equal_to and not_equal_to mismatch between the actual comparison execution and the type inference for the return type. This change adjusts it by using the same operator==() in the return type inference as used in the comparison execution. Co-authored-by: John Wellbelove --- include/etl/functional.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/etl/functional.h b/include/etl/functional.h index 73b1685b..3c1c55b4 100644 --- a/include/etl/functional.h +++ b/include/etl/functional.h @@ -303,7 +303,7 @@ namespace etl typedef int is_transparent; template - constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(lhs) < static_cast(rhs)) + constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(lhs) == static_cast(rhs)) { return static_cast(lhs) == static_cast(rhs); } @@ -329,7 +329,7 @@ namespace etl typedef int is_transparent; template - constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(static_cast(lhs) < static_cast(rhs)) + constexpr auto operator()(T1&& lhs, T2&& rhs) const -> decltype(!(static_cast(lhs) == static_cast(rhs))) { return !(static_cast(lhs) == static_cast(rhs)); } From 67ecc8e11e2be245c15f03b231108b1adbd5882e Mon Sep 17 00:00:00 2001 From: Roland Reichwein Date: Fri, 6 Mar 2026 22:34:54 +0100 Subject: [PATCH 5/7] Add missing tests (#1321) * Add missing tests * Typo fixes --------- Co-authored-by: John Wellbelove --- include/etl/algorithm.h | 2 +- include/etl/array.h | 6 +++--- include/etl/functional.h | 2 +- include/etl/numeric.h | 2 +- test/CMakeLists.txt | 9 +++++++++ test/test_etl_assert.cpp | 2 ++ 6 files changed, 17 insertions(+), 6 deletions(-) diff --git a/include/etl/algorithm.h b/include/etl/algorithm.h index 8ee795a8..7317889c 100644 --- a/include/etl/algorithm.h +++ b/include/etl/algorithm.h @@ -34,7 +34,7 @@ SOFTWARE. #define ETL_ALGORITHM_INCLUDED ///\defgroup algorithm algorithm -/// Including reverse engineered algorithms from C++ 0x11, 0x14, 0x17 +/// Including reverse engineered algorithms from C++11, 14, 17 /// Additional new variants of certain algorithms. ///\ingroup utilities diff --git a/include/etl/array.h b/include/etl/array.h index f1624209..1f2f5044 100644 --- a/include/etl/array.h +++ b/include/etl/array.h @@ -46,7 +46,7 @@ SOFTWARE. #include ///\defgroup array array -/// A replacement for std::array if you haven't got C++0x11. +/// A replacement for std::array if you haven't got C++11. ///\ingroup containers namespace etl @@ -81,7 +81,7 @@ namespace etl //*************************************************************************** ///\ingroup array - /// A replacement for std::array if you haven't got C++0x11. + /// A replacement for std::array if you haven't got C++11. //*************************************************************************** template class array @@ -646,7 +646,7 @@ namespace etl //*************************************************************************** ///\ingroup array - /// A replacement for std::array if you haven't got C++0x11. + /// A replacement for std::array if you haven't got C++11. /// Specialisation for zero sized array. //*************************************************************************** template diff --git a/include/etl/functional.h b/include/etl/functional.h index 3c1c55b4..e313325e 100644 --- a/include/etl/functional.h +++ b/include/etl/functional.h @@ -43,7 +43,7 @@ SOFTWARE. namespace etl { //*************************************************************************** - /// A definition of reference_wrapper for those that don't have C++ 0x11 support. + /// A definition of reference_wrapper for those that don't have C++11 support. ///\ingroup reference //*************************************************************************** template diff --git a/include/etl/numeric.h b/include/etl/numeric.h index dbb43696..3283b338 100644 --- a/include/etl/numeric.h +++ b/include/etl/numeric.h @@ -47,7 +47,7 @@ namespace etl { //*************************************************************************** /// iota - /// Reverse engineered version of std::iota for non C++ 0x11 compilers. + /// Reverse engineered version of std::iota for non C++11 compilers. /// Fills a range of elements with sequentially increasing values starting with value. ///\param first An iterator to the first position to fill. ///\param last An iterator to the last + 1 position. diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index 2fdfc71c..2bec7847 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -86,6 +86,7 @@ add_executable(etl_tests test_closure.cpp test_closure_constexpr.cpp test_compare.cpp + test_concepts.cpp test_constant.cpp test_const_map.cpp test_const_map_constexpr.cpp @@ -172,6 +173,7 @@ add_executable(etl_tests test_endian.cpp test_enum_type.cpp test_error_handler.cpp + test_etl_assert.cpp test_etl_traits.cpp test_exception.cpp test_expected.cpp @@ -183,6 +185,7 @@ add_executable(etl_tests test_flat_multiset.cpp test_flat_set.cpp test_fnv_1.cpp + test_format.cpp test_format_spec.cpp test_forward_list.cpp test_forward_list_shared_pool.cpp @@ -194,10 +197,12 @@ add_executable(etl_tests test_hash.cpp test_hfsm.cpp test_hfsm_recurse_to_inner_state_on_start.cpp + test_hfsm_transition_on_enter.cpp test_histogram.cpp test_index_of_type.cpp test_indirect_vector.cpp test_indirect_vector_external_buffer.cpp + test_inplace_function.cpp test_instance_count.cpp test_integral_limits.cpp test_intrusive_forward_list.cpp @@ -206,7 +211,9 @@ add_executable(etl_tests test_intrusive_queue.cpp test_intrusive_stack.cpp test_invert.cpp + test_invoke.cpp test_io_port.cpp + test_is_invocable.cpp test_iterator.cpp test_jenkins.cpp test_largest.cpp @@ -259,6 +266,7 @@ add_executable(etl_tests test_pool.cpp test_pool_external_buffer.cpp test_priority_queue.cpp + test_print.cpp test_pseudo_moving_average.cpp test_quantize.cpp test_queue.cpp @@ -286,6 +294,7 @@ add_executable(etl_tests test_scaled_rounding.cpp test_set.cpp test_shared_message.cpp + test_signal.cpp test_singleton.cpp test_singleton_base.cpp test_smallest.cpp diff --git a/test/test_etl_assert.cpp b/test/test_etl_assert.cpp index e927a0b2..26fcced4 100644 --- a/test/test_etl_assert.cpp +++ b/test/test_etl_assert.cpp @@ -34,6 +34,8 @@ SOFTWARE. #include "etl/error_handler.h" #include "etl/exception.h" +#include + namespace { class TestException1 : public etl::exception From 8ce59792fd4667c33f61e749f3397a565514fc4d Mon Sep 17 00:00:00 2001 From: Niu Zhihong Date: Sat, 7 Mar 2026 06:04:32 +0800 Subject: [PATCH 6/7] Add ETL_FORMAT_NO_FLOATING_POINT control macro for etl::format (#1329) When ETL_FORMAT_NO_FLOATING_POINT is defined, all floating-point formatting support (float, double, long double) is excluded from etl::format. This reduces code size on targets that do not require floating-point formatting. Guarded sections: - #include - float/double/long double in supported_format_types variant - float/double/long double constructors in basic_format_arg - format_floating_* functions and format_aligned_floating - formatter, formatter, formatter - Floating-point test cases in test_format.cpp Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus Co-authored-by: John Wellbelove --- include/etl/format.h | 14 ++++++++++++++ include/etl/platform.h | 11 +++++++++++ test/test_format.cpp | 2 ++ 3 files changed, 27 insertions(+) diff --git a/include/etl/format.h b/include/etl/format.h index 3268f43b..7812f9ab 100644 --- a/include/etl/format.h +++ b/include/etl/format.h @@ -48,7 +48,9 @@ SOFTWARE. #include "variant.h" #include "visitor.h" +#if ETL_USING_FORMAT_FLOATING_POINT #include +#endif #if ETL_USING_CPP11 @@ -138,9 +140,11 @@ namespace etl unsigned int, long long int, unsigned long long int, +#if ETL_USING_FORMAT_FLOATING_POINT float, double, long double, +#endif const char*, etl::string_view, const void* @@ -302,6 +306,7 @@ namespace etl { } +#if ETL_USING_FORMAT_FLOATING_POINT basic_format_arg(const float v) : data(v) { @@ -316,6 +321,7 @@ namespace etl : data(v) { } +#endif basic_format_arg(const etl::string_view v) : data(v) @@ -1039,6 +1045,7 @@ namespace etl format_plain_num(it, value, spec, width); } +#if ETL_USING_FORMAT_FLOATING_POINT template void format_floating_default(OutputIt& it, T value, const format_spec_t& spec) { @@ -1214,6 +1221,7 @@ namespace etl private_format::format_sequence(it, "."); private_format::format_plain_num(it, fractional_int, spec, fractional_decimals); } +#endif class dummy_assign_to { @@ -1336,6 +1344,7 @@ namespace etl size_t count; }; +#if ETL_USING_FORMAT_FLOATING_POINT template void format_floating_g(OutputIt& it, T value, const format_spec_t& spec) { @@ -1409,6 +1418,7 @@ namespace etl } } } +#endif template struct format_visitor @@ -1490,6 +1500,7 @@ namespace etl return it; } +#if ETL_USING_FORMAT_FLOATING_POINT template typename format_context::iterator format_aligned_floating(Float arg, format_context& fmt_ctx) { @@ -1534,6 +1545,7 @@ namespace etl private_format::fill(it, suffix_size, fmt_ctx.format_spec.fill); return it; } +#endif template void format_string_view(OutputIt& it, etl::string_view arg, const format_spec_t& spec) @@ -2072,6 +2084,7 @@ namespace etl } }; +#if ETL_USING_FORMAT_FLOATING_POINT template<> struct formatter { @@ -2119,6 +2132,7 @@ namespace etl return private_format::format_aligned_floating(arg, fmt_ctx); } }; +#endif template<> struct formatter diff --git a/include/etl/platform.h b/include/etl/platform.h index 6db7c305..a1ae4029 100644 --- a/include/etl/platform.h +++ b/include/etl/platform.h @@ -154,6 +154,16 @@ SOFTWARE. #define ETL_NOT_USING_WIDE_CHARACTERS 0 #endif +//************************************* +// Helper macro for ETL_FORMAT_NO_FLOATING_POINT. +#if defined(ETL_FORMAT_NO_FLOATING_POINT) + #define ETL_USING_FORMAT_FLOATING_POINT 0 + #define ETL_NOT_USING_FORMAT_FLOATING_POINT 1 +#else + #define ETL_USING_FORMAT_FLOATING_POINT 1 + #define ETL_NOT_USING_FORMAT_FLOATING_POINT 0 +#endif + //************************************* // Figure out things about the compiler, if haven't already done so in etl_profile.h #include "profiles/determine_compiler_version.h" @@ -651,6 +661,7 @@ namespace etl static ETL_CONSTANT bool using_exceptions = (ETL_USING_EXCEPTIONS == 1); static ETL_CONSTANT bool using_libc_wchar_h = (ETL_USING_LIBC_WCHAR_H == 1); static ETL_CONSTANT bool using_std_exception = (ETL_USING_STD_EXCEPTION == 1); + static ETL_CONSTANT bool using_format_floating_point = (ETL_USING_FORMAT_FLOATING_POINT == 1); // Has... static ETL_CONSTANT bool has_initializer_list = (ETL_HAS_INITIALIZER_LIST == 1); diff --git a/test/test_format.cpp b/test/test_format.cpp index a6c25eab..3d3338fa 100644 --- a/test/test_format.cpp +++ b/test/test_format.cpp @@ -197,6 +197,7 @@ namespace CHECK_EQUAL("-6759414", test_format(s, "{}", static_cast(-6759414))); } +#if ETL_USING_FORMAT_FLOATING_POINT //************************************************************************* TEST(test_format_float) { @@ -266,6 +267,7 @@ namespace CHECK_EQUAL("0x1.92a738p-5", test_format(s, "{:a}", 0.0000015f)); CHECK_EQUAL("0x1.6345785d8ap+e", test_format(s, "{:a}", 100000000000000000.l)); } +#endif //************************************************************************* TEST(test_format_char_array) From 521df8ee19bf0b84b82086c2441c1c2f0c463380 Mon Sep 17 00:00:00 2001 From: Timon Zijnge <47081647+tzijnge@users.noreply.github.com> Date: Sat, 7 Mar 2026 09:13:00 +0100 Subject: [PATCH 7/7] Manchester documentation (#1325) * manchester * Added manchester code and test * manchester * Formatting and added missing file * manchester * Some functions can only be constexpr since C++14 * manchester * Manchester decode and some refactoring * manchester * Added some missing typenames * manchester * constexpr void function not allowed in C++11 * manchester * condition on static_assert tests * manchester * revert CMakeLists.txt * Using ETL_STATIC_ASSERT * Some cleanup * manchester * Added static_assert message * manchester * Added compile time tests * manchester * Added invert manchester * Some refactoring * manchester * Disable test for now * Move ETL_NODISCARD before static * manchester * Test for valid_span * manchester * Remove redundant (?) storage specifiers for template specializations. Storage specifier already given in base template * manchester * refactoring to get rid of specialized template functions in template class * manchester * cleanup * manchester * Added documentation comments * Some refactoring * manchester * introducing namespace detail_manchester * manchester * Some refactoring * Update tests * manchester * Some refactoring * Removed possible undefined behavior by refactoring encode_span * constexpr version of encode_span * Static assertion for rare case where code doesn't work because CHAR_BIT is not the same as the number of bits in uint_least8_t * manchester * renamed valid to is_valid * manchester * renamed is_valid_span to is_valid * Using etl exceptions in ETL_ASSERT * manchester * Removed _fast functions * merged encode_in_place with encode and decode_in_place with decode * removed _span to create normal overloads of encode and decode for span * Some renaming and minor refactoring * manchester * Fix build issues * manchester * Conditionally compile manchester_decoded * Update test_manchester.cpp Removed redundant semicolon * #1258 Manchester coding * Formatting * consistency: hex literals with lower case 0x * #1258 Manchester coding * Moved copyright to top of file * Make constexpr encode/decode span functions equal for little and big endian platforms * #1258 Manchester coding * Added missing include * Added missing 8bit/64bit guards * Fixed is_valid for big endian platforms * #1258 Manchester coding * private memcpy alias * #1258 Manchester coding * Review comments * #1258 Manchester coding * Cleanup * Fix build error * #1258 Manchester coding * Add manchester documentation * #1258 Manchester coding * Preparation for GitHub pages * #1324 Manchester documentation * Some small fixes --------- Co-authored-by: Timon Zijnge --- docs/_config.yml | 6 ++ docs/index.md | 7 ++ docs/manchester.md | 258 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 271 insertions(+) create mode 100644 docs/_config.yml create mode 100644 docs/index.md create mode 100644 docs/manchester.md diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..6fac68f0 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,6 @@ +plugins: + - jekyll-relative-links +relative_links: + enabled: true +include: + - manchester.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..23e43ac5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,7 @@ +--- +title: ETL documentation +--- + +## Pages + +* [Manchester](manchester.md) diff --git a/docs/manchester.md b/docs/manchester.md new file mode 100644 index 00000000..06c0cf7d --- /dev/null +++ b/docs/manchester.md @@ -0,0 +1,258 @@ +--- +title: Manchester encoding and decoding +--- + +Efficient Manchester encoding and decoding of data. The Manchester code represents a data bit as a sequence of a 'high' and a 'low' value. In software this translates to a conversion from one to two bits, or in a practical situation, from `n` bytes to `n*2` bytes. + +## See also + +[Manchester code](https://en.wikipedia.org/wiki/Manchester_code) + +## Features + +- Normal and inverted Manchester encoding +- Support for multiple encoding chunk sizes: 8-bit, 16-bit and 32-bit +- Span-based operations or chunk-based operations +- Constexpr functions for compile-time encoding/decoding (8-bit chunk size only) +- Validation of encoded data + +## Algorithm background + +To encode the value `0b11001100` we must first duplicate all bits to create the value `0b1111000011110000`. We then perform an XOR of this value with the constant `0b1010101010101010` (`0xAAAA`) to obtain the Manchester coded value of `0b1010010110100101`. We have now replaced each `1` bit with the sequence `10` and each `0` bit with the sequence `01`. + +### 2. Bit duplication + +Bit duplication is achieved with the following steps. This is also called binary interleaving. The example shows encoding of an 8-bit value. + +| Step | High Byte | Low Byte | Operation | +|------|--------------------|--------------------|----------------------------| +| 0 | `_ _ _ _ _ _ _ _` | `A B C D E F G H` | input value (i) | +| 1 | `_ _ _ _ A B C D` | `_ _ _ _ E F G H` | `(i \| (i << 4)) & 0x0F0F` | +| 2 | `_ _ A B _ _ C D` | `_ _ E F _ _ G H` | `(i \| (i << 2)) & 0x3333` | +| 3 | `_ A _ B _ C _ D` | `_ E _ F _ G _ H` | `(i \| (i << 1)) & 0x5555` | +| 4 | `A A B B C C D D` | `E E F F G G H H` | `(i \| (i << 1))` | + +This process can be easily extended to 16-bit or 32-bit values by adding additional steps to the bit duplication. + +### 3. Manchester Decoding + +Manchester decoding is done in a similar, but reversed way. + +### 4. Error Detection + +Error detection in Manchester coded data is done by comparing 2 neighboring bits. If they are +equal, then there is an error in the encoded input data. + +Comparing all 8 bit pairs in a 16-bit word is done as follows. + +| Step | Binary Value | Operation | Description | +|------|--------------|-------------------|-----------------------------------------------------------------------------------------------| +| 1 | `11011000` | Original | First bit pair (lsb, 00) is invalid. Last bit pair is also invalid. Other bit pairs are valid | +| 2 | `01101100` | Shift right by 1 | Shift the original value right by one bit | +| 3 | `10110100` | XOR | XOR the original with the shifted value | +| 4 | `01010101` | Mask with 0x55 | Apply mask to isolate bit pairs | +| 5 | `00010100` | Result | If result is not equal to 0x55, there was an error in the input | + +## Analysis + +Most traditional ways to Manchester encode data consist of a loop over all bits and a nested if-statement to check the value of the current bit. This approach does not scale well to increasing number of bits. The algorithm implemented here contains no conditional code and scales well. Doubling the number of processed bits per step (the chunk size) adds a single row to the bit duplication table. Because of the lack of loops and conditional code, this algorithm is likely to perform better than traditional ones on simple processors or when compiler optimization is disabled. On modern, powerful processors with caches and advanced optimization possibilities this algorithm may not show much benefit. In any case, the performance of the algorithm depends heavily on the processor type, compiler and compiler (optimization) settings. + +## API Reference + +### Classes + +Classes `etl::manchester` and `etl::manchester_inverted` contain static functions for encoding, decoding and validity checking. It is not necessary to instantiate objects of these classes. + +#### etl::manchester + +```cpp +typedef manchester_base manchester; +``` + +Manchester encoder using normal encoding (no inversion). + +#### etl::manchester_inverted + +```cpp +typedef manchester_base manchester_inverted; +``` + +Manchester encoder using inverted encoding. + +### Encoding Functions + +#### Encode single value + +```cpp +template +static ETL_CONSTEXPR14 typename encoded::type encode(TDecoded decoded) +``` + +Encodes a single value using Manchester encoding. + +**Parameters:** + +- `decoded`: The value to encode (`uint8_t`, `uint16_t`, or `uint32_t`) + +**Returns:** + +- The Manchester encoded value (twice the bit width of input) + +**Example:** + +```cpp +uint16_t encoded = etl::manchester::encode(0x55); +``` + +#### Encode range + +```cpp +template +static ETL_CONSTEXPR14 void encode(etl::span decoded, + etl::span encoded) +``` + +Encodes a span of data using the specified chunk size. + +**Parameters:** + +- `decoded`: Source data to encode +- `encoded`: Destination for encoded data (must be twice the size of `decoded`) + +**Template Parameters:** + +- `TChunk`: Chunk size for encoding (`uint8_t`, `uint16_t` or `uint32_t`) + +**Example:** + +```cpp +std::array data = {0x12, 0x34, 0x56, 0x78}; +std::array encoded_data1{}; +std::array encoded_data2{}; + +// Encode with TChunk == uint8_t +etl::manchester::encode(data, encoded_data1); + +// Encode with TChunk == uint32_t +etl::manchester::encode(data, encoded_data2); +``` + +### Decoding Functions + +#### Decode single value + +```cpp +template +static ETL_CONSTEXPR14 typename decoded::type decode(TEncoded encoded) +``` + +Decodes a single Manchester encoded value. + +**Parameters:** + +- `encoded`: The encoded value to decode (`uint16_t`, `uint32_t`, or `uint64_t`) + +**Returns:** + +- The Manchester decoded value (half the bit width of input) + +**Example:** + +```cpp +uint8_t decoded = etl::manchester::decode(0x5A5A); +``` + +#### Decode range + +```cpp +template ::type> +static ETL_CONSTEXPR14 void decode(etl::span encoded, + etl::span decoded) +``` + +Decodes a span of Manchester encoded data. + +**Parameters:** + +- `encoded`: Source data to decode +- `decoded`: Destination for decoded data (must be half the size of `encoded`) + +**Template Parameters:** + +- `TChunk`: Chunk type for decoding (`uint16_t`, `uint32_t`, or `uint64_t`) + +**Example:** + +```cpp +std::array encoded = {/* ... */}; +std::array decoded1 {}; +std::array decoded2 {}; + +// Decode with TChunk == uint16_t +etl::manchester::decode(encoded, decoded1); + +// Decode with TChunk == uint64_t +etl::manchester::decode(encoded, decoded2); +``` + +### Validation Functions + +#### Single value + +```cpp +template +static ETL_CONSTEXPR14 bool is_valid(TChunk encoded) +``` + +Validates that a single value contains valid Manchester encoded data. + +**Parameters:** + +- `encoded`: The encoded value to validate + +**Returns:** + +- `true` if the value contains valid Manchester encoded data, `false` otherwise + +**Example:** + +```cpp +bool valid = etl::manchester::is_valid(0x5A5A); +``` + +#### Range + +```cpp +static ETL_CONSTEXPR14 bool is_valid(etl::span encoded) +``` + +Validates that a range contains valid Manchester encoded data. + +**Parameters:** + +- `encoded`: The range of encoded data to validate + +**Returns:** + +- `true` if all data is valid Manchester encoding, `false` otherwise + +**Example:** + +```cpp +std::array encoded_data = {/* ... */}; +bool valid = etl::manchester::is_valid(encoded_data); +``` + +## Supported Types + +### Input/chunk types for encoding + +- `uint8_t` → `uint16_t` (if 8-bit types are supported) +- `uint16_t` → `uint32_t` +- `uint32_t` → `uint64_t` (if 64-bit types are supported) + +### Input/chunk types for decoding + +- `uint16_t` → `uint8_t` (if 8-bit types are supported) +- `uint32_t` → `uint16_t` +- `uint64_t` → `uint32_t` (if 64-bit types are supported)