Merged from silc_1_0_branch (second merge).

[silc.git] / lib / silcmath / silcmp.h

diff --git a/lib/silcmath/silcmp.h b/lib/silcmath/silcmp.h
index 45d6ff6704256330af59d31781b6bce41d9a9625..ba18ae35bfe1f2d01af2fa818aba398614f0660b 100644 (file)
--- a/lib/silcmath/silcmp.h
+++ b/lib/silcmath/silcmp.h
@@ -18,7 +18,7 @@
  
 */
 
-/****h* silcmath/SilcMPAPI
+/****h* silcmath/SILC MP Interface
  *
  * DESCRIPTION
  *
@@ -34,7 +34,7 @@
 #ifndef SILCMP_H
 #define SILCMP_H
 
-#ifdef SILC_MP_GMP
+#if defined(SILC_MP_GMP)
 #include "mp_gmp.h"            /* SILC_MP_GMP */
 #else
 #include "mp_mpi.h"            /* SILC_MP_NSS_MPI */
@@ -57,7 +57,7 @@
 typedef SILC_MP_INT SilcMPInt;
 /***/
 
-/****f* silcmath/SilcMPAPI/silc_mp_alloc
+/****f* silcmath/SilcMPAPI/silc_mp_init
  *
  * SYNOPSIS
  *
@@ -72,7 +72,7 @@ typedef SILC_MP_INT SilcMPInt;
  ***/
 void silc_mp_init(SilcMPInt *mp);
 
-/****f* silcmath/SilcMPAPI/silc_mp_free
+/****f* silcmath/SilcMPAPI/silc_mp_uninit
  *
  * SYNOPSIS
  *
@@ -106,10 +106,16 @@ size_t silc_mp_size(SilcMPInt *mp);
  *
  * DESCRIPTION
  *
- *    Return the size of the integer in base `base'. Note that this size
- *    is probably only an approximation.  However, it is guaranteed that
- *    the returned size is always at least the size of the integer, however,
- *    it may be larger.
+ *    Return the size of the integer in base `base'.
+ *
+ * NOTES
+ *
+ *    For any other base but 2 this function usually returns only an
+ *    approximated size in the base.  It is however guaranteed that the
+ *    the returned size is always at least the size of the integer or
+ *    larger.
+ *
+ *    For base 2 this returns the exact bit-size of the integer.
  *
  ***/
 size_t silc_mp_sizeinbase(SilcMPInt *mp, int base);
@@ -132,7 +138,7 @@ void silc_mp_set(SilcMPInt *dst, SilcMPInt *src);
  *
  * SYNOPSIS
  *
