Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

FieldArchetype Class Reference
[linbox/field]

#include <archetype.h>

Inheritance diagram for FieldArchetype:

FieldInterface RingArchetype List of all members.

Detailed Description

field specification and archetypical instance.

The FieldArchetype and its encapsulated element class contain pointers to the FieldAbstract and its encapsulated field element, respectively. FieldAbstract then uses virtual member functions to define operations on its encapsulated field element. This field element has no knowledge of the field properties being used on it which means the field object must supply these operations.

It does not contain elements zero and one because they can be created whenever necessary, although it might be beneficial from an efficiency stand point to include them. However, because of archetype use three, the elements themselves cannot be contained, but rather pointers to them.


Public Types

Common Object Interface for a LinBox Field.
typedef ElementArchetype Element
 the type in which field elements are represented.

typedef RandIterArchetype RandIter
 An object of this type is a generator of random field elements.


Public Member Functions

Object Management
These methods are required of all LinBox} fields.

 FieldArchetype (const FieldArchetype &F)
 Copy constructor.

 ~FieldArchetype (void)
 Destructor.

FieldArchetypeoperator= (const FieldArchetype &F)
 Assignment operator.

Elementinit (Element &x, const integer &y=0) const
 Initialization of field element from an integer.

integerconvert (integer &x, const Element &y=0) const
 Conversion of field element to an integer.

Elementassign (Element &x, const Element &y) const
 Assignment of one field element to another.

integercardinality (integer &c) const
 Cardinality.

integercharacteristic (integer &c) const
 Characteristic.

Arithmetic Operations
x <- y op z; x <- op y These operations require all elements, including x, to be initialized before the operation is called. Uninitialized field elements will give undefined results.

bool areEqual (const Element &x, const Element &y) const
 Equality of two elements.

Elementadd (Element &x, const Element &y, const Element &z) const
 Addition, x <-- y + z.

Elementsub (Element &x, const Element &y, const Element &z) const
 Subtraction, x <-- y - z.

Elementmul (Element &x, const Element &y, const Element &z) const
 Multiplication, x <-- y * z.

Elementdiv (Element &x, const Element &y, const Element &z) const
Elementneg (Element &x, const Element &y) const
 Additive Inverse (Negation), x <-- - y.

Elementinv (Element &x, const Element &y) const
 Multiplicative Inverse, x <-- 1 / y.

Elementaxpy (Element &r, const Element &a, const Element &x, const Element &y) const
 Field element AXPY, r <-- a * x + y.

Predicates
bool isZero (const Element &x) const
bool isOne (const Element &x) const
Inplace Arithmetic Operations
x <- x op y; x <- op x These operations require all elements, including x, to be initialized before the operation is called. Uninitialized field elements will give undefined results.

Elementaddin (Element &x, const Element &y) const
Elementsubin (Element &x, const Element &y) const
Elementmulin (Element &x, const Element &y) const
Elementdivin (Element &x, const Element &y) const
Elementnegin (Element &x) const
Elementinvin (Element &x) const
Elementaxpyin (Element &r, const Element &a, const Element &x) const
Input/Output Operations
std::ostream & write (std::ostream &os) const
std::istream & read (std::istream &is)
std::ostream & write (std::ostream &os, const Element &x) const
std::istream & read (std::istream &is, Element &x) const
Implementation-Specific Methods.
These methods are not required of all LinBox Fields} and are included only for this implementation of the archetype.

 FieldArchetype (FieldAbstract *field_ptr, ElementAbstract *elem_ptr, RandIterAbstract *randIter_ptr=0)
template<class Field_qcq>  FieldArchetype (Field_qcq *f)

Protected Member Functions

template<class Field_qcq> void constructor (FieldAbstract *trait, Field_qcq *field_ptr)
template<class Field_qcq> void constructor (void *trait, Field_qcq *field_ptr)
 FieldArchetype ()

Protected Attributes

FieldAbstract_field_ptr
ElementAbstract_elem_ptr
RandIterAbstract_randIter_ptr


Constructor & Destructor Documentation

FieldArchetype const FieldArchetype F  )  [inline]
 

Copy constructor.

Each field class is expected to provide a copy constructor. This is required to allow field objects to be passed by value into functions.

In this archetype implementation, this means copying the field to which F._field_ptr points, the element to which F._elem_ptr points, and the random element generator to which F._randIter_ptr points.

~FieldArchetype void   )  [inline]
 

Destructor.

This destroys the field object, but it does not destroy any field element objects.

In this archetype implementation, destruction is deletion of the field object to which _field_ptr points, the field element to which _elem_ptr points, and the random element generator to which _randIter_ptr points.

FieldArchetype FieldAbstract field_ptr,
ElementAbstract elem_ptr,
RandIterAbstract randIter_ptr = 0
[inline]
 

