elementfns.xml

这是一个C的源代码

<chapter>
<title>Element Functions</title>
<para>
Elements of groups, rings and fields are stored in the <type>element_t</type>
data type. Variables of this type
must be initialized before use, and should be cleared after they are no longer
needed.
</para>
<para>
The <function>element_</function> 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.
</para>
<para>
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.
</para>
<para>
Because of the way PBC is designed, checking that elements
from different algberaic structures have not been mistakenly mixed is
not easy to do at compile-time. Instead, runtime checks are performed if
PBC_DEBUG is defined before the PBC header file is included:
</para>
<programlisting>#define PBC_DEBUG
#include &lt;pbc.h&gt;
</programlisting>
<para>
Note performance will be impaired, so this debugging features should be
disabled in the final build.
</para>
<section>
<title>Initializing Elements</title>
<para>
When an element is initialized it is associated with an algebraic structure,
such as a particular finite field or elliptic curve group.
</para>
<variablelist>
&einit;
</variablelist>
</section>
<section>
<title>Assigning Elements</title>
<para>
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).
</para>
<variablelist>
&eassign;
</variablelist>
</section>
<section>
<title>Converting Elements</title>
<variablelist>
&econvert;
</variablelist>
</section>

<section>
<title>Element Arithmetic</title>
<para>
Unless otherwise stated,
all <type>element_t</type> 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.
</para>
<para>
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.
</para>
<para>
In contrast, the GT group is currently
implemented as a subgroup of a finite field, so only multiplicative operations
should be used for GT.
</para>
<variablelist>
&earith;
</variablelist>
</section>

<section>
<title>Exponentiating Elements</title>
<para>
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:
</para>
<screen>
    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);
</screen>
<variablelist>
&epow;
</variablelist>
</section>

<section>
<title>Comparing Elements</title>
<para>
These functions compare elements from the same algebraic structure.
</para>
<variablelist>
&ecmp;
</variablelist>
</section>

<section>
<title>I/O of Elements</title>
<para>
Functions for producing human-readable outputs for elements.
Converting elements to and from bytes are discussed later.
</para>
<variablelist>
&eio;
</variablelist>
</section>

<section>
<title>Random Elements</title>
<para>
Only works for finite algebraic structures. Effect
on polynomial rings, fields of characteristic zero, etc. undefined.
</para>
<para>
See the chapter on randomness functions on where PBC gets random bits
from and how to select a different source of random bits.
</para>
<variablelist>
&erandom;
</variablelist>
</section>

<section>
<title>Element Import/Export</title>
<para>
Functions for serializing and deserializing elements.
</para>
<variablelist>
&etrade;
</variablelist>
</section>

</chapter>