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

Comparing libecb/ecb.pod (file contents):
Revision 1.83 by root, Mon Jan 20 21:08:19 2020 UTC vs.
Revision 1.101 by root, Mon Nov 22 17:15:50 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++, i..e C, but not C++.
 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.
 IEEE compliant, of course at a speed and code size penalty, and of course
 also within reasonable limits (it tries to convert NaNs, infinities and
 denormals, but will likely convert negative zero to positive zero).
 On all modern platforms (where C<ECB_STDFP> is true), the compiler should
-be able to optimise away this function completely.
+be able to completely optimise away the 32 and 64 bit functions.
 These functions can be helpful when serialising floats to the network - you
 can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
 Another use for these functions is to manipulate floating point values
 =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
 intended to be internal-use only, some of which we forgot to document, and
 some of which we hide because we are not sure we will keep the interface
 stable.
 While you are welcome to rummage around and use whatever you find useful
-(we can't stop you), keep in mind that we will change undocumented
+(we don't want to stop you), keep in mind that we will change undocumented
 functionality in incompatible ways without thinking twice, while we are
 considerably more conservative with documented things.
 =head1 AUTHORS
 C<libecb> is designed and maintained by:
    Emanuele Giaquinta <e.giaquinta@glauco.it>
    Marc Alexander Lehmann <schmorp@schmorp.de>

Diff Legend

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

Comparing libecb/ecb.pod (file contents): Revision 1.83 by root, Mon Jan 20 21:08:19 2020 UTC vs. Revision 1.101 by root, Mon Nov 22 17:15:50 2021 UTC

Diff Legend

Comparing libecb/ecb.pod (file contents):
Revision 1.83 by root, Mon Jan 20 21:08:19 2020 UTC vs.
Revision 1.101 by root, Mon Nov 22 17:15:50 2021 UTC