%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  gf_p_base.tex       LiDIA documentation
%%
%%  This file contains the documentation of the class gf_p_base
%%
%%  Copyright   (c)   1995   by  LiDIA-Group 
%%
%%  Author:  Detlef Anton
%%

\begin{lidia_man}

\markright{\BF{gf\_p\_base}}

\NAME
	\BF{gf\_p\_base} \dotfill polynomial base

\ABSTRACT
	A variable of type \BF{gf\_p\_base} holds a polynomial base
	represented by a polynomial and the corresponding field.\\
	This is the representation of a finite field as the quotient ring
	\MATH{(\Z/p\Z[X])/A}, where \MATH{p} denotes the
	characteristic and \MATH{A} is an ideal generated by an
	irreducible polynomial in \MATH{\Z/p\Z[X]}.

\DESCRIPTION
	A variable of type \BF{gf\_p\_base} consists of a reference \MATH{k}
	to a variable of type \BF{galois\_field}, and of a \BF{poly\_modulus}, in which
	a monic irreducible polynomial of degree \TT{k.degree()} in
	\MATH{\Z/p\Z[X]} is stored, where \MATH{p =} \TT{k.characteristic()}.
	
	Any object of class \BF{gf\_p\_base} contains a reference counter
	to control whether or not it is used by a \BF{gf\_p\_element} object.
	One may modify or delete an instance only if this counter is zero.


   \CONS

	\fcode{\hfill}{gf\_p\_base}{}{
		initializes only the structure of a \BF{gf\_p\_base}.}
	\fcode{\hfill}{gf\_p\_base}{const galois\_field \& K}{
		constructs a polynomial base by giving a field \TT{K}.
		The irreducible polynomial is generated automatically.}
	\fcode{\hfill}{gf\_p\_base}{const galois\_field \& K\k const Fp\_polynomial \& pol}{
		constructs a polynomial base by giving a field \TT{K} and 
		an monic irreducible polynomial \TT{pol} of degree
		\TT{K.degree()} in $\Z/p\Z[X]$, where $p =$ 
		\TT{K.characteristic()}. The behaviour
		of the program is undefined, if \TT{pol} is not irreducible.}
	\fcode{\hfill}{gf\_p\_base}{const gf\_p\_base \& PB}{
		constructs a copy of \TT{PB}.}
	\fcode{\hfill}{\MATH{\sim}gf\_p\_base}{}{}

   \ACCS

	Let \TT{pb} be an instance of type \BF{gf\_p\_base}.

	\cfcode{const galois\_field \& const}{pb.field}{}{
		returns a reference to the field for which \TT{pb} is
		initialized.}
	\cfcode{const Fp\_polynomial \&}{pb.irred\_polynomial}{}{
		returns the polynomial of the polynomial base \TT{pb}.}

   \ASGN

	Let \TT{pb} be an instance of type \BF{gf\_p\_base}.

	The operator $=$ is overloaded. For efficiency reasons, the following
        function is implemented:

        \fcode{void}{pb.assign}{const gf\_p\_base \& PB}{
                        \TT{pb} $=$ \TT{PB}.}

   \HIGH

	Let \TT{pb} be an instance of type \BF{gf\_p\_base}.

	\cfcode{gf\_p\_element}{pb.gen\_primitive\_elem}{}{
		generates a \BF{gf\_p\_element} over \TT{pb}, which is a primitive
		element in the multiplicative group of the corresponding field.}
	\cfcode{gf\_p\_element}{pb.gen\_free\_elem}{}{
		generates a \BF{gf\_p\_element} over \TT{pb}, which is free, that means it
		is a normal base generator.}
	\cfcode{gf\_p\_element}{pb.gen\_free\_primitive\_elem}{}{
		generates a \BF{gf\_p\_element} over \TT{pb}, which is free and
		a primitive element in the multiplicative group of the
		corresponding field.}

   \IO

        The \BF{istream} operator $>\! >$ and the \BF{ostream} operator $<\! <$ are
        overloaded.

        \fcode{istream \&}{operator $>\! >$}{istream \& in\k gf\_p\_base \& PB}{
                reads a polynomial base from \BF{istream} \TT{in}.\\
		The input must be an irreducible polynomial of type
		\BF{Fp\_polynomial}; the
		behaviour of the program is undefined, if it is not
		irreducible. If it is does not have degree
		\TT{PB.field().degree()} and modulus
		\TT{PB.field().characteristic()}, the
		\TT{lidia\_error\_handler} will be invoked.\\
		If \TT{PB.field()} is undefined, the
		\TT{lidia\_error\_handler} will be invoked.}

        \fcode{ostream \&}{operator $<\! <$}{ostream \& out\k const gf\_p\_base \& PB}{
                writes the polynomial base \TT{PB} to \BF{ostream} \TT{out} in form of
		the irreducible polynomial of type \BF{Fp\_polynomial}.}

\SEEALSO
	class \BF{galois\_field}

        class \BF{gf\_p\_element}

%	class \BF{gf\_n\_base}
%
%	class \BF{gf\_n\_element}

\WARNINGS

	Modifying or deleting an object for which there is still a reference
	in some instance of class \BF{gf\_p\_element},
	invokes the \TT{lidia\_error\_handler}.

	At now, two instances of class \BF{gf\_p\_base} with equal
	polynomial bases are considered to be different.

\EXAMPLES

	see example for class \BF{gf\_p\_element}
	
\AUTHOR
	Detlef Anton, Franz-Dieter Berger, Stefan Neis, Thomas Pfahler

\end{lidia_man}
