[ViewVC] Diff of: cvs/libecb/ecb.pod

Comparing libecb/ecb.pod (file contents):
Revision 1.71 by root, Sat Nov 21 16:53:50 2015 UTC vs.
Revision 1.88 by root, Mon Jun 21 21:49:51 2021 UTC

 Its homepage can be found here:
     http://software.schmorp.de/pkg/libecb
-It mainly provides a number of wrappers around GCC built-ins, together
+It mainly provides a number of wrappers around many compiler built-ins,
-with replacement functions for other compilers. In addition to this,
+together with replacement functions for other compilers. In addition
-it provides a number of other lowlevel C utilities, such as endianness
+to this, it provides a number of other lowlevel C utilities, such as
-detection, byte swapping or bit rotations.
+endianness detection, byte swapping or bit rotations.
-Or in other words, things that should be built into any standard C system,
+Or in other words, things that should be built into any standard C
-but aren't, implemented as efficient as possible with GCC, and still
+system, but aren't, implemented as efficient as possible with GCC (clang,
-correct with other compilers.
+msvc...), and still correct with other compilers.
 More might come.
 =head2 ABOUT THE HEADER
 =head2 TYPES / TYPE SUPPORT
 ecb.h makes sure that the following types are defined (in the expected way):
-   int8_t   uint8_t   int16_t  uint16_t
+   int8_t       uint8_
-   int32_t  uint32_t  int64_t  uint64_t
+   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
+   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
 expressions.
-For C<ptrdiff_t> and C<size_t> use C<stddef.h>.
+For C<ptrdiff_t> and C<size_t> use C<stddef.h>/C<cstddef>.
 =head2 LANGUAGE/ENVIRONMENT/COMPILER VERSIONS
 All the following symbols expand to an expression that can be tested in
 preprocessor instructions as well as treated as a boolean (use C<!!> to
 ensure it's either C<0> or C<1> if you need that).
-=over 4
+=over
 =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
 True if the implementation claims to be compliant to C99 (ISO/IEC
 9899:1999) or any later version, while not claiming to be C++.
 Note that later versions (ECB_C11) remove core features again (for
 example, variable length arrays).
-=item ECB_C11
+=item ECB_C11, ECB_C17
-True if the implementation claims to be compliant to C11 (ISO/IEC
+True if the implementation claims to be compliant to C11/C17 (ISO/IEC
-9899:2011) or any later version, while not claiming to be C++.
+9899:2011, :20187) or any later version, while not claiming to be C++.
 =item ECB_CPP
 True if the implementation defines the C<__cplusplus__> macro to a true
 value, which is typically true for C++ compilers.
-=item ECB_CPP11
+=item ECB_CPP11, ECB_CPP14, ECB_CPP17
-True if the implementation claims to be compliant to ISO/IEC 14882:2011
+True if the implementation claims to be compliant to C++11/C++14/C++17
-(C++11) or any later version.
+(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<http://eel.is/c++draft/cpp.predefined#1.8>).
+=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)
+Expands to a true value (suitable for testing by the preprocessor) if the
-if the compiler used is GNU C and the version is the given version, or
+compiler used is GNU C and the version is the given version, or higher.
-higher.
 This macro tries to return false on compilers that claim to be GCC
 compatible but aren't.
 =item ECB_EXTERN_C
    ECB_EXTERN_C_END
 =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<float> and C<double> use IEEE 754 single/binary32
 and double/binary64 representations internally I<and> the endianness of
 both types match the endianness of C<uint32_t> and C<uint64_t>.
 This means you can just copy the bits of a C<float> (or C<double>) to an
 without having to think about format or endianness.
 This is true for basically all modern platforms, although F<ecb.h> might
 not be able to deduce this correctly everywhere and might err on the safe
 side.
+=item ECB_64BIT_NATIVE
+Evaluates to a true value (suitable for both preprocessor and C code
+testing) if 64 bit integer types on this architecture are evaluated
+"natively", that is, with similar speeds as 32 bit integerss. While 64 bit
+integer support is very common (and in fatc required by libecb), 32 bit
+cpus have to emulate operations on them, so you might want to avoid them.
 =item ECB_AMD64, ECB_AMD64_X32
 These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
 ABI, respectively, and undefined elsewhere.
 =back
 =head2 MACRO TRICKERY
-=over 4
+=over
 =item ECB_CONCAT (a, b)
 Expands any macros in C<a> and C<b>, then concatenates the result to form
 a single token. This is mainly useful to form identifiers from components,
 declarations must be put before the whole declaration:
    ecb_const int mysqrt (int a);
    ecb_unused int i;
-=over 4
+=over
 =item ecb_unused
 Marks a function or a variable as "unused", which simply suppresses a
-warning by GCC when it detects it as unused. This is useful when you e.g.
+warning by the compiler when it detects it as unused. This is useful when
-declare a variable but do not always use it:
+you e.g. declare a variable but do not always use it:
   {
     ecb_unused int var;
     #ifdef SOMECONDITION
 used instead of a generic depreciation message when the object is being
 used.
 =item ecb_inline
-Expands either to C<static inline> or to just C<static>, if inline
+Expands either to (a compiler-specific equivalent of) C<static inline> or
-isn't supported. It should be used to declare functions that should be
+to just C<static>, if inline isn't supported. It should be used to declare
-inlined, for code size or speed reasons.
+functions that should be inlined, for code size or speed reasons.
 Example: inline this function, it surely will reduce codesize.
    ecb_inline int
    negmul (int a, int b)
 =back
 =head2 OPTIMISATION HINTS
-=over 4
+=over
 =item bool ecb_is_constant (expr)
 Returns true iff the expression can be deduced to be a compile-time
 constant, and false otherwise.
 =back
 =head2 BIT FIDDLING / BIT WIZARDRY
-=over 4
+=over
 =item bool ecb_big_endian ()
 =item bool ecb_little_endian ()
 =item int ecb_ctz32 (uint32_t x)
 =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
   ecb_ctz32 (6) = 1
 =item bool ecb_is_pot32 (uint32_t x)
 =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
 to compute the integer binary logarithm, i.e. C<floor (log2 (n))>, for
 the given data type), while C<ecb_ld> returns how many bits the number
 itself requires.
 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
   ecb_popcount32 (255) = 8
 =item uint16_t ecb_bitrev16 (uint16_t x)
 =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)
 =item uint32_t ecb_rotl32 (uint32_t x, unsigned int count)
 These two families of functions return the value of C<x> after rotating
 all the bits by C<count> positions to the right (C<ecb_rotr>) or left
 (C<ecb_rotl>).