- *    void silc_mp_set_ui(SilcMPInt *dst, uint32 ui);
+ *    void silc_mp_set_ui(SilcMPInt *dst, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -140,13 +146,13 @@ void silc_mp_set(SilcMPInt *dst, SilcMPInt *src);
  *    initialized.
  *
  ***/
-void silc_mp_set_ui(SilcMPInt *dst, uint32 ui);
+void silc_mp_set_ui(SilcMPInt *dst, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_set_si
  *
  * SYNOPSIS
  *
- *    void silc_mp_set_si(SilcMPInt *dst, int32 si);
+ *    void silc_mp_set_si(SilcMPInt *dst, SilcInt32 si);
  *
  * DESCRIPTION
  *
@@ -154,7 +160,7 @@ void silc_mp_set_ui(SilcMPInt *dst, uint32 ui);
  *    already be initialized.
  *
  ***/
-void silc_mp_set_si(SilcMPInt *dst, int32 si);
+void silc_mp_set_si(SilcMPInt *dst, SilcInt32 si);
 
 /****f* silcmath/SilcMPAPI/silc_mp_set_str
  *
@@ -167,6 +173,11 @@ void silc_mp_set_si(SilcMPInt *dst, int32 si);
  *    Set `dst' integer from string `str' of base `base'. The `dst' must
  *    already be initialized.
  *
+ * NOTES
+ *
+ *    For base 2 the string must be in ASCII bit presentation, not in
+ *    binary.  Use the silc_mp_bin2mp to decode binary into integer.
+ *
  ***/
 void silc_mp_set_str(SilcMPInt *dst, const char *str, int base);
 
@@ -174,14 +185,14 @@ void silc_mp_set_str(SilcMPInt *dst, const char *str, int base);
  *
  * SYNOPSIS
  *
- *    uint32 silc_mp_get_ui(SilcMPInt *mp);
+ *    SilcUInt32 silc_mp_get_ui(SilcMPInt *mp);
  *
  * DESCRIPTION
  *
  *    Returns the least significant unsigned word from `mp'.
  *
  ***/
-uint32 silc_mp_get_ui(SilcMPInt *mp);
+SilcUInt32 silc_mp_get_ui(SilcMPInt *mp);
 
 /****f* silcmath/SilcMPAPI/silc_mp_get_str
  *
@@ -195,6 +206,11 @@ uint32 silc_mp_get_ui(SilcMPInt *mp);
  *    must already have space allocated. The function returns the same
  *    as `str' or NULL on error.
  *
+ * NOTES
+ *
+ *    For base 2 the returned string is in ASCII bit presentation, not
+ *    in binary.  Use the silc_mp_mp2bin to encode integer into binary.
+ *
  ***/
 char *silc_mp_get_str(char *str, SilcMPInt *mp, int base);
 
@@ -215,7 +231,7 @@ void silc_mp_add(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *
  * SYNOPSIS
  *
- *    void silc_mp_add_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+ *    void silc_mp_add_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -223,7 +239,7 @@ void silc_mp_add(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *    to `dst'.
  *
  ***/
-void silc_mp_add_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+void silc_mp_add_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_sub
  *
@@ -242,7 +258,7 @@ void silc_mp_sub(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *
  * SYNOPSIS
  *
- *    void silc_mp_sub_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+ *    void silc_mp_sub_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -250,7 +266,7 @@ void silc_mp_sub(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *    to `dst'.
  *
  ***/
-void silc_mp_sub_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+void silc_mp_sub_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_mul
  *
@@ -269,7 +285,7 @@ void silc_mp_mul(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *
  * SYNOPSIS
  *
- *    void silc_mp_mul_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+ *    void silc_mp_mul_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -277,13 +293,13 @@ void silc_mp_mul(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *    to `dst'.
  *
  ***/
-void silc_mp_mul_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+void silc_mp_mul_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_mul_2exp
  *
  * SYNOPSIS
  *
- *    void silc_mp_mul_2exp(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp);
+ *    void silc_mp_mul_2exp(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp);
  *
  * DESCRIPTION
  *
@@ -291,7 +307,7 @@ void silc_mp_mul_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
  *    `dst'. This is equivalent to dst = mp1 * (2 ^ exp).
  *
  ***/
-void silc_mp_mul_2exp(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp);
+void silc_mp_mul_2exp(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp);
 
 /****f* silcmath/SilcMPAPI/silc_mp_sqrt
  *
@@ -324,7 +340,7 @@ void silc_mp_div(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *
  * SYNOPSIS
  *
- *    void silc_mp_div_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+ *    void silc_mp_div_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -332,7 +348,7 @@ void silc_mp_div(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *    `dst'. This is equivalent to dst = mp1 / ui;
  *
  ***/
-void silc_mp_div_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+void silc_mp_div_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_div_qr
  *
@@ -364,14 +380,14 @@ void silc_mp_div_qr(SilcMPInt *q, SilcMPInt *r, SilcMPInt *mp1,
  *    This is equivalent to dst = mp1 / (2 ^ exp).
  *
  ***/
-void silc_mp_div_2exp(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp);
+void silc_mp_div_2exp(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp);
 
 /****f* silcmath/SilcMPAPI/silc_mp_div_2exp_qr
  *
  * SYNOPSIS
  *
  *    void silc_mp_div_2exp_qr(SilcMPInt *q, SilcMPInt *r, SilcMPInt *mp1, 
- *                             uint32 exp);
+ *                             SilcUInt32 exp);
  *
  * DESCRIPTION
  *
@@ -382,7 +398,7 @@ void silc_mp_div_2exp(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp);
  *
  ***/
 void silc_mp_div_2exp_qr(SilcMPInt *q, SilcMPInt *r, SilcMPInt *mp1, 
-                        uint32 exp);
+                        SilcUInt32 exp);
 
 /****f* silcmath/SilcMPAPI/silc_mp_mod
  *
@@ -404,7 +420,7 @@ void silc_mp_mod(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *
  * SYNOPSIS
  *
- *    void silc_mp_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+ *    void silc_mp_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -413,7 +429,7 @@ void silc_mp_mod(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *mp2);
  *    to dst = mp1 mod ui.
  *
  ***/
-void silc_mp_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+void silc_mp_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_mod_2exp
  *
@@ -429,7 +445,7 @@ void silc_mp_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
  *    function returns the remainder as well.
  *
  ***/
-void silc_mp_mod_2exp(SilcMPInt *dst, SilcMPInt *mp1, uint32 ui);
+void silc_mp_mod_2exp(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_pow
  *
@@ -449,7 +465,7 @@ void silc_mp_pow(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *exp);
  *
  * SYNOPSIS
  *
- *    void silc_mp_pow_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp);
+ *    void silc_mp_pow_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp);
  *
  * DESCRIPTION
  *
@@ -457,7 +473,7 @@ void silc_mp_pow(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *exp);
  *    equivalent to dst = mp1 ^ exp.
  *
  ***/
-void silc_mp_pow_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp);
+void silc_mp_pow_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp);
 
 /****f* silcmath/SilcMPAPI/silc_mp_pow_mod
  *
@@ -479,7 +495,7 @@ void silc_mp_pow_mod(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *exp,
  *
  * SYNOPSIS
  *
- *    void silc_mp_pow_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp, 
+ *    void silc_mp_pow_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp, 
  *                            SilcMPInt *mod);
  *
  * DESCRIPTION
@@ -488,7 +504,7 @@ void silc_mp_pow_mod(SilcMPInt *dst, SilcMPInt *mp1, SilcMPInt *exp,
  *    This is equivalent to dst = (mp1 ^ exp) mod mod.
  *
  ***/
-void silc_mp_pow_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, uint32 exp, 
+void silc_mp_pow_mod_ui(SilcMPInt *dst, SilcMPInt *mp1, SilcUInt32 exp, 
                        SilcMPInt *mod);
 
 /****f* silcmath/SilcMPAPI/silc_mp_modinv
@@ -567,7 +583,7 @@ int silc_mp_cmp(SilcMPInt *mp1, SilcMPInt *mp2);
  *
  * SYNOPSIS
  *
- *    int silc_mp_cmp_si(SilcMPInt *mp1, int32 si);
+ *    int silc_mp_cmp_si(SilcMPInt *mp1, SilcInt32 si);
  *
  * DESCRIPTION
  *
@@ -575,13 +591,13 @@ int silc_mp_cmp(SilcMPInt *mp1, SilcMPInt *mp2);
  *    if `mp1' > `si', `mp1' == `si', or `mp1' < `si', respectively.
  *
  ***/
-int silc_mp_cmp_si(SilcMPInt *mp1, int32 si);
+int silc_mp_cmp_si(SilcMPInt *mp1, SilcInt32 si);
 
 /****f* silcmath/SilcMPAPI/silc_mp_cmp_ui
  *
  * SYNOPSIS
  *
- *    int silc_mp_cmp_ui(SilcMPInt *mp1, uint32 ui);
+ *    int silc_mp_cmp_ui(SilcMPInt *mp1, SilcUInt32 ui);
  *
  * DESCRIPTION
  *
@@ -590,14 +606,14 @@ int silc_mp_cmp_si(SilcMPInt *mp1, int32 si);
  *    respectively.
  *
  ***/
-int silc_mp_cmp_ui(SilcMPInt *mp1, uint32 ui);
+int silc_mp_cmp_ui(SilcMPInt *mp1, SilcUInt32 ui);
 
 /****f* silcmath/SilcMPAPI/silc_mp_mp2bin
  *
  * SYNOPSIS
  *
- *    unsigned char *silc_mp_mp2bin(SilcMPInt *val, uint32 len, 
- *                                  uint32 *ret_len);
+ *    unsigned char *silc_mp_mp2bin(SilcMPInt *val, SilcUInt32 len, 
+ *                                  SilcUInt32 *ret_len);
  *
  * DESCRIPTION
  *
@@ -606,15 +622,15 @@ int silc_mp_cmp_ui(SilcMPInt *mp1, uint32 ui);
  *    buffer is allocated that large. If zero then the size is approximated.
  *
  ***/
-unsigned char *silc_mp_mp2bin(SilcMPInt *val, uint32 len, 
-                             uint32 *ret_len);
+unsigned char *silc_mp_mp2bin(SilcMPInt *val, SilcUInt32 len, 
+                             SilcUInt32 *ret_len);
 
 /****f* silcmath/SilcMPAPI/silc_mp_mp2bin_noalloc
  *
  * SYNOPSIS
  *
  *    void silc_mp_mp2bin_noalloc(SilcMPInt *val, unsigned char *dst,
- *                                uint32 dst_len);
+ *                                SilcUInt32 dst_len);
  *
  * DESCRIPTION
  *
@@ -623,13 +639,13 @@ unsigned char *silc_mp_mp2bin(SilcMPInt *val, uint32 len,
  *
  ***/
 void silc_mp_mp2bin_noalloc(SilcMPInt *val, unsigned char *dst,
-                           uint32 dst_len);
+                           SilcUInt32 dst_len);
 
 /****f* silcmath/SilcMPAPI/silc_mp_bin2mp
  *
  * SYNOPSIS
  *
- *    void silc_mp_bin2mp(unsigned char *data, uint32 len, 
+ *    void silc_mp_bin2mp(unsigned char *data, SilcUInt32 len, 
  *                        SilcMPInt *ret);
  *
  * DESCRIPTION
@@ -638,7 +654,7 @@ void silc_mp_mp2bin_noalloc(SilcMPInt *val, unsigned char *dst,
  *    must be initialized.
  *
  ***/
-void silc_mp_bin2mp(unsigned char *data, uint32 len, SilcMPInt *ret);
+void silc_mp_bin2mp(unsigned char *data, SilcUInt32 len, SilcMPInt *ret);
 
 /****f* silcmath/SilcMPAPI/silc_mp_abs
  *