Added more documentation

docs/iterators/circular_iterator.md

@@ -1,131 +1,235 @@
-circular_iterator
-20.34.0
-An iterator wrapper where increments and decrements will roll around the boundaries of an iterator range.
-It is constructed with the begin and end of the range, plus an optional start position.
-May be used with forward, bidirectional and random access iterators.
+---
+title: "circular_iterator"
+---
 
+{{< callout type="info">}}
+  Header: `circular_iterator.h`  
+  Since: `20.34.0`  
+{{< /callout >}}
+
+An iterator wrapper where increments and decrements will roll around the boundaries of an iterator range.  
+It is constructed with the begin and end of the range, plus an optional start position.  
+May be used with forward, bidirectional and random access iterators.  
+
+```cpp
 template <typename TIterator>
 etl::circular_iterator final;
+```
 
-See also: fixed_iterator
-____________________________________________________________________________________________________
-Types
+## Types
 
+```cpp
 value_type
 difference_type
 pointer
 reference
 iterator_category
-____________________________________________________________________________________________________
-Constructors
+```
 
+## Constructors
+```cpp
 ETL_CONSTEXPR14 circular_iterator()
+```
 Default constructor.
 
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator(TIterator itr_begin, TIterator itr_end)
+```
 Construct from iterators.
 
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator(TIterator itr_begin, TIterator itr_end, TIterator itr_start)
+```
 Construct from iterators and start position
 
-ETL_CONSTEXPR14 circular_iterator(const circular_iterator& other)
-Copy constructor
-____________________________________________________________________________________________________
-Member functions
+---
 
+```cpp
+ETL_CONSTEXPR14 circular_iterator(const circular_iterator& other)
+```
+Copy constructor
+
+## Member functions
+```cpp
 ETL_CONSTEXPR14 circular_iterator& operator =(const circular_iterator& other)
+```
 Assignment operator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 size_t size() const
+```
 Returns the length of the range.
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 bool empty() const
+```
 Returns true if the range is empty.
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 value_type operator *()
+```
 Dereference operator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 const value_type operator *() const
+```
 Dereference operator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 TIterator operator ->()
+```
 -> operator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 const TIterator operator ->() const
+```
 -> operator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 operator TIterator() const
+```
 Conversion operator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 TIterator current() const
+```
 Conversion to the base iterator type
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator& operator ++()
-Increment
-Forward iterator
-Bidirectional iterator
+```
+Increment  
+Forward iterator  
+Bidirectional iterator  
 Random access iterator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator operator ++(int)
-Increment
-Forward iterator
-Bidirectional iterator
-Random access iterator
-____________________________________________________________________________________________________
+```
+Increment  
+Forward iterator  
+Bidirectional iterator  
+Random access iterator  
+
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator& operator --()
-Decrement
-Bidirectional iterator
-Random access iterator
-____________________________________________________________________________________________________
+``
+Decrement  
+Bidirectional iterator  
+Random access iterator  
+
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator operator --(int)
-Decrement
-Bidirectional iterator
-Random access iterator
-____________________________________________________________________________________________________
+```
+Decrement  
+Bidirectional iterator  
+Random access iterator  
+
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator& operator +=(difference_type offset)
-+= operator
+```
++= operator  
 Random access iterator
-____________________________________________________________________________________________________
+
+---
+
+```cpp
 ETL_CONSTEXPR14 circular_iterator& operator -=(typename 
                                                etl::iterator_traits<TIterator>::difference_type 
                                                offset)
+```
 -= operator
 Random access iterator
-____________________________________________________________________________________________________
-Non-member functions
 
+## Non-member functions
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14 
 typename etl::iterator_traits<TIterator>::difference_type 
 operator - (etl::circular_iterator<TIterator>& lhs, etl::circular_iterator<TIterator>& rhs)
-____________________________________________________________________________________________________
+```
+
+---
+
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14
 bool operator ==(const etl::circular_iterator<TIterator>& lhs,
                  const etl::circular_iterator<TIterator>& rhs)
-____________________________________________________________________________________________________
+```
+
+---
+
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14 bool operator ==(const etl::circular_iterator<TIterator>& lhs,
                                  TIterator rhs)
-____________________________________________________________________________________________________
+```
+
+---
+
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14 bool operator ==(TIterator lhs,
                                  const etl::circular_iterator<TIterator>& rhs)
-____________________________________________________________________________________________________
+```
+
+---
+
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14 bool operator !=(const etl::circular_iterator<TIterator>& lhs,
                                  const etl::circular_iterator<TIterator>& rhs)
-____________________________________________________________________________________________________
+```
+
+---
+
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14 bool operator !=(const etl::circular_iterator<TIterator>& lhs,
                                  TIterator rhs)
-____________________________________________________________________________________________________
+```
+
+---
+
+```cpp
 template <typename TIterator>
 ETL_CONSTEXPR14 bool operator !=(TIterator& lhs,
                                  const etl::circular_iterator<TIterator>& rhs)
-____________________________________________________________________________________________________
-Example
+```
 
+## Example
+```cpp
 std::list<int> data{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 };
 
 // The start position to loop from.
@@ -146,4 +250,4 @@ for (int = 0; i < 10; ++i)
 
 Prints the following
 (2,9)(5,6)(8,3)(1,0)(4,7)(7,4)(0,1)(3,8)(6,5)(9,2)
-
+```

docs/raw/utilities/Endian.txt

@@ -1,61 +0,0 @@
-Endian
-Constants & utilities for endianess
-
-For endian specific integral types, see unaligned_type.
-
-The values for endianness are dependant on the platform setup.
-
-If ETL_ENDIAN_NATIVE is defined by the user, then 
-  etl::endian::little = 0
-  etl::endian::big    = 1
-
-If ETL_ENDIAN_NATIVE is not defined by the user, then the ETL selects an appropriate definition.
-If ETL_CPP20_SUPPORTED == 1 and ETL_USING_STL == 1 then
-  etl::endian::little = std::endian::little
-  etl::endian::big    = std::endian::big
-  etl::endian::native = std::endian::native
-
-else, if __BYTE_ORDER__ is defined then
-  If __ORDER_LITTLE_ENDIAN__ is defined then
-    etl::endian::little =  __ORDER_LITTLE_ENDIAN__
-    etl::endian::big    =  __ORDER_BIG_ENDIAN__
-    etl::endian::native =  __BYTE_ORDER__
-
-  else if __LITTLE_ENDIAN__ is defined
-    etl::endian::little =  __LITTLE_ENDIAN__
-    etl::endian::big    =  __BIG_ENDIAN__
-    etl::endian::native =  __BYTE_ORDER__
-
-else
-  The user needs to define ETL_ENDIAN_NATIVE either as 0 for little endian or 1 for big endian.
-____________________________________________________________________________________________________
-endian
-
-A smart enumeration defining little and big members.
-
-etl::endian::little;
-etl::endian::big;
-____________________________________________________________________________________________________
-endianness
-
-Interrogates the endianness of the platform.
-
-etl::endian operator ()() const
-constexpr if ETL_CPP11_SUPPORTED == 1 and ETL_ENDIAN_NATIVE is defined.
-____________________________________________________________________________________________________
-operator etl::endian() const
-constexpr if ETL_CPP11_SUPPORTED == 1 and ETL_ENDIAN_NATIVE is defined.
-____________________________________________________________________________________________________
-static etl::endian value()
-constexpr if ETL_CPP11_SUPPORTED == 1 and ETL_ENDIAN_NATIVE is defined.
-____________________________________________________________________________________________________
-Host to network
-
-template <typename T>
-T hton(T value)
-____________________________________________________________________________________________________
-Network to host
-
-template <typename T>
-T ntoh(T value)
-

docs/raw/utilities/Memory Cast.txt

