ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libecb/ecb.pod
(Generate patch)

Comparing libecb/ecb.pod (file contents):
Revision 1.94 by root, Sat Jul 31 16:13:30 2021 UTC vs.
Revision 1.101 by root, Mon Nov 22 17:15:50 2021 UTC

… …
732=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count) 732=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
733 733
734These two families of functions return the value of C<x> after rotating 734These two families of functions return the value of C<x> after rotating
735all the bits by C<count> positions to the right (C<ecb_rotr>) or left 735all the bits by C<count> positions to the right (C<ecb_rotr>) or left
736(C<ecb_rotl>). There are no restrictions on the value C<count>, i.e. both 736(C<ecb_rotl>). There are no restrictions on the value C<count>, i.e. both
737zero and values equal or larger than the word width work correctly. 737zero and values equal or larger than the word width work correctly. Also,
738notwithstanding C<count> being unsigned, negative numbers work and shift
739to the opposite direction.
738 740
739Current GCC/clang versions understand these functions and usually compile 741Current GCC/clang versions understand these functions and usually compile
740them to "optimal" code (e.g. a single C<rol> or a combination of C<shld> 742them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
741on x86). 743on x86).
742 744
… …
745=item T ecb_rotr (T x, unsigned int count) [C++] 747=item T ecb_rotr (T x, unsigned int count) [C++]
746 748
747Overloaded C++ rotl/rotr functions. 749Overloaded C++ rotl/rotr functions.
748 750
749C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>. 751C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>.
752
753=back
754
755=head2 BIT MIXING, HASHING
756
757Sometimes you have an integer and want to distribute its bits well, for
758example, to use it as a hash in a hashtable. A common example is pointer
759values, which often only have a limited range (e.g. low and high bits are
760often zero).
761
762The following functions try to mix the bits to get a good bias-free
763distribution. They were mainly made for pointers, but the underlying
764integer functions are exposed as well.
765
766As an added benefit, the functions are reversible, so if you find it
767convenient to store only the hash value, you can recover the original
768pointer from the hash ("unmix"), as long as your pinters are 32 or 64 bit
769(if this isn't the case on your platform, drop us a note and we will add
770functions for other bit widths).
771
772The unmix functions are very slightly slower than the mix functions, so
773it is equally very slightly preferable to store the original values wehen
774convenient.
775
776The underlying algorithm if subject to change, so currently these
777functions are not suitable for persistent hash tables, as their result
778value can change between diferent versions of libecb.
779
780=over
781
782=item uintptr_t ecb_ptrmix (void *ptr)
783
784Mixes the bits of a pointer so the result is suitable for hash table
785lookups. In other words, this hashes the pointer value.
786
787=item uintptr_t ecb_ptrmix (T *ptr) [C++]
788
789Overload the C<ecb_ptrmix> function to work for any pointer in C++.
790
791=item void *ecb_ptrunmix (uintptr_t v)
792
793Unmix the hash value into the original pointer. This only works as long
794as the hash value is not truncated, i.e. you used C<uintptr_t> (or
795equivalent) throughout to store it.
796
797=item T *ecb_ptrunmix<T> (uintptr_t v) [C++]
798
799The somewhat less useful template version of C<ecb_ptrunmix> for
800C++. Example:
801
802 sometype *myptr;
803 uintptr_t hash = ecb_ptrmix (myptr);
804 sometype *orig = ecb_ptrunmix<sometype> (hash);
805
806=item uint32_t ecb_mix32 (uint32_t v)
807
808=item uint64_t ecb_mix64 (uint64_t v)
809
810Sometimes you don't have a pointer but an integer whose values are very
811badly distributed. In this case you cna sue these integer versions of the
812mixing function. No C++ template is provided currently.
813
814=item uint32_t ecb_unmix32 (uint32_t v)
815
816=item uint64_t ecb_unmix64 (uint64_t v)
817
818The reverse of the C<ecb_mix> functions - they take a mixed/hashed value
819and recover the original value.
750 820
751=back 821=back
752 822
753=head2 HOST ENDIANNESS CONVERSION 823=head2 HOST ENDIANNESS CONVERSION
754 824
… …
973 1043
974Similar to their 32 bit counterparts, these take a 64 bit argument. 1044Similar to their 32 bit counterparts, these take a 64 bit argument.
975 1045
976=item ECB_I2A_MAX_DIGITS (=21) 1046=item ECB_I2A_MAX_DIGITS (=21)
977 1047
978Instead of using a type specific length macro, youi can just use 1048Instead of using a type specific length macro, you can just use
979C<ECB_I2A_MAX_DIGITS>, which is good enough for any C<ecb_i2a> function. 1049C<ECB_I2A_MAX_DIGITS>, which is good enough for any C<ecb_i2a> function.
980 1050
981=back 1051=back
982 1052
983=head3 LOW-LEVEL API 1053=head3 LOW-LEVEL API
984 1054
985The functions above use a number of low-level APIs which have some strict 1055The functions above use a number of low-level APIs which have some strict
986limitations, but can be used as building blocks (study of C<ecb_i2a_i32> 1056limitations, but can be used as building blocks (studying C<ecb_i2a_i32>
987and related functions is recommended). 1057and related functions is recommended).
988 1058
989There are three families of functions: functions that convert a number 1059There are three families of functions: functions that convert a number
990to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0> 1060to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0>
991for "leading zeroes"), functions that generate up to N digits, skipping 1061for "leading zeroes"), functions that generate up to N digits, skipping
… …
1021 1091
1022=item char *ecb_i2a_08 (char *ptr, uint32_t value) // 64 bit 1092=item char *ecb_i2a_08 (char *ptr, uint32_t value) // 64 bit
1023 1093
1024=item char *ecb_i2a_09 (char *ptr, uint32_t value) // 64 bit 1094=item char *ecb_i2a_09 (char *ptr, uint32_t value) // 64 bit
1025 1095
1026The C<< ecb_i2a_0I<N> > functions take an unsigned I<value> and convert 1096The C<< ecb_i2a_0I<N> >> functions take an unsigned I<value> and convert
1027them to exactly I<N> digits, returning a pointer to the first character 1097them to exactly I<N> digits, returning a pointer to the first character
1028after the digits. The I<value> must be in range. The functions marked with 1098after the digits. The I<value> must be in range. The functions marked with
1029I<32 bit> do their calculations internally in 32 bit, the ones marked with 1099I<32 bit> do their calculations internally in 32 bit, the ones marked with
1030I<64 bit> internally use 64 bit integers, which might be slow on 32 bit 1100I<64 bit> internally use 64 bit integers, which might be slow on 32 bit
1031architectures (the high level API decides on 32 vs. 64 bit versions using 1101architectures (the high level API decides on 32 vs. 64 bit versions using
… …
1045 1115
1046=item char *ecb_i2a_8 (char *ptr, uint32_t value) // 64 bit 1116=item char *ecb_i2a_8 (char *ptr, uint32_t value) // 64 bit
1047 1117
1048=item char *ecb_i2a_9 (char *ptr, uint32_t value) // 64 bit 1118=item char *ecb_i2a_9 (char *ptr, uint32_t value) // 64 bit
1049 1119
1050Similarly, the C<< ecb_i2a_I<N> > functions take an unsigned I<value> 1120Similarly, the C<< ecb_i2a_I<N> >> functions take an unsigned I<value>
1051and convert them to at most I<N> digits, suppressing leading zeroes, and 1121and convert them to at most I<N> digits, suppressing leading zeroes, and
1052returning a pointer to the first character after the digits. 1122returning a pointer to the first character after the digits.
1053 1123
1054=item ECB_I2A_MAX_X5 (=59074) 1124=item ECB_I2A_MAX_X5 (=59074)
1055 1125
… …
1057 1127
1058=item ECB_I2A_MAX_X10 (=2932500665) 1128=item ECB_I2A_MAX_X10 (=2932500665)
1059 1129
1060=item char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit 1130=item char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit
1061 1131
1062The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> > 1132The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >>
1063functions, but they can generate one digit more, as long as the number 1133functions, but they can generate one digit more, as long as the number
1064is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost 1134is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost
106516 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range), 113516 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
1066respectively. 1136respectively.
1067 1137
… …
1107IEEE compliant, of course at a speed and code size penalty, and of course 1177IEEE compliant, of course at a speed and code size penalty, and of course
1108also within reasonable limits (it tries to convert NaNs, infinities and 1178also within reasonable limits (it tries to convert NaNs, infinities and
1109denormals, but will likely convert negative zero to positive zero). 1179denormals, but will likely convert negative zero to positive zero).
1110 1180
1111On all modern platforms (where C<ECB_STDFP> is true), the compiler should 1181On all modern platforms (where C<ECB_STDFP> is true), the compiler should
1112be able to optimise away this function completely. 1182be able to completely optimise away the 32 and 64 bit functions.
1113 1183
1114These functions can be helpful when serialising floats to the network - you 1184These functions can be helpful when serialising floats to the network - you
1115can serialise the return value like a normal uint16_t/uint32_t/uint64_t. 1185can serialise the return value like a normal uint16_t/uint32_t/uint64_t.
1116 1186
1117Another use for these functions is to manipulate floating point values 1187Another use for these functions is to manipulate floating point values
… …
1253intended to be internal-use only, some of which we forgot to document, and 1323intended to be internal-use only, some of which we forgot to document, and
1254some of which we hide because we are not sure we will keep the interface 1324some of which we hide because we are not sure we will keep the interface
1255stable. 1325stable.
1256 1326
1257While you are welcome to rummage around and use whatever you find useful 1327While you are welcome to rummage around and use whatever you find useful
1258(we can't stop you), keep in mind that we will change undocumented 1328(we don't want to stop you), keep in mind that we will change undocumented
1259functionality in incompatible ways without thinking twice, while we are 1329functionality in incompatible ways without thinking twice, while we are
1260considerably more conservative with documented things. 1330considerably more conservative with documented things.
1261 1331
1262=head1 AUTHORS 1332=head1 AUTHORS
1263 1333
1264C<libecb> is designed and maintained by: 1334C<libecb> is designed and maintained by:
1265 1335
1266 Emanuele Giaquinta <e.giaquinta@glauco.it> 1336 Emanuele Giaquinta <e.giaquinta@glauco.it>
1267 Marc Alexander Lehmann <schmorp@schmorp.de> 1337 Marc Alexander Lehmann <schmorp@schmorp.de>
1268
1269

Diff Legend

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