mirror of
https://github.com/ETLCPP/etl.git
synced 2026-10-31 03:16:20 +08:00
25e2d6e8a3
* Adopt the Library Fundamentals TS make_array design for the sequence factories make_array, make_deque, make_vector, make_list, make_forward_list and make_indirect_vector now follow the Library Fundamentals TS std::experimental::make_array design: a defaulted leading template parameter selects the element type explicitly, falling back to the decayed common type of the arguments when it is not supplied. A shared trait (etl::private_make::element_type) performs the selection lazily, so common_type is not instantiated when the element type is explicit. This fixes the explicit-element-type calling style for the four common-type factories, where make_vector<char>(lvalue) never compiled: the explicit argument pinned the first pack parameter to char, making it a char&& that no lvalue can bind to. It also gives make_array and make_deque the deduced form (e.g. make_array(1, 2L) is array<long, 2>) for free. All arguments are converted with static_cast, as in the make_array const-lvalue fix, so const-qualified lvalues and narrowing initialisers work in both forms. Intentional behaviour change: an explicit element type now converts every argument instead of pinning only the first. make_vector<char>(0, 1, ...) previously produced vector<int> - the explicit char affected only the first argument and the element type was still the common type - and now produces vector<char>. test_make_vector documented the old behaviour and has been updated. The keyed set and map factories are unchanged: their key/mapped types are separate mandatory template parameters ahead of a fully-deduced pack, so the explicit-type style already works, and retrofitting deduction there would interact with the defaulted comparator/hash parameters. Adds explicit-element-type tests for the four common-type factories (const/non-const lvalues plus narrowing initialisers) and deduced-element-type tests for make_array and make_deque, and updates the four documented signatures. * Address review comments on the make_xxx factory design - Forward same-type arguments in the make_xxx factories instead of casting them. static_cast produced a prvalue that, before C++17, had to be materialised through the move constructor, rejecting copyable-but-non-movable element types. The new private_make::convert helper forwards arguments that already have the element type and static_casts the rest. - Drop ETL_NOEXCEPT from make_array: conversions can throw, and the other factories do not declare it. - Remove the redundant etl::decay in element_type<void, ...>; etl::common_type already decays its arguments. - Stop leaking the etl::private_make implementation namespace into the documented factory signatures. * Add a test for make_array with an explicit element type and no arguments etl::make_array<int>() produces an empty etl::array<int, 0> and now has a regression test. A call with neither an element type nor arguments remains ill-formed, matching the Library Fundamentals TS: there is nothing to deduce the element type from. The array documentation now states this explicitly. --------- Co-authored-by: John Wellbelove <jwellbelove@users.noreply.github.com> Co-authored-by: Roland Reichwein <Roland.Reichwein@bmw.de>
366 lines
8.1 KiB
Markdown
366 lines
8.1 KiB
Markdown
---
|
|
title: "array"
|
|
weight: 1
|
|
---
|
|
|
|
{{< callout >}}
|
|
Header: `array.h`
|
|
Since: All versions
|
|
Similar to: [std::array](https://en.cppreference.com/w/cpp/container/array.html)
|
|
{{< /callout >}}
|
|
|
|
A fixed capacity array.
|
|
Adds additional members functions, `assign`, `insert` & `erase`.
|
|
|
|
```cpp
|
|
etl::array<typename T, const size_t SIZE>
|
|
```
|
|
|
|
See also:
|
|
[array_view]({{< relref "array-view" >}})
|
|
[multi_array]({{< relref "multi-array" >}})
|
|
|
|
## Template deduction guides
|
|
**C++17 and above**
|
|
|
|
```cpp
|
|
template <typename... T>
|
|
etl::array(T...)
|
|
```
|
|
|
|
### Example
|
|
```cpp
|
|
etl::array data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
|
|
```
|
|
Defines data as an array of 'int', of length '10', containing the supplied data.
|
|
|
|
## Make template
|
|
**C++11 and above**
|
|
|
|
```cpp
|
|
template <typename T = void, typename... TValues>
|
|
constexpr auto make_array(TValues&&... values) -> etl::array</*element-type*/, sizeof...(TValues)>
|
|
```
|
|
|
|
The element type is `T` when supplied, otherwise the decayed common type of
|
|
the arguments (the Library Fundamentals TS `make_array` design). An empty
|
|
array requires the element type to be supplied explicitly, e.g.
|
|
`etl::make_array<int>()`; a call with neither an element type nor arguments
|
|
is ill-formed, as there is nothing to deduce the element type from.
|
|
|
|
### Example
|
|
```cpp
|
|
// Deduced element type: etl::array<int, 10>.
|
|
auto data = etl::make_array(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
|
|
|
|
// Explicit element type: etl::array<char, 10>. Each argument is converted.
|
|
auto chars = etl::make_array<char>(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
|
|
```
|
|
|
|
## Member types
|
|
|
|
`value_type`
|
|
`size_type`
|
|
`difference_type`
|
|
`reference`
|
|
`const_reference`
|
|
`pointer`
|
|
`const_pointer`
|
|
`iterator`
|
|
`const_iterator`
|
|
`reverse_iterator`
|
|
`const_reverse_iterator`
|
|
|
|
`etl::array` iterators are random access.
|
|
|
|
## Static Constants
|
|
|
|
```cpp
|
|
SIZE
|
|
```
|
|
**Description**
|
|
The size of the array.
|
|
|
|
## Constructor
|
|
|
|
```cpp
|
|
etl::array<int, 10> data = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
|
|
```
|
|
**Description**
|
|
Default or copy constructs each element.
|
|
Can be initialised like a C array.
|
|
|
|
## Element access
|
|
```cpp
|
|
T& at(size_t i)
|
|
const T& at(size_t i) const
|
|
```
|
|
**Description**
|
|
Returns a reference or const reference to the indexed element. Emits an etl::array_out_of_range if the index is not in range.
|
|
If asserts or exceptions are not enabled then an out of range index results in undefined behaviour.
|
|
|
|
---
|
|
|
|
```cpp
|
|
T& operator[](size_t i)
|
|
const T& operator[](size_t i) const
|
|
```
|
|
**Description**
|
|
Returns a reference or const reference to the indexed element.
|
|
An out of range index results in undefined behaviour.
|
|
|
|
---
|
|
|
|
```cpp
|
|
T& front()
|
|
const T& front() const
|
|
```
|
|
**Description**
|
|
Returns a reference or const reference to the first element.
|
|
|
|
---
|
|
|
|
```cpp
|
|
T& back()
|
|
const T& back() const
|
|
```
|
|
**Description**
|
|
Returns a reference or const reference to the last element.
|
|
|
|
## Iterators
|
|
|
|
```cpp
|
|
iterator begin()
|
|
const_iterator begin() const
|
|
const_iterator cbegin() const
|
|
```
|
|
**Description**
|
|
Returns an iterator to the beginning of the array.
|
|
|
|
---
|
|
|
|
```cpp
|
|
iterator end()
|
|
const_iterator end() const
|
|
const_iterator cend() const
|
|
```
|
|
**Description**
|
|
Returns an iterator to the end of the array.
|
|
|
|
---
|
|
|
|
```cpp
|
|
iterator rbegin()
|
|
const_iterator rbegin() const
|
|
const_iterator crbegin() const
|
|
```
|
|
**Description**
|
|
Returns a reverse iterator to the beginning of the array.
|
|
|
|
---
|
|
|
|
```cpp
|
|
iterator rend()
|
|
const_iterator rend() const
|
|
const_iterator crend() const
|
|
```
|
|
**Description**
|
|
Returns a reverse iterator to the end of the array.
|
|
|
|
## Capacity
|
|
|
|
```cpp
|
|
bool empty() const
|
|
```
|
|
**Description**
|
|
Returns true if the size of the array is zero, otherwise false.
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t size() const
|
|
```
|
|
**Description**
|
|
Returns the size of the array.
|
|
|
|
---
|
|
|
|
```cpp
|
|
size_t max_size() const
|
|
```
|
|
**Description**
|
|
Returns the maximum possible size of the array.
|
|
|
|
## Modifiers
|
|
|
|
```cpp
|
|
void fill(T value)
|
|
```
|
|
**Description**
|
|
Fills the array with value.
|
|
|
|
## ETL Extensions
|
|
|
|
```cpp
|
|
template <typename TIterator>
|
|
void assign(TIterator first, const TIterator last)
|
|
```
|
|
|
|
```cpp
|
|
template <typename TIterator>
|
|
void assign(TIterator first, const TIterator last, parameter_t value)
|
|
```
|
|
|
|
**Description**
|
|
Assigns a range of values to the array. The second form set uninitialised elements to value.
|
|
If the range is larger than the array then the extra data is ignored.
|
|
If the range is smaller than the array then the unused array elements are left unmodified.
|
|
|
|
---
|
|
|
|
```cpp
|
|
iterator insert_at(size_t position, parameter_t value)
|
|
iterator insert(const_iterator position, parameter_t value)
|
|
```
|
|
|
|
**Description**
|
|
Inserts a value into the array at the specified position, shifting elements to make room.
|
|
Elements may be truncated if they are shifted off the end of the array.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename TIterator>
|
|
iterator insert_at(size_t position, TIterator first, const TIterator last)
|
|
```
|
|
|
|
**Description**
|
|
`position` is not checked for validity.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <typename TIterator>
|
|
iterator insert(const_iterator position, TIterator first, const TIterator last)
|
|
```
|
|
|
|
**Description**
|
|
Inserts a range of values into the array at the specified position, shifting elements to make room.
|
|
Elements may be truncated if they are shifted off the end of the array.
|
|
The range may be larger than the capacity of the array. Excess elements will be ignored.
|
|
|
|
---
|
|
|
|
```cpp
|
|
iterator erase_at(size_t position)
|
|
iterator erase_at(size_t position, parameter_t value)
|
|
iterator erase(const_iterator position)
|
|
iterator erase(const_iterator position, parameter_t value)
|
|
```
|
|
|
|
**Description**
|
|
Erases an element at the specified position, shifting elements into the space.
|
|
The value parameter variants initialise the unused elements with value, while the others leave them unchanged.
|
|
position is not checked for valid range.
|
|
|
|
---
|
|
|
|
```cpp
|
|
iterator erase_range(size_t first, size_t last)
|
|
iterator erase_range(size_t first, size_t last, parameter_t value)
|
|
iterator erase(const_iterator first, const_iterator last)
|
|
iterator erase(const_iterator first, const_iterator last, parameter_t value)
|
|
```
|
|
|
|
**Description**
|
|
Erases a range, shifting elements into the space.
|
|
The value parameter variants initialise the unused elements with value, while the others leave them unchanged.
|
|
first/last are not checked for valid range.
|
|
|
|
## Non-member functions
|
|
**Lexicographically comparisons**
|
|
```cpp
|
|
operator ==
|
|
```
|
|
**Description**
|
|
`true` if the contents of the lists are equal, otherwise `false`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
operator !=
|
|
```
|
|
**Description**
|
|
`true` if the contents of the lists are not equal, otherwise `false`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
operator <
|
|
```
|
|
**Description**
|
|
`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
operator <=
|
|
```
|
|
**Description**
|
|
`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
operator >
|
|
```
|
|
**Description**
|
|
`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
operator >=
|
|
```
|
|
**Description**
|
|
`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`.
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <size_t Index, typename T, size_t Size>
|
|
T& get(etl::array<T, Size>& a)
|
|
|
|
template <size_t Index, typename T, size_t Size>
|
|
const T& get(const etl::array<T, Size>& a)
|
|
```
|
|
**Description**
|
|
Gets a reference to the element at `Index` in the array.
|
|
|
|
## Structured bindings
|
|
`etl::array` provides the tuple-like interface required for C++17 structured bindings.
|
|
|
|
```cpp
|
|
etl::array<int, 3> a = { 1, 2, 3 };
|
|
|
|
auto& [x, y, z] = a; // x, y, z are references to a[0], a[1], a[2]
|
|
```
|
|
|
|
```cpp
|
|
template <typename T, size_t Size>
|
|
struct tuple_size<etl::array<T, Size>>
|
|
```
|
|
**Description**
|
|
Gets the number of elements in the array.
|
|
Specialised in namespaces `etl` and `std` (the `std` specialisation allows the use of C++ structured bindings).
|
|
|
|
---
|
|
|
|
```cpp
|
|
template <size_t Index, typename T, size_t Size>
|
|
struct tuple_element<Index, etl::array<T, Size>>
|
|
```
|
|
**Description**
|
|
Gets the type of the element at `Index` in the array.
|
|
Specialised in namespaces `etl` and `std` (the `std` specialisation allows the use of C++ structured bindings).
|