Constructor. Constructs field from pointer to FieldAbstract} and its encapsulated element and random element generator. Not part of the interface. Creates new copies of field, element, and random iterator generator objects in dynamic memory.

Parameters:
field_ptr pointer to FieldAbstract}.
elem_ptr pointer to ElementAbstract}, which is the encapsulated element of FieldAbstract}.
randIter_ptr pointer to RandIterAbstract}, which is the encapsulated random iterator generator of FieldAbstract}.

FieldArchetype Field_qcq *  f  )  [inline]
 

Constructor. Constructs field from ANYTHING matching the interface using the enveloppe as a FieldAbstract} and its encapsulated element and random element generator if needed.

Parameters:
field_ptr pointer to field matching the interface
elem_ptr pointer to element matching the interface
randIter_ptr pointer to random matching the interface

FieldArchetype  )  [inline, protected]
 

Only authorize inhertied classes to use the empty constructor


Member Function Documentation

FieldArchetype& operator= const FieldArchetype F  )  [inline]
 

Assignment operator.

In this archetype implementation, this means copying the field to which F._field_ptr points, the element to which F._elem_ptr points, and the random element generator to which F._randIter_ptr points.

Parameters:
F  FieldArchetype object.

Element& init Element x,
const integer y = 0
const [inline]
 

Initialization of field element from an integer.

x becomes the image of n under the natural map from the integers to the prime subfield. It is the result obtained from adding n 1's in the field.

This function assumes the output field element x has already been constructed, but that it is not necessarily already initialized. In this archetype implementation, this means the _elem_ptr of x exists, but that it may be the null pointer.

Returns:
reference to x.
Parameters:
x output field element.
n input integer.

integer& convert integer x,
const Element y = 0
const [inline]
 

Conversion of field element to an integer.

The meaning of conversion is specific to each field class. However, if x is in the prime subfield, the integer n returned is such that an init from n will reproduce x. Most often, 0 n < characteristic.

This function assumes the output field element x has already been constructed, but that it is not already initialized. In this archetype, this means the _elem_ptr of y exists, and that it is not the null pointer.

Returns:
reference to x.
Parameters:
n output integer.
x input field element.

Element& assign Element x,
const Element y
const [inline]
 

Assignment of one field element to another.

This function assumes both field elements have already been constructed and initialized.

In this archetype implementation, this means for both x and y, _elem_ptr exists and does not point to null.

Returns:
reference to x
Parameters:
x destination field element.
y source field element.

integer& cardinality integer c  )  const [inline]
 

Cardinality.

Return c, integer representing cardinality of the field. c becomes a non-negative integer for all fields with finite cardinality, and -1 to signify a field of infinite cardinality.

integer& characteristic integer c  )  const [inline]
 

Characteristic.

Return c, integer representing characteristic of the field (the least positive n such that the sum of n copies of x is 0 for all field elements x). c becomes a positive integer for all fields with finite characteristic, and 0 to signify a field of infinite characteristic.

bool areEqual const Element x,
const Element y
const [inline]
 

Equality of two elements.

This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y, _elem_ptr exists and does not point to null.

Returns:
boolean true if equal, false if not.
Parameters:
x field element
y field element

Element& add Element x,
const Element y,
const Element z
const [inline]
 

Addition, x <-- y + z.

This function assumes all the field elements have already been constructed and initialized.

In this implementation, this means for x, y, and z, _elem_ptr exists and does not point to null.

Returns:
reference to x.

Element& sub Element x,
const Element y,
const Element z
const [inline]
 

Subtraction, x <-- y - z.

This function assumes all the field elements have already been constructed and initialized.

In this implementation, this means for x, y, and z, _elem_ptr exists and does not point to null.

Returns:
reference to x.

Element& mul Element x,
const Element y,
const Element z
const [inline]
 

Multiplication, x <-- y * z.

This function assumes all the field elements have already been constructed and initialized.

In this implementation, this means for x, y, and z, _elem_ptr exists and does not point to null.

Returns:
reference to x.

Element& div Element x,
const Element y,
const Element z
const [inline]
 

Division, x <-- y / z.

This function assumes all the field elements have already been constructed and initialized.

In this implementation, this means for x, y, and z, _elem_ptr exists and does not point to null.

Returns:
reference to x.

Element& neg Element x,
const Element y
const [inline]
 

Additive Inverse (Negation), x <-- - y.

This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y _elem_ptr exists and does not point to null.

Returns:
reference to x.

Element& inv Element x,
const Element y
const [inline]
 

Multiplicative Inverse, x <-- 1 / y.

Requires that y is a unit (i.e. nonzero in a field). This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y _elem_ptr exists and does not point to null.

Returns:
reference to x.

Element& axpy Element r,
const Element a,
const Element x,
const Element y
const [inline]
 

Field element AXPY, r <-- a * x + y.

