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

Comparing cvsroot/libecb/ecb.pod (file contents):
Revision 1.84 by root, Mon Jan 20 21:10:16 2020 UTC vs.
Revision 1.99 by root, Fri Aug 20 20:09:12 2021 UTC

10 10
11Its homepage can be found here: 11Its homepage can be found here:
12 12
13 http://software.schmorp.de/pkg/libecb 13 http://software.schmorp.de/pkg/libecb
14 14
15It mainly provides a number of wrappers around GCC built-ins, together 15It mainly provides a number of wrappers around many compiler built-ins,
16with replacement functions for other compilers. In addition to this, 16together with replacement functions for other compilers. In addition
17it provides a number of other lowlevel C utilities, such as endianness 17to this, it provides a number of other lowlevel C utilities, such as
18detection, byte swapping or bit rotations. 18endianness detection, byte swapping or bit rotations.
19 19
20Or in other words, things that should be built into any standard C system, 20Or in other words, things that should be built into any standard C
21but aren't, implemented as efficient as possible with GCC, and still 21system, but aren't, implemented as efficient as possible with GCC (clang,
22correct with other compilers. 22msvc...), and still correct with other compilers.
23 23
24More might come. 24More might come.
25 25
26=head2 ABOUT THE HEADER 26=head2 ABOUT THE HEADER
27 27
80 80
81All the following symbols expand to an expression that can be tested in 81All the following symbols expand to an expression that can be tested in
82preprocessor instructions as well as treated as a boolean (use C<!!> to 82preprocessor instructions as well as treated as a boolean (use C<!!> to
83ensure it's either C<0> or C<1> if you need that). 83ensure it's either C<0> or C<1> if you need that).
84 84
85=over 4 85=over
86 86
87=item ECB_C 87=item ECB_C
88 88
89True if the implementation defines the C<__STDC__> macro to a true value, 89True if the implementation defines the C<__STDC__> macro to a true value,
90while not claiming to be C++, i..e C, but not C++. 90while not claiming to be C++, i..e C, but not C++.
163without having to think about format or endianness. 163without having to think about format or endianness.
164 164
165This is true for basically all modern platforms, although F<ecb.h> might 165This is true for basically all modern platforms, although F<ecb.h> might
166not be able to deduce this correctly everywhere and might err on the safe 166not be able to deduce this correctly everywhere and might err on the safe
167side. 167side.
168
169=item ECB_64BIT_NATIVE
170
171Evaluates to a true value (suitable for both preprocessor and C code
172testing) if 64 bit integer types on this architecture are evaluated
173"natively", that is, with similar speeds as 32 bit integers. While 64 bit
174integer support is very common (and in fact required by libecb), 32 bit
175cpus have to emulate operations on them, so you might want to avoid them.
168 176
169=item ECB_AMD64, ECB_AMD64_X32 177=item ECB_AMD64, ECB_AMD64_X32
170 178
171These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32 179These two macros are defined to C<1> on the x86_64/amd64 ABI and the X32
172ABI, respectively, and undefined elsewhere. 180ABI, respectively, and undefined elsewhere.
179 187
180=back 188=back
181 189
182=head2 MACRO TRICKERY 190=head2 MACRO TRICKERY
183 191
184=over 4 192=over
185 193
186=item ECB_CONCAT (a, b) 194=item ECB_CONCAT (a, b)
187 195
188Expands any macros in C<a> and C<b>, then concatenates the result to form 196Expands any macros in C<a> and C<b>, then concatenates the result to form
189a single token. This is mainly useful to form identifiers from components, 197a single token. This is mainly useful to form identifiers from components,
230declarations must be put before the whole declaration: 238declarations must be put before the whole declaration:
231 239
232 ecb_const int mysqrt (int a); 240 ecb_const int mysqrt (int a);
233 ecb_unused int i; 241 ecb_unused int i;
234 242
235=over 4 243=over
236 244
237=item ecb_unused 245=item ecb_unused
238 246
239Marks a function or a variable as "unused", which simply suppresses a 247Marks a function or a variable as "unused", which simply suppresses a
240warning by GCC when it detects it as unused. This is useful when you e.g. 248warning by the compiler when it detects it as unused. This is useful when
241declare a variable but do not always use it: 249you e.g. declare a variable but do not always use it:
242 250
243 { 251 {
244 ecb_unused int var; 252 ecb_unused int var;
245 253
246 #ifdef SOMECONDITION 254 #ifdef SOMECONDITION
414 422
415=back 423=back
416 424
417=head2 OPTIMISATION HINTS 425=head2 OPTIMISATION HINTS
418 426
419=over 4 427=over
420 428
421=item bool ecb_is_constant (expr) 429=item bool ecb_is_constant (expr)
422 430
423Returns true iff the expression can be deduced to be a compile-time 431Returns true iff the expression can be deduced to be a compile-time
424constant, and false otherwise. 432constant, and false otherwise.
581 589
582=back 590=back
583 591
584=head2 BIT FIDDLING / BIT WIZARDRY 592=head2 BIT FIDDLING / BIT WIZARDRY
585 593
586=over 4 594=over
587 595
588=item bool ecb_big_endian () 596=item bool ecb_big_endian ()
589 597
590=item bool ecb_little_endian () 598=item bool ecb_little_endian ()
591 599
723 731
724=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count) 732=item uint64_t ecb_rotr64 (uint64_t x, unsigned int count)
725 733
726These 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
727all 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
728(C<ecb_rotl>). 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. Also,
738notwithstanding C<count> being unsigned, negative numbers work and shift
739to the opposite direction.
729 740
730Current GCC versions understand these functions and usually compile them 741Current GCC/clang versions understand these functions and usually compile
731to "optimal" code (e.g. a single C<rol> or a combination of C<shld> on 742them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
732x86). 743on x86).
733 744
734=item T ecb_rotl (T x, unsigned int count) [C++] 745=item T ecb_rotl (T x, unsigned int count) [C++]
735 746
736=item T ecb_rotr (T x, unsigned int count) [C++] 747=item T ecb_rotr (T x, unsigned int count) [C++]
737 748
739 750
740C<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>.
741 752
742=back 753=back
743 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.
820
821=back
822
744=head2 HOST ENDIANNESS CONVERSION 823=head2 HOST ENDIANNESS CONVERSION
745 824
746=over 4 825=over
747 826
748=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v) 827=item uint_fast16_t ecb_be_u16_to_host (uint_fast16_t v)
749 828
750=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v) 829=item uint_fast32_t ecb_be_u32_to_host (uint_fast32_t v)
751 830
779 858
780=back 859=back
781 860
782In C++ the following additional template functions are supported: 861In C++ the following additional template functions are supported:
783 862
784=over 4 863=over
785 864
786=item T ecb_be_to_host (T v) 865=item T ecb_be_to_host (T v)
787 866
788=item T ecb_le_to_host (T v) 867=item T ecb_le_to_host (T v)
789 868
790=item T ecb_host_to_be (T v) 869=item T ecb_host_to_be (T v)
791 870
792=item T ecb_host_to_le (T v) 871=item T ecb_host_to_le (T v)
872
873=back
793 874
794These functions work like their C counterparts, above, but use templates, 875These functions work like their C counterparts, above, but use templates,
795which make them useful in generic code. 876which make them useful in generic code.
796 877
797C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t> 878C<T> must be one of C<uint8_t>, C<uint16_t>, C<uint32_t> or C<uint64_t>
800 881
801=head2 UNALIGNED LOAD/STORE 882=head2 UNALIGNED LOAD/STORE
802 883
803These function load or store unaligned multi-byte values. 884These function load or store unaligned multi-byte values.
804 885
805=over 4 886=over
806 887
807=item uint_fast16_t ecb_peek_u16_u (const void *ptr) 888=item uint_fast16_t ecb_peek_u16_u (const void *ptr)
808 889
809=item uint_fast32_t ecb_peek_u32_u (const void *ptr) 890=item uint_fast32_t ecb_peek_u32_u (const void *ptr)
810 891
854 935
855=back 936=back
856 937
857In C++ the following additional template functions are supported: 938In C++ the following additional template functions are supported:
858 939
859=over 4 940=over
860 941
861=item T ecb_peek<T> (const void *ptr) 942=item T ecb_peek<T> (const void *ptr)
862 943
863=item T ecb_peek_be<T> (const void *ptr) 944=item T ecb_peek_be<T> (const void *ptr)
864 945
906(C<uint8_t>) and also have an aligned version (without the C<_u> prefix), 987(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
907all of which hopefully makes them more useful in generic code. 988all of which hopefully makes them more useful in generic code.
908 989
909=back 990=back
910 991
992=head2 FAST INTEGER TO STRING
993
994Libecb defines a set of very fast integer to decimal string (or integer
995to ascii, short C<i2a>) functions. These work by converting the integer
996to a fixed point representation and then successively multiplying out
997the topmost digits. Unlike some other, also very fast, libraries, ecb's
998algorithm should be completely branchless per digit, and does not rely on
999the presence of special cpu functions (such as clz).
1000
1001There is a high level API that takes an C<int32_t>, C<uint32_t>,
1002C<int64_t> or C<uint64_t> as argument, and a low-level API, which is
1003harder to use but supports slightly more formatting options.
1004
1005=head3 HIGH LEVEL API
1006
1007The high level API consists of four functions, one each for C<int32_t>,
1008C<uint32_t>, C<int64_t> and C<uint64_t>:
1009
1010Example:
1011
1012 char buf[ECB_I2A_MAX_DIGITS + 1];
1013 char *end = ecb_i2a_i32 (buf, 17262);
1014 *end = 0;
1015 // buf now contains "17262"
1016
1017=over
1018
1019=item ECB_I2A_I32_DIGITS (=11)
1020
1021=item char *ecb_i2a_u32 (char *ptr, uint32_t value)
1022
1023Takes an C<uint32_t> I<value> and formats it as a decimal number starting
1024at I<ptr>, using at most C<ECB_I2A_I32_DIGITS> characters. Returns a
1025pointer to just after the generated string, where you would normally put
1026the terminating C<0> character. This function outputs the minimum number
1027of digits.
1028
1029=item ECB_I2A_U32_DIGITS (=10)
1030
1031=item char *ecb_i2a_i32 (char *ptr, int32_t value)
1032
1033Same as C<ecb_i2a_u32>, but formats a C<int32_t> value, including a minus
1034sign if needed.
1035
1036=item ECB_I2A_I64_DIGITS (=20)
1037
1038=item char *ecb_i2a_u64 (char *ptr, uint64_t value)
1039
1040=item ECB_I2A_U64_DIGITS (=21)
1041
1042=item char *ecb_i2a_i64 (char *ptr, int64_t value)
1043
1044Similar to their 32 bit counterparts, these take a 64 bit argument.
1045
1046=item ECB_I2A_MAX_DIGITS (=21)
1047
1048Instead of using a type specific length macro, you can just use
1049C<ECB_I2A_MAX_DIGITS>, which is good enough for any C<ecb_i2a> function.
1050
1051=back
1052
1053=head3 LOW-LEVEL API
1054
1055The functions above use a number of low-level APIs which have some strict
1056limitations, but can be used as building blocks (studying C<ecb_i2a_i32>
1057and related functions is recommended).
1058
1059There are three families of functions: functions that convert a number
1060to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0>
1061for "leading zeroes"), functions that generate up to N digits, skipping
1062leading zeroes (C<_N>), and functions that can generate more digits, but
1063the leading digit has limited range (C<_xN>).
1064
1065None of the functions deal with negative numbers.
1066
1067Example: convert an IP address in an u32 into dotted-quad:
1068
1069 uint32_t ip = 0x0a000164; // 10.0.1.100
1070 char ips[3 * 4 + 3 + 1];
1071 char *ptr = ips;
1072 ptr = ecb_i2a_3 (ptr, ip >> 24 ); *ptr++ = '.';
1073 ptr = ecb_i2a_3 (ptr, (ip >> 16) & 0xff); *ptr++ = '.';
1074 ptr = ecb_i2a_3 (ptr, (ip >> 8) & 0xff); *ptr++ = '.';
1075 ptr = ecb_i2a_3 (ptr, ip & 0xff); *ptr++ = 0;
1076 printf ("ip: %s\n", ips); // prints "ip: 10.0.1.100"
1077
1078=over
1079
1080=item char *ecb_i2a_02 (char *ptr, uint32_t value) // 32 bit
1081
1082=item char *ecb_i2a_03 (char *ptr, uint32_t value) // 32 bit
1083
1084=item char *ecb_i2a_04 (char *ptr, uint32_t value) // 32 bit
1085
1086=item char *ecb_i2a_05 (char *ptr, uint32_t value) // 64 bit
1087
1088=item char *ecb_i2a_06 (char *ptr, uint32_t value) // 64 bit
1089
1090=item char *ecb_i2a_07 (char *ptr, uint32_t value) // 64 bit
1091
1092=item char *ecb_i2a_08 (char *ptr, uint32_t value) // 64 bit
1093
1094=item char *ecb_i2a_09 (char *ptr, uint32_t value) // 64 bit
1095
1096The C<< ecb_i2a_0I<N> > functions take an unsigned I<value> and convert
1097them to exactly I<N> digits, returning a pointer to the first character
1098after the digits. The I<value> must be in range. The functions marked with
1099I<32 bit> do their calculations internally in 32 bit, the ones marked with
1100I<64 bit> internally use 64 bit integers, which might be slow on 32 bit
1101architectures (the high level API decides on 32 vs. 64 bit versions using
1102C<ECB_64BIT_NATIVE>).
1103
1104=item char *ecb_i2a_2 (char *ptr, uint32_t value) // 32 bit
1105
1106=item char *ecb_i2a_3 (char *ptr, uint32_t value) // 32 bit
1107
1108=item char *ecb_i2a_4 (char *ptr, uint32_t value) // 32 bit
1109
1110=item char *ecb_i2a_5 (char *ptr, uint32_t value) // 64 bit
1111
1112=item char *ecb_i2a_6 (char *ptr, uint32_t value) // 64 bit
1113
1114=item char *ecb_i2a_7 (char *ptr, uint32_t value) // 64 bit
1115
1116=item char *ecb_i2a_8 (char *ptr, uint32_t value) // 64 bit
1117
1118=item char *ecb_i2a_9 (char *ptr, uint32_t value) // 64 bit
1119
1120Similarly, the C<< ecb_i2a_I<N> > functions take an unsigned I<value>
1121and convert them to at most I<N> digits, suppressing leading zeroes, and
1122returning a pointer to the first character after the digits.
1123
1124=item ECB_I2A_MAX_X5 (=59074)
1125
1126=item char *ecb_i2a_x5 (char *ptr, uint32_t value) // 32 bit
1127
1128=item ECB_I2A_MAX_X10 (=2932500665)
1129
1130=item char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit
1131
1132The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >
1133functions, but they can generate one digit more, as long as the number
1134is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost
113516 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
1136respectively.
1137
1138For example, the digit part of a 32 bit signed integer just fits into the
1139C<ECB_I2A_MAX_X10> range, so while C<ecb_i2a_x10> cannot convert a 10
1140digit number, it can convert all 32 bit signed numbers. Sadly, it's not
1141good enough for 32 bit unsigned numbers.
1142
1143=back
1144
911=head2 FLOATING POINT FIDDLING 1145=head2 FLOATING POINT FIDDLING
912 1146
913=over 4 1147=over
914 1148
915=item ECB_INFINITY [-UECB_NO_LIBM] 1149=item ECB_INFINITY [-UECB_NO_LIBM]
916 1150
917Evaluates to positive infinity if supported by the platform, otherwise to 1151Evaluates to positive infinity if supported by the platform, otherwise to
918a truly huge number. 1152a truly huge number.
943IEEE 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
944also within reasonable limits (it tries to convert NaNs, infinities and 1178also within reasonable limits (it tries to convert NaNs, infinities and
945denormals, but will likely convert negative zero to positive zero). 1179denormals, but will likely convert negative zero to positive zero).
946 1180
947On 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
948be able to optimise away this function completely. 1182be able to completely optimise away the 32 and 64 bit functions.
949 1183
950These functions can be helpful when serialising floats to the network - you 1184These functions can be helpful when serialising floats to the network - you
951can 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.
952 1186
953Another use for these functions is to manipulate floating point values 1187Another use for these functions is to manipulate floating point values
996 1230
997=back 1231=back
998 1232
999=head2 ARITHMETIC 1233=head2 ARITHMETIC
1000 1234
1001=over 4 1235=over
1002 1236
1003=item x = ecb_mod (m, n) 1237=item x = ecb_mod (m, n)
1004 1238
1005Returns C<m> modulo C<n>, which is the same as the positive remainder 1239Returns C<m> modulo C<n>, which is the same as the positive remainder
1006of the division operation between C<m> and C<n>, using floored 1240of the division operation between C<m> and C<n>, using floored
1013C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be 1247C<n> must be strictly positive (i.e. C<< >= 1 >>), while C<m> must be
1014negatable, that is, both C<m> and C<-m> must be representable in its 1248negatable, that is, both C<m> and C<-m> must be representable in its
1015type (this typically excludes the minimum signed integer value, the same 1249type (this typically excludes the minimum signed integer value, the same
1016limitation as for C</> and C<%> in C). 1250limitation as for C</> and C<%> in C).
1017 1251
1018Current GCC versions compile this into an efficient branchless sequence on 1252Current GCC/clang versions compile this into an efficient branchless
1019almost all CPUs. 1253sequence on almost all CPUs.
1020 1254
1021For example, when you want to rotate forward through the members of an 1255For example, when you want to rotate forward through the members of an
1022array for increasing C<m> (which might be negative), then you should use 1256array for increasing C<m> (which might be negative), then you should use
1023C<ecb_mod>, as the C<%> operator might give either negative results, or 1257C<ecb_mod>, as the C<%> operator might give either negative results, or
1024change direction for negative values: 1258change direction for negative values:
1037 1271
1038=back 1272=back
1039 1273
1040=head2 UTILITY 1274=head2 UTILITY
1041 1275
1042=over 4 1276=over
1043 1277
1044=item element_count = ecb_array_length (name) 1278=item element_count = ecb_array_length (name)
1045 1279
1046Returns the number of elements in the array C<name>. For example: 1280Returns the number of elements in the array C<name>. For example:
1047 1281
1055 1289
1056=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF 1290=head2 SYMBOLS GOVERNING COMPILATION OF ECB.H ITSELF
1057 1291
1058These symbols need to be defined before including F<ecb.h> the first time. 1292These symbols need to be defined before including F<ecb.h> the first time.
1059 1293
1060=over 4 1294=over
1061 1295
1062=item ECB_NO_THREADS 1296=item ECB_NO_THREADS
1063 1297
1064If F<ecb.h> is never used from multiple threads, then this symbol can 1298If F<ecb.h> is never used from multiple threads, then this symbol can
1065be defined, in which case memory fences (and similar constructs) are 1299be defined, in which case memory fences (and similar constructs) are

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines