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

Comparing libecb/ecb.pod (file contents):
Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC vs.
Revision 1.98 by root, Fri Aug 20 20:06:47 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
 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++.
 =item ECB_CPP11, ECB_CPP14, ECB_CPP17
 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<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 integers. While 64 bit
+integer support is very common (and in fact 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
 =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 uint64_t ecb_rotr64 (uint64_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>).
+(C<ecb_rotl>). There are no restrictions on the value C<count>, i.e. both
+zero and values equal or larger than the word width work correctly. Also,
+notwithstanding C<count> being unsigned, negative numbers work and shift
+to the opposite direction.
-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++]
 C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
 =back
+=head2 BIT MIXING, HASHING
+Sometimes you have an integer and want to distribute its bits well, for
+example, to use it as a hash in a hashtable. A common example is pointer
+values, which often only have a limited range (e.g. low and high bits are
+often zero).
+The following functions try to mix the bits to get a good bias-free
+distribution. They were mainly made for pointers, but the underlying
+integer functions are exposed as well.
+As an added benefit, the functions are reversible, so if you find it
+convenient to store only the hash value, you can recover the original
+pointer from the hash ("unmix"), as long as your pinters are 32 or 64 bit
+(if this isn't the case on your platform, drop us a note and we will add
+functions for other bit widths).
+The unmix functions are very slightly slower than the mix functions, so
+it is equally very slightly preferable to store the original values wehen
+convenient.
+The underlying algorithm if subject to change, so currently these
+functions are not suitable for persistent hash tables, as their result
+value can change between diferent versions of libecb.
+=over
+=item uintptr_t ecb_ptrmix (void *ptr)
+Mixes the bits of a pointer so the result is suitable for hash table
+lookups. In other words, this hashes the pointer value.
+=item uintptr_t ecb_ptrmix (T *ptr) [C++]
+Overload the C<ecb_ptrmix> function to work for any pointer in C++.
+=item void *ecb_ptrunmix (uintptr_t v)
+Unmix the hash value into the original pointer. This only works as long
+as the hash value is not truncated, i.e. you used C<uintptr_t> (or
+equivalent) throughout to store it.
+=item T *ecb_ptrunmix<T> (uintptr_t v) [C++]
+The somewhat less useful template version of C<ecb_ptrunmix> for
+C++. Example:
+   sometype *myptr;
+   uintptr_t hash = ecb_ptrmix (myptr);
+   sometype *orig = ecb_ptrunmix<sometype> (hash);
+=item uint32_t ecb_mix32 (uint32_t v)
+=item uint64_t ecb_mix64 (uint64_t v)
+Sometimes you don't have a pointer but an integer whose values are very
+badly distributed. In this case you cna sue these integer versions of the
+mixing function. No C++ template is provided currently.
+=item uint32_t ecb_unmix32 (uint32_t v)
+=item uint64_t ecb_unmix64 (uint64_t v)
+The reverse of the C<ecb_mix> functions - they take a mixed/hashed value
+and recover the original value.
+=back
 =head2 HOST ENDIANNESS CONVERSION
-=over 4
+=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)
 =back
 In C++ the following additional template functions are supported:
-=over 4
+=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>
 =head2 UNALIGNED LOAD/STORE
 These function load or store unaligned multi-byte values.
-=over 4
+=over
 =item uint_fast16_t ecb_peek_u16_u (const void *ptr)
 =item uint_fast32_t ecb_peek_u32_u (const void *ptr)
 =back
 In C++ the following additional template functions are supported:
