--- libecb/ecb.pod	2021/06/21 21:49:51	1.88
+++ libecb/ecb.pod	2021/06/21 23:59:58	1.89
@@ -918,6 +918,141 @@
 
 =back
 
+=head2 FAST INTEGER TO STRING
+
+Libecb defines a set of very fast integer to decimal string (or integer
+to ascii, short C<i2a>) functions.  These work by converting the integer
+to a fixed point representation and then successively multiplying out
+the topmost digits. Unlike some other, also very fast, libraries, ecb's
+algorithm should be completely branchless per digit, and does not rely on
+the presence of special cpu functions (such as clz).
+
+There is a high level API that takes an C<int32_t>, C<uint32_t>,
+C<int64_t> or C<uint64_t> as argument, and a low-level API, which is
+harder to use but supports slightly more formatting options.
+
+=head3 HIGH LEVEL API
+
+The high level API consists of four functions, one each for C<int32_t>,
+C<uint32_t>, C<int64_t> and C<uint64_t>:
+
+=over
+
+=item ECB_I2A_I32_DIGITS (=11)
+
+=item char *ecb_i2a_u32 (char *ptr, uint32_t value)
+
+Takes an C<uint32_t> I<value> and formats it as a decimal number starting
+at I<ptr>, using at most C<ECB_I2A_I32_DIGITS> characters. Returns a
+pointer to just after the generated string, where you would normally put
+the temrinating C<0> character. This function outputs the minimum number
+of digits.
+
+=item ECB_I2A_U32_DIGITS (=10)
+
+=item char *ecb_i2a_i32 (char *ptr, int32_t value)
+
+Same as C<ecb_i2a_u32>, but formats a C<int32_t> value, including a minus
+sign if needed.
+
+=item ECB_I2A_I64_DIGITS (=20)
+
+=item char *ecb_i2a_u64 (char *ptr, uint64_t value)
+
+=item ECB_I2A_U64_DIGITS (=21)
+
+=item char *ecb_i2a_i64 (char *ptr, int64_t value)
+
+Similar to their 32 bit counterparts, these take a 64 bit argument.
+
+=item ECB_I2A_DIGITS (=21)
+
+Instead of using a type specific length macro, youi can just use
+C<ECB_I2A_DIGITS>, which is good enough for any C<ecb_i2a> function.
+
+=back
+
+=head3 LOW-LEVEL API
+
+The functions above use a number of low-level APIs which have some strict
+limitaitons, but cna be used as building blocks (study of C<ecb_i2a_i32>
+and related cunctions is recommended).
+
+There are three families of functions: functions that convert a number
+to a fixed number of digits with leading zeroes (C<ecb_i2a_0N>, C<0>
+for "leading zeroes"), functions that generate up to N digits, skipping
+leading zeroes (C<_N>), and functions that can generate more digits, but
+the leading digit has limited range (C<_xN>).
+
+None of the functions deal with negative numbera.
+
+=over
+
+=item char *ecb_i2a_02  (char *ptr, uint32_t value) // 32 bit
+
+=item char *ecb_i2a_03  (char *ptr, uint32_t value) // 32 bit
+
+=item char *ecb_i2a_04  (char *ptr, uint32_t value) // 32 bit
+
+=item char *ecb_i2a_05  (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_06  (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_07  (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_08  (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_09  (char *ptr, uint32_t value) // 64 bit
+
+The C<< ecb_i2a_0I<N> > functions take an unsigned I<value> and convert
+them to exactly I<N> digits, returning a pointer to the first character
+after the digits. The I<value> must be in range. The functions marked with
+I<32 bit> do their calculations internally in 32 bit, the ones marked with
+I<64 bit> internally use 64 bit integers, which might be slow on 32 bit
+architectures (the high level API decides on 32 vs. 64 bit versions using
+C<ECB_64BIT_NATIVE>).
+
+=item char *ecb_i2a_2   (char *ptr, uint32_t value) // 32 bit
+
+=item char *ecb_i2a_3   (char *ptr, uint32_t value) // 32 bit
+
+=item char *ecb_i2a_4   (char *ptr, uint32_t value) // 32 bit
+
+=item char *ecb_i2a_5   (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_6   (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_7   (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_8   (char *ptr, uint32_t value) // 64 bit
+
+=item char *ecb_i2a_9   (char *ptr, uint32_t value) // 64 bit
+
+Similarly, the C<< ecb_i2a_I<N> > functions take an unsigned I<value>
+and convert them to at most I<N> digits, suppressing leading zeroes, and
+returning a pointer to the first character after the digits.
+
+=item ECB_I2A_MAX_X5 (=59074)
+
+=item char *ecb_i2a_x5  (char *ptr, uint32_t value) // 32 bit
+
+=item ECB_I2A_MAX_X10 (=2932500665)
+
+=item char *ecb_i2a_x10 (char *ptr, uint32_t value) // 64 bit
+
+The C<< ecb_i2a_xI<N> >> functions are similar to the C<< ecb_i2a_I<N> >
+functions, but they can generate one digit more, as long as the number
+is within range, which is given by the symbols C<ECB_I2A_MAX_X5> (almost
+16 bit range) and C<ECB_I2A_MAX_X10> (a bit more than 31 bit range),
+respectively.
+
+For example, the sigit part of a 32 bit signed integer just fits into the
+C<ECB_I2A_MAX_X10> range, so while C<ecb_i2a_x10> cannot convert a 10
+digit number, it can convert all 32 bit signed numbers. Sadly, it's not
+good enough for 32 bit unsigned numbers.
+
+=back
+
 =head2 FLOATING POINT FIDDLING
 
 =over