@@ -1,255 +0,0 @@
-Memory Cast 
-20.11.0
-
-Helper classes that simplify the interpretation of memory blocks.
-The member functions contain both compile and run time error checks for correct sized buffers.
-
-etl::mem_cast
-etl::mem_cast_ptr
-etl::mem_cast_types
-____________________________________________________________________________________________________
-Error types
-
-class mem_cast_exception : public etl::exception
-The base exception type for mem_cast types.
-
-class mem_cast_size_exception : public etl::mem_cast_exception
-The exception type when the type size is too large.
-
-class mem_cast_nullptr_exception : public etl::mem_cast_exception
-The exception type when the buffer pointer is null.
-____________________________________________________________________________________________________
-mem_cast
-This class owns an internal memory block, as defined by the template parameters.
-
-template <size_t Size, size_t Alignment>
-class mem_cast
-The class is parameterised by the required memory block size and alignment.
-____________________________________________________________________________________________________
-Member constants
-
-static ETL_CONSTANT size_t Size;
-static ETL_CONSTANT size_t Alignment;
-____________________________________________________________________________________________________
-Member functions
-mem_cast()
-Default constructor.
-The internal memory block contents are undefined.
-____________________________________________________________________________________________________
-template <size_t Other_Size, size_t Other_Alignment>
-mem_cast(const mem_cast<Other_Size, Other_Alignment>& other)
-Copy constructor.
-Copies the contents of the source buffer.
-Static asserts if the other buffer is not large enough.
-___________________________________________________________________________________________________
-template <size_t Other_Size, size_t Other_Alignment>
-mem_cast& operator =(const mem_cast<Other_Size, Other_Alignment>& rhs)
-Assignment operator.
-Static asserts if the rhs buffer is not large enough.
-___________________________________________________________________________________________________
-template <typename T>
-void assign(const T& value)
-Assign from value.
-Static asserts if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-void assign_at_offset(size_t offset, const T& value)
-Assign from value at an offset from the start of the memory block.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset>
-void assign_at_offset(const T& value)
-Assign from value at an offset from the start of the memory block.
-Static asserts if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, typename... TArgs>
-void emplace(TArgs... args)
-Emplace from parameters.
-Static asserts if the buffer is not large enough.
-C++11 or above.
-____________________________________________________________________________________________________
-template <typename T, typename... TArgs>
-void emplace_at_offset(size_t offset, TArgs... args)
-Emplace from parameters at an offset from the start of the memory block.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-C++11 or above.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset, typename... TArgs>
-void emplace_at_offset(TArgs... args)
-Emplace from parameters at an offset from the start of the memory block.
-Static asserts if the buffer is not large enough.
-C++11 or above.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD T& ref()
-Get a reference to T.
-Static asserts if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD const T& ref() const
-Get a const reference to T.
-Static asserts if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD T& ref_at_offset(size_t offset)
-Get a reference to T at an offset from the start of the memory block (dynamic).
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD const T& ref_at_offset(size_t offset) const
-Get a const reference to T at an offset from the start of the memory block (dynamic).
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset>
-ETL_NODISCARD T& ref_at_offset()
-Get a reference to T at an offset from the start of the memory block (static).
-Static asserts if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset>
-ETL_NODISCARD const T& ref_at_offset() const
-Get a const reference to T at an offset from the start of the memory block (static).
-Static asserts if the buffer is not large enough.
-____________________________________________________________________________________________________
-ETL_NODISCARD static ETL_CONSTEXPR size_t size()
-Get the size of the buffer.
-____________________________________________________________________________________________________
-ETL_NODISCARD static ETL_CONSTEXPR size_t alignment()
-Get the alignment of the buffer.
-____________________________________________________________________________________________________
-ETL_NODISCARD char* data()
-Get a pointer to the internal buffer.
-____________________________________________________________________________________________________
-ETL_NODISCARD const char* data() const
-Get a const pointer to the internal buffer
-____________________________________________________________________________________________________
-mem_cast_ptr
-This class contains a pointer to an external memory block.
-class mem_cast_ptr
-____________________________________________________________________________________________________
-Member constants
-
-static ETL_CONSTANT size_t Undefined_Size;
-____________________________________________________________________________________________________
-Member functions
-mem_cast_ptr()
-Default constructor.
-The internal pointer to the memory block is initialised as nullptr.
-The size is defined as Undefined_Size.
-____________________________________________________________________________________________________
-mem_cast_ptr(const mem_cast_ptr& other)
-Copy constructor.
-Copies the memory block pointer, not the contents of the memory block.
-____________________________________________________________________________________________________
-mem_cast_ptr& operator =(const mem_cast_ptr& rhs)
-Assignment operator.
-Copies the memory block pointer, not the contents of the memory block.
-____________________________________________________________________________________________________
-template <typename T>
-void assign(const T& value)
-Assign from value.
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-void assign_at_offset(size_t offset, const T& value)
-Assign from value at an offset from the start of the memory block.
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset>
-void assign_at_offset(const T& value)
-Assign from value at an offset from the start of the memory block.
-____________________________________________________________________________________________________
-template <typename T, typename... TArgs>
-void emplace(TArgs... args)
-Emplace from parameters.
-C++11 or above.
-____________________________________________________________________________________________________
-template <typename T, typename... TArgs>
-void emplace_at_offset(size_t offset, TArgs... args)
-Emplace from parameters at offset.
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-C++11 or above.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset, typename... TArgs>
-void emplace_at_offset(TArgs... args)
-Emplace from parameters at offset.
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-C++11 or above.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD T& ref()
-Get a reference to T.
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD const T& ref() const
-Get a const reference to T.
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD T& ref_at_offset(size_t offset)
-Get a reference to T at an offset from the start of the memory block (dynamic).
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T>
-ETL_NODISCARD const T& ref_at_offset(size_t offset) const
-Get a const reference to T at offset (dynamic).
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset>
-ETL_NODISCARD T& ref_at_offset()
-Get a reference to T at an offset from the start of the memory block (static).
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-template <typename T, size_t Offset>
-ETL_NODISCARD const T& ref_at_offset() const
-Get a const reference to T at an offset from the start of the memory block (static).
-Raises an etl::mem_cast_nullptr_exception ETL_ASSERT if the memory block pointer is null.
-Raises an etl::mem_cast_size_exception ETL_ASSERT if the buffer is not large enough.
-____________________________________________________________________________________________________
-ETL_NODISCARD size_t size() const
-Get the size of the buffer.
-____________________________________________________________________________________________________
-ETL_NODISCARD size_t alignment() const
-Get the alignment of the buffer.
-____________________________________________________________________________________________________
-void data(char* pbuffer, size_t buffer_size = Undefined_Size)
-Set the pointer to the external buffer.
-The default size is Undefined_Size.
-____________________________________________________________________________________________________
-ETL_NODISCARD char* data()
-Get a pointer to the internal buffer.
-____________________________________________________________________________________________________
-ETL_NODISCARD const char* data() const
-Get a const pointer to the internal buffer
-____________________________________________________________________________________________________
-mem_cast_types
-A variant of etl::mem_cast that deduces the size and alignment from the supplied list of types.
-____________________________________________________________________________________________________
-C++03
-template <typename T1,         typename T2  = char, typename T3  = char, typename T4  = char,
-          typename T5  = char, typename T6  = char, typename T7  = char, typename T8  = char,
-          typename T9  = char, typename T10 = char, typename T11 = char, typename T12 = char,
-          typename T13 = char, typename T14 = char, typename T15 = char, typename T16 = char>
-struct mem_cast_types :
-  public etl::mem_cast<etl::largest<T1, T2, T3, T4, T5, T6, T7, T8, 
-                                    T9, T10, T11, T12, T13, T14, T15, T16>::size,
-                       etl::largest<T1, T2, T3, T4, T5, T6, T7, T8,
-                                    T9, T10, T11, T12, T13, T14, T15, T16>::alignment>
-{
-};
-____________________________________________________________________________________________________
-C++11 and above
-template <typename... TTypes>
-using mem_cast_types = etl::mem_cast<etl::largest<TTypes...>::size, 
-                                     etl::largest<TTypes...>::alignment>;
-
-

docs/raw/utilities/bit_stream_reader.txt

@@ -1,163 +0,0 @@
-bit_stream_reader
-
-A binary streaming utility that allows values to be read from an array of char or unsigned char using custom bits widths for efficient packing. Values may be streamed in either msb or lsb format.
-
-Read functions come in both checked and unchecked forms.
-Unchecked reads return a value of the specified type.
-Checked reads assert that there is enough space to read the value, and return an etl::optional containing the type.
-
-bool
-Stored as 1 bit.
-
-Integrals
-By default, stored using full bit width, otherwise uses the specified width.
-
-Custom types
-The user may create specializations of the non-member etl::read functions to stream custom types. Specialisations must be defined in the etl namespace.
-____________________________________________________________________________________________________
-Types
-
-value_type     char
-const_iterator const char*
-____________________________________________________________________________________________________
-Member functions
-
-bit_stream_reader(etl::span<char> span, etl::endian stream_endianness)
-span
-A char span of the read buffer.
-stream_endianness
-The endianness of the stream.
-etl::endian::little or etl::endian::big 
-____________________________________________________________________________________________________
-bit_stream_reader(etl::span<unsigned char> span, etl::endian stream_endianness)
-span
-An unsigned char span of the read buffer.
-stream_endianness
-The endianness of the stream.
-etl::endian::little or etl::endian::big
-____________________________________________________________________________________________________
-bit_stream_reader(void* begin, void* end, etl::endian stream_endianness)
-begin
-A pointer to the beginning of the read buffer.
-end
-A pointer to the beginning of the read buffer.
-stream_endianness
-The endianness of the stream.
-etl::endian::little or etl::endian::big
-____________________________________________________________________________________________________
-bit_stream_reader(void* begin, size_t length, etl::endian stream_endianness)
-begin
-A pointer to the beginning of the read buffer.
-length
-The length, in char, of the read buffer.
-stream_endianness
-The endianness of the stream.
-etl::endian::little or etl::endian::big
-____________________________________________________________________________________________________
-void restart()
-Sets the reader back to the beginning of the stream.
-____________________________________________________________________________________________________
-bool read_unchecked<bool>()
-Unchecked read for bool types.
-
-etl::optional<bool> read<bool>()
-Checked read for bool types.
-____________________________________________________________________________________________________
-template <typename T>
-T read_unchecked(uint_least8_t nbits = CHAR_BIT * sizeof(T))
-Unchecked read.
-Enabled for integral types.
-
-template <typename T>
-etl::optional<T> read(uint_least8_t nbits = CHAR_BIT * sizeof(T))
-Checked read.
-Enabled for integral types.
-____________________________________________________________________________________________________
-bool skip(size_t nbits)
-Skip forward in the stream by nbits.
-If there are not enough bits remaining in the stream it assert an etl::bit_stream_overflow and return false.
-____________________________________________________________________________________________________
-size_t size_bytes() const
-Returns the number of bytes in the stream buffer.
-____________________________________________________________________________________________________
-size_t size_bits() const
-Returns the number of bits in the stream buffer.
-____________________________________________________________________________________________________
-const_iterator begin() const
-const_iterator cbegin() const
-Returns start of the stream buffer.
-____________________________________________________________________________________________________
-const_iterator end() const
-const_iterator cend() const
-Returns end of the stream.
-____________________________________________________________________________________________________
-etl::span<const char> data() const
-Returns a span of whole the stream buffer.
-____________________________________________________________________________________________________
-Non-member functions
-
-template <typename T>
-T read_unchecked(etl::bit_stream_reader& stream)
-Reads an unchecked type from a stream by calling stream.read_unchecked<T>()
-
-template <typename T>
-T read_unchecked(etl::bit_stream_reader& stream, uint_least8_t nbits)
-Reads an unchecked type from a stream by calling stream.read_unchecked<T>(nbits)
-____________________________________________________________________________________________________
-template <typename T>
-etl::optional<T> read(etl::bit_stream_reader& stream)
-Reads a checked type from a stream by calling stream.read<T>()
-
-template <typename T>
-etl::optional<T> read(etl::bit_stream_reader& stream, uint_least8_t nbits)
-Reads a checked type from a stream by calling stream.read<T>(nbits)
-____________________________________________________________________________________________________
-template <>
-bool read_unchecked<bool>(etl::bit_stream_reader& stream)
-Specialisation for bool.
-Reads an unchecked bool from a stream by calling stream.read_unchecked<bool>()
-
-template <>
-etl::optional<bool> read<bool>(etl::bit_stream_reader& stream)
-Specialisation for bool.
-Reads a checked bool from a stream by calling stream.read<bool>()
-____________________________________________________________________________________________________
-By specialisation of the templates, the user may create readers for custom types.
-____________________________________________________________________________________________________
-Example
-
-char c           = 26;         // 6 bits
-unsigned short s = 6742;       // 13 bits
-int32_t i        = 2448037;    // 23 bits
-
-struct CustomType
-{
-char c           = -10;       // 7 bits
-unsigned short s = 1878;      // 11 bits
-int32_t i        = -10836646; // 25 bits
-};
-
-namespace etl
-{
-  // Specialisation for Custom.
-  // Must be defined in the etl namespace.
-  template <>
-  etl::optional<CustomType> read_unchecked<CustomType>(etl::bit_stream_reader& stream)
-  {
-    char c    = stream.read_unchecked<char, 7U>();
-    short s   = stream.read_unchecked<short , 11U>();
-    int32_t i = stream.read_unchecked<int32_t, 25U>();
-
-    return CustomType { c.value(), s.value(), i.value() };
-  }
-}
-
-std::array<char, 100U> storage; // Assume the buffer gets filled with bit stream data.
-etl::bit_stream_reader bit_stream(storage.data(), storage.size());
-
-// Read unchecked values from the stream.
-char c            = etl::read_unchecked<char>(bit_stream, 6U);
-unsigned short s  = etl::read_unchecked<unsigned short>(bit_stream, 13U);
-CustomType custom = etl::read_unchecked<Custom>(bit_stream);
-int32_t i         = etl::read_unchecked<>(bit_stream, 23U);
-

