cln_mirror/doc/cln_7.html

<HTML>
<HEAD>
<!-- Created by texi2html 1.56k from cln.texi on 14 January 2000 -->

<TITLE>CLN, a Class Library for Numbers - 7. Modular integers</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_6.html">previous</A>, <A HREF="cln_8.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC48" HREF="cln_toc.html#TOC48">7. Modular integers</A></H1>


<H2><A NAME="SEC49" HREF="cln_toc.html#TOC49">7.1 Modular integer rings</A></H2>

<P>
CLN implements modular integers, i.e. integers modulo a fixed integer N.
The modulus is explicitly part of every modular integer. CLN doesn't
allow you to (accidentally) mix elements of different modular rings,
e.g. <CODE>(3 mod 4) + (2 mod 5)</CODE> will result in a runtime error.
(Ideally one would imagine a generic data type <CODE>cl_MI(N)</CODE>, but C++
doesn't have generic types. So one has to live with runtime checks.)


<P>
The class of modular integer rings is


<PRE>
                         Ring
                       cl_ring
                      &#60;cl_ring.h&#62;
                          |
                          |
                 Modular integer ring
                    cl_modint_ring
                   &#60;cl_modinteger.h&#62;
</PRE>

<P>
and the class of all modular integers (elements of modular integer rings) is


<PRE>
                    Modular integer
                         cl_MI
                   &#60;cl_modinteger.h&#62;
</PRE>

<P>
Modular integer rings are constructed using the function


<DL COMPACT>

<DT><CODE>cl_modint_ring cl_find_modint_ring (const cl_I&#38; N)</CODE>
<DD>
This function returns the modular ring <SAMP>`Z/NZ'</SAMP>. It takes care
of finding out about special cases of <CODE>N</CODE>, like powers of two
and odd numbers for which Montgomery multiplication will be a win,
and precomputes any necessary auxiliary data for computing modulo <CODE>N</CODE>.
There is a cache table of rings, indexed by <CODE>N</CODE> (or, more precisely,
by <CODE>abs(N)</CODE>). This ensures that the precomputation costs are reduced
to a minimum.
</DL>

<P>
Modular integer rings can be compared for equality:


<DL COMPACT>

<DT><CODE>bool operator== (const cl_modint_ring&#38;, const cl_modint_ring&#38;)</CODE>
<DD>
<DT><CODE>bool operator!= (const cl_modint_ring&#38;, const cl_modint_ring&#38;)</CODE>
<DD>
These compare two modular integer rings for equality. Two different calls
to <CODE>cl_find_modint_ring</CODE> with the same argument necessarily return the
same ring because it is memoized in the cache table.
</DL>


<H2><A NAME="SEC50" HREF="cln_toc.html#TOC50">7.2 Functions on modular integers</A></H2>

<P>
Given a modular integer ring <CODE>R</CODE>, the following members can be used.


<DL COMPACT>

<DT><CODE>cl_I R-&#62;modulus</CODE>
<DD>
This is the ring's modulus, normalized to be nonnegative: <CODE>abs(N)</CODE>.

<DT><CODE>cl_MI R-&#62;zero()</CODE>
<DD>
This returns <CODE>0 mod N</CODE>.

<DT><CODE>cl_MI R-&#62;one()</CODE>
<DD>
This returns <CODE>1 mod N</CODE>.

<DT><CODE>cl_MI R-&#62;canonhom (const cl_I&#38; x)</CODE>
<DD>
This returns <CODE>x mod N</CODE>.

<DT><CODE>cl_I R-&#62;retract (const cl_MI&#38; x)</CODE>
<DD>
This is a partial inverse function to <CODE>R-&#62;canonhom</CODE>. It returns the
standard representative (<CODE>&#62;=0</CODE>, <CODE>&#60;N</CODE>) of <CODE>x</CODE>.

<DT><CODE>cl_MI R-&#62;random(cl_random_state&#38; randomstate)</CODE>
<DD>
<DT><CODE>cl_MI R-&#62;random()</CODE>
<DD>
This returns a random integer modulo <CODE>N</CODE>.
</DL>

<P>
The following operations are defined on modular integers.


<DL COMPACT>

<DT><CODE>cl_modint_ring x.ring ()</CODE>
<DD>
Returns the ring to which the modular integer <CODE>x</CODE> belongs.

<DT><CODE>cl_MI operator+ (const cl_MI&#38;, const cl_MI&#38;)</CODE>
<DD>
Returns the sum of two modular integers. One of the arguments may also be
a plain integer.

<DT><CODE>cl_MI operator- (const cl_MI&#38;, const cl_MI&#38;)</CODE>
<DD>
Returns the difference of two modular integers. One of the arguments may also be
a plain integer.

<DT><CODE>cl_MI operator- (const cl_MI&#38;)</CODE>
<DD>
Returns the negative of a modular integer.

<DT><CODE>cl_MI operator* (const cl_MI&#38;, const cl_MI&#38;)</CODE>
<DD>
Returns the product of two modular integers. One of the arguments may also be
a plain integer.

<DT><CODE>cl_MI square (const cl_MI&#38;)</CODE>
<DD>
Returns the square of a modular integer.

<DT><CODE>cl_MI recip (const cl_MI&#38; x)</CODE>
<DD>
Returns the reciprocal <CODE>x^-1</CODE> of a modular integer <CODE>x</CODE>. <CODE>x</CODE>
must be coprime to the modulus, otherwise an error message is issued.

<DT><CODE>cl_MI div (const cl_MI&#38; x, const cl_MI&#38; y)</CODE>
<DD>
Returns the quotient <CODE>x*y^-1</CODE> of two modular integers <CODE>x</CODE>, <CODE>y</CODE>.
<CODE>y</CODE> must be coprime to the modulus, otherwise an error message is issued.

<DT><CODE>cl_MI expt_pos (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
<DD>
<CODE>y</CODE> must be &#62; 0. Returns <CODE>x^y</CODE>.

<DT><CODE>cl_MI expt (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
<DD>
Returns <CODE>x^y</CODE>. If <CODE>y</CODE> is negative, <CODE>x</CODE> must be coprime to the
modulus, else an error message is issued.

<DT><CODE>cl_MI operator&#60;&#60; (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
<DD>
Returns <CODE>x*2^y</CODE>.

<DT><CODE>cl_MI operator&#62;&#62; (const cl_MI&#38; x, const cl_I&#38; y)</CODE>
<DD>
Returns <CODE>x*2^-y</CODE>. When <CODE>y</CODE> is positive, the modulus must be odd,
or an error message is issued.

<DT><CODE>bool operator== (const cl_MI&#38;, const cl_MI&#38;)</CODE>
<DD>
<DT><CODE>bool operator!= (const cl_MI&#38;, const cl_MI&#38;)</CODE>
<DD>
Compares two modular integers, belonging to the same modular integer ring,
for equality.

<DT><CODE>cl_boolean zerop (const cl_MI&#38; x)</CODE>
<DD>
Returns true if <CODE>x</CODE> is <CODE>0 mod N</CODE>.
</DL>

<P>
The following output functions are defined (see also the chapter on
input/output).


<DL COMPACT>

<DT><CODE>void fprint (cl_ostream stream, const cl_MI&#38; x)</CODE>
<DD>
<DT><CODE>cl_ostream operator&#60;&#60; (cl_ostream stream, const cl_MI&#38; x)</CODE>
<DD>
Prints the modular integer <CODE>x</CODE> on the <CODE>stream</CODE>. The output may depend
on the global printer settings in the variable <CODE>cl_default_print_flags</CODE>.
</DL>

<P><HR><P>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_6.html">previous</A>, <A HREF="cln_8.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
</BODY>
</HTML>