coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-10-28 18:07:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

Correct the documented make_xxx factory signatures and examples (#1530)

Browse Source 
* 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 <jwellbelove@users.noreply.github.com>
This commit is contained in:
rleigh-electradx 2026-08-04 11:45:49 +01:00 committed by GitHub
parent 62925ec1ad
commit c8bc1bd896
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
17 changed files with 146 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/containers/arrays/array.md
View File

@ -39,7 +39,7 @@ Defines data as an array of 'int', of length '10', containing the supplied data.
```cpp
template <typename T, typename... TValues>
constexpr auto make_array(TValues&&... values)
constexpr auto make_array(TValues&&... values) -> etl::array<T, sizeof...(TValues)>
```
### Example

8
docs/containers/lists/forward-list.md
View File

@ -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 <typename T, typename... TValues>
constexpr auto make_forward_list(TValues&&... values)
template <typename... T>
constexpr auto make_forward_list(T&&... t) -> etl::forward_list<typename etl::common_type_t<T...>, sizeof...(T)>
```
The element type is deduced as the common type of the arguments.
### Example
```cpp
auto data = etl::make_forward_list<int>(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

6
docs/containers/maps/flat-map.md
View File

@ -40,13 +40,13 @@ template <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_flat_map(TValues&&... values)
constexpr auto make_flat_map(TPairs&&... pairs) -> etl::flat_map<TKey, TMapped, sizeof...(TPairs), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_flat_map<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
etl::pair{4, 5}, etl::pair{6, 7});
auto data = etl::make_flat_map<int, int>(etl::pair<int, int>{0, 1}, etl::pair<int, int>{2, 3},
etl::pair<int, int>{4, 5}, etl::pair<int, int>{6, 7});
```
## Member types

8
docs/containers/maps/flat-multimap.md
View File

@ -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 TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_flat_map(TValues&&... values)
constexpr auto make_flat_multimap(TPairs&&... pairs) -> etl::flat_multimap<TKey, TMapped, sizeof...(TPairs), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_flat_map<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
etl::pair{4, 5}, etl::pair{6, 7});
auto data = etl::make_flat_multimap<int, int>(etl::pair<int, int>{0, 1}, etl::pair<int, int>{2, 3},
etl::pair<int, int>{4, 5}, etl::pair<int, int>{6, 7});
```
## Member types

6
docs/containers/maps/map.md
View File

@ -38,13 +38,13 @@ template <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_flat_map(TValues&&... values)
constexpr auto make_map(TPairs&&... pairs) -> etl::map<TKey, TMapped, sizeof...(TPairs), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_map<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
etl::pair{4, 5}, etl::pair{6, 7});
auto data = etl::make_map<int, int>(etl::pair<int, int>{0, 1}, etl::pair<int, int>{2, 3},
etl::pair<int, int>{4, 5}, etl::pair<int, int>{6, 7});
```
## Member types

6
docs/containers/maps/multimap.md
View File

@ -38,13 +38,13 @@ template <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_flat_map(TValues&&... values)
constexpr auto make_multimap(TPairs&&... pairs) -> etl::multimap<TKey, TMapped, sizeof...(TPairs), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_multimap<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
etl::pair{4, 5}, etl::pair{6, 7});
auto data = etl::make_multimap<int, int>(etl::pair<int, int>{0, 1}, etl::pair<int, int>{2, 3},
etl::pair<int, int>{4, 5}, etl::pair<int, int>{6, 7});
```
## Member types

29
docs/containers/maps/reference-flat-map.md
View File

@ -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 <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
template <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_reference_flat_map(TValues&&... values)
constexpr auto make_reference_flat_map(TPairs&&... pairs) -> etl::reference_flat_map<TKey, TMapped, sizeof...(TPairs), TKeyCompare>
```
### Example
auto data = etl::make_reference_flat_map<int, int>(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<int, int> p0{0, 1};
etl::pair<int, int> p1{2, 3};
etl::pair<int, int> p2{4, 5};
etl::pair<int, int> p3{6, 7};
auto data = etl::make_reference_flat_map<int, int>(p0, p1, p2, p3);
```
## Member types

29
docs/containers/maps/reference-flat-multimap.md
View File

@ -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 <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
template <typename TKey,
typename TMapped,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_reference_flat_map(TValues&&... values)
constexpr auto make_reference_flat_multimap(TPairs&&... pairs) -> etl::reference_flat_multimap<TKey, TMapped, sizeof...(TPairs), TKeyCompare>
```
### Example
auto data = etl::make_reference_flat_multimap<int, int>(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<int, int> p0{0, 1};
etl::pair<int, int> p1{2, 3};
etl::pair<int, int> p2{4, 5};
etl::pair<int, int> p3{6, 7};
auto data = etl::make_reference_flat_multimap<int, int>(p0, p1, p2, p3);
```
## Member types

12
docs/containers/maps/unordered-map.md
View File