-=over 4
+=over
 =item T ecb_peek<T>      (const void *ptr)
 =item T ecb_peek_be<T>   (const void *ptr)
 (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 FAST INTEGER TO STRING
+Libecb defines a set of very fast integer to decimal string (or integer
+to ascii, short C<i2a>) functions.  These work by converting the integer
+to a fixed point representation and then successively multiplying out
+the topmost digits. Unlike some other, also very fast, libraries, ecb's
+algorithm should be completely branchless per digit, and does not rely on
+the presence of special cpu functions (such as clz).
+There is a high level API that takes an C<int32_t>, C<uint32_t>,
+C<int64_t> or C<uint64_t> as argument, and a low-level API, which is
+harder to use but supports slightly more formatting options.
+=head3 HIGH LEVEL API
+The high level API consists of four functions, one each for C<int32_t>,
+C<uint32_t>, C<int64_t> and C<uint64_t>:
+Example:
+   char buf[ECB_I2A_MAX_DIGITS + 1];
+   char *end = ecb_i2a_i32 (buf, 17262);
+   *end = 0;
+   // buf now contains "17262"
+=over
+=item ECB_I2A_I32_DIGITS (=11)
+=item char *ecb_i2a_u32 (char *ptr, uint32_t value)
+Takes an C<uint32_t> I<value> and formats it as a decimal number starting
+at I<ptr>, using at most C<ECB_I2A_I32_DIGITS> characters. Returns a
+pointer to just after the generated string, where you would normally put
+the terminating C<0> character. This function outputs the minimum number
+of digits.
+=item ECB_I2A_U32_DIGITS (=10)
+=item char *ecb_i2a_i32 (char *ptr, int32_t value)
+Same as C<ecb_i2a_u32>, but formats a C<int32_t> value, including a minus
+sign if needed.
+=item ECB_I2A_I64_DIGITS (=20)
+=item char *ecb_i2a_u64 (char *ptr, uint64_t value)
+=item ECB_I2A_U64_DIGITS (=21)
+=item char *ecb_i2a_i64 (char *ptr, int64_t value)
+Similar to their 32 bit counterparts, these take a 64 bit argument.
+=item ECB_I2A_MAX_DIGITS (=21)
+Instead of using a type specific length macro, you can just use
+C<ECB_I2A_MAX_DIGITS>, which is good enough for any C<ecb_i2a> function.
+=back
+=head3 LOW-LEVEL API
+The functions above use a number of low-level APIs which have some strict
+limitations, but can be used as building blocks (studying C<ecb_i2a_i32>
+and related functions is recommended).
+There are three families of functions: functions that convert a number
+to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0>
+for "leading zeroes"), functions that generate up to N digits, skipping
+leading zeroes (C<_N>), and functions that can generate more digits, but
+the leading digit has limited range (C<_xN>).
+None of the functions deal with negative numbers.
+Example: convert an IP address in an u32 into dotted-quad:
+   uint32_t ip = 0x0a000164; // 10.0.1.100
+   char ips[3 * 4 + 3 + 1];
+   char *ptr = ips;
+   ptr = ecb_i2a_3 (ptr,  ip >> 24        ); *ptr++ = '.';
+   ptr = ecb_i2a_3 (ptr, (ip >> 16) & 0xff); *ptr++ = '.';
+   ptr = ecb_i2a_3 (ptr, (ip >>  8) & 0xff); *ptr++ = '.';
+   ptr = ecb_i2a_3 (ptr,  ip        & 0xff); *ptr++ = 0;
+   printf ("ip: %s\n", ips); // prints "ip: 10.0.1.100"
+=over
+=item char *ecb_i2a_02  (char *ptr, uint32_t value) // 32 bit
+=item char *ecb_i2a_03  (char *ptr, uint32_t value) // 32 bit
+=item char *ecb_i2a_04  (char *ptr, uint32_t value) // 32 bit
+=item char *ecb_i2a_05  (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_06  (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_07  (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_08  (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_09  (char *ptr, uint32_t value) // 64 bit
+The C<< ecb_i2a_0I<N> > functions take an unsigned I<value> and convert
+them to exactly I<N> digits, returning a pointer to the first character
+after the digits. The I<value> must be in range. The functions marked with
+I<32 bit> do their calculations internally in 32 bit, the ones marked with
+I<64 bit> internally use 64 bit integers, which might be slow on 32 bit
+architectures (the high level API decides on 32 vs. 64 bit versions using
+C<ECB_64BIT_NATIVE>).
+=item char *ecb_i2a_2   (char *ptr, uint32_t value) // 32 bit
+=item char *ecb_i2a_3   (char *ptr, uint32_t value) // 32 bit
+=item char *ecb_i2a_4   (char *ptr, uint32_t value) // 32 bit
+=item char *ecb_i2a_5   (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_6   (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_7   (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_8   (char *ptr, uint32_t value) // 64 bit
+=item char *ecb_i2a_9   (char *ptr, uint32_t value) // 64 bit
+Similarly, the C<< ecb_i2a_I<N> > functions take an unsigned I<value>
+and convert them to at most I<N> digits, suppressing leading zeroes, and
+returning a pointer to the first character after the digits.
+=item ECB_I2A_MAX_X5 (=59074)
+=item char *ecb_i2a_x5  (char *ptr, uint32_t value) // 32 bit
+=item ECB_I2A_MAX_X10 (=2932500665)
+=item char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit
+The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >
+functions, but they can generate one digit more, as long as the number
+is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost
+16 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
+respectively.
+For example, the digit part of a 32 bit signed integer just fits into the
+C<ECB_I2A_MAX_X10> range, so while C<ecb_i2a_x10> cannot convert a 10
+digit number, it can convert all 32 bit signed numbers. Sadly, it's not
+good enough for 32 bit unsigned numbers.
+=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.
 =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.81 by root, Mon Jan 20 21:01:29 2020 UTC vs. Revision 1.98 by root, Fri Aug 20 20:06:47 2021 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.81 by root, Mon Jan 20 21:01:29 2020 UTC vs.
Revision 1.98 by root, Fri Aug 20 20:06:47 2021 UTC