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

\begin{lidia_man}

\markright{\BF{galois\_field}}

\NAME
	\BF{galois\_field} \dotfill galois field

\ABSTRACT
	A variable of type \BF{galois\_field} holds a finite field represented by
	its characteristic and its degree.
	
	Any object of class \BF{galois\_field} contains a reference counter
	to control whether or not it is used by a \BF{gf\_p\_base}
	%or \BF{gf\_n\_base}
	object.
	One may modifiy or delete an instance only if this counter is zero.


\DESCRIPTION
	A variable of type \BF{galois\_field} consists of a bigint $p$, which 
	represents the characteristic and therefore must be a prime
	number, and of a \BF{lidia\_size\_t} $n$, which represents the degree of
	the field. In the following $p$ means the characteristic 
	and $n$ means the degree of the field.

   \CONS

	\fcode{\hfill}{galois\_field}{}{
		initializes only the structure of a field, without giving 
		a field.}
	\fcode{\hfill}{galois\_field}{const bigint \& characteristic\k
                   lidia\_size\_t degree = 1}{
		constructs a field by giving the \TT{characteristic}
		and \TT{degree} of it. The default degree is 1. If
		\TT{characteristic} is not a prime number, the behaviour
		of the program is undefined.}
	\fcode{\hfill}{galois\_field}{const bigint \& characteristic\k
                   lidia\_size\_t degree\k
                   const factorization\TEMPL{bigint} \& fact}{
		constructs a field by giving the \TT{characteristic},
		the \TT{degree} and the factorization \TT{fact} of the number 
		of elements in the multiplicative group of the constructed field. If
		\TT{fact} is not a factorization of $\TT{characteristic}^{\TT{degree}}-1$,
		the behaviour of the program is undefined.}
	\fcode{\hfill}{galois\_field}{const factorization\TEMPL{bigint} \& fact}{
		constructs a field by only giving a factorization \TT{fact} of
		the number of elements in the multiplicative group of the constructed field.
		\TT{fact} does not have to be a prime factorization.}
	\fcode{\hfill}{galois\_field}{const galois\_field \& K}{
		constructs a copy of \TT{K}.}
	\fcode{\hfill}{\MATH{\sim}galois\_field}{}{}

   \ACCS

	Let \TT{f} be an instance of type \BF{galois\_field}.

	\cfcode{const bigint \&}{f.characteristic}{}{
	        returns the characteristic of the field \TT{f}.}
	\cfcode{lidia\_size\_t}{f.degree}{}{
	        returns the degree of the field \TT{f}.}
	\cfcode{const bigint \&}{f.number\_of\_elements}{}{
                returns the number of elements of the field \TT{f}.} 
	\cfcode{const factorization\TEMPL{bigint} \&}
		{f.factorization\_of\_mult\_order}{}{
                returns the prime factorization of the
                number of elements in the multiplicative group of \TT{f}.}

   \ASGN

	Let \TT{f} be an instance of type \BF{galois\_field}.
	The operator $=$ is overloaded. For efficiency reasons, the following
        function is implemented:

	\fcode{void}{f.assign}{const galois\_field \& K}{
			\TT{f} $=$ \TT{K}.}

   \IO

	The \BF{istream} operator $>\! >$ and the \BF{ostream} operator $<\! <$ are
	overloaded.
 
	\fcode{istream \&}{operator $>\! >$}{istream \& in\k galois\_field \& K}{
		reads a field from \BF{istream} \TT{in}. The input must be of the 
		form \mbox{``(p, n)''}, where p is the characteristic and n
		the degree of the field \TT{K}.}

	\fcode{ostream \&}{operator $<\! <$}{ostream \& out\k const galois\_field \& K}{
		writes the field \TT{K} to \BF{ostream} \TT{out} in form of ``(p, n)'',
		where p is the characteristic and n the degree of the field \TT{K}.}
 
\SEEALSO
	class \BF{gf\_p\_base} 

	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\_base},
	%or \BF{gf\_n\_base}
	invokes the \TT{lidia\_error\_handler}.

	At now, two equal instances of class \BF{galois\_field} with equal characteristic
	and degree 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}