@ -44,17 +44,17 @@ C++11 and above
```cpp
template <typename TKey,
typename TValue,
typename THash = etl::hash<TKey>,
typename TKeyEqual = etl::equal_to<TKey>
typename T,
typename THash = etl::hash<TKey>,
typename TKeyEqual = etl::equal_to<TKey>,
typename... TPairs>
constexpr auto make_unordered_map(TValues&&... values)
constexpr auto make_unordered_map(TPairs&&... pairs) -> etl::unordered_map<TKey, T, sizeof...(TPairs), sizeof...(TPairs), THash, TKeyEqual>
```
### Example
```cpp
auto data = etl::make_unordered_map<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
etl::pair{4, 5}, etl::pair{6, 7});
auto data = etl::make_unordered_map<int, int>(etl::pair<int, int>{0, 1}, etl::pair<int, int>{2, 3},
etl::pair<int, int>{4, 5}, etl::pair<int, int>{6, 7});
```
## Member types

12
docs/containers/maps/unordered-multimap.md
View File

@ -42,17 +42,17 @@ C++11 and above
```cpp
template <typename TKey,
typename TValue,
typename THash = etl::hash<TKey>,
typename TKeyEqual = etl::equal_to<TKey>
typename T,
typename THash = etl::hash<TKey>,
typename TKeyEqual = etl::equal_to<TKey>,
typename... TPairs>
constexpr auto make_unordered_map(TValues&&... values)
constexpr auto make_unordered_multimap(TPairs&&... pairs) -> etl::unordered_multimap<TKey, T, sizeof...(TPairs), sizeof...(TPairs), THash, TKeyEqual>
```
### Example
```cpp
auto data = etl::make_unordered_map<int, int>(etl::pair{0, 1}, etl::pair{2, 3},
etl::pair{4, 5}, etl::pair{6, 7});
auto data = etl::make_unordered_multimap<int, int>(etl::pair<int, int>{0, 1}, etl::pair<int, int>{2, 3},
etl::pair<int, int>{4, 5}, etl::pair<int, int>{6, 7});
```
## Member types

6
docs/containers/queues & stacks/deque.md
View File

@ -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 <typename T, typename... TValues>
constexpr auto make_deque(TValues&&... values)
C++11 and above
constexpr auto make_deque(TValues&&... values) -> etl::deque<T, sizeof...(TValues)>
```
### Example
```cpp

11
docs/containers/sets/flat-multiset.md
View File

@ -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 <typename T,
typename TKeyCompare = etl::less<T>>
constexpr auto make_flat_set(TValues&&... values)
template <typename TKey,
typename TKeyCompare = etl::less<TKey>,
typename... T>
constexpr auto make_flat_multiset(T&&... keys) -> etl::flat_multiset<TKey, sizeof...(T), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_flat_set<int>({0, 1, 2, 3 });
auto data = etl::make_flat_multiset<int>(0, 1, 2, 3);
```
## Member types

9
docs/containers/sets/flat-set.md
View File

@ -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 <typename T,
typename TKeyCompare = etl::less<T>>
constexpr auto make_flat_set(TValues&&... values)
template <typename TKey,
typename TKeyCompare = etl::less<TKey>,
typename... T>
constexpr auto make_flat_set(T&&... keys) -> etl::flat_set<TKey, sizeof...(T), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_flat_set<int>({0, 1, 2, 3 });
auto data = etl::make_flat_set<int>(0, 1, 2, 3);
```
## Member types

6
docs/containers/sets/multiset.md
View File

@ -37,13 +37,13 @@ Defines data as an multiset of `int`, of length 8, containing the supplied data.
```cpp
template <typename TKey,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_set(TValues&&... values)
typename... T>
constexpr auto make_multiset(T&&... keys) -> etl::multiset<TKey, sizeof...(T), TKeyCompare>
```
### Example
```cpp
auto data = etl::make_set<int>(0, 1, 2, 3, 4, 5, 6, 7);
auto data = etl::make_multiset<int>(0, 1, 2, 3, 4, 5, 6, 7);
```
## Member types

30
docs/containers/sets/reference-flat-multiset.md
View File

@ -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 TKey
**C++11 and above**
```cpp
template <typename TKey,
typename TKeyCompare = etl::less<TKey>,
typename... T>
constexpr auto make_reference_flat_set(T&&... values)
constexpr auto make_reference_flat_multiset(T&&... keys) -> etl::reference_flat_multiset<TKey, sizeof...(T), TKeyCompare>
```
### Example
auto data = etl::make_reference_flat_set<int>(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<int>(k0, k1, k2, k3, k4, k5, k6, k7);
```
## Member types

30
docs/containers/sets/reference-flat-set.md
View File

@ -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 TKey
**C++11 and above**
```cpp
template <typename TKey,
typename TKeyCompare = etl::less<TKey>,
typename... T>
constexpr auto make_reference_flat_set(T&&... values)
constexpr auto make_reference_flat_set(T&&... keys) -> etl::reference_flat_set<TKey, sizeof...(T), TKeyCompare>
```
### Example
auto data = etl::make_reference_flat_set<int>(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<int>(k0, k1, k2, k3, k4, k5, k6, k7);
```
## Member types

6
docs/containers/sets/set.md
View File

@ -36,9 +36,9 @@ Defines data as an set of `int`, of length 8, containing the supplied data.
```cpp
template <typename TKey,
typename TKeyCompare = etl::less<TKey>,
typename... TPairs>
constexpr auto make_set(TValues&&... values)
typename TCompare = etl::less<TKey>,
typename... T>
constexpr auto make_set(T&&... keys) -> etl::set<TKey, sizeof...(T), TCompare>
```
### Example