… | |
… | |
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 | |
734 | These two families of functions return the value of C<x> after rotating |
734 | These two families of functions return the value of C<x> after rotating |
735 | all the bits by C<count> positions to the right (C<ecb_rotr>) or left |
735 | all 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 |
737 | zero and values equal or larger than the word width work correctly. |
737 | zero and values equal or larger than the word width work correctly. Also, |
|
|
738 | notwithstanding C<count> being unsigned, negative numbers work and shift |
|
|
739 | to the opposite direction. |
738 | |
740 | |
739 | Current GCC/clang versions understand these functions and usually compile |
741 | Current GCC/clang versions understand these functions and usually compile |
740 | them to "optimal" code (e.g. a single C<rol> or a combination of C<shld> |
742 | them to "optimal" code (e.g. a single C<rol> or a combination of C<shld> |
741 | on x86). |
743 | on 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 | |
747 | Overloaded C++ rotl/rotr functions. |
749 | Overloaded C++ rotl/rotr functions. |
748 | |
750 | |
749 | C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>. |
751 | C<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 | |
|
|
757 | Sometimes you have an integer and want to distribute its bits well, for |
|
|
758 | example, to use it as a hash in a hashtable. A common example is pointer |
|
|
759 | values, which often only have a limited range (e.g. low and high bits are |
|
|
760 | often zero). |
|
|
761 | |
|
|
762 | The following functions try to mix the bits to get a good bias-free |
|
|
763 | distribution. They were mainly made for pointers, but the underlying |
|
|
764 | integer functions are exposed as well. |
|
|
765 | |
|
|
766 | As an added benefit, the functions are reversible, so if you find it |
|
|
767 | convenient to store only the hash value, you can recover the original |
|
|
768 | pointer 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 |
|
|
770 | functions for other bit widths). |
|
|
771 | |
|
|
772 | The unmix functions are very slightly slower than the mix functions, so |
|
|
773 | it is equally very slightly preferable to store the original values wehen |
|
|
774 | convenient. |
|
|
775 | |
|
|
776 | The underlying algorithm if subject to change, so currently these |
|
|
777 | functions are not suitable for persistent hash tables, as their result |
|
|
778 | value can change between diferent versions of libecb. |
|
|
779 | |
|
|
780 | =over |
|
|
781 | |
|
|
782 | =item uintptr_t ecb_ptrmix (void *ptr) |
|
|
783 | |
|
|
784 | Mixes the bits of a pointer so the result is suitable for hash table |
|
|
785 | lookups. In other words, this hashes the pointer value. |
|
|
786 | |
|
|
787 | =item uintptr_t ecb_ptrmix (T *ptr) [C++] |
|
|
788 | |
|
|
789 | Overload the C<ecb_ptrmix> function to work for any pointer in C++. |
|
|
790 | |
|
|
791 | =item void *ecb_ptrunmix (uintptr_t v) |
|
|
792 | |
|
|
793 | Unmix the hash value into the original pointer. This only works as long |
|
|
794 | as the hash value is not truncated, i.e. you used C<uintptr_t> (or |
|
|
795 | equivalent) throughout to store it. |
|
|
796 | |
|
|
797 | =item T *ecb_ptrunmix<T> (uintptr_t v) [C++] |
|
|
798 | |
|
|
799 | The somewhat less useful template version of C<ecb_ptrunmix> for |
|
|
800 | C++. 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 | |
|
|
810 | Sometimes you don't have a pointer but an integer whose values are very |
|
|
811 | badly distributed. In this case you cna sue these integer versions of the |
|
|
812 | mixing 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 | |
|
|
818 | The reverse of the C<ecb_mix> functions - they take a mixed/hashed value |
|
|
819 | and 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 | |
974 | Similar to their 32 bit counterparts, these take a 64 bit argument. |
1044 | Similar 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 | |
978 | Instead of using a type specific length macro, youi can just use |
1048 | Instead of using a type specific length macro, you can just use |
979 | C<ECB_I2A_MAX_DIGITS>, which is good enough for any C<ecb_i2a> function. |
1049 | C<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 | |
985 | The functions above use a number of low-level APIs which have some strict |
1055 | The functions above use a number of low-level APIs which have some strict |
986 | limitations, but can be used as building blocks (study of C<ecb_i2a_i32> |
1056 | limitations, but can be used as building blocks (studying C<ecb_i2a_i32> |
987 | and related functions is recommended). |
1057 | and related functions is recommended). |
988 | |
1058 | |
989 | There are three families of functions: functions that convert a number |
1059 | There are three families of functions: functions that convert a number |
990 | to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0> |
1060 | to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0> |
991 | for "leading zeroes"), functions that generate up to N digits, skipping |
1061 | for "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 | |
1026 | The C<< ecb_i2a_0I<N> > functions take an unsigned I<value> and convert |
1096 | The C<< ecb_i2a_0I<N> >> functions take an unsigned I<value> and convert |
1027 | them to exactly I<N> digits, returning a pointer to the first character |
1097 | them to exactly I<N> digits, returning a pointer to the first character |
1028 | after the digits. The I<value> must be in range. The functions marked with |
1098 | after the digits. The I<value> must be in range. The functions marked with |
1029 | I<32 bit> do their calculations internally in 32 bit, the ones marked with |
1099 | I<32 bit> do their calculations internally in 32 bit, the ones marked with |
1030 | I<64 bit> internally use 64 bit integers, which might be slow on 32 bit |
1100 | I<64 bit> internally use 64 bit integers, which might be slow on 32 bit |
1031 | architectures (the high level API decides on 32 vs. 64 bit versions using |
1101 | architectures (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 | |
1050 | Similarly, the C<< ecb_i2a_I<N> > functions take an unsigned I<value> |
1120 | Similarly, the C<< ecb_i2a_I<N> >> functions take an unsigned I<value> |
1051 | and convert them to at most I<N> digits, suppressing leading zeroes, and |
1121 | and convert them to at most I<N> digits, suppressing leading zeroes, and |
1052 | returning a pointer to the first character after the digits. |
1122 | returning 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 | |
1062 | The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> > |
1132 | The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >> |
1063 | functions, but they can generate one digit more, as long as the number |
1133 | functions, but they can generate one digit more, as long as the number |
1064 | is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost |
1134 | is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost |
1065 | 16 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range), |
1135 | 16 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range), |
1066 | respectively. |
1136 | respectively. |
1067 | |
1137 | |
… | |
… | |
1107 | IEEE compliant, of course at a speed and code size penalty, and of course |
1177 | IEEE compliant, of course at a speed and code size penalty, and of course |
1108 | also within reasonable limits (it tries to convert NaNs, infinities and |
1178 | also within reasonable limits (it tries to convert NaNs, infinities and |
1109 | denormals, but will likely convert negative zero to positive zero). |
1179 | denormals, but will likely convert negative zero to positive zero). |
1110 | |
1180 | |
1111 | On all modern platforms (where C<ECB_STDFP> is true), the compiler should |
1181 | On all modern platforms (where C<ECB_STDFP> is true), the compiler should |
1112 | be able to optimise away this function completely. |
1182 | be able to completely optimise away the 32 and 64 bit functions. |
1113 | |
1183 | |
1114 | These functions can be helpful when serialising floats to the network - you |
1184 | These functions can be helpful when serialising floats to the network - you |
1115 | can serialise the return value like a normal uint16_t/uint32_t/uint64_t. |
1185 | can serialise the return value like a normal uint16_t/uint32_t/uint64_t. |
1116 | |
1186 | |
1117 | Another use for these functions is to manipulate floating point values |
1187 | Another use for these functions is to manipulate floating point values |
… | |
… | |
1253 | intended to be internal-use only, some of which we forgot to document, and |
1323 | intended to be internal-use only, some of which we forgot to document, and |
1254 | some of which we hide because we are not sure we will keep the interface |
1324 | some of which we hide because we are not sure we will keep the interface |
1255 | stable. |
1325 | stable. |
1256 | |
1326 | |
1257 | While you are welcome to rummage around and use whatever you find useful |
1327 | While 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 |
1259 | functionality in incompatible ways without thinking twice, while we are |
1329 | functionality in incompatible ways without thinking twice, while we are |
1260 | considerably more conservative with documented things. |
1330 | considerably more conservative with documented things. |
1261 | |
1331 | |
1262 | =head1 AUTHORS |
1332 | =head1 AUTHORS |
1263 | |
1333 | |
1264 | C<libecb> is designed and maintained by: |
1334 | C<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 | |
|
|