== 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[]