From c8bc1bd8965343e6deb5b52111bbed86a8a20910 Mon Sep 17 00:00:00 2001 From: rleigh-electradx Date: Tue, 4 Aug 2026 11:45:49 +0100 Subject: [PATCH] Correct the documented make_xxx factory signatures and examples (#1530) * Corrected the documented make_xxx factory signatures and examples The Make template sections across the container documentation had drifted from the implementations, largely through copy-paste: - map.md, multimap.md and flat-multimap.md all documented make_flat_map; multiset.md documented make_set; flat-multiset.md documented make_flat_set; unordered-multimap.md documented make_unordered_map. Names and examples now match each container. - Every signature omitted the C++11-required trailing return type despite the sections being labelled C++11 and above; several also used a parameter name (TValues) that did not match any template parameter, and the unordered map headers were missing a comma. - forward-list.md documented a make_array-style signature with an explicit element type; the real function deduces the element type as the common type of the arguments, as documented for make_list. - The flat_set/flat_multiset template headers were missing the variadic parameter pack, and their examples passed a braced list to a variadic function, which does not compile; set.md used TKeyCompare where the implementation uses TCompare. - deque.md and the reference container docs were missing code fences. - Updated the four reference_flat_* function. However these functions cannot be instantiated at all (the reference containers have no initializer_list constructor, since one would dangle by design), so the documented examples have never compiled. Every remaining documented example verified to compile with clang 22 (C++17) against the current headers. * Fixed C++17-only syntax in factory examples and flagged the non-compilable ones Review feedback on the make_xxx documentation examples: - All the map-family factory examples are labelled C++11 and above but constructed their pairs with class template argument deduction (etl::pair{0, 1}), which requires C++17. The pairs in the make_flat_map, make_flat_multimap, make_map, make_multimap, make_unordered_map, make_unordered_multimap, make_reference_flat_map and make_reference_flat_multimap examples now name their template arguments explicitly. The template deduction guide examples are unchanged, as those sections are labelled C++17 and above. Verified with clang 22 in C++14 mode, which, like C++11, has no deduction guides. - The four make_reference_flat_* examples are now preceded by a warning callout stating that they do not currently compile: the functions cannot be instantiated because the reference containers have no initializer_list constructor. The examples themselves are retained, rewritten to pass named lvalues rather than temporaries, since the reference containers store references to external objects and the temporaries would dangle even if the functions compiled. The defect is being reported separately. --------- Co-authored-by: John Wellbelove --- docs/containers/arrays/array.md | 2 +- docs/containers/lists/forward-list.md | 8 +++-- docs/containers/maps/flat-map.md | 6 ++-- docs/containers/maps/flat-multimap.md | 8 ++--- docs/containers/maps/map.md | 6 ++-- docs/containers/maps/multimap.md | 6 ++-- docs/containers/maps/reference-flat-map.md | 29 +++++++++++++----- .../maps/reference-flat-multimap.md | 29 +++++++++++++----- docs/containers/maps/unordered-map.md | 12 ++++---- docs/containers/maps/unordered-multimap.md | 12 ++++---- docs/containers/queues & stacks/deque.md | 6 ++-- docs/containers/sets/flat-multiset.md | 11 +++---- docs/containers/sets/flat-set.md | 9 +++--- docs/containers/sets/multiset.md | 6 ++-- .../sets/reference-flat-multiset.md | 30 ++++++++++++++++--- docs/containers/sets/reference-flat-set.md | 30 ++++++++++++++++--- docs/containers/sets/set.md | 6 ++-- 17 files changed, 146 insertions(+), 70 deletions(-) diff --git a/docs/containers/arrays/array.md b/docs/containers/arrays/array.md index 1b848dac..fcf8af32 100644 --- a/docs/containers/arrays/array.md +++ b/docs/containers/arrays/array.md @@ -39,7 +39,7 @@ Defines data as an array of 'int', of length '10', containing the supplied data. ```cpp template -constexpr auto make_array(TValues&&... values) +constexpr auto make_array(TValues&&... values) -> etl::array ``` ### Example diff --git a/docs/containers/lists/forward-list.md b/docs/containers/lists/forward-list.md index 2be721e0..442d6b51 100644 --- a/docs/containers/lists/forward-list.md +++ b/docs/containers/lists/forward-list.md @@ -65,13 +65,15 @@ Defines data as an `forward_list` of int, of length 10, containing the supplied ## Make template **C++11 and above** ```cpp -template - constexpr auto make_forward_list(TValues&&... values) +template +constexpr auto make_forward_list(T&&... t) -> etl::forward_list, sizeof...(T)> ``` +The element type is deduced as the common type of the arguments. + ### Example ```cpp -auto data = etl::make_forward_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); +auto data = etl::make_forward_list(0, 1, 2, 3, 4, 5, 6, 7, 8, 9); ``` ## Member types diff --git a/docs/containers/maps/flat-map.md b/docs/containers/maps/flat-map.md index dd1d1850..cc3ea886 100644 --- a/docs/containers/maps/flat-map.md +++ b/docs/containers/maps/flat-map.md @@ -40,13 +40,13 @@ template , typename... TPairs> -constexpr auto make_flat_map(TValues&&... values) +constexpr auto make_flat_map(TPairs&&... pairs) -> etl::flat_map ``` ### Example ```cpp -auto data = etl::make_flat_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); +auto data = etl::make_flat_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); ``` ## Member types diff --git a/docs/containers/maps/flat-multimap.md b/docs/containers/maps/flat-multimap.md index b6f6832d..58bda46b 100644 --- a/docs/containers/maps/flat-multimap.md +++ b/docs/containers/maps/flat-multimap.md @@ -33,20 +33,20 @@ etl::flat_multimap data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, etl: ``` Defines data as an `flat_multimap` of `int`/`int` pairs, of length 4, containing the supplied data. -## make_flat_map +## make_flat_multimap C++11 and above ```cpp template , typename... TPairs> -constexpr auto make_flat_map(TValues&&... values) +constexpr auto make_flat_multimap(TPairs&&... pairs) -> etl::flat_multimap ``` ### Example ```cpp -auto data = etl::make_flat_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); +auto data = etl::make_flat_multimap(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); ``` ## Member types diff --git a/docs/containers/maps/map.md b/docs/containers/maps/map.md index c2c26396..8b747fb8 100644 --- a/docs/containers/maps/map.md +++ b/docs/containers/maps/map.md @@ -38,13 +38,13 @@ template , typename... TPairs> -constexpr auto make_flat_map(TValues&&... values) +constexpr auto make_map(TPairs&&... pairs) -> etl::map ``` ### Example ```cpp -auto data = etl::make_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); +auto data = etl::make_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); ``` ## Member types diff --git a/docs/containers/maps/multimap.md b/docs/containers/maps/multimap.md index 09fda167..67c02108 100644 --- a/docs/containers/maps/multimap.md +++ b/docs/containers/maps/multimap.md @@ -38,13 +38,13 @@ template , typename... TPairs> -constexpr auto make_flat_map(TValues&&... values) +constexpr auto make_multimap(TPairs&&... pairs) -> etl::multimap ``` ### Example ```cpp -auto data = etl::make_multimap(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); +auto data = etl::make_multimap(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); ``` ## Member types diff --git a/docs/containers/maps/reference-flat-map.md b/docs/containers/maps/reference-flat-map.md index 57f7dda1..baa0a013 100644 --- a/docs/containers/maps/reference-flat-map.md +++ b/docs/containers/maps/reference-flat-map.md @@ -36,19 +36,32 @@ etl::reference_flat_map data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4, 5}, Defines data as an reference_flat_map of int, of length 4, containing the supplied data. ## Make template -C++11 and above - +**C++11 and above** ```cpp -template , +template , typename... TPairs> -constexpr auto make_reference_flat_map(TValues&&... values) +constexpr auto make_reference_flat_map(TPairs&&... pairs) -> etl::reference_flat_map ``` ### Example -auto data = etl::make_reference_flat_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); + +{{< callout type="warning" >}} + This example does not currently compile: `make_reference_flat_map` cannot be + instantiated, because the reference containers have no `initializer_list` + constructor for its braced return value to bind to. This is a known defect. +{{< /callout >}} + +```cpp +// The referenced objects must outlive the container. +etl::pair p0{0, 1}; +etl::pair p1{2, 3}; +etl::pair p2{4, 5}; +etl::pair p3{6, 7}; + +auto data = etl::make_reference_flat_map(p0, p1, p2, p3); +``` ## Member types diff --git a/docs/containers/maps/reference-flat-multimap.md b/docs/containers/maps/reference-flat-multimap.md index 9d4ccd64..01bdb556 100644 --- a/docs/containers/maps/reference-flat-multimap.md +++ b/docs/containers/maps/reference-flat-multimap.md @@ -36,19 +36,32 @@ etl::reference_flat_multimap data{ etl::pair{0, 1}, etl::pair{2, 3}, etl::pair{4 Defines data as an reference_flat_multimap of int, of length 4, containing the supplied data. ## Make template -C++11 and above - +**C++11 and above** ```cpp -template , +template , typename... TPairs> -constexpr auto make_reference_flat_map(TValues&&... values) +constexpr auto make_reference_flat_multimap(TPairs&&... pairs) -> etl::reference_flat_multimap ``` ### Example -auto data = etl::make_reference_flat_multimap(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); + +{{< callout type="warning" >}} + This example does not currently compile: `make_reference_flat_multimap` cannot be + instantiated, because the reference containers have no `initializer_list` + constructor for its braced return value to bind to. This is a known defect. +{{< /callout >}} + +```cpp +// The referenced objects must outlive the container. +etl::pair p0{0, 1}; +etl::pair p1{2, 3}; +etl::pair p2{4, 5}; +etl::pair p3{6, 7}; + +auto data = etl::make_reference_flat_multimap(p0, p1, p2, p3); +``` ## Member types diff --git a/docs/containers/maps/unordered-map.md b/docs/containers/maps/unordered-map.md index bf2810ad..ba576cd6 100644 --- a/docs/containers/maps/unordered-map.md +++ b/docs/containers/maps/unordered-map.md @@ -44,17 +44,17 @@ C++11 and above ```cpp template , - typename TKeyEqual = etl::equal_to + typename T, + typename THash = etl::hash, + typename TKeyEqual = etl::equal_to, typename... TPairs> -constexpr auto make_unordered_map(TValues&&... values) +constexpr auto make_unordered_map(TPairs&&... pairs) -> etl::unordered_map ``` ### Example ```cpp -auto data = etl::make_unordered_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); +auto data = etl::make_unordered_map(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); ``` ## Member types diff --git a/docs/containers/maps/unordered-multimap.md b/docs/containers/maps/unordered-multimap.md index 5e50cba3..9622f558 100644 --- a/docs/containers/maps/unordered-multimap.md +++ b/docs/containers/maps/unordered-multimap.md @@ -42,17 +42,17 @@ C++11 and above ```cpp template , - typename TKeyEqual = etl::equal_to + typename T, + typename THash = etl::hash, + typename TKeyEqual = etl::equal_to, typename... TPairs> -constexpr auto make_unordered_map(TValues&&... values) +constexpr auto make_unordered_multimap(TPairs&&... pairs) -> etl::unordered_multimap ``` ### Example ```cpp -auto data = etl::make_unordered_map(etl::pair{0, 1}, etl::pair{2, 3}, - etl::pair{4, 5}, etl::pair{6, 7}); +auto data = etl::make_unordered_multimap(etl::pair{0, 1}, etl::pair{2, 3}, + etl::pair{4, 5}, etl::pair{6, 7}); ``` ## Member types diff --git a/docs/containers/queues & stacks/deque.md b/docs/containers/queues & stacks/deque.md index a4960607..f326e308 100644 --- a/docs/containers/queues & stacks/deque.md +++ b/docs/containers/queues & stacks/deque.md @@ -32,9 +32,11 @@ etl::deque data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 }; Defines data as an `deque` of `int`, of length `10`, containing the supplied data. ## Make template +**C++11 and above** +```cpp template - constexpr auto make_deque(TValues&&... values) - C++11 and above +constexpr auto make_deque(TValues&&... values) -> etl::deque +``` ### Example ```cpp diff --git a/docs/containers/sets/flat-multiset.md b/docs/containers/sets/flat-multiset.md index 890fcd52..d88e4a17 100644 --- a/docs/containers/sets/flat-multiset.md +++ b/docs/containers/sets/flat-multiset.md @@ -33,17 +33,18 @@ etl::flat_multiset data{ 0, 1, 2, 3 }; ``` Defines data as an `flat_multiset` of `int`, of length 4, containing the supplied data. -## make_flat_set +## make_flat_multiset C++11 and above ```cpp -template > -constexpr auto make_flat_set(TValues&&... values) +template , + typename... T> +constexpr auto make_flat_multiset(T&&... keys) -> etl::flat_multiset ``` ### Example ```cpp -auto data = etl::make_flat_set({0, 1, 2, 3 }); +auto data = etl::make_flat_multiset(0, 1, 2, 3); ``` ## Member types diff --git a/docs/containers/sets/flat-set.md b/docs/containers/sets/flat-set.md index 6f9c0540..e5c08610 100644 --- a/docs/containers/sets/flat-set.md +++ b/docs/containers/sets/flat-set.md @@ -36,14 +36,15 @@ Defines data as an `flat_set` of `int`, of length 4, containing the supplied dat ## make_flat_set C++11 and above ```cpp -template > -constexpr auto make_flat_set(TValues&&... values) +template , + typename... T> +constexpr auto make_flat_set(T&&... keys) -> etl::flat_set ``` ### Example ```cpp -auto data = etl::make_flat_set({0, 1, 2, 3 }); +auto data = etl::make_flat_set(0, 1, 2, 3); ``` ## Member types diff --git a/docs/containers/sets/multiset.md b/docs/containers/sets/multiset.md index 9bf091c8..4e3de78f 100644 --- a/docs/containers/sets/multiset.md +++ b/docs/containers/sets/multiset.md @@ -37,13 +37,13 @@ Defines data as an multiset of `int`, of length 8, containing the supplied data. ```cpp template , - typename... TPairs> -constexpr auto make_set(TValues&&... values) + typename... T> +constexpr auto make_multiset(T&&... keys) -> etl::multiset ``` ### Example ```cpp -auto data = etl::make_set(0, 1, 2, 3, 4, 5, 6, 7); +auto data = etl::make_multiset(0, 1, 2, 3, 4, 5, 6, 7); ``` ## Member types diff --git a/docs/containers/sets/reference-flat-multiset.md b/docs/containers/sets/reference-flat-multiset.md index 9e7dd725..9bb622dc 100644 --- a/docs/containers/sets/reference-flat-multiset.md +++ b/docs/containers/sets/reference-flat-multiset.md @@ -32,13 +32,35 @@ etl::reference_flat_setdata{ 0, 1, 2, 3, 4, 5, 6, 7 }; Defines data as a set of int/int pairs, of length 8, containing the supplied data. ## Make template -C++11 and above -template , typename... T> -constexpr auto make_reference_flat_set(T&&... values) +constexpr auto make_reference_flat_multiset(T&&... keys) -> etl::reference_flat_multiset +``` ### Example -auto data = etl::make_reference_flat_set(0, 1, 2, 3, 4, 5, 6, 7); + +{{< callout type="warning" >}} + This example does not currently compile: `make_reference_flat_multiset` cannot be + instantiated, because the reference containers have no `initializer_list` + constructor for its braced return value to bind to. This is a known defect. +{{< /callout >}} + +```cpp +// The referenced objects must outlive the container. +int k0 = 0; +int k1 = 1; +int k2 = 2; +int k3 = 3; +int k4 = 4; +int k5 = 5; +int k6 = 6; +int k7 = 7; + +auto data = etl::make_reference_flat_multiset(k0, k1, k2, k3, k4, k5, k6, k7); +``` ## Member types diff --git a/docs/containers/sets/reference-flat-set.md b/docs/containers/sets/reference-flat-set.md index da2c9dc9..8ff1e296 100644 --- a/docs/containers/sets/reference-flat-set.md +++ b/docs/containers/sets/reference-flat-set.md @@ -32,13 +32,35 @@ etl::reference_flat_setdata{ 0, 1, 2, 3, 4, 5, 6, 7 }; Defines data as a set of int/int pairs, of length 8, containing the supplied data. ## Make template -C++11 and above -template , typename... T> -constexpr auto make_reference_flat_set(T&&... values) +constexpr auto make_reference_flat_set(T&&... keys) -> etl::reference_flat_set +``` ### Example -auto data = etl::make_reference_flat_set(0, 1, 2, 3, 4, 5, 6, 7); + +{{< callout type="warning" >}} + This example does not currently compile: `make_reference_flat_set` cannot be + instantiated, because the reference containers have no `initializer_list` + constructor for its braced return value to bind to. This is a known defect. +{{< /callout >}} + +```cpp +// The referenced objects must outlive the container. +int k0 = 0; +int k1 = 1; +int k2 = 2; +int k3 = 3; +int k4 = 4; +int k5 = 5; +int k6 = 6; +int k7 = 7; + +auto data = etl::make_reference_flat_set(k0, k1, k2, k3, k4, k5, k6, k7); +``` ## Member types diff --git a/docs/containers/sets/set.md b/docs/containers/sets/set.md index cec118bd..b6da157f 100644 --- a/docs/containers/sets/set.md +++ b/docs/containers/sets/set.md @@ -36,9 +36,9 @@ Defines data as an set of `int`, of length 8, containing the supplied data. ```cpp template , - typename... TPairs> -constexpr auto make_set(TValues&&... values) + typename TCompare = etl::less, + typename... T> +constexpr auto make_set(T&&... keys) -> etl::set ``` ### Example