Added note that mp_radix_size_overestimate is similar in behavior to GMP's mpz_sizeinbase

Author: czurnieden

bn_mp_radix_size_overestimate.c

@@ -11,11 +11,10 @@
 /* returns size of ASCII representation */
 
 /*
-   Overestimate the amount of memory needed for the number-to-string conversions.
-   The results for powers-of-two are exact but it will overestimate the actual
-   amount by up to 1 character for all other bases with the exception of MP_16BIT
-   where the overestimate is up to to 2 characters for all those other bases if
-   the "int" type has more than 16 bits.
+
+   Behaves like the function mp(n|z)_sizeinbase of GMP for all digit-sizes except MP_8BIT
+   and MP_16BIT (if the "int" for MP_16BIT has more than 16 bits) where it can overshoot by two.
+   The results for bases that are powers-of-two are exact.
 */
 
 /*
@@ -104,7 +103,7 @@ static const mp_word logbases_low[65] = {
     638097011ul, 1073048670ul, 1651143338ul, 3473298766ul,          0ul
 };
 
-/* TODO: This assumes the type "long long" exists. If it doesn't use the tables for MP_16BIT */
+/* TODO: This assumes the type "long long" exists. If it doesn't: use the tables for MP_16BIT */
 #elif ( (defined MP_28BIT) || (defined MP_31BIT) || (defined MP_32BIT)  || (defined MP_64BIT) )
 #define LTM_RADIX_SIZE_SCALE 61
 #ifdef MP_64BIT

doc/bn.tex

@@ -2118,11 +2118,13 @@ \subsection{To ASCII}
 This stores in ``size'' the exact number of characters (including space for the NUL terminator) required.  Upon error this function returns an error code and ``size'' will be zero. It uses \texttt{mp\_ilogb} to compute the size in O(log n) with quite a large overhead. This function is deprecated in favor of
 \texttt{mp\_radix\_sizeinbase} described below. If the exact size is still required after the removal of this function use \texttt{mp\_ilogb} directly.
 
-\index{mp\_radix\_sizeinbase}
+\index{mp\_radix\_overestimate}
 \begin{alltt}
-int mp_radix_sizeinbase (mp_int * a, int radix, int *size)
+int mp_radix_size_overestimate (mp_int * a, int radix, int *size)
 \end{alltt}
-This stores in ``size'' the number of characters (including space for the NUL terminator) required.  Upon error this function returns an error code and ``size'' will be zero. This function can overshoot by one (two in case of \texttt{MP\_8BIT}). It uses tables to compute the result in O(1) with quite a small overhead.
+This stores in ``size'' the number of characters (including space for the NUL terminator) required.  Upon error this function returns an error code and ``size'' will be zero. This function can overshoot by one (two in case of \texttt{MP\_8BIT} and also for \texttt{MP\_16BIT} if the type \texttt{int} has more than 16 bits). The results for bases that are powers-of-two are exact. It uses tables to compute the result in O(1) with quite a small overhead.
+
+The behavior is similar to the behavior of the function \texttt{mpn\_sizeinbase} in GMP for \texttt{MP\_32BIT}, and \texttt{MP\_64BIT}.
 
 If \texttt{LTM\_NO\_FILE} is not defined a function to write to a file is also available.
 \index{mp\_fwrite}

tommath.h

@@ -713,7 +713,11 @@ mp_err mp_to_radix(const mp_int *a, char *str, size_t maxlen, int radix) MP_WUR;
 
 /* exact but slow  O(n^2)*/
 mp_err mp_radix_size(const mp_int *a, int radix, int *size) MP_WUR;
-/* can overshoot by one or two characters but is O(1) (table based with a very small overhead) */
+/*
+   Can overshoot by one or two characters but is O(1) (table based with a very small overhead)
+   Behaves like the function mp(n|z)_sizeinbase of GMP for all digit-sizes except MP_8BIT
+   and MP_16BIT (if the "int" for MP_16BIT has more than 16 bits) where it can overshoot by two.
+ */
 mp_err mp_radix_size_overestimate(const mp_int *a, const int base, int *size) MP_WUR;
 #ifndef MP_NO_FILE
 mp_err mp_fread(mp_int *a, int radix, FILE *stream) MP_WUR;