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.90 by root, Tue Jun 22 00:01:15 2021 UTC vs.
Revision 1.94 by root, Sat Jul 31 16:13:30 2021 UTC

… …
168 168
169=item ECB_64BIT_NATIVE 169=item ECB_64BIT_NATIVE
170 170
171Evaluates to a true value (suitable for both preprocessor and C code 171Evaluates to a true value (suitable for both preprocessor and C code
172testing) if 64 bit integer types on this architecture are evaluated 172testing) if 64 bit integer types on this architecture are evaluated
173"natively", that is, with similar speeds as 32 bit integerss. While 64 bit 173"natively", that is, with similar speeds as 32 bit integers. While 64 bit
174integer support is very common (and in fatc required by libecb), 32 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. 175cpus have to emulate operations on them, so you might want to avoid them.
176 176
177=item ECB_AMD64, ECB_AMD64_X32 177=item ECB_AMD64, ECB_AMD64_X32
178 178
179These 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
… …
731 731
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>). 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.
737 738
738Current GCC/clang versions understand these functions and usually compile 739Current GCC/clang versions understand these functions and usually compile
739them to "optimal" code (e.g. a single C<rol> or a combination of C<shld> 740them to "optimal" code (e.g. a single C<rol> or a combination of C<shld>
740on x86). 741on x86).
741 742
… …
934=head3 HIGH LEVEL API 935=head3 HIGH LEVEL API
935 936
936The high level API consists of four functions, one each for C<int32_t>, 937The high level API consists of four functions, one each for C<int32_t>,
937C<uint32_t>, C<int64_t> and C<uint64_t>: 938C<uint32_t>, C<int64_t> and C<uint64_t>:
938 939
940Example:
941
942 char buf[ECB_I2A_MAX_DIGITS + 1];
943 char *end = ecb_i2a_i32 (buf, 17262);
944 *end = 0;
945 // buf now contains "17262"
946
939=over 947=over
940 948
941=item ECB_I2A_I32_DIGITS (=11) 949=item ECB_I2A_I32_DIGITS (=11)
942 950
943=item char *ecb_i2a_u32 (char *ptr, uint32_t value) 951=item char *ecb_i2a_u32 (char *ptr, uint32_t value)
944 952
945Takes an C<uint32_t> I<value> and formats it as a decimal number starting 953Takes an C<uint32_t> I<value> and formats it as a decimal number starting
946at I<ptr>, using at most C<ECB_I2A_I32_DIGITS> characters. Returns a 954at I<ptr>, using at most C<ECB_I2A_I32_DIGITS> characters. Returns a
947pointer to just after the generated string, where you would normally put 955pointer to just after the generated string, where you would normally put
948the temrinating C<0> character. This function outputs the minimum number 956the terminating C<0> character. This function outputs the minimum number
949of digits. 957of digits.
950 958
951=item ECB_I2A_U32_DIGITS (=10) 959=item ECB_I2A_U32_DIGITS (=10)
952 960
953=item char *ecb_i2a_i32 (char *ptr, int32_t value) 961=item char *ecb_i2a_i32 (char *ptr, int32_t value)
… …
973=back 981=back
974 982
975=head3 LOW-LEVEL API 983=head3 LOW-LEVEL API
976 984
977The functions above use a number of low-level APIs which have some strict 985The functions above use a number of low-level APIs which have some strict
978limitaitons, but cna be used as building blocks (study of C<ecb_i2a_i32> 986limitations, but can be used as building blocks (study of C<ecb_i2a_i32>
979and related cunctions is recommended). 987and related functions is recommended).
980 988
981There are three families of functions: functions that convert a number 989There are three families of functions: functions that convert a number
982to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0> 990to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0>
983for "leading zeroes"), functions that generate up to N digits, skipping 991for "leading zeroes"), functions that generate up to N digits, skipping
984leading zeroes (C<_N>), and functions that can generate more digits, but 992leading zeroes (C<_N>), and functions that can generate more digits, but
985the leading digit has limited range (C<_xN>). 993the leading digit has limited range (C<_xN>).
986 994
987None of the functions deal with negative numbera. 995None of the functions deal with negative numbers.
996
997Example: convert an IP address in an u32 into dotted-quad:
998
999 uint32_t ip = 0x0a000164; // 10.0.1.100
1000 char ips[3 * 4 + 3 + 1];
1001 char *ptr = ips;
1002 ptr = ecb_i2a_3 (ptr, ip >> 24 ); *ptr++ = '.';
1003 ptr = ecb_i2a_3 (ptr, (ip >> 16) & 0xff); *ptr++ = '.';
1004 ptr = ecb_i2a_3 (ptr, (ip >> 8) & 0xff); *ptr++ = '.';
1005 ptr = ecb_i2a_3 (ptr, ip & 0xff); *ptr++ = 0;
1006 printf ("ip: %s\n", ips); // prints "ip: 10.0.1.100"
988 1007
989=over 1008=over
990 1009
991=item char *ecb_i2a_02 (char *ptr, uint32_t value) // 32 bit 1010=item char *ecb_i2a_02 (char *ptr, uint32_t value) // 32 bit
992 1011
… …
1044functions, but they can generate one digit more, as long as the number 1063functions, but they can generate one digit more, as long as the number
1045is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost 1064is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost
104616 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range), 106516 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
1047respectively. 1066respectively.
1048 1067
1049For example, the sigit part of a 32 bit signed integer just fits into the 1068For example, the digit part of a 32 bit signed integer just fits into the
1050C<ECB_I2A_MAX_X10> range, so while C<ecb_i2a_x10> cannot convert a 10 1069C<ECB_I2A_MAX_X10> range, so while C<ecb_i2a_x10> cannot convert a 10
1051digit number, it can convert all 32 bit signed numbers. Sadly, it's not 1070digit number, it can convert all 32 bit signed numbers. Sadly, it's not
1052good enough for 32 bit unsigned numbers. 1071good enough for 32 bit unsigned numbers.
1053 1072
1054=back 1073=back

Diff Legend

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