-Current GCC versions understand these functions and usually compile them
+Current GCC/clang versions understand these functions and usually compile
-to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on
+them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
-x86).
+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
+=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
+=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)
+=back
+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
+=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
+=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
-=over 4
+=over
 =item ECB_INFINITY [-UECB_NO_LIBM]
 Evaluates to positive infinity if supported by the platform, otherwise to
 a truly huge number.
 =item uint16_t ecb_binary32_to_binary16 (uint32_t x)
 =item uint32_t ecb_binary16_to_binary32 (uint16_t x)
 Convert a IEEE binary32/single precision to binary16/half format, and vice
-versa, handling all details (round-to-even, subnormals, infinity and NaNs)
+versa, handling all details (round-to-nearest-even, subnormals, infinity
-correctly.
+and NaNs) correctly.
 These are functions are available under C<-DECB_NO_LIBM>, since
 they do not rely on the platform floating point format. The
 C<ecb_float_to_binary16> and C<ecb_binary16_to_float> functions are
 usually what you want.
 =back
 =head2 ARITHMETIC
-=over 4
+=over
 =item x = ecb_mod (m, n)
 Returns C<m> modulo C<n>, which is the same as the positive remainder
 of the division operation between C<m> and C<n>, using floored
 C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
 negatable, that is, both C<m> and C<-m> must be representable in its
 type (this typically excludes the minimum signed integer value, the same
 limitation as for C</> and C<%> in C).
-Current GCC versions compile this into an efficient branchless sequence on
+Current GCC/clang versions compile this into an efficient branchless
-almost all CPUs.
+sequence on almost all CPUs.
 For example, when you want to rotate forward through the members of an
 array for increasing C<m> (which might be negative), then you should use
 C<ecb_mod>, as the C<%> operator might give either negative results, or
 change direction for negative values:
 =back
 =head2 UTILITY
-=over 4
+=over
 =item element_count = ecb_array_length (name)
 Returns the number of elements in the array C<name>. For example:
 =head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
 These symbols need to be defined before including F<ecb.h> the first time.
-=over 4
+=over
 =item ECB_NO_THREADS
 If F<ecb.h> is never used from multiple threads, then this symbol can
 be defined, in which case memory fences (and similar constructs) are

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libecb/ecb.pod (file contents): Revision 1.71 by root, Sat Nov 21 16:53:50 2015 UTC vs. Revision 1.88 by root, Mon Jun 21 21:49:51 2021 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.71 by root, Sat Nov 21 16:53:50 2015 UTC vs.
Revision 1.88 by root, Mon Jun 21 21:49:51 2021 UTC