--- libecb/ecb.pod	2018/11/19 00:27:38	1.74
+++ libecb/ecb.pod	2020/01/20 21:02:28	1.82
@@ -60,9 +60,15 @@
 
 ecb.h makes sure that the following types are defined (in the expected way):
 
-   int8_t   uint8_t   int16_t  uint16_t
-   int32_t  uint32_t  int64_t  uint64_t
-   intptr_t uintptr_t
+   int8_t       uint8_
+   int16_t      uint16_t
+   int32_t      uint32_
+   int64_t      uint64_t
+   int_fast8_t  uint_fast8_t
+   int_fast16_t uint_fast16_t
+   int_fast32_t uint_fast32_t
+   int_fast64_t uint_fast64_t
+   intptr_t     uintptr_t
 
 The macro C<ECB_PTRSIZE> is defined to the size of a pointer on this
 platform (currently C<4> or C<8>) and can be used in preprocessor
@@ -81,7 +87,7 @@
 =item ECB_C
 
 True if the implementation defines the C<__STDC__> macro to a true value,
-while not claiming to be C++.
+while not claiming to be C++, i..e C, but not C++.
 
 =item ECB_C99
 
@@ -106,6 +112,12 @@
 True if the implementation claims to be compliant to C++11/C++14/C++17
 (ISO/IEC 14882:2011, :2014, :2017) or any later version.
 
+=item ECB_OPTIMIZE_SIZE
+
+Is C<1> when the compiler optimizes for size, C<0> otherwise. This symbol
+can also be defined before including F<ecb.h>, in which case it will be
+unchanged.
+
 =item ECB_GCC_VERSION (major, minor)
 
 Expands to a true value (suitable for testing in by the preprocessor)
@@ -585,12 +597,17 @@
 
 =item int ecb_ctz64 (uint64_t x)
 
+=item int ecb_ctz (T x) [C++]
+
 Returns the index of the least significant bit set in C<x> (or
 equivalently the number of bits set to 0 before the least significant bit
 set), starting from 0. If C<x> is 0 the result is undefined.
 
 For smaller types than C<uint32_t> you can safely use C<ecb_ctz32>.
 
+The overloaded C++ C<ecb_ctz> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
+
 For example:
 
   ecb_ctz32 (3) = 0
@@ -600,14 +617,21 @@
 
 =item bool ecb_is_pot64 (uint32_t x)
 
+=item bool ecb_is_pot (T x) [C++]
+
 Returns true iff C<x> is a power of two or C<x == 0>.
 
 For smaller types than C<uint32_t> you can safely use C<ecb_is_pot32>.
 
+The overloaded C++ C<ecb_is_pot> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
+
 =item int ecb_ld32 (uint32_t x)
 
 =item int ecb_ld64 (uint64_t x)
 
+=item int ecb_ld64 (T x) [C++]
+
 Returns the index of the most significant bit set in C<x>, or the number
 of digits the number requires in binary (so that C<< 2**ld <= x <
 2**(ld+1) >>). If C<x> is 0 the result is undefined. A common use case is
@@ -621,14 +645,22 @@
 
 For smaller types than C<uint32_t> you can safely use C<ecb_ld32>.
 
+The overloaded C++ C<ecb_ld> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
+
 =item int ecb_popcount32 (uint32_t x)
 
 =item int ecb_popcount64 (uint64_t x)
 
+=item int ecb_popcount (T x) [C++]
+
 Returns the number of bits set to 1 in C<x>.
 
 For smaller types than C<uint32_t> you can safely use C<ecb_popcount32>.
 
+The overloaded C++ C<ecb_popcount> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
+
 For example:
 
   ecb_popcount32 (7) = 3
@@ -640,24 +672,39 @@
 
 =item uint32_t ecb_bitrev32 (uint32_t x)
 
+=item T ecb_bitrev (T x) [C++]
+
 Reverses the bits in x, i.e. the MSB becomes the LSB, MSB-1 becomes LSB+1
 and so on.
 
+The overloaded C++ C<ecb_bitrev> function supports C<uint8_t>, C<uint16_t> and C<uint32_t> types.
+
 Example:
 
    ecb_bitrev8 (0xa7) = 0xea
    ecb_bitrev32 (0xffcc4411) = 0x882233ff
 
+=item T ecb_bitrev (T x) [C++]
+
+Overloaded C++ bitrev function.
+
+C<T> must be one of C<uint8_t>, C<uint16_t> or C<uint32_t>.
+
 =item uint32_t ecb_bswap16 (uint32_t x)
 
 =item uint32_t ecb_bswap32 (uint32_t x)
 
 =item uint64_t ecb_bswap64 (uint64_t x)
 
+=item T ecb_bswap (T x)
+
 These functions return the value of the 16-bit (32-bit, 64-bit) value
 C<x> after reversing the order of bytes (0x11223344 becomes 0x44332211 in
 C<ecb_bswap32>).
 
+The overloaded C++ C<ecb_bswap> function supports C<uint8_t>, C<uint16_t>,
+C<uint32_t> and C<uint64_t> types.
+
 =item uint8_t  ecb_rotl8  (uint8_t  x, unsigned int count)
 
 =item uint16_t ecb_rotl16 (uint16_t x, unsigned int count)
@@ -682,6 +729,181 @@
 to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
 x86).
 
