linbox
Protected Member Functions | Protected Attributes
RingArchetype Class Reference

specification and archetypic instance for the ring interfaceThe RingArchetype and its encapsulated element class contain pointers to the RingAbstract and its encapsulated ring element, respectively. More...

#include <archetype.h>

+ Inheritance diagram for RingArchetype:

Public Types

Common Object Interface for a LinBox Ring.

These methods are required of all LinBox rings.

typedef FieldArchetype::Element Element
 element type.
typedef FieldArchetype::RandIter RandIter
 Random iterator generator type.

Public Member Functions

Object Management
 RingArchetype (const RingArchetype &F)
 Copy constructor.
bool isUnit (const Element &x) const
 Invertibility test.
bool isZeroDivisor (const Element &x) const
 Divisibility of zero test.
 RingArchetype (RingAbstract *ring_ptr, ElementAbstract *elem_ptr, RandIterAbstract *randIter_ptr=0)
 Constructor.
template<class Ring_qcq >
 RingArchetype (Ring_qcq *f)
 Constructor.
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
 Division, x <-- y / z.
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
 Zero equality.
bool isOne (const Element &x) const
 One equality.
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
 Inplace Addition.
Elementsubin (Element &x, const Element &y) const
 Inplace Subtraction.
Elementmulin (Element &x, const Element &y) const
 Inplace Multiplication.
Elementdivin (Element &x, const Element &y) const
 Inplace Division.
Elementnegin (Element &x) const
 Inplace Additive Inverse (Inplace Negation).
Elementinvin (Element &x) const
 Inplace Multiplicative Inverse.
Elementaxpyin (Element &r, const Element &a, const Element &x) const
 Inplace AXPY.
Input/Output Operations
std::ostreamwrite (std::ostream &os) const
 Print field.
std::ostreamwrite (std::ostream &os, const Element &x) const
 Print field element.
std::istreamread (std::istream &is)
 Read field.
std::istreamread (std::istream &is, Element &x) const
 Read field element.

Protected Member Functions

template<class Field_qcq >
void constructor (FieldAbstract *trait, Field_qcq *field_ptr)
 Template method for constructing archetype from a derived class of FieldAbstract.
template<class Field_qcq >
void constructor (void *trait, Field_qcq *field_ptr)
 Template method for constructing archetype from a class not derived from FieldAbstract.

Protected Attributes

FieldAbstract_field_ptr
 Pointer to FieldAbstract object.
ElementAbstract_elem_ptr
 Pointer to ElementAbstract object.
RandIterAbstract_randIter_ptr
 Pointer to RandIterAbstract object.

Object Management

Elementinit (Element &x, const integer &n=0) const
 Initialization of field element from an integer.
