coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-06-15 08:26:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

More documentation updates

Browse Source
This commit is contained in:
John Wellbelove 2026-05-12 11:07:03 +01:00
parent d69acc57b8
commit 0d709324bd
13 changed files with 2073 additions and 1000 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

572
docs/containers/deque.md Normal file
View File

@ -0,0 +1,572 @@
---
title: "deque"
---
{{< callout >}}
Header: `deque.h`
Similar to: [std::deque](https://en.cppreference.com/w/cpp/container/deque.html)
{{< /callout >}}
A fixed capacity deque.
```cpp
etl::deque<typename T, const size_t SIZE>
```
Inherits from `etl::ideque<T>`.
`etl::ideque` may be used as a size independent pointer or reference type for any `etl::deque` instance.
Has the ability to be copied by low level functions such as `memcpy` by use of a `repair()` function.
## Template deduction guides
```cpp
template <typename... T>
etl::deque(T...)
```
C++17 and above.
### Example
```cpp
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
template <typename T, typename... TValues>
constexpr auto make_deque(TValues&&... values)
C++11 and above
### Example
```cpp
auto data = etl::make_deque<int>(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
```
## Member types
```cpp
value_type T
size_type std::size_t
difference_type std::ptrdiff_t
reference value_type&
const_reference const value_type&
rvalue_reference value_type&&
pointer value_type*
const_pointer const value_type*
iterator Random access iterator
const_iterator Constant random access iterator
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator std::reverse_iterator<const_iterator>
```
## Static Constants
`MAX_SIZE` The maximum size of the `deque`.
## Constructor
```cpp
etl::deque<typename T, const size_t SIZE>()
etl::deque<typename T, const size_t SIZE>(size_t initialSize)
etl::deque<typename T, const size_t SIZE>(size_t initialSize, parameter_t value)
template <typename TIterator>
etl::deque<typename T, const size_t SIZE>(TIterator begin, TIterator end)
etl::deque<typename T, const size_t SIZE>(const etl::deque<typename T, const size_t SIZE>& other)
etl::deque<typename T, const size_t SIZE>(etl::deque<typename T, const size_t SIZE>&& other)
```cpp
## 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::deque_out_of_range` if the index is out of range of the array. Undefined behaviour if asserts or exceptions are not enabled.
---
```cpp
T& operator[](size_t i)
const T& operator[](size_t i) const
```
**Description**
Returns a reference or const reference to the indexed element.
---
T& front()
const T& front() const
**Description**
Returns a reference or const reference to the first element.
---
T& back()
const T& back() const
**Description**
Returns a reference or const reference to the last element.
---
void fill(value_type value)
**Description**
Fill the current size of the buffer with `value`.
Since: `20.24.0`
## Iterators
```cpp
iterator begin()
const_iterator begin() const
const_iterator cbegin() const
```
**Description**
Returns an iterator to the beginning of the `deque`.
---
```cpp
iterator end()
const_iterator end() const
const_iterator cend() const
```
**Description**
Returns an iterator to the end of the deque.
---
```cpp
reverse_iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const
```
**Description**
Returns a reverse iterator to the beginning of the deque.
---
```cpp
iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const
```
**Description**
Returns a reverse iterator to the end of the deque.
## Capacity
```cpp
bool empty() const
```
**Description**
Returns `true` if the size of the deque is zero, otherwise `false`.
---
```cpp
bool full() const
```
**Description**
Returns `true` if the size of the deque is `SIZE`, otherwise `false`.
---
```cpp
size_t size() const
```
**Description**
Returns the size of the deque.
---
```cpp
void resize(size_t new_size, T value = T())
```
**Description**
Resizes the deque, up to the maximum capacity.
Emits an `etl::deque_full` if the deque does not have the capacity.
---
```cpp
size_t max_size() const
```
**Description**
Returns the maximum possible size of the deque.
---
```cpp
size_t capacity() const
```
**Description**
Returns the maximum possible size of the deque.
---
```cpp
size_t available() const
```
**Description**
Returns the remaining available capacity in the deque.
## Modifiers
```cpp
template <typename TIterator>
void assign(TIterator begin, TIterator end)
```
**Description**
Fills the deque with the range.
The range is not checked for validity.
---
```cpp
void assign(size_t n, const_reference value)
```
**Description**
Fills the deque with the values.
Emits etl::deque_iterator if the distance between begin and end is illegal, otherwise undefined behaviour if asserts or exceptions are not enabled.
---
```cpp
void push_front(const_reference value)
void push_front(rvalue_reference value)
```
**Description**
Pushes a value to the front of the deque.
If the deque is full and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::deque_full`, otherwise undefined behaviour if asserts or exceptions are not enabled.
---
```cpp
void push_back(const_reference value)
void push_back(rvalue_reference value)
```
**Description**
Pushes a value to the back of the deque.
If the deque is full and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::deque_full`, otherwise undefined behaviour if asserts or exceptions are not enabled.
---
```cpp
void pop_front()
```
**Description**
Pop a value from the front of the deque.
If the deque is empty and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::deque_empty`, otherwise undefined behaviour if asserts or exceptions are not enabled.
---
```cpp
void pop_back()
```
**Description**
Pop a value from the back of the deque.
If the deque is empty and `ETL_CHECK_PUSH_POP` is defined then emits an `etl::deque_empty`, otherwise undefined behaviour if asserts or exceptions are not enabled.
---
```cpp
void insert(iterator position, size_t n, parameter_t value)
```
---
```cpp
template <typename TIterator>
void insert(iterator position, TIterator begin, TIterator end)
iterator insert(iterator position, parameter_t value)
iterator insert(iterator position, rvalue_reference value)
```
Before: `20.20.0`
---
```cpp
template <typename TIterator>
iterator insert(const_iterator position, TIterator begin, TIterator end)
iterator insert(const_iterator position, parameter_t value)
iterator insert(const_iterator position, rvalue_reference value)
```
**Description**
Inserts values in to the deque. If the deque is full then emits an `etl::deque_full exception`.
Undefined behaviour if asserts or exceptions are not enabled.
Since: `20.20.0`
---
```cpp
template <typename TIterator>
iterator erase(TIterator begin, TIterator end)
```
```cpp
iterator erase(iterator position)
```
Before: `20.20.0`
---
```cpp
iterator erase(iterator position)
iterator erase(const_iterator position)
```
**Description**
Erases values in the deque.
Undefined behaviour if asserts or exceptions are not enabled and begin, end or position are invalid.
Since: `20.20.0`
---
C++03
Before: `20.20.0`
```cpp
template <typename T1>
iterator emplace(iterator insert_position, const T1& value1)
template <typename T1, typename T2>
iterator emplace(iterator insert_position, const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
iterator emplace(iterator insert_position, const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
iterator emplace(iterator insert_position, const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
```
---
```cpp
template <typename ... Args>
iterator emplace(iterator insert_position, Args&& ... args)
```
---
C++03
Since: `20.20.0`
```cpp
template <typename T1>
iterator emplace(const_iterator insert_position, const T1& value1)
template <typename T1, typename T2>
iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
```
---
C++11 and above
```cpp
template <typename ... Args>
iterator emplace(const_iterator insert_position, Args&& ... args)
```
---
C++03
Before: `20.35.8`
```cpp
template <typename T1>
void emplace_front(const T1& value1)
template <typename T1, typename T2>
void emplace_front(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
void emplace_front(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
void emplace_front(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
```
---
C++11 and above
```cpp
template <typename ... Args>
void emplace_front(Args&& ... args)
```
---
C++03
Since `20.35.10`
```cpp
template <typename T1>
reference emplace_front(const T1& value1)
template <typename T1, typename T2>
reference emplace_front(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
reference emplace_front(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
reference emplace_front(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
```
---
C++11 and above
```cpp
template <typename ... Args>
reference emplace_front(Args&& ... args)
```
---
C++03
Before: 20.35.8
```cpp
template <typename T1>
void emplace_back(const T1& value1)
template <typename T1, typename T2>
void emplace_back(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
void emplace_back(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
void emplace_back(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
```
---
C++11 and above
```cpp
template <typename ... Args>
void emplace_back(Args&& ... args)
```
---
C++03
Since: 20.35.10
```cpp
template <typename T1>
reference emplace_back(const T1& value1)
template <typename T1, typename T2>
reference emplace_back(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
reference emplace_back(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
reference emplace_back(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
```
---
C++11 and above
```cpp
template <typename ... Args>
reference emplace_back(Args&& ... args)
```
---
```cpp
void clear()
```
**Description**
Clears the deque to a size of zero.
---
```cpp
void repair()
```
**Description**
This function must be called if the deque has been copied via a low level method such as `memcpy`.
This can only be called from an `etl::deque` instance, unless `ETL_IDEQUE_REPAIR_ENABLE` is defined. Be aware that doing this introduces a virtual function to the class.
Has no effect if the object has not been copied in this way.
**Note:**
The contained type must be trivially copyable.
Compilers that satisfy the C++11 type traits support check in `platform.h` will generate an assert if the type is incompatible.
### Example
```cpp
typedef etl::deque<int, 10> Data;
Data data(8, 1);
char buffer[sizeof(Data)];
memcpy(&buffer, &data, sizeof(Data));
Data& rdata(*reinterpret_cast<Data*>(buffer));
// Do not access the copied object in any way until you have called this.
rdata.repair();
```
---
```cpp
etl::deque<typename T, const size_t SIZE>&
operator =(const etl::deque<typename T, const size_t SIZE>& other)
etl::deque<typename T, const size_t SIZE>&
operator =(etl::deque<typename T, const size_t SIZE>&& other)
etl::ideque<typename T>&
operator =(const etl::ideque<typename T>& other)
etl::deque<typename T>&
operator =(etl::deque<typename T>&& other)
```
## Non-member functions
- `==`
`true` if the contents of the vectors are equal, otherwise `false`.
- `!=`
`true` if the contents of the vectors are not equal, otherwise `false`.
-
`<`
`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`.
-
`<=`
`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`.
- `>`
`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`.
- `>=`
`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`.

73
docs/containers/packet.md Normal file
View File

@ -0,0 +1,73 @@
---
title: "packet"
---
A homogeneous container that can contain one of several types that are all inherited from the same base class.
```cpp
etl::packet<typename TBase, size_t SIZE, size_t ALIGNMENT>
```
## Template parameters
`TBase`
&emsp;The base class for all objects. The destructor must be virtual.
`SIZE`
&emsp;The size of the largest type.
`ALIGNMENT`
&emsp;The largest alignment of all of the types.
## Member types
`base_t` = `TBase`
## Contructors
**C++03**
```cpp
template <typename T>
explicit packet(const T& value)
```
**C++11**
```cpp
template <typename T>
explicit packet(T&& value)
```
**Description**
Constructs an object of type `T` with the supplied value.
Static asserts on any type that does not derive from `TBase`.
Static asserts on any type that does not conform to the maximum size and alignment.
## Destructor
```cpp
~packet()
```
**Description**
Destructs the contained object
## Operators
**C++03**
```cpp
template <typename T>
packet& operator =(const T& value)
```
**C++11**
```cpp
template <typename T>
packet& operator =(T&& value)
```
**Description**
Assigns a new object to the packet.
The previous object is destructed.
## Access
```cpp
const TBase& get() const
```
**Description**
Returns a const reference to the contained object.

6
docs/containers/queues/_index.md Normal file
View File

@ -0,0 +1,6 @@
---
title: "Queues"
weight: 100
---
Queue like containers.

292
docs/containers/queues/circular-buffer.md Normal file
View File

@ -0,0 +1,292 @@
---
title: "circular_buffer"
---
{{< callout >}}
Header: `circular_buffer.h`
{{< /callout >}}
A fixed capacity circular buffer.
```cpp
etl::circular_buffer<typename T, size_t SIZE>
etl::circular_buffer_ext<typename T>
```
Inherits from `etl::icircular_buffer<T>`
`etl::icircular_buffer` may be used as a size independent pointer or reference type for any `etl::circular_buffer` instance.
## External buffer
```cpp
etl::circular_buffer_ext<typename T>
```
For this template the constructor expects pointer and size parameters to the externally provided buffer. This buffer must not be shared concurrently with any other container.
When a `circular_buffer` with an external buffer is moved, the data is moved, not the pointer to the buffer.
The external buffer MUST be declared one item larger that the intended capacity of the circular buffer.
A swap on a `circular_buffer` with an external buffer is fast as it will swap buffer pointers rather than copying items.
## Template deduction guides
```cpp
template <typename T, typename... Ts>
etl::circular_buffer(T, Ts...)
-> etl::circular_buffer<T, 1U + sizeof...(Ts)>;
```
C++17 and above.
Only enabled if `Ts...` is the same type as `T`.
### Example
```cpp
etl::circular_buffer data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
```
Defines data as a `circular_buffer` of `int`, of length `10`, containing the supplied data.
## Member types
```cpp
value_type T
size_type std::size_t
difference_type std::ptrdiff_t
reference value_type&
const_reference const value_type&
rvalue_reference value_type&&
pointer value_type*
const_pointer const value_type*
iterator Random access iterator
const_iterator Constant random access iterator
reverse_iterator reverse_iterator<iterator>
const_reverse_iterator reverse_iterator<const_iterator>
```
## Static Constants
`MAX_SIZE` The maximum size of the circular_buffer.
## Constructors
```cpp
circular_buffer<typename T, size_t SIZE>();
circular_buffer<typename T, size_t SIZE>(const etl::circular_buffer<typename T, size_t SIZE>& other);
circular_buffer<typename T, size_t SIZE>(etl::circular_buffer<typename T, size_t SIZE>&& other);
```
---
```cpp
circular_buffer_ext(void* buffer, size_t max_size)
circular_buffer_ext(size_t max_size) 20.32.1
template <typename TIterator>
circular_buffer_ext(TIterator first, const TIterator& last, void* buffer, size_t max_size)
circular_buffer_ext(std::initializer_list<T> init, void* buffer, size_t max_size)
circular_buffer_ext(const circular_buffer_ext& other, void* buffer, size_t max_size)
```
## Status
```cpp
bool is_valid() const
```
**Description**
Returns `true` if the buffer has been set through the constructor or `set_buffer`.
For circular_buffer_ext only.
Since: `20.32.1`
## Element access
```cpp
reference operator[](size_t i)
const_reference operator[](size_t i) const
```
**Description**
Returns a reference or const reference to the indexed element.
---
```cpp
reference front()
const_reference front() const
```
**Description**
Returns a reference or const reference to the first element.
---
```cpp
reference back()
const_reference back() const
```
**Description**
Returns a reference or const reference to the last element.
---
```cpp
void fill(value_type value)
```
**Description**
Fill the current size of the buffer with `value`.
Since: `20.24.0`
## Iterators
```cpp
iterator begin()
const_iterator begin() const
const_iterator cbegin() const
```
**Description**
Returns an iterator to the beginning of the `circular_buffer`.
---
```cpp
iterator end()
const_iterator end() const
const_iterator cend() const
```
**Description**
Returns an iterator to the end of the `circular_buffer`.
---
```cpp
iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const
```
**Description**
Returns a reverse iterator to the beginning of the `circular_buffer`.
---
```cpp
iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const
```
**Description**
Returns a reverse iterator to the end of the `circular_buffer`.
## Capacity
```cpp
bool empty() const
```
**Description**
Returns `true` if the size of the circular_buffer is zero, otherwise `false`.
---
```cpp
bool full() const
```
**Description**
Returns `true` if the size of the circular_buffer is `SIZE`, otherwise `false`.
---
```cpp
size_t size() const
```
**Description**
Returns the size of the `circular_buffer`.
---
```cpp
size_t max_size() const
```
**Description**
Returns the maximum possible size of the `circular_buffer`.
---
```cpp
size_t capacity() const
```
**Description**
Returns the maximum possible size of the `circular_buffer`.
---
```cpp
size_t available() const
```
**Description**
Returns the remaining available capacity in the `circular_buffer`.
## Modifiers
```cpp
void set_buffer(void* buffer)
```
**Description**
Sets the associated buffer.
For circular_buffer_ext only.
Since: `20.32.1`
---
```cpp
void push(const_reference value)
void push(rvalue_reference value)
```
**Description**
Pushes a value to the back of the `circular_buffer`.
---
```cpp
template <typename TIterator>
void push(TIterator first, const TIterator& last)
```
**Description**
Pushes values to the back of the `circular_buffer`.
---
```cpp
void pop()
```
**Description**
Pop a value from the front of the `circular_buffer`.
---
```cpp
void clear()
```
**Description**
Clears the circular_buffer to a size of zero.
---
```cpp
void swap(circular_buffer<T, SIZE>& other)
```
**Description**
Swaps the `circular_buffer` with `other`.
---
```cpp
void swap(circular_buffer_ext<T> other)
```
**Description**
Swaps the `circular_buffer_ext` with `other`.
The internal pointers to the external buffers are swapped.
## Non-member functions
`==` `true` if the contents of the vectors are equal, otherwise `false`.
`!=` `true` if the contents of the vectors are not equal, otherwise `false`.
`swap` Swaps two circular buffers. A circular buffer with internal storage copies items, while one with an external buffer will swap pointers.

435
docs/containers/vector.md
View File

@ -4,7 +4,438 @@ title: "vector"
{{< callout >}}
Header: `vector.h`
Since: All versions
Similar to: [std::vectr](https://en.cppreference.com/w/cpp/container/vector.html)
Similar to: [std::vector](https://en.cppreference.com/w/cpp/container/vector.html)
{{< /callout >}}
A fixed capacity vector.
```cpp
etl::vector<typename T, size_t SIZE>
etl::vector_ext<typename T>
```
## ivector
Inherits from `etl::ivector<T>`
`etl::ivector` may be used as a size independent pointer or reference type for any `etl::vector` instance.
There is a specialisation for pointers that means that just one instantiation of code for all pointer types.
The one caveat is that `etl::vector` cannot directly store pointers to member functions. They must be wrapped in either a custom struct, one of the `etl::function` or `etl::deletgate` templates, or `std::function`.
Has the ability to be copied by low level functions such as `memcpy` by use of a `repair()` function.
See the function reference for an example of use.
Unlike `std::vector`, An iterator to an `etl::vector` element is never invalidated by a call to `resize()`.
The size of the instance will be `(SIZE * sizeof(T)) + (2 * sizeof(size_t)) + sizeof(T*)`.
For a 32 bit environment the overhead (compared to an array) will usually be 12 bytes.
---
## External buffer
```cpp
etl::vector_ext<typename T>
```
With this template the constructor expects pointer and size parameters to the externally provided buffer. This buffer must not be shared concurrently with any other vector.
When a vector with an external buffer is moved, the data is moved, not the pointer to the buffer.
## Template deduction guides
C++17 and above
template <typename T, typename... Ts>
etl::vector(T...)
template <typename T, typename... Ts>
etl::vector(T*...)
### Example
etl::vector data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
Defines data as an vector of int, of length 10, containing the supplied data.
## Member types
```cpp
value_type T
size_type size_t
difference_type ptrdiff_t
reference value_type&
const_reference const value_type&
rvalue_reference value_type&&
pointer value_type*
const_pointer const value_type*
iterator Random access iterator
const_iterator Constant random access iterator
reverse_iterator ETL_OR_STD::reverse_iterator<iterator>
const_reverse_iterator ETL_OR_STD::reverse_iterator<const_iterator>
```
## Constructors
**Internal buffer**
```cpp
etl::vector<typename T, const size_t SIZE>();
etl::vector<typename T, const size_t SIZE>(size_t initialSize);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, const T& value);
template <typename TIterator>
etl::vector<typename T, const size_t SIZE>(TIterator begin, TIterator end);
etl::vector<typename T, const size_t SIZE>(const etl::vector<typename T, const size_t SIZE>&);
etl::vector<typename T, const size_t SIZE>(etl::vector<typename T, const size_t SIZE>&&);
**External buffer**
etl::vector<typename T, const size_t SIZE>(void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(size_t initialSize, const T& value, void* buffer, size_t max_size);
template <typename TIterator>
etl::vector<typename T, const size_t SIZE>(TIterator begin, TIterator end, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(const etl::vector<typename T, const size_t SIZE>&, void* buffer, size_t max_size);
etl::vector<typename T, const size_t SIZE>(etl::vector<typename T, const size_t SIZE>&&, void* buffer, size_t max_size);
```
If the vector is full then emits an `etl::vector_full`. If asserts or exceptions are not enabled then undefined behaviour occurs.
## Element access
```cpp
T& at(size_t i)
const T& at(size_t i) const
```
Returns a reference or const reference to the indexed element. Emits an etl::vector_out_of_range if the index is out of range of the array. If asserts or exceptions are not enabled then undefined behaviour occurs.
---
```cpp
T& operator[](size_t i)
const T& operator[](size_t i) const
```
Returns a reference or const reference to the indexed element.
if the index is out of range of the array then undefined behaviour occurs.
---
```cpp
T& front()
const T& front() const
```
Returns a reference or const reference to the first element.
Undefined behaviour if the vector is empty.
---
```cpp
T& back()
const T& back() const
```
Returns a reference or const reference to the last element.
Undefined behaviour if the vector is empty.
---
```cpp
T* data()
const T* data() const
```
Returns a pointer or const pointer to the internal buffer.
## Iterators
```cpp
iterator begin()
const_iterator begin() const
const_iterator cbegin() const
```
Returns an iterator to the beginning of the vector.
---
```cpp
iterator end()
const_iterator end() const
const_iterator cend() const
```
Returns an iterator to the end of the vector.
---
```cpp
iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const
```
Returns a reverse iterator to the beginning of the vector.
---
```cpp
iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const
```
Returns a reverse iterator to the end of the vector.
## Capacity
```cpp
bool empty() const
```
Returns `true` if the size of the vector is zero, otherwise `false`.
---
```cpp
bool full() const
```
Returns `true` if the size of the vector is `SIZE`, otherwise `false`.
---
```cpp
size_t size() const
```
Returns the size of the vector.
---
```cpp
void resize(size_t new_size, const_reference value = T())
```
Resizes the vector, up to the maximum capacity.
Emits an `etl::vector_full` if the vector does not have the capacity.
---
```cpp
void uninitialized_resize(size_t new_size)
```
Resizes the vector, up to the maximum capacity, without initialising the new elements.
Since: `20.4.0`
---
```cpp
size_t max_size() const
```
Returns the maximum possible size of the vector.
---
```cpp
size_t capacity() const
```
Returns the maximum possible size of the vector.
---
```cpp
size_t available() const
```
Returns the remaining available capacity in the vector.
## Modifiers
```cpp
template <typename TIterator>
void assign(TIterator begin, TIterator end)
```
```cpp
void assign(size_t n, const T& value)
```
Fills the vector with the values. Emits `etl::vector_iterator` if the distance between begin and end is illegal.
(debug mode only). If asserts or exceptions are not enabled undefined behaviour occurs.
---
```cpp
void push_back(const T& value)
void push_back(T&& value)
```
Pushes a value to the back of the vector.
If the vector is full then emits an `etl::vector_full`. If asserts or exceptions are not enabled undefined behaviour occurs.
---
**C++03**
Since: `20.38.0`
```cpp
void emplace();
void emplace(const T1& value1)
void emplace(const T1& value1, const T2& value2)
void emplace(const T1& value1, const T2& value2, const T3& value3)
void emplace(const T1& value1, const T2& value2, const T3& value3, const T4& value4)
```
**C++11**
```cpp
template <typename… Args>
void emplace(Args&&… args);
```
Constructs an item at the back of the the vector 'in place'.
Supports up to four constructor parameters.
Pushes a value to the back of the vector. The first pushes a value, the second allocates the new element but does not initialise it.
If the vector is full then emits an `etl::vector_full`. If asserts or exceptions are not enabled undefined behaviour occurs.
---
**C++03**
Before `20.35.10`
```cpp
void emplace_back(const T1& value1)
void emplace_back(const T1& value1, const T2& value2)
void emplace_back(const T1& value1, const T2& value2, const T3& value3)
void emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4)
```
Since: `20.35.10`
```cpp
reference emplace_back(); 20.38.0
reference emplace_back(const T1& value1)
reference emplace_back(const T1& value1, const T2& value2)
reference emplace_back(const T1& value1, const T2& value2, const T3& value3)
reference emplace_back(const T1& value1, const T2& value2, const T3& value3, const T4& value4)
```
**C++11**
Before: `20.35.10`
```cpp
template <typename Args...>
void emplace_back(Args&&... args)
```
Since: `20.35.10`
```cpp
template <typename Args...>
reference emplace_back(Args&&... args)
```
Constructs an item at the back of the the vector 'in place'.
Supports up to four constructor parameters.
Pushes a value to the back of the vector.
If the vector is full then emits an `etl::vector_full`. If asserts or exceptions are not enabled undefined behaviour occurs.
---
```cpp
void pop_back()
```
Pop a value from the back of the vector.
If the vector is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::vector_empty. If asserts or exceptions are not enabled undefined behaviour occurs.
---
Before: `20.20.0`
```cpp
template <typename TIterator>
void insert(iterator position, TIterator begin, TIterator end)
```
```cpp
iterator insert(iterator position, const T& value)
iterator insert(iterator position, T&& value)
void insert(iterator position, size_t n, const T& value)
```
Since: `20.20.0`
```cpp
template <typename TIterator>
iterator insert(const_iterator position, TIterator begin, TIterator end)
```
```cpp
iterator insert(const_iterator position, const T& value)
iterator insert(const_iterator position, T&& value)
iterator insert(const_iterator position, size_t n, const T& value)
```
Inserts values in to the vector.
If the vector is full then emits an `etl::vector_full` exception. If asserts or exceptions are not enabled undefined behaviour occurs.
---
```cpp
template <typename TIterator>
iterator erase(TIterator begin, TIterator end)
```
```cpp
iterator erase(iterator position)
```
Erases values in the vector.
Iterators are not checked.
---
```cpp
void clear()
```
Clears the vector to a size of zero.
---
```cpp
void fill(value_type value)
```
Fill the current size of the buffer with `value`.
Since: `20.24.0`
---
```cpp
void repair()
```
This function must be called if the vector has been copied via a low level method such as `memcpy`.
This can only be called from an `etl::vector` instance, unless `ETL_IVECTOR_REPAIR_ENABLE` is defined. Be aware that doing so introduces a virtual function to the class.
Has no effect if the object has not been copied in this way.
**Note:**
The contained type must be trivially copyable.
Compilers that satisfy the C++11 type traits support check in `platform.h` will generate an assert if the type is incompatible.
### Example:
```cpp
typedef etl::vector<int, 10> Data;
Data data(8, 1);
char buffer[sizeof(Data)];
memcpy(&buffer, &data, sizeof(Data));
Data& rdata(*reinterpret_cast<Data*>(buffer));
// Do not access the copied object in any way until you have called this.
rdata.repair();
```
## Non-member functions
```cpp
template <typename T, typename U>
typename etl::ivector<T>::difference_type erase(etl::ivector<T>& v, const U& value)
```
Erases all elements that compare equal to value from the vector.
---
```cpp
template <typename T, typename TPredicate>
typename etl::ivector<T>::difference_type erase_if(etl::ivector<T>& v, TPredicate predicate)
```
Erases all elements that satisfy the predicate from the vector.
## Operators
- `==`
`true` if the contents of the vectors are equal, otherwise `false`.
- `!=`
`true` if the contents of the vectors are not equal, otherwise `false`.
- `<`
`true` if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise `false`.
- `<=`
`true` if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise `false`.
- `>`
`true` if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise `false`.
- `>=`
`true` if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise `false`.

10
docs/multi-tasking/cooperative-scheduler.md
View File

@ -15,8 +15,8 @@ Calls a 'watchdog' callback whenever the scheduler returns.
The scheduler makes use of `etl::task`.
## Scheduling Policies
A number of built-in scheduling policies are available.
Note: The tasks are stored in decreasing priority id order. i.e. Higher id = higher priority.
A number of built-in scheduling policies are available.
**Note:** The tasks are stored in decreasing priority id order. i.e. Higher id = higher priority.
### Sequential Single
```cpp
@ -189,18 +189,18 @@ Inherits from `etl::scheduler_exception`
As a basic example, you will have to define the following...
**Tasks**
For each of your tasks, derive a class from etl::task and overide the two virtual functions uint32_t task_request_work() const and void task_process_work(). task_request_work returns a value that informs the scheduler that this task has work to process. The return value should be non-zero if the task has work. This meaning of this is user defined, it could be the number of messages in the task's queue, or just a 0 = no work, 1 = have work. task_process_work allows the task to process any work that it has. How much work it processes on each call is user defined; often it will be one 'unit' of work and letting the policy determine which task gets the next opportunity to process more.
For each of your tasks, derive a class from etl::task and override the two virtual functions `uint32_t task_request_work()` const and `void task_process_work()`. `task_request_work` returns a value that informs the scheduler that this task has work to process. The return value should be non-zero if the task has work. This meaning of this is user defined, it could be the number of messages in the task's queue, or just a `0` = no work, `1` = have work. `task_process_work` allows the task to process any work that it has. How much work it processes on each call is user defined; often it will be one 'unit' of work and letting the policy determine which task gets the next opportunity to process more.
**Task list**
An array of pointers to the tasks. Passed to the scheduler with `add_task_list`.
Use add_task to add additional tasks.
Use `add_task` to add additional tasks.
**The scheduler**
An instance of `etl::scheduler` with the required scheduling policy.
Initialise the task list by calling add_task_list.
**Callbacks**
If you wish to get callbacks for 'idle' or 'watchdog' then define callback functions and call set_idle_callback and set_watchdog_callback to tell the scheduler.
If you wish to get callbacks for 'idle' or 'watchdog' then define callback functions and call `set_idle_callback` and `set_watchdog_callback`.
The callbacks may be global, static or member function, wrapped in an etl::function.
**Starting the scheduler**

4
docs/multi-tasking/task.md
View File

@ -34,7 +34,7 @@ Virtual destructor
virtual uint32_t task_request_work() const = 0;
```
The derived task must override this.
Should return a value that represents the amount of work to do. This may be the number of items in the task's message queue, for example.
Should return a value that represents the amount of work to do. For example, this may be the number of items in the task's message queue.
Return zero if the task requires no processing time.
---
@ -69,6 +69,8 @@ bool task_is_running() const;
```
Returns `true` if the task is in the 'running' state.
---
```cpp
etl::task_priority_t get_task_priority() const
```

172
docs/raw/containers/circular_buffer.txt
View File

@ -1,172 +0,0 @@
circular_buffer
A fixed capacity circular buffer.
STL equivalent: none
etl::circular_buffer<typename T, size_t SIZE>
etl::circular_buffer_ext<typename T>
Inherits from etl::icircular_buffer<T>
etl::icircular_buffer may be used as a size independent pointer or reference type for any etl::circular_buffer instance.
____________________________________________________________________________________________________
External buffer
etl::circular_buffer_ext<typename T>
For this template the constructor expects pointer and size parameters to the externally provided buffer. This buffer must not be shared concurrently with any other vector.
When a circular with an external buffer is moved, the data is moved, not the pointer to the buffer.
The external buffer MUST be declared one item larger that the intended capacity of the circular buffer.
A swap on a circular buffer with an external buffer is fast as it will swap buffer pointers rather than copying items.
____________________________________________________________________________________________________
Template deduction guides
C++17 and above
template <typename T, typename... Ts>
etl::circular_buffer(T, Ts...)
-> etl::circular_buffer<etl::enable_if_t<(etl::is_same_v<T, Ts> && ...), T>, 1U + sizeof...(Ts)>;
Example
etl::circular_buffer data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
Defines data as an circular_buffer of int, of length 10, containing the supplied data.
____________________________________________________________________________________________________
Member types
value_type T
size_type std::size_t
difference_type std::ptrdiff_t
reference value_type&
const_reference const value_type&
rvalue_reference value_type&&
pointer value_type*
const_pointer const value_type*
iterator Random access iterator
const_iterator Constant random access iterator
reverse_iterator reverse_iterator<iterator>
const_reverse_iterator reverse_iterator<const_iterator>
____________________________________________________________________________________________________
Static Constants
MAX_SIZE The maximum size of the circular_buffer.
____________________________________________________________________________________________________
Constructor
circular_buffer<typename T, size_t SIZE>();
circular_buffer<typename T, size_t SIZE>(const etl::circular_buffer<typename T, size_t SIZE>& other);
circular_buffer<typename T, size_t SIZE>(etl::circular_buffer<typename T, size_t SIZE>&& other);
____________________________________________________________________________________________________
circular_buffer_ext(void* buffer, size_t max_size)
circular_buffer_ext(size_t max_size) 20.32.1
template <typename TIterator>
circular_buffer_ext(TIterator first, const TIterator& last, void* buffer, size_t max_size)
circular_buffer_ext(std::initializer_list<T> init, void* buffer, size_t max_size)
circular_buffer_ext(const circular_buffer_ext& other, void* buffer, size_t max_size)
____________________________________________________________________________________________________
Status
bool is_valid() const
Returns true if the buffer has been set through the constructor or set_buffer.
For circular_buffer_ext only.
20.32.1
____________________________________________________________________________________________________
Element access
reference operator[](size_t i)
const_reference operator[](size_t i) const
Returns a reference or const reference to the indexed element
____________________________________________________________________________________________________
reference front()
const_reference front() const
Returns a reference or const reference to the first element.
____________________________________________________________________________________________________
reference back()
const_reference back() const
Returns a reference or const reference to the last element.
____________________________________________________________________________________________________
void fill(value_type value)
Fill the current size of the buffer with value
20.24.0
____________________________________________________________________________________________________
Iterators
iterator begin()
const_iterator begin() const
const_iterator cbegin() const
Returns an iterator to the beginning of the circular_buffer.
____________________________________________________________________________________________________
iterator end()
const_iterator end() const
const_iterator cend() const
Returns an iterator to the end of the circular_buffer.
____________________________________________________________________________________________________
iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const
Returns a reverse iterator to the beginning of the circular_buffer.
____________________________________________________________________________________________________
iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const
Returns a reverse iterator to the end of the circular_buffer.
____________________________________________________________________________________________________
Capacity
bool empty() const
Returns true if the size of the circular_buffer is zero, otherwise false.
____________________________________________________________________________________________________
bool full() const
Returns true if the size of the circular_buffer is SIZE, otherwise false.
____________________________________________________________________________________________________
size_t size() const
Returns the size of the circular_buffer.
____________________________________________________________________________________________________
size_t max_size() const
Returns the maximum possible size of the circular_buffer.
____________________________________________________________________________________________________
size_t capacity() const
Returns the maximum possible size of the circular_buffer.
____________________________________________________________________________________________________
size_t available() const
Returns the remaining available capacity in the circular_buffer.
____________________________________________________________________________________________________
Modifiers
void set_buffer(void* buffer)
Sets the associated buffer.
For circular_buffer_ext only.
20.32.1
____________________________________________________________________________________________________
void push(const_reference value)
void push(rvalue_reference value)
Pushes a value to the back of the circular_buffer.
____________________________________________________________________________________________________
template <typename TIterator>
void push(TIterator first, const TIterator& last)
Pushes values to the back of the circular_buffer.
____________________________________________________________________________________________________
void pop()
Pop a value from the front of the circular_buffer.
____________________________________________________________________________________________________
void clear()
Clears the circular_buffer to a size of zero.
____________________________________________________________________________________________________
void swap(circular_buffer<T, SIZE>& other)
Swaps the circular_buffer with other.
void swap(circular_buffer_ext<T> other)
Swaps the circular_buffer_ext with other.
The internal pointers to the external buffers are swapped.
____________________________________________________________________________________________________
Non-member functions
== true if the contents of the vectors are equal, otherwise false.
!= true if the contents of the vectors are not equal, otherwise false.
swap Swaps two circular buffers. A circular buffer with internal storage copies items while one with an external buffer will swap pointers.

360
docs/raw/containers/deque.txt
View File

@ -1,360 +0,0 @@
deque
A fixed capacity deque.
STL equivalent: std::deque
etl::deque<typename T, const size_t SIZE>
Inherits from etl::ideque<T>
etl::ideque may be used as a size independent pointer or reference type for any etl::deque instance.
Has the ability to be copied by low level functions such as memcpy by use of a repair() function.
See the function reference for an example of use.
____________________________________________________________________________________________________
Template deduction guides
C++17 and above
template <typename... T>
etl::deque(T...)
Example
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
template <typename T, typename... TValues>
constexpr auto make_deque(TValues&&... values)
Example
auto data = etl::make_deque<int>(0, 1, 2, 3, 4, 5, 6, 7, 8, 9);
____________________________________________________________________________________________________
Member types
value_type T
size_type std::size_t
difference_type std::ptrdiff_t
reference value_type&
const_reference const value_type&
rvalue_reference value_type&&
pointer value_type*
const_pointer const value_type*
iterator Random access iterator
const_iterator Constant random access iterator
reverse_iterator std::reverse_iterator<iterator>
const_reverse_iterator std::reverse_iterator<const_iterator>
____________________________________________________________________________________________________
Static Constants
MAX_SIZE The maximum size of the deque.
____________________________________________________________________________________________________
Constructor
etl::deque<typename T, const size_t SIZE>();
etl::deque<typename T, const size_t SIZE>(size_t initialSize);
etl::deque<typename T, const size_t SIZE>(size_t initialSize, parameter_t value);
template <typename TIterator>
etl::deque<typename T, const size_t SIZE>(TIterator begin, TIterator end);
etl::deque<typename T, const size_t SIZE>(const etl::deque<typename T, const size_t SIZE>& other);
etl::deque<typename T, const size_t SIZE>(etl::deque<typename T, const size_t SIZE>&& other);
____________________________________________________________________________________________________
Element access
T& at(size_t i)
const T& at(size_t i) const
Returns a reference or const reference to the indexed element.
Emits an etl::deque_out_of_range if the index is out of range of the array. Undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
T& operator[](size_t i)
const T& operator[](size_t i) const
Returns a reference or const reference to the indexed element.
____________________________________________________________________________________________________
T& front()
const T& front() const
Returns a reference or const reference to the first element.
____________________________________________________________________________________________________
T& back()
const T& back() const
Returns a reference or const reference to the last element.
____________________________________________________________________________________________________
void fill(value_type value)
Fill the current size of the buffer with value
20.24.0
____________________________________________________________________________________________________
Iterators
iterator begin()
const_iterator begin() const
const_iterator cbegin() const
Returns an iterator to the beginning of the deque.
____________________________________________________________________________________________________
iterator end()
const_iterator end() const
const_iterator cend() const
Returns an iterator to the end of the deque.
____________________________________________________________________________________________________
reverse_iterator rbegin()
const_reverse_iterator rbegin() const
const_reverse_iterator crbegin() const
Returns a reverse iterator to the beginning of the deque.
____________________________________________________________________________________________________
iterator rend()
const_reverse_iterator rend() const
const_reverse_iterator crend() const
Returns a reverse iterator to the end of the deque.
____________________________________________________________________________________________________
Capacity
bool empty() const
Returns true if the size of the deque is zero, otherwise false.
____________________________________________________________________________________________________
bool full() const
Returns true if the size of the deque is SIZE, otherwise false.
____________________________________________________________________________________________________
size_t size() const
Returns the size of the deque.
____________________________________________________________________________________________________
void resize(size_t new_size, T value = T())
Resizes the deque, up to the maximum capacity.
Emits an etl::deque_full if the deque does not have the capacity.
____________________________________________________________________________________________________
size_t max_size() const
Returns the maximum possible size of the deque.
____________________________________________________________________________________________________
size_t capacity() const
Returns the maximum possible size of the deque.
____________________________________________________________________________________________________
size_t available() const
Returns the remaining available capacity in the deque.
____________________________________________________________________________________________________
Modifiers
template <typename TIterator>
void assign(TIterator begin, TIterator end);
Fills the deque with the range.
The range is not checked for validity.
____________________________________________________________________________________________________
void assign(size_t n, const_reference value);
Fills the deque with the values.
Emits etl::deque_iterator if the distance between begin and end is illegal, otherwise undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
void push_front(const_reference value);
void push_front(rvalue_reference value);
Pushes a value to the front of the deque.
If the deque is full and ETL_CHECK_PUSH_POP is defined then emits an etl::deque_full, otherwise undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
void push_back(const_reference value);
void push_back(rvalue_reference value);
Pushes a value to the back of the deque.
If the deque is full and ETL_CHECK_PUSH_POP is defined then emits an etl::deque_full, otherwise undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
void pop_front();
Pop a value from the front of the deque.
If the deque is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::deque_empty, otherwise undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
void pop_back();
Pop a value from the back of the deque.
If the deque is empty and ETL_CHECK_PUSH_POP is defined then emits an etl::deque_empty, otherwise undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
void insert(iterator position, size_t n, parameter_t value);
<=20.19.0
template <typename TIterator>
void insert(iterator position, TIterator begin, TIterator end);
iterator insert(iterator position, parameter_t value);
iterator insert(iterator position, rvalue_reference value);
>=20.20.0
template <typename TIterator>
iterator insert(const_iterator position, TIterator begin, TIterator end);
iterator insert(const_iterator position, parameter_t value);
iterator insert(const_iterator position, rvalue_reference value);
Inserts values in to the deque. If the deque is full then emits an etl::deque_full exception.
Undefined behaviour if asserts or exceptions are not enabled.
____________________________________________________________________________________________________
template <typename TIterator>
iterator erase(TIterator begin, TIterator end);
<= 20.19.0
iterator erase(iterator position);
>= 20.20.0
iterator erase(iterator position);
iterator erase(const_iterator position);
Erases values in the deque.
Undefined behaviour if asserts or exceptions are not enabled and begin, end or position are invalid.
____________________________________________________________________________________________________
<=20.19.0
C++03
template <typename T1>
iterator emplace(iterator insert_position, const T1& value1)
template <typename T1, typename T2>
iterator emplace(iterator insert_position, const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
iterator emplace(iterator insert_position, const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
iterator emplace(iterator insert_position, const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
C++11 and above
template <typename ... Args>
iterator emplace(iterator insert_position, Args&& ... args)
>=20.20.0
C++03
template <typename T1>
iterator emplace(const_iterator insert_position, const T1& value1)
template <typename T1, typename T2>
iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
C++11 and above
template <typename ... Args>
iterator emplace(const_iterator insert_position, Args&& ... args)
____________________________________________________________________________________________________
<=20.35.9
C++03
template <typename T1>
void emplace_front(const T1& value1)
template <typename T1, typename T2>
void emplace_front(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
void emplace_front(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
void emplace_front(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
C++11 and above
template <typename ... Args>
void emplace_front(Args&& ... args)
>=20.35.10
C++03
template <typename T1>
reference emplace_front(const T1& value1)
template <typename T1, typename T2>
reference emplace_front(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
reference emplace_front(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
reference emplace_front(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
C++11 and above
template <typename ... Args>
reference emplace_front(Args&& ... args)
____________________________________________________________________________________________________
<=20.35.9
C++03
template <typename T1>
void emplace_back(const T1& value1)
template <typename T1, typename T2>
void emplace_back(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
void emplace_back(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
void emplace_back(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
C++11 and above
template <typename ... Args>
void emplace_back(Args&& ... args)
>=20.35.10
C++03
template <typename T1>
reference emplace_back(const T1& value1)
template <typename T1, typename T2>
reference emplace_back(const T1& value1, const T2& value2)
template <typename T1, typename T2, typename T3>
reference emplace_back(const T1& value1, const T2& value2,
const T3& value3)
template <typename T1, typename T2, typename T3, typename T4>
reference emplace_back(const T1& value1, const T2& value2,
const T3& value3, const T4& value4)
C++11 and above
template <typename ... Args>
reference emplace_back(Args&& ... args)
____________________________________________________________________________________________________
void clear();
Clears the deque to a size of zero.
____________________________________________________________________________________________________
void repair()
This function must be called if the deque has been copied via a low level method such as memcpy.
This can only be called from an etl::deque instance, unless ETL_IDEQUE_REPAIR_ENABLE is defined. Be aware that doing this introduces a virtual function to the class.
Has no effect if the object has not been copied in this way.
NOTE:
The contained type must be trivially copyable.
Compilers that satisfy the C++11 type traits support check in platform.h will generate an assert if the type is incompatible.
Example:
typedef etl::deque<int, 10> Data;
Data data(8, 1);
char buffer[sizeof(Data)];
memcpy(&buffer, &data, sizeof(Data));
Data& rdata(*reinterpret_cast<Data*>(buffer));
// Do not access the copied object in any way until you have called this.
rdata.repair();
____________________________________________________________________________________________________
etl::deque<typename T, const size_t SIZE>&
operator =(const etl::deque<typename T, const size_t SIZE>& other);
etl::deque<typename T, const size_t SIZE>&
operator =(etl::deque<typename T, const size_t SIZE>&& other);
etl::ideque<typename T>&
operator =(const etl::ideque<typename T>& other);
etl::deque<typename T>&
operator =(etl::deque<typename T>&& other);
____________________________________________________________________________________________________
Non-member functions
== true if the contents of the vectors are equal, otherwise false.
!= true if the contents of the vectors are not equal, otherwise false.
< true if the contents of the lhs are lexicographically less than the contents of the rhs, otherwise false.
<= true if the contents of the lhs are lexicographically less than or equal to the contents of the rhs, otherwise false.
> true if the contents of the lhs are lexicographically greater than the contents of the rhs, otherwise false.
>= true if the contents of the lhs are lexicographically greater than or equal to the contents of the rhs, otherwise false.

448
docs/raw/utilities/Memory.txt
View File

@ -1,448 +0,0 @@
Memory
These functions will create objects in uninitialised memory.
POD types will be default or value initialised, Non-trivial types by calling placement new.
____________________________________________________________________________________________________
address_of
template <typename T>
T* addressof(T& t)
Returns the address of an object.
____________________________________________________________________________________________________
default_delete
template <typename T>
struct default_delete
template <typename T>
struct default_delete<T[]>
____________________________________________________________________________________________________
Create / Destroy
Functions that create or destroy items in uninitialised memory.
template <typename T>
void create_default_at(T* p)
template <typename T, typename TCounter>
void create_default_at(T* p, Tcounter count)
Creates a default value. For POD types this will be undefined.
The second version is supplied a counter, which will be incremented.
____________________________________________________________________________________________________
template <typename T>
void create_value_at(T* p)
template <typename T, typename TCounter>
void create_value_at(T* p, Tcounter count)
Creates a default value by constructing the item with T().
The second version is supplied a counter, which will be incremented.
____________________________________________________________________________________________________
template <typename T>
void create_copy_at(T* p)
template <typename T, typename TCounter>
void create_copy_at(T* p, const T& value, Tcounter count)
Creates a default value by constructing the item with T(value).
The second version is supplied a counter, which will be incremented.
____________________________________________________________________________________________________
template <typename T, typename TCounter>
T& make_default_at(T* p, Tcounter count)
Creates a default value. For POD types this will be undefined.
Returns a reference to the new object.
The second version is supplied a counter, which will be incremented.
template <typename T>
T& make_value_at(T* p)
____________________________________________________________________________________________________
template <typename T, typename TCounter>
T& make_value_at(T* p, Tcounter count)
Creates a default value by constructing the item with T().
Returns a reference to the new object.
The second version is supplied a counter, which will be incremented.
template <typename T>
T& make_copy_at(T* p)
____________________________________________________________________________________________________
template <typename T, typename TCounter>
T& make_copy_at(T* p, const T& value, Tcounter count)
Creates a default value by constructing the item with T(value).
Returns a reference to the new object.
The second version is supplied a counter, which will be incremented.
template <typename T>
void destroy_at(T* p)
____________________________________________________________________________________________________
template <typename T, typename TCounter>
void destroy_at(T* p, TCounter& count)
Calls the destructor for non-pod types.
The second version is supplied a counter, which will be decremented.
template <typename T, typename TSize >
void destroy_n(T* p, TSize n)
____________________________________________________________________________________________________
template <typename T, typename TSize, typename TCounter>
void destroy_n(T* p, TSize n, TCounter& count)
Calls the destructor for a range of non-pod types, starting at address p.
The second version is supplied a counter, which will be decremented by the number of items destructed.
template <typename T>
void destroy(T* p, T* p_end)
____________________________________________________________________________________________________
template <typename T, typename TCounter>
void destroy(T* p, T* p_end, TCounter& count)
Calls the destructor for a range of non-pod types, starting at address p.
The second version is supplied a counter, which will be decremented by the number of items destructed.
____________________________________________________________________________________________________
template <typename T>
struct create_copy
Derive from this, passing the derived class as the template parameter.
Provides the following member functions that constructs a copy at the specified address.
____________________________________________________________________________________________________
void create_copy_at(void* p);
____________________________________________________________________________________________________
template <typename TCounter>
void create_copy_at(void* p, Tcounter& count);
____________________________________________________________________________________________________
T& make_copy_at(void* p);
____________________________________________________________________________________________________
template <typename TCounter>
T& make_copy_at(void* p, Tcounter& count);
____________________________________________________________________________________________________
Example:
class Test : public etl::create_copy<Test>
{
// Other members.
};
// Allocate memory large enough to contain a 'Test' object.
char buffer[sizeof(Test)];
Test test;
// Copy construct 'test' into the buffer memory.
Test& t = test.make_copy_at(buffer);
____________________________________________________________________________________________________
Create / Destroy objects
Functions that create or destroy objects in uninitialised memory.
Variations of the functions above that don't require an explicit reinterpret_cast.
template <typename TObject>
TObject& construct_object_at(void* p, TObject&& object)
20.35.12
Construct the object at p.
In a debug build the pointer is checked for correct alignment. An etl::alignment_error is asserted if incorrect.
____________________________________________________________________________________________________
template <typename TObject, typename... TArgs>
TObject& construct_object_at(void* p, TArgs&&... args)
20.35.12
Construct the object at p from arguments.
In a debug build the pointer is checked for correct alignment. An etl::alignment_error is asserted if incorrect.
____________________________________________________________________________________________________
template <typename TObject>
TObject& get_object_at(void* p)
20.35.12
Get the object at p.
In a debug build the pointer is checked for correct alignment. An etl::alignment_error is asserted if incorrect.
____________________________________________________________________________________________________
template <typename TObject>
void destroy_object_at(void* p)
20.35.12
Destroy the object at p.
In a debug build the pointer is checked for correct alignment. An etl::alignment_error is asserted if incorrect.
____________________________________________________________________________________________________
uninitialzed_fill
template <typename TIterator, typename TSize, typename T>
TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value)
template <typename TIterator, typename TSize, typename T, typename TCounter>
TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter)
Fills uninitialised memory with N values.
____________________________________________________________________________________________________
template <typename TIterator, typename T>
TIterator uninitialized_fill(TIterator o_begin, TIterator o_end, const T& value)
template <typename TIterator, typename TSize, typename T, typename TCounter>
TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter)
Fills uninitialised memory range with a value.
____________________________________________________________________________________________________
uninitialised_copy
template <typename TInputIterator, typename TOutputIterator>
TIterator uninitialized_copy(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin)
template <typename TInputIterator, typename TOutputIterator, typename TCounter>
TIterator uninitialized_copy(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin, typename TCounter)
Copies a range of objects to uninitialised memory.
____________________________________________________________________________________________________
uninitialized_copy_n
template <typename TInputIterator, typename TSize, typename TOutputIterator>
TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin)
template <typename TInputIterator, typename TSize, typename TOutputIterator, typename TCounter>
TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin, typename TCounter)
Copies N objects to uninitialised memory.
____________________________________________________________________________________________________
uninitialized_move
template <typename TInputIterator, typename TOutputIterator>
TIterator uninitialized_move(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin)
template <typename TInputIterator, typename TOutputIterator, typename TCounter>
TIterator uninitialized_move(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin, typename TCounter)
Moves a range of objects to uninitialised memory.
Note: If using C++03 then this function will call etl::uninitialized_copy
____________________________________________________________________________________________________
uninitialized_copy_n
template <typename TInputIterator, typename TSize, typename TOutputIterator>
TIterator uninitialized_move_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin)
template <typename TInputIterator, typename TSize, typename TOutputIterator, typename TCounter>
TIterator uninitialized_move_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin, typename TCounter)
Moves N objects to uninitialised memory.
Note: If using C++03 then this function will call etl::uninitialized_copy_n
____________________________________________________________________________________________________
uninitialized_default_construct
template <typename TOutputIterator>
void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end)
____________________________________________________________________________________________________
template <typename TOutputIterator, typename TCounter>
void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end, typename TCounter)
____________________________________________________________________________________________________
template <typename TOutputIterator, typename TSize>
TOutputIterator uninitialized_default_construct_n(TOutputIterator o_begin, TSize n)
____________________________________________________________________________________________________
template <typename TOutputIterator, typename TSize, typename TCounter>
TOutputIterator uninitialized_default_construct_n(TOutputIterator o_begin, TSize n, TCounter& count)
Creates default values. For POD types this will be undefined.
____________________________________________________________________________________________________
uninitialized_value_construct
template <typename TOutputIterator>
void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end)
____________________________________________________________________________________________________
template <typename TOutputIterator, typename TCounter>
void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end, TCounter& count)
____________________________________________________________________________________________________
template <typename TOutputIterator, typename TSize>
TOutputIterator uninitialized_value_construct_n(TOutputIterator o_begin, TSize n)
____________________________________________________________________________________________________
template <typename TOutputIterator, typename TSize, typename TCounter>
TOutputIterator uninitialized_value_construct_n(TOutputIterator o_begin, TSize n, TCounter& count)
Creates values constructed with T().
____________________________________________________________________________________________________
unique_ptr
Like std::unique_ptr, etl::unique_ptr is a smart pointer that owns and manages another object through a pointer and disposes of that object when the unique_ptr goes out of scope.
https://en.cppreference.com/w/cpp/memory/unique_ptr
template<typename T>
class unique_ptr
____________________________________________________________________________________________________
template<typename T>
class unique_ptr<T[]>
____________________________________________________________________________________________________
Memory clear
void memory_clear(volatile char* p, size_t n)
template <typename T>
void memory_clear(volatile T &object)
A low level function that clears an object's memory to zero.
template <typename T>
void memory_clear_range(volatile T* begin, size_t n)
template <typename T>
void memory_clear_range(volatile T* begin, volatile T* end)
A low level function that clears a range to zero.
____________________________________________________________________________________________________
Memory set
void memory_set(volatile char* p, size_t n, char value)
template <typename T>
void memory_set(volatile T &object, char value)
Low level functions that clear an object's memory to a value.
template <typename T>
void memory_set_range(volatile T* begin, size_t n, char value)
template <typename T>
void memory_set_range(volatile T* begin, volatile T* end, char value)
Low level functions that set a range to a value.
____________________________________________________________________________________________________
wipe_on_destruct
A template class that will wipe the derived objects storage to zero on destruction.
Designed to eliminate sensitive data lurking around in memory after an object has been destructed.
template <typename T>
struct wipe_on_destruct
T is the derived class whose storage must be wiped.
Example
struct UserData : public etl::wipe_on_destruct<UserData>
{
char secret_passcode[16];
char sensitive_user_name[16];
};
When an instance of UserData is destructed, the memory that it occupied will be set to zero.
____________________________________________________________________________________________________
uninitialized_buffer
template <size_t VObject_Size, size_t VN_Objects, size_t VAlignment>
class uninitialized_buffer
Creates an uninitialized memory buffer of VN_Objects each of VObject_Size with alignment VAlignment.
____________________________________________________________________________________________________
uninitialized_buffer_of
template <typename T, size_t VN_Objects>
class uninitialized_buffer_of
Creates an uninitialized memory buffer of VN_Objects each of type T.
____________________________________________________________________________________________________
mem_copy
20.26.0
template <typename TPointer>
TPointer mem_copy(const TPointer sb, const TPointer se, TPointer db) ETL_NOEXCEPT
Template wrapper for memcpy.
Copies all of the bytes in the source range to the destination range.
Type must be trivially copyable.
sb Pointer to source begin.
se Pointer to source end.
db Pointer to destination begin.
Returns a pointer to the destination.
____________________________________________________________________________________________________
template <typename TPointer>
TPointer mem_copy(const TPointer sb, size_t n, TPointer db) ETL_NOEXCEPT
Template wrapper for memcpy.
Copies all of the bytes in the source range to the destination range.
Type must be trivially copyable.
sb Pointer to source begin.
n Source length.
db Pointer to destination begin.
Returns a pointer to the destination.
____________________________________________________________________________________________________
mem_move
20.26.0
template <typename TPointer>
TPointer mem_move(const TPointer sb, const TPointer se, TPointer db) ETL_NOEXCEPT
Template wrapper for memmove.
Moves all of the bytes in the source range to the destination range.
Type must be trivially copyable.
sb Pointer to source begin.
se Pointer to source end.
db Pointer to destination begin.
Returns a pointer to the destination.
____________________________________________________________________________________________________
template <typename TPointer>
TPointer mem_move(const TPointer sb, size_t n, TPointer db) ETL_NOEXCEPT
Template wrapper for memmove.
Moves all of the bytes in the source range to the destination range.
Type must be trivially copyable.
sb Pointer to source begin.
n Source length.
db Pointer to destination begin.
Returns a pointer to the destination.
____________________________________________________________________________________________________
mem_compare
20.26.0
template <typename TPointer>
TPointer mem_compare(const TPointer sb, const TPointer se, TPointer db) ETL_NOEXCEPT
Template wrapper for memcmp.
Searches all of the bytes in the range for value.
Type must be trivially copyable.
sb Pointer to source begin.
se Pointer to source end.
db Pointer to destination begin.
Returns <0, 0, >0. See documentation for memcmp.
____________________________________________________________________________________________________
template <typename TPointer>
TPointer mem_compare(const TPointer sb, size_t n, TPointer db) ETL_NOEXCEPT
Template wrapper for memcmp.
Type must be trivially copyable.
sb Pointer to source begin.
n Source length.
db Pointer to destination begin.
Returns <0, 0, >0. See documentation for memcmp.
____________________________________________________________________________________________________
mem_set
20.26.0
template <typename TPointer, typename T>
TPointer mem_set(const TPointer db, const TPointer de, T value) ETL_NOEXCEPT
Template wrapper for memset.
Sets all of the bytes in the range to value.
Type must be trivially copyable.
db Pointer to destination begin.
de Pointer to destination end.
value The value to write to the memory. This value is cast to char.
Returns a pointer to the destination.
____________________________________________________________________________________________________
template <typename TPointer, typename T>
TPointer mem_set(const TPointer db, size_t n, T value) ETL_NOEXCEPT
Template wrapper for memset.
Sets all of the bytes in the range to value.
Type must be trivially copyable.
db Pointer to destination begin.
n Destination length.
value The value to write to the memory. This value is cast to char.
Returns a pointer to the destination.
____________________________________________________________________________________________________
mem_char
20.26.0
template <typename TPointer, typename T>
TPointer mem_char(const TPointer sb, const TPointer se, T value) ETL_NOEXCEPT
Template wrapper for memchr.
Searches all of the bytes in the range for value.
Type must be trivially copyable.
db Pointer to source begin.
de Pointer to source begin.
value The value to search for. This value is cast to char.
Returns a pointer to the character or se if not found.
____________________________________________________________________________________________________
template <typename TPointer, typename T>
TPointer mem_char(const TPointer sb, size_t n, T value) ETL_NOEXCEPT
Template wrapper for memchr.
Searches all of the bytes in the range for value.
Type must be trivially copyable.
db Pointer to destination begin.
n Source length.
value The value to search for. This value is cast to char.
Returns a pointer to the character or sb + n if not found.

17
docs/strings/string.md
View File

@ -4,12 +4,14 @@ title: "basic_string"
{{< callout type="info">}}
Header:
`basic_string.h`
`string.h`
`wstring.h`
`u8string.h`
`u16string.h`
`u32string.h`
Similar to:
`std::basic_string`
`std::string`
`std::wstring`
`std::u8string`
@ -17,7 +19,7 @@ title: "basic_string"
`std::u32string`
{{< /callout >}}
Fixed capacity string classes.
### Fixed capacity string classes.
```cpp
etl::string<size_t Size>
@ -27,6 +29,7 @@ etl::u16string<size_t Size>
etl::u32string<size_t Size>
```
### Strings with externally defined buffers.
```cpp
etl::string_ext
etl::wstring_ext
@ -35,20 +38,20 @@ etl::u32string_ext
```
Inherits from `etl::istring`, `etl::iwstring`, `etl::iu8string`, `etl::iu16string` or `etl::iu32string`.
The base classes may be used as a size independent pointer or reference type for any string instance.
These base classes may be used as a size independent pointer or reference type for any string instance.
Has the ability to be copied by low level functions such as `memcpy` by use of a `repair()` function.
See the function reference for an example of use.
Note: `cstring.h` is deprecated
**Note:** `cstring.h` is deprecated
## Macros
If `ETL_DISABLE_STRING_TRUNCATION_CHECKS` is defined then the string will not be checked for truncation and
the truncation functions will not be available.
`ETL_DISABLE_STRING_TRUNCATION_CHECKS`
If defined then the string will not be checked for truncation and the truncation functions will not be available.
If `ETL_DISABLE_STRING_CLEAR_AFTER_USE` is defined then the string will not be cleared after use and the
'secure' functions will not be available.
`ETL_DISABLE_STRING_CLEAR_AFTER_USE`
If is defined then the string will not be cleared after use and the 'secure' functions will not be available.
Defining both of these macros can reduce the overhead of an `etl::string` by up to 4 bytes.

10
docs/utilities/error-handler.md
View File

@ -74,8 +74,8 @@ Raises the error and calls `return value`.
Note: Not all error methods will call the return, such as when using C++ exceptions.
The macro will call return for the following combinations:-
- ETL_LOG_ERRORS only.
- ETL_DEBUG not defined.
- `ETL_LOG_ERRORS` only.
- `ETL_DEBUG` not defined.
---
@ -89,14 +89,14 @@ If `ETL_VERBOSE_ERRORS` is defined then `ETL_TEXT` uses the verbose text. By def
The terse text used in the library follows a `<numeric><alpha>` pattern. For example, errors in `etl::vector` start with `"17"` and the alpha code for 'vector full' is `"A"`. The return from the `what()` member function in this case will be `"17A"`.
When ETL_LOG_ERRORS is defined, error exceptions are passed to etl::error_handler::error() before throwing the exception or calling the assert. This will do nothing until a user defined handler function is set. The user function may either be a free function or a member function.
When `ETL_LOG_ERRORS` is defined, error exceptions are passed to `etl::error_handler::error()` before throwing the exception or calling the assert. This will do nothing until a user defined handler function is set. The user function may either be a free function or a member function.
There is an additional switch that enables checks to be made on pushes and pops to containers, ETL_CHECK_PUSH_POP.
There is an additional switch that enables checks to be made on pushes and pops to containers, `ETL_CHECK_PUSH_POP`.
This is not enabled by default as empty/full checks will usually be made by the calling code.
---
There are versions of the assert macros that are only enabled when `ETL_IS_DEBUG_BUILD` is true:-
There are versions of the assert macros that are only enabled when `ETL_IS_DEBUG_BUILD` is `true`:-
```cpp
ETL_DEBUG_ASSERT(condition, ETL_ERROR(error_exception_class))

674
docs/utilities/memory.md Normal file
View File

@ -0,0 +1,674 @@
---
title: "memory"
---
## address_of
```cpp
template <typename T>
T* addressof(T& t)
```
**Description**
Returns the address of an object.
## default_delete
```cpp
template <typename T>
struct default_delete
```
---
```cpp
template <typename T>
struct default_delete<T[]>
```
## create_default_at
```cpp
template <typename T>
void create_default_at(T* p)
```
Creates a default value. For POD types this will be undefined.
---
```cpp
template <typename T, typename TCounter>
void create_default_at(T* p, TCounter count)
```
Creates a default value. For POD types this will be undefined.
The supplied counter will be incremented.
## create_value_at
```cpp
template <typename T>
void create_value_at(T* p)
```
Creates a default value by constructing the item with `T()`.
---
```cpp
template <typename T, typename TCounter>
void create_value_at(T* p, Tcounter count)
```
Creates a default value by constructing the item with `T()`.
The supplied a counter will be incremented.
## create_copy_at
```cpp
template <typename T>
void create_copy_at(T* p)
```
Creates a default value by constructing the item with `T(value)`.
---
```cpp
template <typename T, typename TCounter>
void create_copy_at(T* p, const T& value, Tcounter count)
```
Creates a default value by constructing the item with `T(value)`.
The supplied counter will be incremented.
## make_default_at
```cpp
template <typename T>
T& make_default_at(T* p)
```
Creates a default value. For POD types this will be undefined.
Returns a reference to the new object.
---
```cpp
template <typename T, typename TCounter>
T& make_default_at(T* p, Tcounter count)
```
**Description**
Creates a default value. For POD types this will be undefined.
Returns a reference to the new object.
The supplied counter will be incremented.
## make_value_at
```cpp
template <typename T>
T& make_value_at(T* p)
```
Creates a default value by constructing the item with `T()`.
Returns a reference to the new object.
---
```cpp
template <typename T, typename TCounter>
T& make_value_at(T* p, Tcounter count)
```
Creates a default value by constructing the item with `T()`.
Returns a reference to the new object.
## make_copy_at
Creates a default value by constructing the item with `T(value)`.
Returns a reference to the new object.
The second version is supplied a counter, which will be incremented.
```cpp
template <typename T>
T& make_copy_at(T* p)
```
---
```cpp
template <typename T, typename TCounter>
T& make_copy_at(T* p, const T& value, Tcounter count)
```
## destroy_at
```cpp
template <typename T>
void destroy_at(T* p)
```
Calls the destructor for non-pod types.
---
```cpp
template <typename T, typename TCounter>
void destroy_at(T* p, TCounter& count)
```
Calls the destructor for non-pod types.
The supplied counter will be decremented.
## destroy_n
```cpp
template <typename T, typename TSize >
void destroy_n(T* p, TSize n)
```
Calls the destructor for a range of non-pod types, starting at address `p`.
---
```cpp
template <typename T, typename TSize, typename TCounter>
void destroy_n(T* p, TSize n, TCounter& count)
```
Calls the destructor for a range of non-pod types, starting at address `p`.
The supplied counter will be decremented by the number of items destructed.
## destroy
```cpp
template <typename T>
void destroy(T* p, T* p_end)
```
Calls the destructor for a range of non-pod types, starting at address `p`.
---
```cpp
template <typename T, typename TCounter>
void destroy(T* p, T* p_end, TCounter& count)
```
Calls the destructor for a range of non-pod types, starting at address `p`.
The supplied counter will be decremented by the number of items destructed.
## create_copy
```cpp
template <typename T>
struct create_copy
```
Derive from this, passing the derived class as the template parameter.
Provides the following member functions that constructs a copy at the specified address.
---
```cpp
void create_copy_at(void* p);
```
---
```cpp
template <typename TCounter>
void create_copy_at(void* p, Tcounter& count);
```
---
```cpp
T& make_copy_at(void* p);
```
---
```cpp
template <typename TCounter>
T& make_copy_at(void* p, Tcounter& count);
```
### Example:
```cpp
class Test : public etl::create_copy<Test>
{
// Other members.
};
// Allocate memory large enough to contain a 'Test' object.
char buffer[sizeof(Test)];
Test test;
// Copy construct 'test' into the buffer memory.
Test& t = test.make_copy_at(buffer);
```
---
Create / Destroy objects
Functions that create or destroy objects in uninitialised memory.
Variations of the functions above that don't require an explicit `reinterpret_cast`.
```cpp
template <typename TObject>
TObject& construct_object_at(void* p, TObject&& object)
```
Construct the object at `p`.
In a debug build the pointer is checked for correct alignment.
An `etl::alignment_error` is asserted if incorrect.
Since: `20.35.12`
---
```cpp
template <typename TObject, typename... TArgs>
TObject& construct_object_at(void* p, TArgs&&... args)
```
Construct the object at `p` from arguments.
In a debug build the pointer is checked for correct alignment.
An `etl::alignment_error` is asserted if incorrect.
Since: `20.35.12`
---
```cpp
template <typename TObject>
TObject& get_object_at(void* p)
```
Get the object at `p`.
In a debug build the pointer is checked for correct alignment.
An `etl::alignment_error` is asserted if incorrect.
Since: `20.35.12`
---
```cpp
template <typename TObject>
void destroy_object_at(void* p)
```
Destroy the object at `p`.
In a debug build the pointer is checked for correct alignment. An etl::alignment_error is asserted if incorrect.
Since: `20.35.12`
## uninitialzed_fill
Fills uninitialised memory with N values.
```cpp
template <typename TIterator, typename TSize, typename T>
TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value)
```
---
```cpp
template <typename TIterator, typename TSize, typename T, typename TCounter>
TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter)
```
---
```cpp
template <typename TIterator, typename T>
TIterator uninitialized_fill(TIterator o_begin, TIterator o_end, const T& value)
```
---
```cpp
template <typename TIterator, typename TSize, typename T, typename TCounter>
TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter)
```
Fills uninitialised memory range with a value.
## uninitialised_copy
```cpp
template <typename TInputIterator, typename TOutputIterator>
TIterator uninitialized_copy(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin)
```
```cpp
template <typename TInputIterator, typename TOutputIterator, typename TCounter>
TIterator uninitialized_copy(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin, typename TCounter)
```
Copies a range of objects to uninitialised memory.
## uninitialized_copy_n
```cpp
template <typename TInputIterator, typename TSize, typename TOutputIterator>
TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin)
```
---
```cpp
template <typename TInputIterator, typename TSize, typename TOutputIterator, typename TCounter>
TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin, typename TCounter)
```
Copies N objects to uninitialised memory.
## uninitialized_move
```cpp
template <typename TInputIterator, typename TOutputIterator>
TIterator uninitialized_move(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin)
```
```cpp
template <typename TInputIterator, typename TOutputIterator, typename TCounter>
TIterator uninitialized_move(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin, typename TCounter)
```
Moves a range of objects to uninitialised memory.
Note: If using C++03 then this function will call `etl::uninitialized_copy`
## uninitialized_copy_n
```cpp
template <typename TInputIterator, typename TSize, typename TOutputIterator>
TIterator uninitialized_move_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin)
```
---
```cpp
template <typename TInputIterator, typename TSize, typename TOutputIterator, typename TCounter>
TIterator uninitialized_move_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin, typename TCounter)
```
Moves N objects to uninitialised memory.
Note: If using C++03 then this function will call `etl::uninitialized_copy_n`
## uninitialized_default_construct
```cpp
template <typename TOutputIterator>
void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end)
```
---
```cpp
template <typename TOutputIterator, typename TCounter>
void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end, typename TCounter)
```
---
```cpp
template <typename TOutputIterator, typename TSize>
TOutputIterator uninitialized_default_construct_n(TOutputIterator o_begin, TSize n)
```
---
```cpp
template <typename TOutputIterator, typename TSize, typename TCounter>
TOutputIterator uninitialized_default_construct_n(TOutputIterator o_begin, TSize n, TCounter& count)
```
Creates default values. For POD types this will be undefined.
## uninitialized_value_construct
```cpp
template <typename TOutputIterator>
void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end)
```
---
```cpp
template <typename TOutputIterator, typename TCounter>
void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end, TCounter& count)
```
---
```cpp
template <typename TOutputIterator, typename TSize>
TOutputIterator uninitialized_value_construct_n(TOutputIterator o_begin, TSize n)
```
---
```cpp
template <typename TOutputIterator, typename TSize, typename TCounter>
TOutputIterator uninitialized_value_construct_n(TOutputIterator o_begin, TSize n, TCounter& count)
```
Creates values constructed with `T()`.
## unique_ptr
Like `std::unique_ptr`, `etl::unique_ptr` is a smart pointer that owns and manages another object through a pointer and disposes of that object when the `unique_ptr` goes out of scope.
https://en.cppreference.com/w/cpp/memory/unique_ptr
```cpp
template<typename T>
class unique_ptr
```
---
```cpp
template<typename T>
class unique_ptr<T[]>
```
## Memory clear
```cpp
void memory_clear(volatile char* p, size_t n)
```
---
```cpp
template <typename T>
void memory_clear(volatile T &object)
```
A low level function that clears an object's memory to zero.
## memory_clear_range
```cpp
template <typename T>
void memory_clear_range(volatile T* begin, size_t n)
```
---
```cpp
template <typename T>
void memory_clear_range(volatile T* begin, volatile T* end)
```
A low level function that clears a range to zero.
## memory_set
```cpp
void memory_set(volatile char* p, size_t n, char value)
```
```cpp
template <typename T>
void memory_set(volatile T &object, char value)
```
Low level functions that clear an object's memory to a value.
## memory_set_range
```cpp
template <typename T>
void memory_set_range(volatile T* begin, size_t n, char value)
```
---
```cpp
template <typename T>
void memory_set_range(volatile T* begin, volatile T* end, char value)
```
Low level functions that set a range to a value.
## wipe_on_destruct
A template class that will wipe the derived objects storage to zero on destruction.
Designed to eliminate sensitive data lurking around in memory after an object has been destructed.
```cpp
template <typename T>
struct wipe_on_destruct
```
`T` is the derived class whose storage must be wiped.
### Example
```cpp
struct UserData : public etl::wipe_on_destruct<UserData>
{
char secret_passcode[16];
char sensitive_user_name[16];
};
```
When an instance of `UserData` is destructed, the memory that it occupied will be set to zero.
## uninitialized_buffer
```cpp
template <size_t VObject_Size, size_t VN_Objects, size_t VAlignment>
class uninitialized_buffer
```
Creates an uninitialized memory buffer of `VN_Objects` each of `VObject_Size` with alignment `VAlignment`.
## uninitialized_buffer_of
```cpp
template <typename T, size_t VN_Objects>
class uninitialized_buffer_of
```
Creates an uninitialized memory buffer of `VN_Objects` each of type `T`.
## mem_copy
Since: `20.26.0`
```cpp
template <typename TPointer>
TPointer mem_copy(const TPointer sb, const TPointer se, TPointer db) ETL_NOEXCEPT
```
Template wrapper for `memcpy`.
Copies all of the bytes in the source range to the destination range.
Type must be trivially copyable.
`sb` Pointer to source begin.
`se` Pointer to source end.
`db` Pointer to destination begin.
Returns a pointer to the destination.
---
```cpp
template <typename TPointer>
TPointer mem_copy(const TPointer sb, size_t n, TPointer db) ETL_NOEXCEPT
```
Template wrapper for `memcpy`.
Copies all of the bytes in the source range to the destination range.
Type must be trivially copyable.
`sb` Pointer to source begin.
`n` Source length.
`db` Pointer to destination begin.
Returns a pointer to the destination.
## mem_move
Since: `20.26.0`
```cpp
template <typename TPointer>
TPointer mem_move(const TPointer sb, const TPointer se, TPointer db) ETL_NOEXCEPT
```
Template wrapper for `memmove`.
Moves all of the bytes in the source range to the destination range.
Type must be trivially copyable.
`sb` Pointer to source begin.
`se` Pointer to source end.
`db` Pointer to destination begin.
Returns a pointer to the destination.
---
```cpp
template <typename TPointer>
TPointer mem_move(const TPointer sb, size_t n, TPointer db) ETL_NOEXCEPT
```
Template wrapper for `memmove`.
Moves all of the bytes in the source range to the destination range.
Type must be trivially copyable.
`sb` Pointer to source begin.
`n` Source length.
`db` Pointer to destination begin.
Returns a pointer to the destination.
## mem_compare
Since: `20.26.0`
```cpp
template <typename TPointer>
TPointer mem_compare(const TPointer sb, const TPointer se, TPointer db) ETL_NOEXCEPT
```
Template wrapper for `memcmp`.
Searches all of the bytes in the range for value.
Type must be trivially copyable.
`sb` Pointer to source begin.
`se` Pointer to source end.
`db` Pointer to destination begin.
Returns `<0`, `0`, `>0`. See documentation for `memcmp`.
---
```cpp
template <typename TPointer>
TPointer mem_compare(const TPointer sb, size_t n, TPointer db) ETL_NOEXCEPT
```
Template wrapper for `memcmp`.
Type must be trivially copyable.
`sb` Pointer to source begin.
`n` Source length.
`db` Pointer to destination begin.
Returns `<0`, `0`, `>0`. See documentation for `memcmp`.
## mem_set
Since: `20.26.0`
```cpp
template <typename TPointer, typename T>
TPointer mem_set(const TPointer db, const TPointer de, T value) ETL_NOEXCEPT
```
Template wrapper for `memset`.
Sets all of the bytes in the range to `value`.
Type must be trivially copyable.
`db` Pointer to destination begin.
`de` Pointer to destination end.
`value` The value to write to the memory. This value is cast to `char`.
Returns a pointer to the destination.
---
```cpp
template <typename TPointer, typename T>
TPointer mem_set(const TPointer db, size_t n, T value) ETL_NOEXCEPT
```
Template wrapper for `memset`.
Sets all of the bytes in the range to `value`.
Type must be trivially copyable.
`db` Pointer to destination begin.
`n` Destination length.
`value` The value to write to the memory. This value is cast to `char`.
Returns a pointer to the destination.
## mem_char
Since: `20.26.0`
```cpp
template <typename TPointer, typename T>
TPointer mem_char(const TPointer sb, const TPointer se, T value) ETL_NOEXCEPT
```
Template wrapper for `memchr`.
Searches all of the bytes in the range for `value`.
Type must be trivially copyable.
`db` Pointer to source begin.
`de` Pointer to source begin.
`value` The value to search for. This value is cast to `char`.
Returns a pointer to the character or se if not found.
---
```cpp
template <typename TPointer, typename T>
TPointer mem_char(const TPointer sb, size_t n, T value) ETL_NOEXCEPT
```
Template wrapper for `memchr`.
Searches all of the bytes in the range for `value`.
Type must be trivially copyable.
`db` Pointer to destination begin.
`n` Source length.
`value` The value to search for. This value is cast to `char`.
Returns a pointer to the character or `sb + n` if not found.