--- cvsroot/libecb/ecb.pod 2020/01/20 13:13:56 1.76 +++ cvsroot/libecb/ecb.pod 2020/01/20 21:10:16 1.84 @@ -87,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 @@ -112,11 +112,19 @@ 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. +Note that many C++20 features will likely have their own feature test +macros (see e.g. L). + +=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, 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) -if the compiler used is GNU C and the version is the given version, or -higher. +Expands to a true value (suitable for testing by the preprocessor) if the +compiler used is GNU C and the version is the given version, or higher. This macro tries to return false on compilers that claim to be GCC compatible but aren't. @@ -145,7 +153,7 @@ =item ECB_STDFP -If this evaluates to a true value (suitable for testing in by the +If this evaluates to a true value (suitable for testing by the preprocessor), then C and C use IEEE 754 single/binary32 and double/binary64 representations internally I the endianness of both types match the endianness of C and C. @@ -410,12 +418,6 @@ =over 4 -=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, in which case it will be -unchanged. - =item bool ecb_is_constant (expr) Returns true iff the expression can be deduced to be a compile-time @@ -597,12 +599,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 (or equivalently the number of bits set to 0 before the least significant bit set), starting from 0. If C is 0 the result is undefined. For smaller types than C you can safely use C. +The overloaded C++ C function supports C, C, +C and C types. + For example: ecb_ctz32 (3) = 0 @@ -612,14 +619,21 @@ =item bool ecb_is_pot64 (uint32_t x) +=item bool ecb_is_pot (T x) [C++] + Returns true iff C is a power of two or C. For smaller types than C you can safely use C. +The overloaded C++ C function supports C, C, +C and C 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, or the number of digits the number requires in binary (so that C<< 2**ld <= x < 2**(ld+1) >>). If C is 0 the result is undefined. A common use case is @@ -633,14 +647,22 @@ For smaller types than C you can safely use C. +The overloaded C++ C function supports C, C, +C and C 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. For smaller types than C you can safely use C. +The overloaded C++ C function supports C, C, +C and C types. + For example: ecb_popcount32 (7) = 3 @@ -652,28 +674,38 @@ =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 function supports C, C and C types. + Example: ecb_bitrev8 (0xa7) = 0xea ecb_bitrev32 (0xffcc4411) = 0x882233ff +=item T ecb_bitrev (T x) [C++] + +Overloaded C++ bitrev function. + +C must be one of C, C or C. + =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 after reversing the order of bytes (0x11223344 becomes 0x44332211 in C). -=item T ecb_bswap (T x) [C++] - -For C++, an additional generic bswap function is provided. It supports -C, C, C and C. +The overloaded C++ C function supports C, C, +C and C types. =item uint8_t ecb_rotl8 (uint8_t x, unsigned int count) @@ -699,6 +731,14 @@ to "optimal" code (e.g. a single C or a combination of C 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 must be one of C, C, C or C. + =back =head2 HOST ENDIANNESS CONVERSION @@ -720,7 +760,7 @@ Convert an unsigned 16, 32 or 64 bit value from big or little endian to host byte order. The naming convention is C(C|C)C<_u>C<16|32|64>C<_to_host>, -where be and le stand for big endian and little endian, respectively. +where C and C stand for big endian and little endian, respectively. =item uint_fast16_t ecb_host_to_be_u16 (uint_fast16_t v) @@ -739,7 +779,7 @@ =back -In C++ the following additional functions are supported: +In C++ the following additional template functions are supported: =over 4 @@ -751,8 +791,8 @@ =item T ecb_host_to_le (T v) -These work like their C counterparts, above, but use templates for the -type, which make them useful in generic code. +These functions work like their C counterparts, above, but use templates, +which make them useful in generic code. C must be one of C, C, C or C (so unlike their C counterparts, there is a version for C, which @@ -814,27 +854,27 @@ =back -In C++ the following additional functions are supported: +In C++ the following additional template functions are supported: =over 4 -=item T ecb_peek (const void *ptr) +=item T ecb_peek (const void *ptr) -=item T ecb_peek_be (const void *ptr) +=item T ecb_peek_be (const void *ptr) -=item T ecb_peek_le (const void *ptr) +=item T ecb_peek_le (const void *ptr) -=item T ecb_peek_u (const void *ptr) +=item T ecb_peek_u (const void *ptr) -=item T ecb_peek_be_u (const void *ptr) +=item T ecb_peek_be_u (const void *ptr) -=item T ecb_peek_le_u (const void *ptr) +=item T ecb_peek_le_u (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 top be specified explicitly, e.g. +Since the type cannot be deduced, it has to be specified explicitly, e.g. uint_fast16_t v = ecb_peek (ptr);