+=item T ecb_rotl (T x, unsigned int count) [C++]
+
+=item T ecb_rotr (T x, unsigned int count) [C++]
+
+Overloaded C++ rotl/rotr functions.
+
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
+
+=back
+
+=head2 HOST ENDIANNESS CONVERSION
+
+=over 4
+
+=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
+
+=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
+
+=item uint_fast64_t ecb_be_u64_to_host (uint_fast64_t v)
+
+=item uint_fast16_t ecb_le_u16_to_host (uint_fast16_t v)
+
+=item uint_fast32_t ecb_le_u32_to_host (uint_fast32_t v)
+
+=item uint_fast64_t ecb_le_u64_to_host (uint_fast64_t v)
+
+Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order.
+
+The naming convention is C<ecb_>(C<be>|C<le>)C<_u>C<16|32|64>C<_to_host>,
+where C<be> and C<le> stand for big endian and little endian, respectively.
+
+=item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v)
+
+=item uint_fast32_t ecb_host_to_be_u32 (uint_fast32_t v)
+
+=item uint_fast64_t ecb_host_to_be_u64 (uint_fast64_t v)
+
+=item uint_fast16_t ecb_host_to_le_u16 (uint_fast16_t v)
+
+=item uint_fast32_t ecb_host_to_le_u32 (uint_fast32_t v)
+
+=item uint_fast64_t ecb_host_to_le_u64 (uint_fast64_t v)
+
+Like above, but converts I<from> host byte order to the specified
+endianness.
+
+=back
+
+In C++ the following additional template functions are supported:
+
+=over 4
+
+=item T ecb_be_to_host (T v)
+
+=item T ecb_le_to_host (T v)
+
+=item T ecb_host_to_be (T v)
+
+=item T ecb_host_to_le (T v)
+
+These functions work like their C counterparts, above, but use templates,
+which make them useful in generic code.
+
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
+(so unlike their C counterparts, there is a version for C<uint8_t>, which
+again can be useful in generic code).
+
+=head2 UNALIGNED LOAD/STORE
+
+These function load or store unaligned multi-byte values.
+
+=over 4
+
+=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
+
+=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
+
+=item uint_fast64_t ecb_peek_u64_u (const void *ptr)
+
+These functions load an unaligned, unsigned 16, 32 or 64 bit value from
+memory.
+
+=item uint_fast16_t ecb_peek_be_u16_u (const void *ptr)
+
+=item uint_fast32_t ecb_peek_be_u32_u (const void *ptr)
+
+=item uint_fast64_t ecb_peek_be_u64_u (const void *ptr)
+
+=item uint_fast16_t ecb_peek_le_u16_u (const void *ptr)
+
+=item uint_fast32_t ecb_peek_le_u32_u (const void *ptr)
+
+=item uint_fast64_t ecb_peek_le_u64_u (const void *ptr)
+
+Like above, but additionally convert from big endian (C<be>) or little
+endian (C<le>) byte order to host byte order while doing so.
+
+=item ecb_poke_u16_u (void *ptr, uint16_t v)
+
+=item ecb_poke_u32_u (void *ptr, uint32_t v)
+
+=item ecb_poke_u64_u (void *ptr, uint64_t v)
+
+These functions store an unaligned, unsigned 16, 32 or 64 bit value to
+memory.
+
+=item ecb_poke_be_u16_u (void *ptr, uint_fast16_t v)
+
+=item ecb_poke_be_u32_u (void *ptr, uint_fast32_t v)
+
+=item ecb_poke_be_u64_u (void *ptr, uint_fast64_t v)
+
+=item ecb_poke_le_u16_u (void *ptr, uint_fast16_t v)
+
+=item ecb_poke_le_u32_u (void *ptr, uint_fast32_t v)
+
+=item ecb_poke_le_u64_u (void *ptr, uint_fast64_t v)
+
+Like above, but additionally convert from host byte order to big endian
+(C<be>) or little endian (C<le>) byte order while doing so.
+
+=back
+
+In C++ the following additional template functions are supported:
+
+=over 4
+
+=item T ecb_peek<T>      (const void *ptr)
+
+=item T ecb_peek_be<T>   (const void *ptr)
+
+=item T ecb_peek_le<T>   (const void *ptr)
+
+=item T ecb_peek_u<T>    (const void *ptr)
+
+=item T ecb_peek_be_u<T> (const void *ptr)
+
+=item T ecb_peek_le_u<T> (const void *ptr)
+
+Similarly to their C counterparts, these functions load an unsigned 8, 16,
+32 or 64 bit value from memory, with optional conversion from big/little
+endian.
+
+Since the type cannot be deduced, it has to be specified explicitly, e.g.
+
+   uint_fast16_t v = ecb_peek<uint16_t> (ptr);
+
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
+
+Unlike their C counterparts, these functions support 8 bit quantities
+(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
+all of which hopefully makes them more useful in generic code.
+
+=item ecb_poke      (void *ptr, T v)
+
+=item ecb_poke_be   (void *ptr, T v)
+
+=item ecb_poke_le   (void *ptr, T v)
+
+=item ecb_poke_u    (void *ptr, T v)
+
+=item ecb_poke_be_u (void *ptr, T v)
+
+=item ecb_poke_le_u (void *ptr, T v)
+
+Again, similarly to their C counterparts, these functions store an
+unsigned 8, 16, 32 or z64 bit value to memory, with optional conversion to
+big/little endian.
+
+C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
+
+Unlike their C counterparts, these functions support 8 bit quantities
+(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
+all of which hopefully makes them more useful in generic code.
+
 =back
 
 =head2 FLOATING POINT FIDDLING