diff --git a/docs/containers/deque.md b/docs/containers/deque.md new file mode 100644 index 00000000..13b455d0 --- /dev/null +++ b/docs/containers/deque.md @@ -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 +``` + +Inherits from `etl::ideque`. +`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 +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 + constexpr auto make_deque(TValues&&... values) + C++11 and above + +### Example +```cpp +auto data = etl::make_deque(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 +const_reverse_iterator std::reverse_iterator +``` + +## Static Constants + +`MAX_SIZE` The maximum size of the `deque`. + +## Constructor + +```cpp +etl::deque() +etl::deque(size_t initialSize) +etl::deque(size_t initialSize, parameter_t value) + +template +etl::deque(TIterator begin, TIterator end) + +etl::deque(const etl::deque& other) +etl::deque(etl::deque&& 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 +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 +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 +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 +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 +iterator emplace(iterator insert_position, const T1& value1) + +template +iterator emplace(iterator insert_position, const T1& value1, const T2& value2) + +template +iterator emplace(iterator insert_position, const T1& value1, const T2& value2, + const T3& value3) + +template +iterator emplace(iterator insert_position, const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` + +--- + +```cpp +template +iterator emplace(iterator insert_position, Args&& ... args) +``` + +--- + +C++03 +Since: `20.20.0` + +```cpp +template +iterator emplace(const_iterator insert_position, const T1& value1) + +template +iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2) + +template +iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2, + const T3& value3) + +template +iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` + +--- + +C++11 and above + +```cpp +template +iterator emplace(const_iterator insert_position, Args&& ... args) +``` + +--- + +C++03 +Before: `20.35.8` + +```cpp +template +void emplace_front(const T1& value1) + +template +void emplace_front(const T1& value1, const T2& value2) + +template +void emplace_front(const T1& value1, const T2& value2, + const T3& value3) + +template +void emplace_front(const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` + +--- + +C++11 and above + +```cpp +template +void emplace_front(Args&& ... args) +``` + +--- + +C++03 +Since `20.35.10` + +```cpp +template +reference emplace_front(const T1& value1) + +template +reference emplace_front(const T1& value1, const T2& value2) + +template +reference emplace_front(const T1& value1, const T2& value2, + const T3& value3) + +template +reference emplace_front(const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` + +--- + +C++11 and above + +```cpp +template +reference emplace_front(Args&& ... args) +``` + +--- + +C++03 +Before: 20.35.8 + +```cpp +template +void emplace_back(const T1& value1) + +template +void emplace_back(const T1& value1, const T2& value2) + +template +void emplace_back(const T1& value1, const T2& value2, + const T3& value3) + +template +void emplace_back(const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` + +--- + +C++11 and above + +```cpp +template +void emplace_back(Args&& ... args) +``` + +--- + +C++03 +Since: 20.35.10 + +```cpp +template +reference emplace_back(const T1& value1) + +template +reference emplace_back(const T1& value1, const T2& value2) + +template +reference emplace_back(const T1& value1, const T2& value2, + const T3& value3) + +template +reference emplace_back(const T1& value1, const T2& value2, + const T3& value3, const T4& value4) +``` + +--- + +C++11 and above + +```cpp +template +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 Data; + +Data data(8, 1); + +char buffer[sizeof(Data)]; + +memcpy(&buffer, &data, sizeof(Data)); + +Data& rdata(*reinterpret_cast(buffer)); + +// Do not access the copied object in any way until you have called this. +rdata.repair(); +``` + +--- + +```cpp +etl::deque& + operator =(const etl::deque& other) + +etl::deque& + operator =(etl::deque&& other) + +etl::ideque& + operator =(const etl::ideque& other) + +etl::deque& + operator =(etl::deque&& 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`. diff --git a/docs/containers/packet.md b/docs/containers/packet.md new file mode 100644 index 00000000..4533be50 --- /dev/null +++ b/docs/containers/packet.md @@ -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 +``` + +## Template parameters +`TBase` + The base class for all objects. The destructor must be virtual. + +`SIZE` + The size of the largest type. + +`ALIGNMENT` + The largest alignment of all of the types. + +## Member types + +`base_t` = `TBase` + +## Contructors + +**C++03** +```cpp +template +explicit packet(const T& value) +``` + +**C++11** +```cpp +template +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 +packet& operator =(const T& value) +``` + +**C++11** +```cpp +template +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. diff --git a/docs/containers/queues/_index.md b/docs/containers/queues/_index.md new file mode 100644 index 00000000..fae5dc75 --- /dev/null +++ b/docs/containers/queues/_index.md @@ -0,0 +1,6 @@ +--- +title: "Queues" +weight: 100 +--- + +Queue like containers. \ No newline at end of file diff --git a/docs/containers/queues/circular-buffer.md b/docs/containers/queues/circular-buffer.md new file mode 100644 index 00000000..cfc1b656 --- /dev/null +++ b/docs/containers/queues/circular-buffer.md @@ -0,0 +1,292 @@ +--- +title: "circular_buffer" +--- + +{{< callout >}} + Header: `circular_buffer.h` +{{< /callout >}} + +A fixed capacity circular buffer. + +```cpp +etl::circular_buffer +etl::circular_buffer_ext +``` + +Inherits from `etl::icircular_buffer` +`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 +``` +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 +etl::circular_buffer(T, Ts...) + -> etl::circular_buffer; +``` +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 +const_reverse_iterator reverse_iterator +``` + +## Static Constants + +`MAX_SIZE` The maximum size of the circular_buffer. + +## Constructors + +```cpp +circular_buffer(); + +circular_buffer(const etl::circular_buffer& other); + +circular_buffer(etl::circular_buffer&& other); +``` + +--- + +```cpp +circular_buffer_ext(void* buffer, size_t max_size) + +circular_buffer_ext(size_t max_size) 20.32.1 + +template +circular_buffer_ext(TIterator first, const TIterator& last, void* buffer, size_t max_size) + +circular_buffer_ext(std::initializer_list 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 +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& other) +``` +**Description** +Swaps the `circular_buffer` with `other`. + +--- + +```cpp +void swap(circular_buffer_ext 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. diff --git a/docs/containers/vector.md b/docs/containers/vector.md index e3fe14a9..f7981f90 100644 --- a/docs/containers/vector.md +++ b/docs/containers/vector.md @@ -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 +etl::vector_ext +``` + +## ivector +Inherits from `etl::ivector` +`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 +``` +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 +etl::vector(T...) + +template +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 +const_reverse_iterator ETL_OR_STD::reverse_iterator +``` + +## Constructors + +**Internal buffer** +```cpp +etl::vector(); +etl::vector(size_t initialSize); +etl::vector(size_t initialSize, const T& value); + +template +etl::vector(TIterator begin, TIterator end); + +etl::vector(const etl::vector&); +etl::vector(etl::vector&&); + +**External buffer** +etl::vector(void* buffer, size_t max_size); +etl::vector(size_t initialSize, void* buffer, size_t max_size); +etl::vector(size_t initialSize, const T& value, void* buffer, size_t max_size); + +template +etl::vector(TIterator begin, TIterator end, void* buffer, size_t max_size); + +etl::vector(const etl::vector&, void* buffer, size_t max_size); + +etl::vector(etl::vector&&, 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 +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 +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 +void emplace_back(Args&&... args) +``` + +Since: `20.35.10` +```cpp +template +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 +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 +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 +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 Data; + +Data data(8, 1); +char buffer[sizeof(Data)]; + +memcpy(&buffer, &data, sizeof(Data)); + +Data& rdata(*reinterpret_cast(buffer)); + +// Do not access the copied object in any way until you have called this. +rdata.repair(); +``` + +## Non-member functions + +```cpp +template +typename etl::ivector::difference_type erase(etl::ivector& v, const U& value) +``` +Erases all elements that compare equal to value from the vector. + +--- + +```cpp +template +typename etl::ivector::difference_type erase_if(etl::ivector& 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`. diff --git a/docs/multi-tasking/cooperative-scheduler.md b/docs/multi-tasking/cooperative-scheduler.md index d6bdeb90..90a4ee0b 100644 --- a/docs/multi-tasking/cooperative-scheduler.md +++ b/docs/multi-tasking/cooperative-scheduler.md @@ -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** diff --git a/docs/multi-tasking/task.md b/docs/multi-tasking/task.md index 094e9854..1194618c 100644 --- a/docs/multi-tasking/task.md +++ b/docs/multi-tasking/task.md @@ -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 ``` diff --git a/docs/raw/containers/circular_buffer.txt b/docs/raw/containers/circular_buffer.txt deleted file mode 100644 index 3d831a64..00000000 --- a/docs/raw/containers/circular_buffer.txt +++ /dev/null @@ -1,172 +0,0 @@ -circular_buffer - -A fixed capacity circular buffer. -STL equivalent: none - -etl::circular_buffer -etl::circular_buffer_ext - -Inherits from etl::icircular_buffer -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 -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 -etl::circular_buffer(T, Ts...) - -> etl::circular_buffer && ...), 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 -const_reverse_iterator reverse_iterator -____________________________________________________________________________________________________ -Static Constants - -MAX_SIZE The maximum size of the circular_buffer. -____________________________________________________________________________________________________ -Constructor - -circular_buffer(); - -circular_buffer(const etl::circular_buffer& other); - -circular_buffer(etl::circular_buffer&& other); -____________________________________________________________________________________________________ -circular_buffer_ext(void* buffer, size_t max_size) - -circular_buffer_ext(size_t max_size) 20.32.1 - -template -circular_buffer_ext(TIterator first, const TIterator& last, void* buffer, size_t max_size) - -circular_buffer_ext(std::initializer_list 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 -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& other) -Swaps the circular_buffer with other. - -void swap(circular_buffer_ext 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. - - diff --git a/docs/raw/containers/deque.txt b/docs/raw/containers/deque.txt deleted file mode 100644 index c52cdad8..00000000 --- a/docs/raw/containers/deque.txt +++ /dev/null @@ -1,360 +0,0 @@ -deque - -A fixed capacity deque. -STL equivalent: std::deque - -etl::deque - -Inherits from etl::ideque -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 -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 - constexpr auto make_deque(TValues&&... values) - -Example -auto data = etl::make_deque(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 -const_reverse_iterator std::reverse_iterator -____________________________________________________________________________________________________ -Static Constants - -MAX_SIZE The maximum size of the deque. -____________________________________________________________________________________________________ -Constructor - -etl::deque(); -etl::deque(size_t initialSize); -etl::deque(size_t initialSize, parameter_t value); - -template -etl::deque(TIterator begin, TIterator end); - -etl::deque(const etl::deque& other); -etl::deque(etl::deque&& 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 -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 -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 -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 -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 -iterator emplace(iterator insert_position, const T1& value1) - -template -iterator emplace(iterator insert_position, const T1& value1, const T2& value2) - -template -iterator emplace(iterator insert_position, const T1& value1, const T2& value2, - const T3& value3) - -template -iterator emplace(iterator insert_position, const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -iterator emplace(iterator insert_position, Args&& ... args) - ->=20.20.0 -C++03 -template -iterator emplace(const_iterator insert_position, const T1& value1) - -template -iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2) - -template -iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2, - const T3& value3) - -template -iterator emplace(const_iterator insert_position, const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -iterator emplace(const_iterator insert_position, Args&& ... args) -____________________________________________________________________________________________________ -<=20.35.9 -C++03 -template -void emplace_front(const T1& value1) - -template -void emplace_front(const T1& value1, const T2& value2) - -template -void emplace_front(const T1& value1, const T2& value2, - const T3& value3) - -template -void emplace_front(const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -void emplace_front(Args&& ... args) - ->=20.35.10 -C++03 -template -reference emplace_front(const T1& value1) - -template -reference emplace_front(const T1& value1, const T2& value2) - -template -reference emplace_front(const T1& value1, const T2& value2, - const T3& value3) - -template -reference emplace_front(const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -reference emplace_front(Args&& ... args) -____________________________________________________________________________________________________ -<=20.35.9 -C++03 -template -void emplace_back(const T1& value1) - -template -void emplace_back(const T1& value1, const T2& value2) - -template -void emplace_back(const T1& value1, const T2& value2, - const T3& value3) - -template -void emplace_back(const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -void emplace_back(Args&& ... args) - ->=20.35.10 -C++03 -template -reference emplace_back(const T1& value1) - -template -reference emplace_back(const T1& value1, const T2& value2) - -template -reference emplace_back(const T1& value1, const T2& value2, - const T3& value3) - -template -reference emplace_back(const T1& value1, const T2& value2, - const T3& value3, const T4& value4) - -C++11 and above -template -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 Data; - -Data data(8, 1); - -char buffer[sizeof(Data)]; - -memcpy(&buffer, &data, sizeof(Data)); - -Data& rdata(*reinterpret_cast(buffer)); - -// Do not access the copied object in any way until you have called this. -rdata.repair(); -____________________________________________________________________________________________________ - -etl::deque& - operator =(const etl::deque& other); - -etl::deque& - operator =(etl::deque&& other); - -etl::ideque& - operator =(const etl::ideque& other); - -etl::deque& - operator =(etl::deque&& 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. - - diff --git a/docs/raw/utilities/Memory.txt b/docs/raw/utilities/Memory.txt deleted file mode 100644 index f8f3ceb9..00000000 --- a/docs/raw/utilities/Memory.txt +++ /dev/null @@ -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 -T* addressof(T& t) -Returns the address of an object. -____________________________________________________________________________________________________ -default_delete - -template -struct default_delete - -template -struct default_delete -____________________________________________________________________________________________________ -Create / Destroy -Functions that create or destroy items in uninitialised memory. - -template -void create_default_at(T* p) - -template -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 -void create_value_at(T* p) - -template -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 -void create_copy_at(T* p) - -template -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 -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 -T& make_value_at(T* p) - -____________________________________________________________________________________________________ -template -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 -T& make_copy_at(T* p) -____________________________________________________________________________________________________ -template -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 -void destroy_at(T* p) -____________________________________________________________________________________________________ -template -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 -void destroy_n(T* p, TSize n) -____________________________________________________________________________________________________ -template -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 -void destroy(T* p, T* p_end) -____________________________________________________________________________________________________ -template -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 -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 -void create_copy_at(void* p, Tcounter& count); -____________________________________________________________________________________________________ -T& make_copy_at(void* p); -____________________________________________________________________________________________________ -template -T& make_copy_at(void* p, Tcounter& count); -____________________________________________________________________________________________________ -Example: -class Test : public etl::create_copy -{ - // 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 -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 -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 -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 -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 -TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value) - -template -TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter) - -Fills uninitialised memory with N values. -____________________________________________________________________________________________________ -template -TIterator uninitialized_fill(TIterator o_begin, TIterator o_end, const T& value) - -template -TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter) - -Fills uninitialised memory range with a value. -____________________________________________________________________________________________________ -uninitialised_copy - -template -TIterator uninitialized_copy(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin) - -template -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 -TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin) - -template -TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin, typename TCounter) - -Copies N objects to uninitialised memory. -____________________________________________________________________________________________________ -uninitialized_move - -template -TIterator uninitialized_move(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin) - -template -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 -TIterator uninitialized_move_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin) - -template -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 -void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end) -____________________________________________________________________________________________________ -template -void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end, typename TCounter) -____________________________________________________________________________________________________ -template -TOutputIterator uninitialized_default_construct_n(TOutputIterator o_begin, TSize n) -____________________________________________________________________________________________________ -template -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 -void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end) -____________________________________________________________________________________________________ -template -void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end, TCounter& count) -____________________________________________________________________________________________________ -template -TOutputIterator uninitialized_value_construct_n(TOutputIterator o_begin, TSize n) -____________________________________________________________________________________________________ -template -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 -class unique_ptr -____________________________________________________________________________________________________ -template -class unique_ptr -____________________________________________________________________________________________________ -Memory clear - -void memory_clear(volatile char* p, size_t n) - -template -void memory_clear(volatile T &object) - -A low level function that clears an object's memory to zero. - -template -void memory_clear_range(volatile T* begin, size_t n) - -template -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 -void memory_set(volatile T &object, char value) - -Low level functions that clear an object's memory to a value. - -template -void memory_set_range(volatile T* begin, size_t n, char value) - -template -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 -struct wipe_on_destruct -T is the derived class whose storage must be wiped. - -Example - -struct UserData : public etl::wipe_on_destruct -{ - 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 -class uninitialized_buffer -Creates an uninitialized memory buffer of VN_Objects each of VObject_Size with alignment VAlignment. -____________________________________________________________________________________________________ -uninitialized_buffer_of - -template -class uninitialized_buffer_of -Creates an uninitialized memory buffer of VN_Objects each of type T. -____________________________________________________________________________________________________ -mem_copy -20.26.0 - -template -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 -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 -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 -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 -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 -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 -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 -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 -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 -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. - diff --git a/docs/strings/string.md b/docs/strings/string.md index 151b4bfe..56793a73 100644 --- a/docs/strings/string.md +++ b/docs/strings/string.md @@ -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 @@ -27,6 +29,7 @@ etl::u16string etl::u32string ``` +### 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. diff --git a/docs/utilities/error-handler.md b/docs/utilities/error-handler.md index 7aa31fd5..ea3ab091 100644 --- a/docs/utilities/error-handler.md +++ b/docs/utilities/error-handler.md @@ -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 `` 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)) diff --git a/docs/utilities/memory.md b/docs/utilities/memory.md new file mode 100644 index 00000000..46272db1 --- /dev/null +++ b/docs/utilities/memory.md @@ -0,0 +1,674 @@ +--- +title: "memory" +--- + +## address_of +```cpp +template +T* addressof(T& t) +``` +**Description** +Returns the address of an object. + +## default_delete +```cpp +template +struct default_delete +``` + +--- + +```cpp +template +struct default_delete +``` + +## create_default_at + +```cpp +template +void create_default_at(T* p) +``` +Creates a default value. For POD types this will be undefined. + +--- + +```cpp +template +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 +void create_value_at(T* p) +``` +Creates a default value by constructing the item with `T()`. + +--- + +```cpp +template +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 +void create_copy_at(T* p) +``` +Creates a default value by constructing the item with `T(value)`. + +--- + +```cpp +template +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 +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 +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 +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 +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 +T& make_copy_at(T* p) +``` + +--- + +```cpp +template +T& make_copy_at(T* p, const T& value, Tcounter count) +``` + +## destroy_at +```cpp +template +void destroy_at(T* p) +``` +Calls the destructor for non-pod types. + +--- + +```cpp +template +void destroy_at(T* p, TCounter& count) +``` +Calls the destructor for non-pod types. +The supplied counter will be decremented. + +## destroy_n +```cpp +template +void destroy_n(T* p, TSize n) +``` +Calls the destructor for a range of non-pod types, starting at address `p`. + +--- + +```cpp +template +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 +void destroy(T* p, T* p_end) +``` +Calls the destructor for a range of non-pod types, starting at address `p`. + +--- + +```cpp +template +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 +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 +void create_copy_at(void* p, Tcounter& count); +``` + +--- + +```cpp +T& make_copy_at(void* p); +``` + +--- + +```cpp +template +T& make_copy_at(void* p, Tcounter& count); +``` + +### Example: +```cpp +class Test : public etl::create_copy +{ + // 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 +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 +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 +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 +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 +TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value) +``` + +--- + +```cpp +template +TIterator uninitialized_fill_n(TIterator o_begin, TSize count, const T& value, typename TCounter) +``` +--- + +```cpp +template +TIterator uninitialized_fill(TIterator o_begin, TIterator o_end, const T& value) +``` + +--- + +```cpp +template +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 +TIterator uninitialized_copy(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin) +``` + +```cpp +template +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 +TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin) +``` + +--- + +```cpp +template +TIterator uninitialized_copy_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin, typename TCounter) +``` +Copies N objects to uninitialised memory. + +## uninitialized_move + +```cpp +template +TIterator uninitialized_move(TInputIterator i_begin, TInputIterator i_end, TOutputIterator o_begin) +``` + +```cpp +template +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 +TIterator uninitialized_move_n(TInputIterator i_begin, TSize count, TOutputIterator o_begin) +``` + +--- + +```cpp +template +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 +void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end) +``` + +--- + +```cpp +template +void uninitialized_default_construct(TOutputIterator o_begin, TOutputIterator o_end, typename TCounter) +``` + +--- + +```cpp +template +TOutputIterator uninitialized_default_construct_n(TOutputIterator o_begin, TSize n) +``` + +--- + +```cpp +template +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 +void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end) +``` + +--- + +```cpp +template +void uninitialized_value_construct(TOutputIterator o_begin, TOutputIterator o_end, TCounter& count) +``` + +--- + +```cpp +template +TOutputIterator uninitialized_value_construct_n(TOutputIterator o_begin, TSize n) +``` + +--- + +```cpp +template +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 +class unique_ptr +``` + +--- + +```cpp +template +class unique_ptr +``` + +## Memory clear + +```cpp +void memory_clear(volatile char* p, size_t n) +``` + +--- + +```cpp +template +void memory_clear(volatile T &object) +``` +A low level function that clears an object's memory to zero. + +## memory_clear_range + +```cpp +template +void memory_clear_range(volatile T* begin, size_t n) +``` + +--- + +```cpp +template +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 +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 +void memory_set_range(volatile T* begin, size_t n, char value) +``` + +--- + +```cpp +template +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 +struct wipe_on_destruct +``` +`T` is the derived class whose storage must be wiped. + +### Example +```cpp +struct UserData : public etl::wipe_on_destruct +{ + 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 +class uninitialized_buffer +``` +Creates an uninitialized memory buffer of `VN_Objects` each of `VObject_Size` with alignment `VAlignment`. + +## uninitialized_buffer_of + +```cpp +template +class uninitialized_buffer_of +``` +Creates an uninitialized memory buffer of `VN_Objects` each of type `T`. + +## mem_copy +Since: `20.26.0` + +```cpp +template +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 +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 +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 +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 +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 +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 +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 +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 +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 +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.