1 files changed, 111 insertions, 0 deletions
diff --git a/moon-abe/pbc-0.5.14/doc/elementfns.txt b/moon-abe/pbc-0.5.14/doc/elementfns.txt
new file mode 100644
index 00000000..cadf78b0
--- /dev/null
+++ b/moon-abe/pbc-0.5.14/doc/elementfns.txt
@@ -0,0 +1,111 @@
+== Element functions ==
+
+Elements of groups, rings and fields are stored in the +element_t+ data type.
+Variables of this type must be initialized before use, and should be cleared
+after they are no longer needed.
+
+The +element_+ functions must be used with caution.  Just as division by zero
+does not make sense for integers, some operations may not make sense for
+particular elements. For example, in a ring, one cannot in general invert
+elements.
+
+Another caveat is that many of these functions assume their arguments come from
+the same ring, group or field. No implicit type casting is performed.
+
+For debug builds, turn on run-time checks by defining `PBC_DEBUG` before
+including `pbc.h`:
+
+  #define PBC_DEBUG
+  #include <pbc.h>
+
+Also, when `PBC_DEBUG` is defined, the following macros are active.
+Normally they are replaced with empty statements.
+
+include::gen/debug.txt[]
+
+=== Initializing elements ===
+
+When an element is initialized it is associated with an algebraic structure,
+such as a particular finite field or elliptic curve group.
+
+We use G1 and G2 to denote the input groups to the pairing, and GT for the
+output group. All have order r, and Zr means the ring of integers modulo r.
+G1 is the smaller group (the group of points over the base field). With
+symmetric pairings, G1 = G2.
+
+include::gen/einit.txt[]
+
+=== Assigning elements ===
+
+These functions assign values to elements. When integers are assigned,
+they are mapped to algebraic structures canonically if it makes sense
+(e.g. rings and fields).
+
+include::gen/eassign.txt[]
+
+=== Converting elements ===
+
+include::gen/econvert.txt[]
+
+=== Element arithmetic ===
+
+Unless otherwise stated, all +element_t+ arguments to these functions must have
+been initialized to be from the same algebraic structure.  When one of these
+functions expects its arguments to be from particular algebraic structures,
+this is reflected in the name of the function.
+
+The addition and multiplication functions perform addition and multiplication
+operations in rings and fields. For groups of points on an ellitpic curve, such
+as the G1 and G2 groups associated with pairings, both addition and
+multiplication represent the group operation (and similarly both 0 and 1
+represent the identity element).  It is recommended that programs choose and
+one convention and stick with it to avoid confusion.
+
+In contrast, the GT group is currently
+implemented as a subgroup of a finite field, so only multiplicative operations
+should be used for GT.
+
+include::gen/earith.txt[]
+
+=== Exponentiating elements ===
+
+Exponentiation and multiexponentiation functions.  If it is known in advance
+that a particular element will be exponentiated several times in the future,
+time can be saved in the long run by first calling the preprocessing function:
+
+    element_pp_t g_pp;
+    element_pp_init(g_pp, g);
+    element_pp_pow(h, pow1, g_pp); // h = g^pow1
+    element_pp_pow(h, pow2, g_pp); // h = g^pow2
+    element_pp_pow(h, pow3, g_pp); // h = g^pow3
+    element_pp_clear(g_pp);
+
+include::gen/epow.txt[]
+
+=== Comparing elements ===
+
+These functions compare elements from the same algebraic structure.
+
+include::gen/ecmp.txt[]
+
+=== Element I/O ===
+
+Functions for producing human-readable outputs for elements.
+Converting elements to and from bytes are discussed later.
+
+include::gen/eio.txt[]
+
+=== Random elements ===
+
+Only works for finite algebraic structures. Effect on polynomial rings, fields
+of characteristic zero, etc. undefined.
+
+See <<randomref>> for how PBC gets random bits.
+
+include::gen/erandom.txt[]
+
+=== Element import/export ===
+
+Functions for serializing and deserializing elements.
+
+include::gen/etrade.txt[]