/**************************************************************************\

MODULE: zz_pE

SUMMARY:

The class zz_pE is used to represent polynomials in Z_p[X] modulo a
polynomial P.  The modulus P may be any polynomial with deg(P) > 0,
not necessarily irreducible.  The modulus p defining Z_p need
not be prime either.

Objects of the class zz_pE are represented as a zz_pX of degree < deg(P).

An executing program maintains a "current modulus", which is set to P
using zz_pE::init(P).  The current modulus *must* be initialized before
any zz_pE constructors are invoked.

The modulus may be changed, and a mechanism is provided for saving and
restoring a modulus (see classes zz_pEBak and zz_pEContext below).


\**************************************************************************/

#include <NTL/lzz_pX.h>

class zz_pE {
public:
   
   zz_pE(); // initial value 0

   zz_pE(const zz_pE& a); // copy constructor
   
   zz_pE& operator=(const zz_pE& a); // assignment
   zz_pE& operator=(const zz_p& a); // assignment
   zz_pE& operator=(long a); // assignment
   
   ~zz_pE(); // destructor

   void init(const zz_pX& P);
   // zz_pE::init(P) initializes the current modulus to P;
   // required: deg(P) >= 1.
   
   static const zz_pXModulus& modulus();
   // zz_pE::modulus() yields read-only reference to the current modulus 

   static long degree();
   // zz_pE::degree() returns deg(P)
};


const zz_pX& rep(const zz_pE& a); // read-only access to representation of a



/**************************************************************************\

                                  Comparison

\**************************************************************************/

long operator==(const zz_pE& a, const zz_pE& b);
long operator!=(const zz_pE& a, const zz_pE& b);

long IsZero(const zz_pE& a);  // test for 0
long IsOne(const zz_pE& a);  // test for 1

// PROMOTIONS: ==, != promote {long, zz_p} to zz_pE on (a, b).


/**************************************************************************\

                                    Addition 

\**************************************************************************/

// operator notation:

zz_pE operator+(const zz_pE& a, const zz_pE& b);

zz_pE operator-(const zz_pE& a, const zz_pE& b);
zz_pE operator-(const zz_pE& a);

zz_pE& operator+=(zz_pE& x, const zz_pE& a);
zz_pE& operator+=(zz_pE& x, const zz_p& a);
zz_pE& operator+=(zz_pE& x, long a);

zz_pE& operator++(zz_pE& x); // prefix
void operator++(zz_pE& x, int); // postfix

zz_pE& operator-=(zz_pE& x, const zz_pE& a);
zz_pE& operator-=(zz_pE& x, const zz_p& a);
zz_pE& operator-=(zz_pE& x, long a);

zz_pE& operator--(zz_pE& x); // prefix
void operator--(zz_pE& x, int); // postfix

// procedural versions:

void add(zz_pE& x, const zz_pE& a, const zz_pE& b); // x = a + b
void sub(zz_pE& x, const zz_pE& a, const zz_pE& b); // x = a - b 
void negate(zz_pE& x, const zz_pE& a); // x = - a 

// PROMOTIONS: +, -, add, sub promote {long, zz_p} to zz_pE on (a, b).


/**************************************************************************\

                                  Multiplication 

\**************************************************************************/


// operator notation:

zz_pE operator*(const zz_pE& a, const zz_pE& b);

zz_pE& operator*=(zz_pE& x, const zz_pE& a);
zz_pE& operator*=(zz_pE& x, const zz_p& a);
zz_pE& operator*=(zz_pE& x, long a);

// procedural versions:


void mul(zz_pE& x, const zz_pE& a, const zz_pE& b); // x = a * b

void sqr(zz_pE& x, const zz_pE& a); // x = a^2
zz_pE sqr(const zz_pE& a); 

// PROMOTIONS: *, mul promote {long, zz_p} to zz_pE on (a, b).



/**************************************************************************\

                                     Division

\**************************************************************************/


// operator notation:

zz_pE operator/(const zz_pE& a, const zz_pE& b);

zz_pE& operator/=(zz_pE& x, const zz_pE& a);
zz_pE& operator/=(zz_pE& x, const zz_p& a);
zz_pE& operator/=(zz_pE& x, long a);


// procedural versions:

void div(zz_pE& x, const zz_pE& a, const zz_pE& b);
// x = a/b.  If b is not invertible, an error is raised.

void inv(zz_pE& x, const zz_pE& a);
zz_pE inv(const zz_pE& a);
// x = 1/a

PROMOTIONS: /, div promote {long, zz_p} to zz_pE on (a, b).


/**************************************************************************\

                                  Exponentiation

\**************************************************************************/



void power(zz_pE& x, const zz_pE& a, const ZZ& e); 
zz_pE power(const zz_pE& a, const ZZ& e);

void power(zz_pE& x, const zz_pE& a, long e); 
zz_pE power(const zz_pE& a, long e);

// x = a^e (e may be negative)



/**************************************************************************\

                               Random Elements

\**************************************************************************/


void random(zz_pE& x);
zz_pE random_zz_pE();
// x = random element in zz_pE.

/**************************************************************************\

                               Norms and Traces

\**************************************************************************/



void trace(zz_p& x, const zz_pE& a);  // x = trace of a
zz_p trace(const zz_pE& a);

void norm(zz_p& x, const zz_pE& a);   // x = norm of a
zz_p norm(const zz_pE& a);



/**************************************************************************\

                                Input/Output

\**************************************************************************/


ostream& operator<<(ostream& s, const zz_pE& a);

istream& operator>>(istream& s, zz_pE& x);
// a zz_pX is read and reduced mod p


/**************************************************************************\

                       Modulus Switching 

A class zz_pEBak is provided for "backing up" the current modulus.

Here is what you do to save the current modulus, temporarily
set it to something new, and then restore it:

   zz_pEBak bak;
   bak.save();   // save current modulus (if any)

   zz_pE::init(P);  // set modulus to desired value P

      // ...

   bak.restore(); // restore old modulus (if any)

Note that between the save and restore, you may have several calls to
zz_pE::init, each of which simply clobbers the previous modulus.

The zz_pEBak interface is good for implementing simple stack-like
modulus "context switching".  For more general context switching,
see zz_pEContext below.

..........................................................................

When the current modulus is changed, there may be extant
zz_pE objects. If the old modulus was saved and then later restored, 
these objects can be used again as if the modulus had never changed.  
Note, however, that if a zz_pE object is created under one modulus 
and then used in any way (except destroyed) under another, 
program behavior is not predictable.  This condition is not
explicitly checked for, but an error is likely to be raised.
One should also not presume that things will work properly
if the modulus is changed, but its value happens to be the same---
one should restore the same "context", from either a zz_pEBak
or a zz_pEContext object.  This is anyway more efficient.

\**************************************************************************/




class zz_pEBak {
public:

   // To describe this logic, think of a zz_pEBak object
   // of having two components: a modulus Q (possibly "null") and 
   // an "auto-restore bit" b.

   // There is also a global current modulus P (initially "null").

   zz_pEBak();  // Q = "null", b = 0

   ~zz_pEBak();  // if (b) P = Q

   void save();  // Q = P, b = 1 
   void restore();  // P = Q, b = 0


private:
   zz_pEBak(const zz_pEBak&);  // copy disabled
   void operator=(const zz_pEBak&);  // assignment disabled
};


// more general context switching:

class zz_pEContext {

// A zz_pEContext object has a modulus Q (possibly "null"),
// but has no auto-restore bit like a zz_pEBak object.
// However, these objects can be initialized and copied with
// complete generality.

// As above, P is the current global modulus (initially "null")

public:

zz_pEContext(); // Q = "null"
zz_pEContext(const zz_pX& new_Q); // Q = new_Q

void save(); // Q = P
void restore() const; // P = Q

zz_pEContext(const zz_pEContext&);  // copy
zz_pEContext& operator=(const zz_pEContext&); // assignment
~zz_pEContext(); // destructor


};


/**************************************************************************\

                               Miscellany

\**************************************************************************/

void clear(zz_pE& x); // x = 0
void set(zz_pE& x); // x = 1

static const zz_pE& zz_pE::zero();
// zz_pE::zero() yields a read-only reference to zero

void swap(zz_pE& x, zz_pE& y);
// swap x and y (done by "pointer swapping", if possible).

static ZZ& zz_pE::cardinality();
// yields the cardinality, i.e., p^{zz_pE::degree()}