integerconvert (integer &n, 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.
Element one
 Copy constructor.
Element zero
 Copy constructor.
Element mone
 Copy constructor.

Detailed Description

specification and archetypic instance for the ring interface

The RingArchetype and its encapsulated element class contain pointers to the RingAbstract and its encapsulated ring element, respectively.

RingAbstract then uses virtual member functions to define operations on its encapsulated ring element. This ring element has no knowledge of the ring properties being used on it which means the ring 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.


Constructor & Destructor Documentation

RingArchetype ( const RingArchetype F) [inline]

Copy constructor.

Constructs RingArchetype object by copying the ring. This is required to allow ring objects to be passed by value into functions.

In this implementation, this means copying the ring to which F._ring_ptr points, the element to which F._elem_ptr points, and the random element generator to which F._randIter_ptr points.

Parameters:
FRingArchetype object.
RingArchetype ( RingAbstract ring_ptr,
ElementAbstract elem_ptr,
RandIterAbstract randIter_ptr = 0 
) [inline]

Constructor.

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

Parameters:
ring_ptrpointer to RingAbstract.
elem_ptrpointer to ElementAbstract, which is the encapsulated element of RingAbstract.
randIter_ptrpointer to RandIterAbstract, which is the encapsulated random iterator generator of RingAbstract.
RingArchetype ( Ring_qcq *  f) [inline]

Constructor.

Constructs ring from ANYTHING matching the interface using the enveloppe as a RingAbstract and its encapsulated element and random element generator if needed.

Parameters:
f

Member Function Documentation

bool isUnit ( const Element x) const [inline]

Invertibility test.

Test if ring element is invertible. This function assumes the ring 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:
xring element.
bool isZeroDivisor ( const Element x) const [inline]

Divisibility of zero test.

Test if ring element is a zero divisor. This function assumes the ring 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 divides zero, false if not.
Parameters:
xring element.
Element& init ( Element x,
const integer n = 0 
) const [inline, inherited]

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:
xoutput field element.
ninput integer.
integer& convert ( integer n,
const Element y = 0 
) const [inline, inherited]

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 \leq n < \mathrm{characteristic}$.

Returns:
reference to n.
Parameters:
noutput integer.
yinput field element.
Element& assign ( Element x,
const Element y 
) const [inline, inherited]

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:
xdestination field element.
ysource field element.
integer& cardinality ( integer c) const [inline, inherited]

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, inherited]

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, inherited]

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:
xfield element
yfield element
Element& add ( Element x,
const Element y,
const Element z 
) const [inline, inherited]

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, inherited]

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, inherited]

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, inherited]

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, inherited]

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, inherited]

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, inherited]

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, inherited]

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:
xfield element.
bool isOne ( const Element x) const [inline, inherited]

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:
xfield element.
Element& addin ( Element x,
const Element y 
) const [inline, inherited]

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:
xfield element (reference returned).
yfield element.
Element& subin ( Element x,
const Element y 
) const [inline, inherited]

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:
xfield element (reference returned).
yfield element.
Element& mulin ( Element x,
const Element y 
) const [inline, inherited]

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:
xfield element (reference returned).
yfield element.
Element& divin ( Element x,
const Element y 
) const [inline, inherited]

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:
xfield element (reference returned).
yfield element.
Element& negin ( Element x) const [inline, inherited]

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:
xfield element (reference returned).
Element& invin ( Element x) const [inline, inherited]

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:
xfield element (reference returned).
Element& axpyin ( Element r,
const Element a,
const Element x 
) const [inline, inherited]

Inplace AXPY.

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

Returns:
reference to r.
Parameters:
rfield element (reference returned).
afield element.
xfield element.
std::ostream& write ( std::ostream os) const [inline, inherited]

Print field.

Returns:
output stream to which field is written.
Parameters:
osoutput stream to which field is written.
std::ostream& write ( std::ostream os,
const Element x 
) const [inline, inherited]

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:
osoutput stream to which field element is written.
xfield element.
std::istream& read ( std::istream is) [inline, inherited]

Read field.

Returns:
input stream from which field is read.
Parameters:
isinput stream from which field is read.
std::istream& read ( std::istream is,
Element x 
) const [inline, inherited]

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:
isinput stream from which field element is read.
xfield element.
void constructor ( FieldAbstract trait,
Field_qcq *  field_ptr 
) [inline, protected, inherited]

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:
traitpointer to FieldAbstract or class derived from it
field_ptrpointer to class derived from FieldAbstract
void constructor ( void *  trait,
Field_qcq *  field_ptr 
) [inline, protected, inherited]

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:
traitpointer to class not derived from FieldAbstract
field_ptrpointer to class not derived from FieldAbstract

Field Documentation

Element one [inherited]

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.

Element zero [inherited]

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.

Element mone [inherited]

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.

FieldAbstract* _field_ptr [mutable, protected, inherited]

Pointer to FieldAbstract object.

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

ElementAbstract* _elem_ptr [mutable, protected, inherited]

Pointer to ElementAbstract object.

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

RandIterAbstract* _randIter_ptr [mutable, protected, inherited]

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: