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

Comparing libecb/ecb.pod (file contents):
Revision 1.88 by root, Mon Jun 21 21:49:51 2021 UTC vs.
Revision 1.89 by root, Mon Jun 21 23:59:58 2021 UTC

… …
916(C<uint8_t>) and also have an aligned version (without the C<_u> prefix), 916(C<uint8_t>) and also have an aligned version (without the C<_u> prefix),
917all of which hopefully makes them more useful in generic code. 917all of which hopefully makes them more useful in generic code.
918 918
919=back 919=back
920 920
921=head2 FAST INTEGER TO STRING
922
923Libecb defines a set of very fast integer to decimal string (or integer
924to ascii, short C<i2a>) functions. These work by converting the integer
925to a fixed point representation and then successively multiplying out
926the topmost digits. Unlike some other, also very fast, libraries, ecb's
927algorithm should be completely branchless per digit, and does not rely on
928the presence of special cpu functions (such as clz).
929
930There is a high level API that takes an C<int32_t>, C<uint32_t>,
931C<int64_t> or C<uint64_t> as argument, and a low-level API, which is
932harder to use but supports slightly more formatting options.
933
934=head3 HIGH LEVEL API
935
936The high level API consists of four functions, one each for C<int32_t>,
937C<uint32_t>, C<int64_t> and C<uint64_t>:
938
939=over
940
941=item ECB_I2A_I32_DIGITS (=11)
942
943=item char *ecb_i2a_u32 (char *ptr, uint32_t value)
944
945Takes 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
947pointer to just after the generated string, where you would normally put
948the temrinating C<0> character. This function outputs the minimum number
949of digits.
950
951=item ECB_I2A_U32_DIGITS (=10)
952
953=item char *ecb_i2a_i32 (char *ptr, int32_t value)
954
955Same as C<ecb_i2a_u32>, but formats a C<int32_t> value, including a minus
956sign if needed.
957
958=item ECB_I2A_I64_DIGITS (=20)
959
960=item char *ecb_i2a_u64 (char *ptr, uint64_t value)
961
962=item ECB_I2A_U64_DIGITS (=21)
963
964=item char *ecb_i2a_i64 (char *ptr, int64_t value)
965
966Similar to their 32 bit counterparts, these take a 64 bit argument.
967
968=item ECB_I2A_DIGITS (=21)
969
970Instead of using a type specific length macro, youi can just use
971C<ECB_I2A_DIGITS>, which is good enough for any C<ecb_i2a> function.
972
973=back
974
975=head3 LOW-LEVEL API
976
977The 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>
979and related cunctions is recommended).
980
981There 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>
983for "leading zeroes"), functions that generate up to N digits, skipping
984leading zeroes (C<_N>), and functions that can generate more digits, but
985the leading digit has limited range (C<_xN>).
986
987None of the functions deal with negative numbera.
988
989=over
990
991=item char *ecb_i2a_02 (char *ptr, uint32_t value) // 32 bit
992
993=item char *ecb_i2a_03 (char *ptr, uint32_t value) // 32 bit
994
995=item char *ecb_i2a_04 (char *ptr, uint32_t value) // 32 bit
996
997=item char *ecb_i2a_05 (char *ptr, uint32_t value) // 64 bit
998
999=item char *ecb_i2a_06 (char *ptr, uint32_t value) // 64 bit
1000
1001=item char *ecb_i2a_07 (char *ptr, uint32_t value) // 64 bit
1002
1003=item char *ecb_i2a_08 (char *ptr, uint32_t value) // 64 bit
1004
1005=item char *ecb_i2a_09 (char *ptr, uint32_t value) // 64 bit
1006
1007The C<< ecb_i2a_0I<N> > functions take an unsigned I<value> and convert
1008them to exactly I<N> digits, returning a pointer to the first character
1009after the digits. The I<value> must be in range. The functions marked with
1010I<32 bit> do their calculations internally in 32 bit, the ones marked with
1011I<64 bit> internally use 64 bit integers, which might be slow on 32 bit
1012architectures (the high level API decides on 32 vs. 64 bit versions using
1013C<ECB_64BIT_NATIVE>).
1014
1015=item char *ecb_i2a_2 (char *ptr, uint32_t value) // 32 bit
1016
1017=item char *ecb_i2a_3 (char *ptr, uint32_t value) // 32 bit
1018
1019=item char *ecb_i2a_4 (char *ptr, uint32_t value) // 32 bit
1020
1021=item char *ecb_i2a_5 (char *ptr, uint32_t value) // 64 bit
1022
1023=item char *ecb_i2a_6 (char *ptr, uint32_t value) // 64 bit
1024
1025=item char *ecb_i2a_7 (char *ptr, uint32_t value) // 64 bit
1026
1027=item char *ecb_i2a_8 (char *ptr, uint32_t value) // 64 bit
1028
1029=item char *ecb_i2a_9 (char *ptr, uint32_t value) // 64 bit
1030
1031Similarly, the C<< ecb_i2a_I<N> > functions take an unsigned I<value>
1032and convert them to at most I<N> digits, suppressing leading zeroes, and
1033returning a pointer to the first character after the digits.
1034
1035=item ECB_I2A_MAX_X5 (=59074)
1036
1037=item char *ecb_i2a_x5 (char *ptr, uint32_t value) // 32 bit
1038
1039=item ECB_I2A_MAX_X10 (=2932500665)
1040
1041=item char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit
1042
1043The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >
1044functions, 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
104616 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
1047respectively.
1048
1049For example, the sigit 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
1051digit number, it can convert all 32 bit signed numbers. Sadly, it's not
1052good enough for 32 bit unsigned numbers.
1053
1054=back
1055
921=head2 FLOATING POINT FIDDLING 1056=head2 FLOATING POINT FIDDLING
922 1057
923=over 1058=over
924 1059
925=item ECB_INFINITY [-UECB_NO_LIBM] 1060=item ECB_INFINITY [-UECB_NO_LIBM]

Diff Legend

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