docs/raw/utilities/bit_stream_writer.md

@@ -0,0 +1,408 @@
+---
+title: "bit_stream_writer"
+---
+
+{{< callout type="info">}}
+  Header: `bit_stream_writer.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+A binary streaming utility that allows values to be written to an array of char or unsigned char using custom bits widths for efficient packing. Values may be streamed in either msb or lsb format.
+
+Write functions come in both checked and unchecked forms.
+- Unchecked writes return `void`.
+- Checked writes assert that there is enough space to store the value, and return a `bool` indicating success or failure.
+
+A callback delegate can be assigned that will be called with a span of filled bytes.
+If the callback is used then the stream is reset to empty or the last unfilled byte after each callback. This allows a very small buffer to be assigned.
+
+## Storage
+`bool` 
+Stored as 1 bit.
+
+Integrals
+By default, stored using full bit width, otherwise uses the specified width.
+
+Custom types
+The user may create specializations of the non-member etl::write functions to stream custom types. Specialisations must be defined in the `etl` namespace.
+
+## Types
+
+```cpp
+value_type              char
+iterator                value_type*
+const_iterator          const value_type*   
+callback_parameter_type etl::span<value_type>
+callback_type           etl::delegate<void(callback_parameter_type)>
+```
+
+## Member functions
+```cpp
+bit_stream_writer(etl::span<char> span, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from span.  
+**Parameters**  
+`span` A char span of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.   
+`callback` An optional callback.
+
+---
+
+```cpp
+bit_stream_writer(etl::span<unsigned char> span, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from span.  
+**Parameters**  
+`span` A char span of the read buffer.  
+`stream_endianness` The endianness of the stream. etl::endian::little or etl::endian::big.  
+`callback` An optional callback.
+
+---
+
+```cpp
+bit_stream_writer(void* begin, void* end, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from range.  
+**Parameters**  
+`begin` A pointer to the beginning of the read buffer.  
+`end` A pointer to the beginning of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+`callback` An optional callback.
+
+---
+
+```cpp
+bit_stream_writer(void* begin, size_t length_chars, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from begin and length.  
+**Parameters**  
+`begin` A pointer to the beginning of the read buffer.  
+`length` The length, in char, of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+
+---
+
+```cpp
+void restart()
+```
+**Description**  
+Sets the indexes back to the beginning of the stream.
+
+---
+
+```cpp
+size_t capacity_bytes() const
+```
+**Description**  
+Returns the maximum capacity in bytes.
+
+---
+
+```cpp
+size_t capacity_bits() const
+```
+**Description**  
+Returns the maximum capacity in bits.
+
+---
+
+```cpp
+bool empty() const
+```
+**Description**  
+Returns true if the bitsteam indexes have been reset
+
+---
+
+```cpp
+bool full() const
+```
+**Description**  
+Returns true if the bitsteam indexes have reached the end
+
+---
+
+```cpp
+void write_unchecked(bool value)
+```
+**Description**  
+Writes a boolean to the stream.
+
+---
+
+```cpp
+bool write(bool value)
+```
+**Description**  
+Writes a boolean to the stream.
+
+---
+
+```cpp
+template <typename T>
+void write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Enabled for integral types.
+
+---
+
+```cpp
+template <typename T>
+bool write(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Enabled for integral types.
+
+---
+
+```cpp
+bool skip(size_t nbits)
+```
+**Description**  
+Skip forward in the stream by nbits.  
+If there are not enough bits remaining in the stream it assert an etl::bit_stream_overflow and return false.
+
+---
+
+```cpp
+size_t size_bytes() const
+```
+**Description**  
+Returns the number of bytes used in the stream.
+
+---
+
+```cpp
+size_t size_bits() const
+```
+**Description**  
+Returns the number of bits used in the stream.
+
+---
+
+```cpp
+template <size_t Nbits>
+size_t available() const
+```
+**Description**  
+The number of multiples of Nbits available in the stream.  
+Compile time.
+
+---
+
+```cpp
+template <typename T>
+size_t available() const
+```
+**Description**  
+The number of T available in the stream.  
+Compile time.
+
+---
+
+```cpp
+size_t available(size_t nbits) const
+```
+**Description**  
+The number of 'bit width' available in the stream.  
+Run time.
+
+---
+
+```cpp
+size_t available_bits() const
+```
+**Description**  
+The number of bits left in the stream.
+
+---
+
+```cpp
+iterator begin()
+```
+**Description**  
+Returns start of the stream.
+
+---
+
+```cpp
+const_iterator begin() const
+```
+**Description**  
+Returns start of the stream.
+
+---
+
+```cpp
+const_iterator cbegin() const
+```
+**Description**  
+Returns start of the stream.
+
+---
+
+```cpp
+iterator end()
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+const_iterator end() const
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+const_iterator cend() const
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+etl::span<char> used_data()
+```
+**Description**  
+Returns a span of the used portion of the stream.
+
+---
+
+```cpp
+etl::span<const char> used_data() const
+```
+**Description**  
+Returns a span of the used portion of the stream.
+
+---
+
+```cpp
+etl::span<char> data()
+```
+**Description**  
+Returns a span of whole the stream.
+
+---
+
+```cpp
+etl::span<const char> data() const
+```
+**Description**  
+Returns a span of whole the stream.
+
+---
+
+```cpp
+void flush()
+```
+**Description**  
+Flush the last byte, if partially filled, to the callback.
+This is only required when a callback delegate has been set.
+
+---
+
+```cpp
+void set_callback(callback_type callback_)
+```
+**Description**  
+Sets the delegate to call afer every write.
+
+---
+
+```cpp
+callback_type get_callback() const
+```
+**Description**  
+Gets the function to call afer every write.
+
+---
+
+## Non-member functions
+
+```cpp
+void write_unchecked(etl::bit_stream_writer& stream, bool value)
+```
+**Description**  
+Implementation of the write unchecked function.
+For bool types only.
+
+---
+
+```cpp
+bool write(etl::bit_stream_writer& stream, bool value)
+```
+**Description**  
+Implementation of the write function.
+For bool types only.
+
+---
+
+```cpp
+template <typename T>
+void write_unchecked(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+  Default implementation of the write function.
+  For integral types only (but not bool).
+  Overload this to support custom types.
+
+---
+
+```cpp
+template <typename T>
+bool write(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Default implementation of the write function.
+For integral types only (but not bool).
+Overload this to support custom types.
+
+---
+
+By specialisation of the templates, the user may create writers for custom types.
+
+## Example
+```cpp
+char c           = 26;         // 6 bits
+unsigned short s = 6742;       // 13 bits
+int32_t i        = 2448037;    // 23 bits
+
+struct CustomType
+{
+char c           = -10;       // 7 bits
+unsigned short s = 1878;      // 11 bits
+int32_t i        = -10836646; // 25 bits
+};
+
+namespace etl
+{
+  // Specialisation for Custom.
+  // Must be defined in the etl namespace.
+  template <>
+  void write_unchecked<CustomType>(etl::bit_stream_reader& stream)
+  {
+    stream.write_unchecked<char, 7U>();
+    stream.write_unchecked<short , 11U>();
+    stream.write_unchecked<int32_t, 25U>();
+  }
+}
+
+std::array<char, 100U> storage; // Assume the buffer gets filled with bit stream data.
+etl::bit_stream_reader bit_stream(storage.data(), storage.size());
+
+// Write unchecked values to the stream.
+etl::write_unchecked<char>(bit_stream, 6U);
+etl::write_unchecked<unsigned short>(bit_stream, 13U);
+etl::write_unchecked<Custom>(bit_stream);
+etl::write_unchecked<>(bit_stream, 23U);
+```

docs/raw/utilities/integral_limits.txt

@@ -1,23 +0,0 @@
-integral_limits
-A set of templated constants to determine limits of integral types at compile time.
-Defines the following constants for each integral type:-
-
-Member constants
-min        The minimum value the type can hold.
-max        The maximum value the type can hold.
-bits       The number of bits used for this type.
-is_signed  Whether the type is signed.
-
-Example
-template <const size_t SIZE>
-struct Value
-{
-  etl::array<T, SIZE> data;
-};
-
-template <typename T>
-void foo(const Value<etl::integral_limits<T>::bits>& value)
-{
-  size_t size = value.data.size(); // Same as the number of bits that represent a T
-}
-

docs/raw/utilities/not_null.txt

@@ -1,59 +0,0 @@
-not_null
-20.43.0
-A container for pointers that are not allowed to be null.
-
-template <typename T>
-class not_null;
-
-Specialised for pointers and etl::unique_ptr.
-
-template <typename T>
-class not_null<T*> 
-
-template <typename T, typename TDeleter>
-class not_null<etl::unique_ptr<T, TDeleter>> 
-____________________________________________________________________________________________________
-Public types
-
-T        value_type;
-T*       pointer;
-const T* const_pointer;
-T&       reference;
-const T& const_reference;
-pointer  underlying_type;
-____________________________________________________________________________________________________
-Member functions
-
-explicit not_null(underlying_type ptr)
-Constructs a not_null from an underlying type.
-Asserts etl::not_null_contains_null if the pointer is null.
-
-not_null(const etl::not_null<T*>& other)
-Copy constructor from a not_null.
-____________________________________________________________________________________________________
-not_null& operator =(const etl::not_null<T*>& rhs) 
-Assignment from a not_null.
-
-not_null& operator =(underlying_type rhs) 
-Assignment from a pointer.
-Asserts etl::not_null_contains_null if the pointer is null.
-____________________________________________________________________________________________________
-pointer get() const 
-Gets the underlying pointer.
-____________________________________________________________________________________________________
-operator pointer() const 
-Implicit conversion to pointer.
-____________________________________________________________________________________________________
-reference operator*() const
-Dereference operator.
-____________________________________________________________________________________________________
-pointer operator->() const 
-Arrow operator.
-____________________________________________________________________________________________________
-underlying_type& underlying() 
-Gets a reference to the underlying type.
-
-const underlying_type& underlying() const 
-Gets a const reference to the underlying type.
-____________________________________________________________________________________________________
-

docs/raw/utilities/nth_type.txt

@@ -1,14 +0,0 @@
-nth_type
-
-
-Defines the nth type in a variadic list of types.
-
-template <size_t N, typename... TTypes>
-struct nth_type;
-
-template <size_t N, typename... TTypes>
-using nth_type_t = typename nth_type<N, TTypes...>::type;
-
-Member type is defined as the nth type in the type list.
-Static asserts if N is out of range.
-

docs/raw/utilities/nullptr.txt

@@ -1,8 +0,0 @@
-nullptr
-
-
-Defines ETL_NULLPTR as either nullptr or NULL, dependent on the compiler support.
-
-Defines etl::nullptr_t
-20.39.0
-

docs/raw/utilities/numeric.txt

@@ -1,26 +0,0 @@
-numeric
-Numeric functions reverse engineered from C++ 11.
-
-____________________________________________________________________________________________________
-iota
-Fills a range of elements with sequentially increasing values starting with value.
-See std::iota
-
-template <typename TIterator, typename T>
-void iota(TIterator first, TIterator last, T value);
-____________________________________________________________________________________________________
-lerp
-Returns the result of a + t(b − a)
-
-template <typename T>
-T lerp(T a, T b, T t) ETL_NOEXCEPT
-____________________________________________________________________________________________________
-midpoint
-Calculates the midpoint of integers, floating-points, or pointers.
-
-template <typename T>
-ETL_CONSTEXPR T midpoint(T a, T b)
-
-template <typename T>
-ETL_CONSTEXPR T midpoint(T* a, T* b)
-

docs/types/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Types"
+weight: 100
+---
+
+Classes that work with types.

docs/types/largest.md

@@ -1,36 +1,50 @@
-largest
-Allows the largest type or largest alignment to be determined.
-This file is generated from largest_generator.h. See Generators
+---
+title: "largest"
+---
 
-____________________________________________________________________________________________________
-largest_type
-Template to determine the largest type and size. 
-Defines type and size of the  largest type parameter.
+{{< callout type="info">}}
+  Header: `largest.h`  
+  Since: `TBC`  
+{{< /callout >}}
 
-____________________________________________________________________________________________________
-C++ 03
+Allows the largest type or largest alignment to be determined.  
+This file is generated from `largest_generator.h`. See Generators
+
+## largest_type
+Template to determine the largest type and size.  
+Defines type and size of the  largest type parameter.  
+
+### C++ 03
 By default, supports up to 16 types.
 
+```cpp
 template <typename T1,         typename T2  = void, typename T3  = void, typename T4  = void,
           typename T5  = void, typename T6  = void, typename T7  = void, typename T8  = void,
           typename T9  = void, typename T10 = void, typename T11 = void, typename T12 = void,
           typename T13 = void, typename T14 = void, typename T15 = void, typename T16 = void>
 struct largest_type;
+```
 
-C++ 11 and above
+### C++ 11 and above
+```cpp
 template <typename... TTypes>
 struct largest_type;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <typename... T>
 using largest_type_t = typename largest_type<T...>::type;
+```
 
-C++17 and above
+### C++17 and above
+```cpp
 template <typename... T>
 constexpr size_t largest_type_v = largest_type<T...>::size;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 template <typename T1, typename T2, typename T3>
 struct Test
 {
@@ -43,31 +57,35 @@ struct Test
     size = etl::largest_type<T1, T2, T3>::size;
   }
 };
+```
 
-____________________________________________________________________________________________________
-largest_alignment
-Template to determine the largest alignment. By default, supports up to 16 types.
+## largest_alignment
+Template to determine the largest alignment.    
 Defines value which is the largest alignment.
 
-____________________________________________________________________________________________________
-C++ 03
-
+### C++ 03
+```cpp
 template <typename T1,         typename T2  = void, typename T3  = void, typename T4  = void,
           typename T5  = void, typename T6  = void, typename T7  = void, typename T8  = void,
           typename T9  = void, typename T10 = void, typename T11 = void, typename T12 = void,
           typename T13 = void, typename T14 = void, typename T15 = void, typename T16 = void>
 struct largest_alignment;
+```
 
-C++ 11 and above
+### C++ 11 and above
+```cpp
 template <typename... TTypes>
 struct largest_alignment;
+```
 
-C++ 17 and above
+### C++ 17 and above
+```cpp
 template <typename... T>
 constexpr size_t largest_alignment_v = largest_alignment<T...>::size;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 template <typename T1, typename T2, typename T3>
 struct Test
 {
@@ -77,92 +95,106 @@ struct Test
     ALIGNMENT = etl::largest_alignment<T1, T2, T3>::value
   };
 };
+```
 
-____________________________________________________________________________________________________
-larger_int_type
-Template to determine the next larger sized signed int type. The template type maybe signed or unsigned.
+## larger_int_type
+Template to determine the next larger sized signed int type. The template type maybe signed or unsigned.  
 If there is no larger type then the signed version of the original type is returned.
 
+```cpp
 template <typename T>
 struct larger_int_type;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <typename... T>
 using larger_int_type_t = typename larger_int_type<T...>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Would normally define type_t as an int
 typedef etl::larger_int_type<short>::type type_t; 
 
 // Would normally define type_t as an int
 typedef etl::larger_int_type<unsigned short>::type type_t; 
+```
 
-____________________________________________________________________________________________________
-larger_uint_type
-Template to determine the next larger sized unsigned int type. The template type maybe signed or unsigned.
+## larger_uint_type
+Template to determine the next larger sized unsigned int type. The template type maybe signed or unsigned.  
 If there is no larger type then the unsigned version of the original type is returned.
 
+```cpp
 template <typename T>
 struct larger_uint_type;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <typename... T>
 using larger_int_type_t = typename larger_int_type<T...>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Would normally define type_t as an unsigned int
 typedef etl::larger_uint_type<short>::type type_t; 
 
 // Would normally define type_t as an unsigned int
 typedef etl::larger_uint_type<unsigned short>::type type_t; 
+```
 
-____________________________________________________________________________________________________
-larger_type
-Template to determine the next larger sized int type. The template type maybe signed or unsigned.
-Signed parameters define signed types, unsigned parameters define unsigned types.
+## larger_type
+Template to determine the next larger sized int type. The template type maybe signed or unsigned.  
+Signed parameters define signed types, unsigned parameters define unsigned types.  
 If there is no larger type then the original type is returned.
 
+```cpp
 template <typename T>
 struct larger_type;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <typename... T>
 using larger_type_t = typename larger_type<T...>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Would normally define type_t as an int
 typedef etl::larger_type<short>::type type_t;
 
 // Would normally define type_t as an unsigned int
 typedef etl::larger_type<unsigned short>::type type_t;
+```
 
-____________________________________________________________________________________________________
-largest
-A handy combination of two of the previous templates.
-Template to determine the largest type, size and alignment. By default, supports up to 16 types.
-Defines type which is the type of the largest type parameter.
-Defines size which is the size of the largest parameter.
-Defines alignment which largest alignment of all the type parameters.
-NOTE: This may not be the alignment of the largest type.
+## largest
+A handy combination of two of the previous templates.  
+Template to determine the largest type, size and alignment.  
+Defines type which is the type of the largest type parameter.  
+Defines size which is the size of the largest parameter.  
+Defines alignment which largest alignment of all the type parameters.  
+NOTE: This may not be the alignment of the largest type.  
 
-____________________________________________________________________________________________________
-C++ 03
+### C++ 03
+```cpp
 template <typename T1,         typename T2  = void, typename T3  = void, typename T4  = void,
           typename T5  = void, typename T6  = void, typename T7  = void, typename T8  = void,
           typename T9  = void, typename T10 = void, typename T11 = void, typename T12 = void,
           typename T13 = void, typename T14 = void, typename T15 = void, typename T16 = void>
 struct largest;
+```
 
-____________________________________________________________________________________________________
-C++ 11 and above
+### C++ 11 and above
+```cpp
 template <typename... TTypes>
 struct largest;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <typename... T>
 using largest_t = typename largest<T...>::type;
-
-
+```

docs/types/smallest.md

@@ -1,37 +1,51 @@
-smallest
-Allows the smallest type to be determined.
+---
+title: "smallest"
+---
+
+{{< callout type="info">}}
+  Header: `smallest.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+Allows the smallest type to be determined.  
 This file is generated from smallest_generator.h. See Generators
 
-____________________________________________________________________________________________________
-smallest _type
-Template to determine the smallest type
-Defines type which is the type of the smallest parameter.
-Defines size which is the size of the smallest parameter.
+## smallest _type
+Template to determine the smallest type  
+Defines type which is the type of the smallest parameter.  
+Defines size which is the size of the smallest parameter.  
 
-____________________________________________________________________________________________________
-C++ 03
+### C++ 03
 By default, supports up to 16 types.
 
+```cpp
 template <typename T1,         typename T2  = void, typename T3  = void, typename T4  = void,
           typename T5  = void, typename T6  = void, typename T7  = void, typename T8  = void,
           typename T9  = void, typename T10 = void, typename T11 = void, typename T12 = void,
           typename T13 = void, typename T14 = void, typename T15 = void, typename T16 = void>
 struct smallest_type;
+```
 
-C++ 11 and above
+### C++ 11 and above
+```cpp
 template <typename... TTypes>
 struct smallest_type;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <typename... T>
 using smallest_type_t = typename smallest_type<T...>::type;
+```
 
-C++17 and above
+### C++17 and above
+```cpp
 template <typename... T>
 constexpr size_t smallest_type_v = smallest_type<T...>::size;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 template <typename T1, typename T2, typename T3>
 struct Test
 {
@@ -44,73 +58,88 @@ struct Test
     size = etl::largest_type<T1, T2, T3>::size;
   }
 };
+```
 
-____________________________________________________________________________________________________
-smallest_int_for_bits
-Template to determine the smallest integral type that will accommodate the required number of bits.
+## smallest_int_for_bits
+Template to determine the smallest integral type that will accommodate the required number of bits.  
 Defines type which is the type of the smallest integer type.
 
+```cpp
 template <size_t N>
 struct smallest_int_for_bits;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <size_t N>
 using smallest_int_for_bits_t = typename smallest_int_for_bits<N>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Defines type_t as the type that will accommodate 12 bits.
 typedef typename etl::smallest_int_for_bits<12>::type type_t;
+```
 
-____________________________________________________________________________________________________
-smallest_uint_for_bits
-Template to determine the smallest integral type that will accommodate the required number of bits.
+## smallest_uint_for_bits
+Template to determine the smallest integral type that will accommodate the required number of bits.  
 Defines type which is the type of the smallest unsigned integer type.
 
+```cpp
 template <size_t N>
 struct smallest_uint_for_bits;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <size_t N>
 using smallest_uint_for_bits_t = typename smallest_uint_for_bits<N>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Defines type_t as the type that will accommodate 12 bits.
 typedef typename etl::smallest_uint_for_bits<>::type type_t;
+```
 
-____________________________________________________________________________________________________
-smallest_int_for_value
-Template to determine the smallest integral type that will accommodate the value.
+## smallest_int_for_value
+Template to determine the smallest integral type that will accommodate the value.  
 Defines type which is the type of the smallest integer type.
 
+```cpp
 template <intmax_t VALUE>
 struct smallest_int_for_value;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <intmax_t VALUE>
 using smallest_int_for_value_t = typename smallest_int_for_value<VALUE>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Defines type_t as the signed type that will accommodate a value of 193.
 typedef typename etl::smallest_int_for_value<193>::type type_t;
+```
 
-____________________________________________________________________________________________________
-smallest_uint_for_value
-Template to determine the smallest unsigned integral type that will accommodate the value.
+## smallest_uint_for_value
+Template to determine the smallest unsigned integral type that will accommodate the value.  
 Defines type which is the type of the smallest unsigned integer type.
 
+```cpp
 template <const uintmax_t VALUE>
 struct smallest_uint_for_value;
+```
 
-C++14 and above
+### C++14 and above
+```cpp
 template <uintmax_t VALUE>
 using smallest_uint_for_value_t = typename smallest_uint_for_value<VALUE>::type;
+```
 
-____________________________________________________________________________________________________
-Example
+### Example
+```cpp
 // Defines type_t as the smallest unsigned type that will accommodate a value of 193.
 typedef typename etl::smallest_uint_for_value<193>::type type_t;
-
-
+```

docs/utilities/alignment.md

@@ -2,6 +2,11 @@
 title: alignment
 ---
 
+{{< callout type="info">}}
+  Header: `alignment.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
 A way of aligning memory storage through template parameters.
 
 ## type_with_alignment

docs/utilities/bit_stream_reader.md

@@ -0,0 +1,262 @@
+---
+title: "bit_stream_reader"
+---
+
+{{< callout type="info">}}
+  Header: `bit_stream_reader.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+A binary streaming utility that allows values to be read from an array of char or unsigned char using custom bits widths for efficient packing. Values may be streamed in either msb or lsb format.  
+
+Read functions come in both checked and unchecked forms.  
+- Unchecked reads return a value of the specified type.  
+- Checked reads assert that there is enough space to read the value, and return an `etl::optional`.  
+
+## Storage Size
+
+- `bool`  
+Stored as 1 bit.  
+
+- Integrals  
+By default, stored using full bit width, otherwise uses the specified width.  
+
+- Custom types  
+The user may create specializations of the non-member `etl::read` functions to stream custom types. Specialisations must be defined in the `etl` namespace.  
+
+## Types
+
+```cpp
+value_type     char
+const_iterator const char*
+```
+
+---
+
+## Member functions
+
+```cpp
+bit_stream_reader(etl::span<char> span, etl::endian stream_endianness)
+```
+**Parameters**  
+`span` A `char` span of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+
+---
+
+```cpp
+bit_stream_reader(etl::span<unsigned char> span, etl::endian stream_endianness)
+```
+**Parameters**  
+`span` `An unsigned char span` of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+
+---
+
+```cpp
+bit_stream_reader(void* begin, void* end, etl::endian stream_endianness)
+```
+`begin` A pointer to the beginning of the read buffer.  
+`end` A pointer to the beginning of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+
+---
+
+```cpp
+bit_stream_reader(void* begin, size_t length, etl::endian stream_endianness)
+```
+`begin` A pointer to the beginning of the read buffer.  
+`length` The length, in char, of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+
+---
+
+```cpp
+void restart()
+```
+**Description**  
+Sets the reader back to the beginning of the stream.
+
+---
+
+```cpp
+bool read_unchecked<bool>()
+```
+**Description**  
+Unchecked read for `bool` types.
+
+---
+
+```cpp
+etl::optional<bool> read<bool>()
+```
+**Description**  
+Checked read for `bool` types.
+
+---
+
+```cpp
+template <typename T>
+T read_unchecked(uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Unchecked read.  
+Enabled for integral types.
+
+---
+
+```cpp
+template <typename T>
+etl::optional<T> read(uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Checked read.  
+Enabled for integral types.
+
+---
+
+```cpp
+bool skip(size_t nbits)
+```
+**Description**  
+Skip forward in the stream by `nbits`.  
+If there are not enough bits remaining in the stream it assert an `etl::bit_stream_overflow` and return `false`.
+
+---
+
+```cpp
+size_t size_bytes() const
+```
+**Description**  
+Returns the number of bytes in the stream buffer.
+
+---
+
+```cpp
+size_t size_bits() const
+```
+**Description**  
+Returns the number of bits in the stream buffer.
+
+---
+
+```cpp
+const_iterator begin() const
+const_iterator cbegin() const
+```
+**Description**  
+Returns start of the stream buffer.
+
+---
+
+```cpp
+const_iterator end() const
+const_iterator cend() const
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+etl::span<const char> data() const
+```
+**Description**  
+Returns a span of whole the stream buffer.
+
+---
+
+## Non-member functions
+
+```cpp
+template <typename T>
+T read_unchecked(etl::bit_stream_reader& stream)
+```
+Reads an unchecked type from a stream by calling `stream.read_unchecked<T>()`.
+
+---
+
+```cpp
+template <typename T>
+T read_unchecked(etl::bit_stream_reader& stream, uint_least8_t nbits)
+```
+**Description**  
+Reads an unchecked type from a stream by calling `stream.read_unchecked<T>(nbits)`.
+
+---
+
+```cpp
+template <typename T>
+etl::optional<T> read(etl::bit_stream_reader& stream)
+```
+**Description**  
+Reads a checked type from a stream by calling `stream.read<T>()`.
+
+---
+
+```cpp
+template <typename T>
+etl::optional<T> read(etl::bit_stream_reader& stream, uint_least8_t nbits)
+```
+**Description**  
+Reads a checked type from a stream by calling `stream.read<T>(nbits)`.
+
+---
+
+```cpp
+template <>
+bool read_unchecked<bool>(etl::bit_stream_reader& stream)
+```
+Specialisation for bool.  
+Reads an unchecked bool from a stream by calling `stream.read_unchecked<bool>()`.
+
+---
+
+```cpp
+template <>
+etl::optional<bool> read<bool>(etl::bit_stream_reader& stream)
+```
+Specialisation for bool.  
+Reads a checked bool from a stream by calling stream.read<bool>()
+
+---
+
+By specialisation of the templates, the user may create readers for custom types.
+
+## Example
+```cpp
+char c           = 26;         // 6 bits
+unsigned short s = 6742;       // 13 bits
+int32_t i        = 2448037;    // 23 bits
+
+struct CustomType
+{
+char c           = -10;       // 7 bits
+unsigned short s = 1878;      // 11 bits
+int32_t i        = -10836646; // 25 bits
+};
+
+namespace etl
+{
+  // Specialisation for Custom.
+  // Must be defined in the etl namespace.
+  template <>
+  etl::optional<CustomType> read_unchecked<CustomType>(etl::bit_stream_reader& stream)
+  {
+    char c    = stream.read_unchecked<char, 7U>();
+    short s   = stream.read_unchecked<short , 11U>();
+    int32_t i = stream.read_unchecked<int32_t, 25U>();
+
+    return CustomType { c.value(), s.value(), i.value() };
+  }
+}
+
+std::array<char, 100U> storage; // Assume the buffer gets filled with bit stream data.
+etl::bit_stream_reader bit_stream(storage.data(), storage.size());
+
+// Read unchecked values from the stream.
+char c            = etl::read_unchecked<char>(bit_stream, 6U);
+unsigned short s  = etl::read_unchecked<unsigned short>(bit_stream, 13U);
+CustomType custom = etl::read_unchecked<Custom>(bit_stream);
+int32_t i         = etl::read_unchecked<>(bit_stream, 23U);
+```

docs/utilities/bit_stream_writer.md

@@ -0,0 +1,408 @@
+---
+title: "bit_stream_writer"
+---
+
+{{< callout type="info">}}
+  Header: `bit_stream_writer.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+A binary streaming utility that allows values to be written to an array of char or unsigned char using custom bits widths for efficient packing. Values may be streamed in either msb or lsb format.
+
+Write functions come in both checked and unchecked forms.
+- Unchecked writes return `void`.
+- Checked writes assert that there is enough space to store the value, and return a `bool` indicating success or failure.
+
+A callback delegate can be assigned that will be called with a span of filled bytes.
+If the callback is used then the stream is reset to empty or the last unfilled byte after each callback. This allows a very small buffer to be assigned.
+
+## Storage
+- `bool`  
+Stored as 1 bit.  
+
+- Integrals  
+By default, stored using full bit width, otherwise uses the specified width.  
+
+- Custom types  
+The user may create specializations of the non-member etl::write functions to stream custom types. Specialisations must be defined in the `etl` namespace.  
+
+## Types
+
+```cpp
+value_type              char
+iterator                value_type*
+const_iterator          const value_type*   
+callback_parameter_type etl::span<value_type>
+callback_type           etl::delegate<void(callback_parameter_type)>
+```
+
+## Member functions
+```cpp
+bit_stream_writer(etl::span<char> span, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from span.  
+**Parameters**  
+`span` A char span of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.   
+`callback` An optional callback.
+
+---
+
+```cpp
+bit_stream_writer(etl::span<unsigned char> span, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from span.  
+**Parameters**  
+`span` A char span of the read buffer.  
+`stream_endianness` The endianness of the stream. etl::endian::little or etl::endian::big.  
+`callback` An optional callback.
+
+---
+
+```cpp
+bit_stream_writer(void* begin, void* end, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from range.  
+**Parameters**  
+`begin` A pointer to the beginning of the read buffer.  
+`end` A pointer to the beginning of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+`callback` An optional callback.
+
+---
+
+```cpp
+bit_stream_writer(void* begin, size_t length_chars, etl::endian stream_endianness, callback_type callback = callback_type())
+```
+**Description**  
+Construct from begin and length.  
+**Parameters**  
+`begin` A pointer to the beginning of the read buffer.  
+`length` The length, in char, of the read buffer.  
+`stream_endianness` The endianness of the stream. `etl::endian::little` or `etl::endian::big`.  
+
+---
+
+```cpp
+void restart()
+```
+**Description**  
+Sets the indexes back to the beginning of the stream.
+
+---
+
+```cpp
+size_t capacity_bytes() const
+```
+**Description**  
+Returns the maximum capacity in bytes.
+
+---
+
+```cpp
+size_t capacity_bits() const
+```
+**Description**  
+Returns the maximum capacity in bits.
+
+---
+
+```cpp
+bool empty() const
+```
+**Description**  
+Returns true if the bitsteam indexes have been reset
+
+---
+
+```cpp
+bool full() const
+```
+**Description**  
+Returns true if the bitsteam indexes have reached the end
+
+---
+
+```cpp
+void write_unchecked(bool value)
+```
+**Description**  
+Writes a boolean to the stream.
+
+---
+
+```cpp
+bool write(bool value)
+```
+**Description**  
+Writes a boolean to the stream.
+
+---
+
+```cpp
+template <typename T>
+void write_unchecked(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Enabled for integral types.
+
+---
+
+```cpp
+template <typename T>
+bool write(T value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Enabled for integral types.
+
+---
+
+```cpp
+bool skip(size_t nbits)
+```
+**Description**  
+Skip forward in the stream by nbits.  
+If there are not enough bits remaining in the stream it assert an etl::bit_stream_overflow and return false.
+
+---
+
+```cpp
+size_t size_bytes() const
+```
+**Description**  
+Returns the number of bytes used in the stream.
+
+---
+
+```cpp
+size_t size_bits() const
+```
+**Description**  
+Returns the number of bits used in the stream.
+
+---
+
+```cpp
+template <size_t Nbits>
+size_t available() const
+```
+**Description**  
+The number of multiples of Nbits available in the stream.  
+Compile time.
+
+---
+
+```cpp
+template <typename T>
+size_t available() const
+```
+**Description**  
+The number of T available in the stream.  
+Compile time.
+
+---
+
+```cpp
+size_t available(size_t nbits) const
+```
+**Description**  
+The number of 'bit width' available in the stream.  
+Run time.
+
+---
+
+```cpp
+size_t available_bits() const
+```
+**Description**  
+The number of bits left in the stream.
+
+---
+
+```cpp
+iterator begin()
+```
+**Description**  
+Returns start of the stream.
+
+---
+
+```cpp
+const_iterator begin() const
+```
+**Description**  
+Returns start of the stream.
+
+---
+
+```cpp
+const_iterator cbegin() const
+```
+**Description**  
+Returns start of the stream.
+
+---
+
+```cpp
+iterator end()
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+const_iterator end() const
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+const_iterator cend() const
+```
+**Description**  
+Returns end of the stream.
+
+---
+
+```cpp
+etl::span<char> used_data()
+```
+**Description**  
+Returns a span of the used portion of the stream.
+
+---
+
+```cpp
+etl::span<const char> used_data() const
+```
+**Description**  
+Returns a span of the used portion of the stream.
+
+---
+
+```cpp
+etl::span<char> data()
+```
+**Description**  
+Returns a span of whole the stream.
+
+---
+
+```cpp
+etl::span<const char> data() const
+```
+**Description**  
+Returns a span of whole the stream.
+
+---
+
+```cpp
+void flush()
+```
+**Description**  
+Flush the last byte, if partially filled, to the callback.
+This is only required when a callback delegate has been set.
+
+---
+
+```cpp
+void set_callback(callback_type callback_)
+```
+**Description**  
+Sets the delegate to call after every write.
+
+---
+
+```cpp
+callback_type get_callback() const
+```
+**Description**  
+Gets the function to call afer every write.
+
+---
+
+## Non-member functions
+
+```cpp
+void write_unchecked(etl::bit_stream_writer& stream, bool value)
+```
+**Description**  
+Implementation of the write unchecked function.
+For `bool` types only.
+
+---
+
+```cpp
+bool write(etl::bit_stream_writer& stream, bool value)
+```
+**Description**  
+Implementation of the write function.
+For `bool` types only.
+
+---
+
+```cpp
+template <typename T>
+void write_unchecked(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+  Default implementation of the write function.
+  For integral types only (but not bool).
+  Overload this to support custom types.
+
+---
+
+```cpp
+template <typename T>
+bool write(etl::bit_stream_writer& stream, const T& value, uint_least8_t nbits = CHAR_BIT * sizeof(T))
+```
+**Description**  
+Default implementation of the write function.
+For integral types only (but not bool).
+Overload this to support custom types.
+
+---
+
+By specialisation of the templates, the user may create writers for custom types.
+
+## Example
+```cpp
+char c           = 26;         // 6 bits
+unsigned short s = 6742;       // 13 bits
+int32_t i        = 2448037;    // 23 bits
+
+struct CustomType
+{
+char c           = -10;       // 7 bits
+unsigned short s = 1878;      // 11 bits
+int32_t i        = -10836646; // 25 bits
+};
+
+namespace etl
+{
+  // Specialisation for Custom.
+  // Must be defined in the etl namespace.
+  template <>
+  void write_unchecked<CustomType>(etl::bit_stream_reader& stream)
+  {
+    stream.write_unchecked<char, 7U>();
+    stream.write_unchecked<short , 11U>();
+    stream.write_unchecked<int32_t, 25U>();
+  }
+}
+
+std::array<char, 100U> storage; // Assume the buffer gets filled with bit stream data.
+etl::bit_stream_reader bit_stream(storage.data(), storage.size());
+
+// Write unchecked values to the stream.
+etl::write_unchecked<char>(bit_stream, 6U);
+etl::write_unchecked<unsigned short>(bit_stream, 13U);
+etl::write_unchecked<Custom>(bit_stream);
+etl::write_unchecked<>(bit_stream, 23U);
+```

docs/utilities/compare.md

@@ -1,29 +1,60 @@
-compare
-A helper class that defines <=, >, >= in terms of std::less or a user supplied compare type. 
+---
+title: "compare"
+---
 
-template <typename T, typename TLess = std::less<T> >
+{{< callout type="info">}}
+  Header: `compare.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+A helper class that defines `<=`, `>`, `>=` in terms of `etl::less` or a user supplied compare type. 
+
+```cpp
+template <typename T, typename TLess = etl::less<T> >
 struct compare
-____________________________________________________________________________________________________
-Types
+```
+
+## Types
+```cpp
 first_argument_type;
 second_argument_type;
 result_type;
-____________________________________________________________________________________________________
-Members
+```
+
+## Members
+```cpp
 static result_type lt(first_argument_type lhs, second_argument_type rhs)
-Returns true if lhs < rhs, otherwise false.
+```
+**Return**  
+`true` if `lhs < rhs`, otherwise `false`.
 
+---
+
+```cpp
 static result_type lte(first_argument_type lhs, second_argument_type rhs)
-Returns true if lhs <= rhs, otherwise false.
+```
+**Return**  
+`true` if `lhs <= rhs`, otherwise `false`.
 
+---
+
+```cpp
 static result_type gt(first_argument_type lhs, second_argument_type rhs)
-Returns true if lhs > rhs, otherwise false.
+```
+**Return**  
+`true` if `lhs > rhs`, otherwise `false`.
 
+---
+
+```cpp
 static result_type gte(first_argument_type lhs, second_argument_type rhs)
-Returns true if lhs >= rhs, otherwise false.
-____________________________________________________________________________________________________
-Example 1
-Using std::less
+```
+**Return**  
+`true` if `lhs >= rhs`, otherwise `false`.
+
+## Example 1
+```cpp
+using std::less
 struct Test
 {
   int a;
@@ -53,9 +84,11 @@ bool operator >=(const Test& lhs, const Test& rhs)
 {
   return Compare::gte(lhs, rhs);
 }
-____________________________________________________________________________________________________
-Example 2
+```
+
+## Example 2
 Separate 'less-than' class.
+```cpp
 struct Test
 {
   int a;
@@ -91,9 +124,12 @@ bool operator >=(const Test& lhs, const Test& rhs)
 {
   return Compare::gte(lhs, rhs);
 }
-____________________________________________________________________________________________________
-Example 3
+```
+
+## Example 3
 Inheritance
+
+```cpp
 struct Test : public etl::compare<Test>
 {
   int a;
@@ -121,5 +157,4 @@ bool operator >=(const Test& lhs, const Test& rhs)
 {
   return Test::gte(lhs, rhs);
 }
-
-
+```

docs/utilities/cyclic_value.md

@@ -1,87 +1,164 @@
-cyclic_value
-Provides a value that cycles between two limits.
-Supports increments, decrements and arbitrary advance.
-Supports compile time and runtime variants
+---
+title: "cyclic_value"
+---
 
-template <typename T, const T FIRST = 0, const T LAST = 0>
+{{< callout type="info">}}
+  Header: `cyclic_value.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+Provides a value that cycles between two limits.  
+Supports increments, decrements and arbitrary advance.  
+Supports compile time and runtime variants.  
+
+```cpp
+template <typename T, const T First = 0, const T Last = 0>
 class cyclic_value
+```
 
+```cpp
 etl::cyclic_value<int, 2, 7> value_ct; // Compile time. Fixed range of 2 to 7 inclusive.
 
 etl::cyclic_value<int> value_rt(2, 7); // Run time. Modifiable range.
 value_rt.set(3, 8);
-____________________________________________________________________________________________________
-Constructor
+```
+
+## Constructor
+```cpp
 cyclic_value<int> value;
+```
 Creates a runtime cyclic value of type int with default constructed initial defined limits.
 
+---
+
+```cpp
 cyclic_value<int, N, M> value;
+```
 Creates a compile time cyclic value of type int with fixed limits of N and M.
 
+**Example**  
+```cpp
 cyclic_value<int> value(N, M);
+```
 Creates a runtime cyclic value of type int with initial defined limits of N and M.
-____________________________________________________________________________________________________
-Modifiers
+
+## Modifiers
+```cpp
 cyclic_value& operator ++();
 cyclic_value& operator ++(int);
+```
 Increments the value. If the value is at the last value then is set to the first.
 
+---
+
+```cpp
 cyclic_value& operator --();
 cyclic_value& operator --(int);
+```
 Decrements the value. If the value is at the first value then is set to the last.
 
+---
+
+```cpp
 void advance(int n);
+```
 Advances the value by the specified amount, wrapping if necessary.
 
-____________________________________________________________________________________________________
-Access
+## Access
+```cpp
 T get() const;
+```
 Gets the current value
 
+---
+
+```cpp
 T first() const;
+```
 Sets the current value to the first value
 
+---
+
+```cpp
 T last() const;
+```
 Sets the current value to the last value
 
+---
+
+```cpp
 void set(T first, T last);
+```
 Sets the new first and last values. Sets the current value to first.
 
+---
+
+```cpp
 void set(T value);
+```
 Sets the current value.
 
+---
+
+```cpp
 void to_first();
+```
 Sets the current value to the first value
 
+---
+
+```cpp
 void to_last();
+```
 Sets the current value to the last value
-____________________________________________________________________________________________________
-Operations
 
+## Operations
+
+```cpp
 void swap(cyclic_value<T, FIRST, LAST>& other);
+```
 Swaps with another cyclic value.
 
+---
+
+```cpp
 void swap(cyclic_value<T, FIRST, LAST>& lhs, cyclic_value<T, FIRST, LAST>& rhs);
+```
 Swaps with another cyclic value.
-____________________________________________________________________________________________________
-Operators
+
+## Operators
+```cpp
 operator T();
 operator const T() const;
-Conversion operators to T.
+```
+Conversion operators to `T`.
 
+---
+
+```cpp
 cyclic_value& operator =(T t);
-Sets the current value to t.
-____________________________________________________________________________________________________
-Non-member functions
+```
+Sets the current value to `t`.
+
+## Non-member functions
+```cpp
 template <typename T, const T FIRST, const T LAST>
 void swap(cyclic_value<T, FIRST, LAST>& lhs, cyclic_value<T, FIRST, LAST>& rhs)
+```
 Swaps two cyclic values.
 
+---
+
+```cpp
 template <typename T, const T FIRST, const T LAST>
 bool operator == (cyclic_value<T, FIRST, LAST>& lhs, cyclic_value<T, FIRST, LAST>& rhs)
+```
 Checks equality of two cyclic values.
 
+---
+
+```cpp
 template <typename T, const T FIRST, const T LAST>
 bool operator != (cyclic_value<T, FIRST, LAST>& lhs, cyclic_value<T, FIRST, LAST>& rhs)
+```
 Checks inequality of two cyclic values.
-

docs/utilities/debug_count.md

@@ -2,6 +2,11 @@
 title: "debug_count"
 ---
 
+{{< callout type="info">}}
+  Header: `debug_count.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
 A utility class designed for debugging purposes. This is used in the ETL containers to check that all placement new'd items have been destructed. When neither `DEBUG` or `_DEBUG` is defined then this class does nothing and will be optimised away.
 
 If the count is decremented below zero then an assert will be generated.  

docs/utilities/instance_count.md

@@ -0,0 +1,49 @@
+---
+title: "instance_count"
+---
+
+{{< callout type="info">}}
+  Header: `instance_count.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+Inherit from this class to count instances of a class.
+
+Before: `20.25.0`
+```cpp
+etl::instance_count<typename T>
+```
+This class is not thread safe.
+
+From: `20.25.0`
+```cpp
+etl::instance_count<typename T, typename TCounter = uint32_t>
+```
+This class is not thread safe unless `TCounter` is an atomic type.
+
+## Types
+
+`type`         The type being counted.
+`counter_type` The type used for the counter.
+
+## Member functions
+```cpp
+static const counter_type& get_instance_count()
+```
+Returns a const reference to the current count.
+
+---
+
+```cpp
+static void reset_instance_count()
+```
+Resets the count to zero.
+
+## Example
+Instances of `My_Class` will be counted and can be accessed by the inherited member function `get_instance_count()`.
+
+```cpp
+class My_Class : public etl::instance_count<My_Class, std::atomic_uint8_t>
+{
+};
+```

docs/utilities/integral_limits.md

@@ -0,0 +1,31 @@
+---
+title: "integral_limits"
+---
+
+{{< callout type="info">}}
+  Header: `integral_limits.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+A set of templated constants to determine limits of integral types at compile time.  
+
+## Member constants
+`min`        The minimum value the type can hold.  
+`max`        The maximum value the type can hold.  
+`bits`       The number of bits used for this type.  
+`is_signed`  Whether the type is signed.
+
+## Example
+```cpp
+template <const size_t SIZE>
+struct Value
+{
+  etl::array<T, SIZE> data;
+};
+
+template <typename T>
+void foo(const Value<etl::integral_limits<T>::bits>& value)
+{
+  size_t size = value.data.size(); // Same as the number of bits that represent a T
+}
+```

docs/utilities/mem_cast.md

@@ -0,0 +1,426 @@
+---
+title: "mem_cast"
+---
+
+{{< callout type="info">}}
+  Header: `mem_cast.h`
+  Since: `20.11.0`  
+{{< /callout >}}
+
+Helper classes that simplify the interpretation of memory blocks.  
+The member functions contain both compile and run time error checks for correct sized buffers.
+
+```cpp
+etl::mem_cast
+etl::mem_cast_ptr
+etl::mem_cast_types
+```
+
+## Error types
+
+```cpp
+class mem_cast_exception : public etl::exception
+```
+The base exception type for mem_cast types.
+
+```cpp
+class mem_cast_size_exception : public etl::mem_cast_exception
+```
+The exception type when the type size is too large.
+
+```cpp
+class mem_cast_nullptr_exception : public etl::mem_cast_exception
+```
+The exception type when the buffer pointer is null.
+
+## mem_cast
+```cpp
+template <size_t Size, size_t Alignment>
+class mem_cast
+```
+The class is parameterised by the required memory block size and alignment.
+
+## Member constants
+
+```cpp
+static ETL_CONSTANT size_t Size;
+static ETL_CONSTANT size_t Alignment;
+```
+
+## Member functions
+```cpp
+mem_cast()
+```
+Default constructor.  
+The internal memory block contents are undefined.
+
+---
+
+```cpp
+template <size_t Other_Size, size_t Other_Alignment>
+mem_cast(const mem_cast<Other_Size, Other_Alignment>& other)
+```
+Copy constructor.  
+Copies the contents of the source buffer.  
+Static asserts if the other buffer is not large enough.  
+
+---
+
+```cpp
+template <size_t Other_Size, size_t Other_Alignment>
+mem_cast& operator =(const mem_cast<Other_Size, Other_Alignment>& rhs)
+```
+Assignment operator.  
+Static asserts if the rhs buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+void assign(const T& value)
+```
+Assign from value.  
+Static asserts if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+void assign_at_offset(size_t offset, const T& value)
+```
+Assign from value at an offset from the start of the memory block.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, size_t Offset>
+void assign_at_offset(const T& value)
+```
+Assign from value at an offset from the start of the memory block.  
+Static asserts if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, typename... TArgs>
+void emplace(TArgs... args)
+```
+Emplace from parameters.  
+Static asserts if the buffer is not large enough.  
+C++11 or above.
+
+---
+
+```cpp
+template <typename T, typename... TArgs>
+void emplace_at_offset(size_t offset, TArgs... args)
+```
+Emplace from parameters at an offset from the start of the memory block.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.  
+C++11 or above.
+
+---
+
+```cpp
+template <typename T, size_t Offset, typename... TArgs>
+void emplace_at_offset(TArgs... args)
+```
+Emplace from parameters at an offset from the start of the memory block.  
+Static asserts if the buffer is not large enough.  
+C++11 or above.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD T& ref()
+```
+Get a reference to `T`.  
+Static asserts if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD const T& ref() const
+```
+Get a const reference to `T`.  
+Static asserts if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD T& ref_at_offset(size_t offset)
+```
+Get a reference to T at an offset from the start of the memory block (dynamic).  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD const T& ref_at_offset(size_t offset) const
+```
+Get a const reference to `T` at an offset from the start of the memory block (dynamic).  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, size_t Offset>
+ETL_NODISCARD T& ref_at_offset()
+```
+Get a reference to `T` at an offset from the start of the memory block (static).  
+Static asserts if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, size_t Offset>
+ETL_NODISCARD const T& ref_at_offset() const
+```
+Get a const reference to `T` at an offset from the start of the memory block (static).  
+Static asserts if the buffer is not large enough.
+
+---
+
+```cpp
+ETL_NODISCARD static ETL_CONSTEXPR size_t size()
+```
+Get the size of the buffer.
+
+---
+
+```cpp
+ETL_NODISCARD static ETL_CONSTEXPR size_t alignment()
+```
+Get the alignment of the buffer.
+
+---
+
+```cpp
+ETL_NODISCARD char* data()
+```
+Get a pointer to the internal buffer.
+
+---
+
+```cpp
+ETL_NODISCARD const char* data() const
+```
+Get a const pointer to the internal buffer
+
+## mem_cast_ptr
+This class contains a pointer to an external memory block.
+```cpp
+class mem_cast_ptr
+```
+
+## Member constants
+```cpp
+static ETL_CONSTANT size_t Undefined_Size;
+```
+
+## Member functions
+```cpp
+mem_cast_ptr()
+```
+Default constructor.  
+The internal pointer to the memory block is initialised as `nullptr`.  
+The size is defined as `Undefined_Size`.
+
+```cpp
+mem_cast_ptr(const mem_cast_ptr& other)
+```
+Copy constructor.  
+Copies the memory block pointer, not the contents of the memory block.
+
+---
+
+```cpp
+mem_cast_ptr& operator =(const mem_cast_ptr& rhs)
+```
+Assignment operator.  
+Copies the memory block pointer, not the contents of the memory block.
+
+---
+
+```cpp
+template <typename T>
+void assign(const T& value)
+```
+Assign from value.  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+void assign_at_offset(size_t offset, const T& value)
+```
+Assign from value at an offset from the start of the memory block.  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, size_t Offset>
+void assign_at_offset(const T& value)
+```
+Assign from value at an offset from the start of the memory block.
+
+---
+
+```cpp
+template <typename T, typename... TArgs>
+void emplace(TArgs... args)
+```
+Emplace from parameters.  
+C++11 or above.
+
+---
+
+```cpp
+template <typename T, typename... TArgs>
+void emplace_at_offset(size_t offset, TArgs... args)
+```
+Emplace from parameters at offset.  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.  
+C++11 or above.
+
+---
+
+```cpp
+template <typename T, size_t Offset, typename... TArgs>
+void emplace_at_offset(TArgs... args)
+```
+Emplace from parameters at offset.  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.  
+C++11 or above.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD T& ref()
+```
+Get a reference to `T`.  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD const T& ref() const
+```
+Get a const reference to `T`.  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD T& ref_at_offset(size_t offset)
+```
+Get a reference to `T` at an offset from the start of the memory block (dynamic).
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T>
+ETL_NODISCARD const T& ref_at_offset(size_t offset) const
+```
+Get a const reference to `T` at offset (dynamic).  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, size_t Offset>
+ETL_NODISCARD T& ref_at_offset()
+```
+Get a reference to `T` at an offset from the start of the memory block (static).  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+template <typename T, size_t Offset>
+ETL_NODISCARD const T& ref_at_offset() const
+```
+Get a const reference to T at an offset from the start of the memory block (static).  
+Raises an `etl::mem_cast_nullptr_exception` `ETL_ASSERT` if the memory block pointer is null.  
+Raises an `etl::mem_cast_size_exception` `ETL_ASSERT` if the buffer is not large enough.
+
+---
+
+```cpp
+ETL_NODISCARD size_t size() const
+```
+Get the size of the buffer.
+
+---
+
+```cpp
+ETL_NODISCARD size_t alignment() const
+```
+Get the alignment of the buffer.
+
+---
+
+```cpp
+void data(char* pbuffer, size_t buffer_size = Undefined_Size)
+```
+Set the pointer to the external buffer.  
+The default size is `Undefined_Size`.
+
+---
+
+```cpp
+ETL_NODISCARD char* data()
+```
+Get a pointer to the internal buffer.
+
+---
+
+```cpp
+ETL_NODISCARD const char* data() const
+```
+Get a const pointer to the internal buffer
+
+## mem_cast_types
+A variant of `etl::mem_cast` that deduces the size and alignment from the supplied list of types.
+
+### C++03
+```cpp
+template <typename T1,         typename T2  = char, typename T3  = char, typename T4  = char,
+          typename T5  = char, typename T6  = char, typename T7  = char, typename T8  = char,
+          typename T9  = char, typename T10 = char, typename T11 = char, typename T12 = char,
+          typename T13 = char, typename T14 = char, typename T15 = char, typename T16 = char>
+struct mem_cast_types :
+  public etl::mem_cast<etl::largest<T1, T2, T3, T4, T5, T6, T7, T8, 
+                                    T9, T10, T11, T12, T13, T14, T15, T16>::size,
+                       etl::largest<T1, T2, T3, T4, T5, T6, T7, T8,
+                                    T9, T10, T11, T12, T13, T14, T15, T16>::alignment>
+{
+};
+```
+
+### C++11 and above
+```cpp
+template <typename... TTypes>
+using mem_cast_types = etl::mem_cast<etl::largest<TTypes...>::size, 
+                                     etl::largest<TTypes...>::alignment>;
+```

docs/utilities/not_null.md

@@ -0,0 +1,121 @@
+---
+title: "not_null"
+---
+
+{{< callout type="info">}}
+  Header: `not_null.h`  
+  Since: `20.43.0`  
+{{< /callout >}}
+
+A container for pointers that are not allowed to be null.
+
+```cpp
+template <typename T>
+class not_null;
+```
+
+**Specialised for pointers and etl::unique_ptr.**  
+
+```cpp
+template <typename T>
+class not_null<T*> 
+```
+
+---
+
+```cpp
+template <typename T, typename TDeleter>
+class not_null<etl::unique_ptr<T, TDeleter>> 
+```
+
+## Public types
+
+```cpp
+T        value_type;
+T*       pointer;
+const T* const_pointer;
+T&       reference;
+const T& const_reference;
+pointer  underlying_type;
+```
+
+## Member functions
+```cpp
+explicit not_null(underlying_type ptr)
+Constructs a not_null from an underlying type.
+```
+**Description**  
+Asserts `etl::not_null_contains_null` if the pointer is null.
+
+---
+
+```cpp
+not_null(const etl::not_null<T*>& other)
+```
+**Description**  
+Copy constructor from a `not_null`.
+
+---
+
+```cpp
+not_null& operator =(const etl::not_null<T*>& rhs) 
+```
+**Description**  
+Assignment from a `not_null`.
+
+---
+
+```cpp
+not_null& operator =(underlying_type rhs) 
+```
+**Description**  
+Assignment from a pointer.  
+Asserts `etl::not_null_contains_null` if the pointer is null.
+
+---
+
+```cpp
+pointer get() const 
+```
+**Description**  
+Gets the underlying pointer.
+
+---
+
+```cpp
+operator pointer() const 
+```
+**Description**  
+Implicit conversion to pointer.
+
+---
+
+```cpp
+reference operator*() const
+```
+**Description**  
+Dereference operator.
+
+---
+
+```cpp
+pointer operator->() const 
+```
+**Description**  
+Arrow operator.
+
+---
+
+```cpp
+underlying_type& underlying() 
+```
+**Description**  
+Gets a reference to the underlying type.
+
+---
+
+```cpp
+const underlying_type& underlying() const 
+```
+**Description**  
+Gets a const reference to the underlying type.

docs/utilities/nth_type.md

@@ -0,0 +1,36 @@
+---
+title: "nth_type"
+---
+
+{{< callout type="info">}}
+  Header: `nth_type.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+Defines the nth type in a variadic list of types.
+
+## Member types
+`type`      Defined as the nth type in the type list.  
+`type_list` An etl::type_list of all of the types.  
+
+Static asserts if N is out of range.
+
+## Classes
+```cpp
+template <size_t Index, typename... TTypes>
+struct nth_type
+```
+
+---
+
+```cpp
+template <size_t Index, typename... TTypes>
+struct nth_type<Index, etl::type_list<TTypes...>>
+```
+
+---
+
+```cpp
+template <size_t Index, typename... TTypes>
+using nth_type_t = typename nth_type<Index, TTypes...>::type;
+```

docs/utilities/null_type.md

@@ -1,13 +1,23 @@
-null_type
+---
+title: "null_type"
+---
+
+{{< callout type="info">}}
+  Header: `null_type.h`  
+  Since: `TBC`  
+{{< /callout >}}
 
 A placeholder type to use as unique default types in a list of template type parameters.
 
+```cpp
 template <size_t N>
 class null_type
 {
 };
+```
 
-Example
+## Example
+```cpp
 template <typename T1 = etl::null_type<1>, typename T2 = etl::null_type<2>>
 class MyClass
-
+```

docs/utilities/nullptr.md

@@ -0,0 +1,16 @@
+---
+title: "nullptr"
+---
+
+{{< callout type="info">}}
+  Header: `nullptr.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+Defines `ETL_NULLPTR` as either `nullptr` or `NULL`, dependent on the compiler support.
+
+---
+
+Defines `etl::nullptr_t`  
+Since: `20.39.0`
+

docs/utilities/numeric.md

@@ -0,0 +1,46 @@
+---
+title: "numeric"
+---
+
+{{< callout type="info">}}
+  Header: `numeric.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
+Numeric functions reverse engineered from C++ 11.
+
+## iota
+```cpp
+template <typename TIterator, typename T>
+void iota(TIterator first, TIterator last, T value);
+```
+**Description**  
+Fills a range of elements with sequentially increasing values starting with `value`.  
+See [std::iota](https://en.cppreference.com/cpp/algorithm/iota_)
+
+
+## lerp
+```cpp
+template <typename T>
+T lerp(T a, T b, T t) ETL_NOEXCEPT
+```
+**Description**  
+Linear interpolation.  
+Returns the result of `a + t(b − a)`.
+
+## midpoint
+```cpp
+template <typename T>
+ETL_CONSTEXPR T midpoint(T a, T b)
+```
+**Description**  
+Calculates the midpoint of integers or floating-point numbers.
+
+---
+
+```cpp
+template <typename T>
+ETL_CONSTEXPR T midpoint(T* a, T* b)
+```
+**Description**  
+Calculates the midpoint of pointers.

docs/utilities/type_id.md

@@ -2,6 +2,11 @@
 title: "type_id"
 ---
 
+{{< callout type="info">}}
+  Header: `type_id.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
 Below is a concise, technical overview of the `etl::type_id` facility, suitable for design documentation or code review context.
 
 ## Overview: 

docs/utilities/versions.md

@@ -2,6 +2,11 @@
 title: "Versions"
 ---
 
+{{< callout type="info">}}
+  Header: `version.h`  
+  Since: `TBC`  
+{{< /callout >}}
+
 As set of macros that allow the version of the ETL to be determined.
 
 ## Definitions