Added Then* methods, updated documentation

doc.go

@@ -17,8 +17,9 @@
 	maximize performance.
 
 	Since this library provides low-level access to pairing primitives, it is
-	very easy to construct insecure systems. This library is intended to be used
-	by cryptographers or to implement well-analyzed cryptosystems.
+	very easy to accidentally construct insecure systems. This library is
+	intended to be used by cryptographers or to implement well-analyzed
+	cryptosystems.
 
 	Pairings
 

element.go

@@ -25,6 +25,14 @@ import "runtime"
 //
 // This assigns x = ((a+b)*c)^2.
 //
+// This technique is useful because it allows the target of operations to be
+// different than the operands. However, several convenience functions have
+// been provided to improve the readability of chained calls. These functions
+// are of the form Then*, and implicitly specify the target as the first
+// operand. The above example can be rewritten as:
+//
+// 	x.Add(a, b).ThenMul(c).ThenSquare()
+//
 // Whenever possible, the methods defined on Element use the same names as
 // those in the math/big package.
 //

element_arith_simple.go

+package pbc
+
+import "math/big"
+
+// ThenAdd is an alias for el.Add(el, y).
+//
+// Requirements:
+// el and y must be from the same algebraic structure.
+func (el *Element) ThenAdd(y *Element) *Element { return el.Add(el, y) }
+
+// ThenSub is an alias for el.Sub(el, y).
+//
+// Requirements:
+// el and y must be from the same algebraic structure.
+func (el *Element) ThenSub(y *Element) *Element { return el.Sub(el, y) }
+
+// ThenMul is an alias for el.Mul(el, y).
+//
+// Requirements:
+// el and y must be from the same algebraic structure.
+func (el *Element) ThenMul(y *Element) *Element { return el.Mul(el, y) }
+
+// ThenMulBig is an alias for el.MulBig(el, i).
+func (el *Element) ThenMulBig(i *big.Int) *Element { return el.MulBig(el, i) }
+
+// ThenMulInt32 is an alias for el.MulInt32(el, i).
+func (el *Element) ThenMulInt32(i int32) *Element { return el.MulInt32(el, i) }
+
+// ThenMulZn is an alias for el.MulZn(el, i).
+//
+// Requirements:
+// i must be an element of an integer mod ring (e.g., Zn for some n).
+func (el *Element) ThenMulZn(i *Element) *Element { return el.MulZn(el, i) }
+
+// ThenDiv is an alias for el.Div(el, y).
+//
+// Requirements:
+// el and y must be from the same algebraic structure.
+func (el *Element) ThenDiv(y *Element) *Element { return el.Div(el, y) }
+
+// ThenDouble is an alias for el.Double(el).
+func (el *Element) ThenDouble() *Element { return el.Double(el) }
+
+// ThenHalve is an alias for el.Halve(el).
+func (el *Element) ThenHalve() *Element { return el.Halve(el) }
+
+// ThenSquare is an alias for el.Square(el).
+func (el *Element) ThenSquare() *Element { return el.Square(el) }
+
+// ThenNeg is an alias for el.Neg(el).
+func (el *Element) ThenNeg() *Element { return el.Neg(el) }
+
+// ThenInvert is an alias for el.Invert(el).
+func (el *Element) ThenInvert() *Element { return el.Invert(el) }
+
+// ThenPowBig is an alias for el.PowBig(el, i).
+func (el *Element) ThenPowBig(i *big.Int) *Element { return el.PowBig(el, i) }
+
+// ThenPowZn is an alias for el.PowZn(el, i).
+//
+// Requirements:
+// i must be an element of an integer mod ring (e.g., Zn for some n, typically
+// the order of the algebraic structure that el lies in).
+func (el *Element) ThenPowZn(i *Element) *Element { return el.PowZn(el, i) }