This function assumes all field elements have already been constructed and initialized.

Returns:
reference to r.

bool isZero const Element x  )  const [inline]
 

Zero equality. Test if field element is equal to zero. This function assumes the field element has already been constructed and initialized.

In this implementation, this means the _elem_ptr of x exists and does not point to null.

Returns:
boolean true if equals zero, false if not.
Parameters:
x field element.

bool isOne const Element x  )  const [inline]
 

One equality. Test if field element is equal to one. This function assumes the field element has already been constructed and initialized.

In this implementation, this means the _elem_ptr of x exists and does not point to null.

Returns:
boolean true if equals one, false if not.
Parameters:
x field element.

Element& addin Element x,
const Element y
const [inline]
 

Inplace Addition. x += y This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y _elem_ptr exists and does not point to null.

Returns:
reference to x.
Parameters:
x field element (reference returned).
y field element.

Element& subin Element x,
const Element y
const [inline]
 

Inplace Subtraction. x -= y This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y _elem_ptr exists and does not point to null.

Returns:
reference to x.
Parameters:
x field element (reference returned).
y field element.

Element& mulin Element x,
const Element y
const [inline]
 

Inplace Multiplication. x *= y This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y _elem_ptr exists and does not point to null.

Returns:
reference to x.
Parameters:
x field element (reference returned).
y field element.

Element& divin Element x,
const Element y
const [inline]
 

Inplace Division. x /= y This function assumes both field elements have already been constructed and initialized.

In this implementation, this means for both x and y _elem_ptr exists and does not point to null.

Returns:
reference to x.
Parameters:
x field element (reference returned).
y field element.

Element& negin Element x  )  const [inline]
 

Inplace Additive Inverse (Inplace Negation). x = - x This function assumes the field element has already been constructed and initialized.

In this implementation, this means the _elem_ptr of x exists and does not point to null.

Returns:
reference to x.
Parameters:
x field element (reference returned).

Element& invin Element x  )  const [inline]
 

Inplace Multiplicative Inverse. x = 1 / x This function assumes the field elementhas already been constructed and initialized.

In this implementation, this means the _elem_ptr of x exists and does not point to null.

Returns:
reference to x.
Parameters:
x field element (reference returned).

Element& axpyin Element r,
const Element a,
const Element x
const [inline]
 

Inplace AXPY. r += a * x This function assumes all field elements have already been constructed and initialized.

Returns:
reference to r.
Parameters:
r field element (reference returned).
a field element.
x field element.

std::ostream& write std::ostream &  os  )  const [inline]
 

Print field.

Returns:
output stream to which field is written.
Parameters:
os output stream to which field is written.

std::istream& read std::istream &  is  )  [inline]
 

Read field.

Returns:
input stream from which field is read.
Parameters:
is input stream from which field is read.

std::ostream& write std::ostream &  os,
const Element x
const [inline]
 

Print field element. This function assumes the field element has already been constructed and initialized.

In this implementation, this means for the _elem_ptr for x exists and does not point to null.

Returns:
output stream to which field element is written.
Parameters:
os output stream to which field element is written.
x field element.

std::istream& read std::istream &  is,
Element x
const [inline]
 

Read field element. This function assumes the field element has already been constructed and initialized.

In this implementation, this means for the _elem_ptr for x exists and does not point to null.

Returns:
input stream from which field element is read.
Parameters:
is input stream from which field element is read.
x field element.

void constructor FieldAbstract trait,
Field_qcq *  field_ptr
[inline, protected]
 

Template method for constructing archetype from a derived class of FieldAbstract. This class is needed to help the constructor differentiate between classes derived from FieldAbstract and classes that aren't. Should be called with the same argument to both parameters?

Parameters:
trait pointer to FieldAbstract or class derived from it
field_ptr pointer to class derived from FieldAbstract

void constructor void *  trait,
Field_qcq *  field_ptr
[inline, protected]
 

Template method for constructing archetype from a class not derived from FieldAbstract. This class is needed to help the constructor differentiate between classes derived from FieldAbstract and classes that aren't. Should be called with the same argument to both parameters?

Parameters:
trait pointer to class not derived from FieldAbstract
field_ptr pointer to class not derived from FieldAbstract


Member Data Documentation

FieldAbstract* _field_ptr [mutable, protected]
 

Pointer to FieldAbstract object. Not part of the interface. Included to allow for archetype use three.

ElementAbstract* _elem_ptr [mutable, protected]
 

Pointer to ElementAbstract object. Not part of the interface. Included to allow for archetype use three.

RandIterAbstract* _randIter_ptr [mutable, protected]
 

Pointer to RandIterAbstract object. Not part of the interface. Included to allow for archetype use three.


The documentation for this class was generated from the following file:
Generated on Thu Feb 8 22:33:05 2007 for linbox by doxygen 1.3.4