# Crate guff[−][src]

Expand description

# Grand Unified Finite Field library*

Implements GF(2x) for various “natural” sizes such as 28, 216 and 232.

# Basic Use: doing maths on elements of a particular field

The general outline for using this library is:

• decide what “class” of field you want to use (GF(28), GF(216), …);

• decide if you want to use one of the optimised adaptations or are happy with the default, generic code;

• create a new field object (we can call `f`) of that class with your chosen field polynomial (aka “irreducible polynomial”) by calling the appropriate constructor;

• use that object to do maths in that field: eg, `result = f.mul(a,b)`

Example of using the default generic code:

```use guff::{GaloisField, F4, new_gf4};

// Create a GF(2**4) field from a struct
// * `19` is the field's irreducible polynomial
// * `3` is the same value with bit 0x10 removed
let f = F4 { full : 19, compact : 3 };

assert_eq!(f.pow(5,3), f.mul(5,f.mul(5,5)) );

// The same, but using a constructor as syntactic sugar
let f2 = new_gf4(19, 3);

assert_eq!(f2.pow(5,3), f2.mul(5, f2.mul(5,5)) );
assert_eq!(f.pow(5,3), f2.pow(5,3));
```

The `guff::good` module provides a set of reasonably good implementations that in most cases should be better than the generic implementation. Example of use:

```use guff::GaloisField;
use guff::good::{F4_0x13, new_gf4_0x13};

let f = new_gf4_0x13();

assert_eq!(f.pow(5,3), f.mul(5, f.mul(5,5)) );
```

# Vector Operations

Many applications involving Galois Fields involve working with vectors of field elements instead of single elements. Various primitive methods are implemented:

• sum of vector elements
• sum of two equal-length vectors
• cross product (pairwise multiplication of elements)
• dot product (sum of cross-product values)
• scaling a vector by a constant
• fused multiply add (scale and sum by a pair of constants across vector)

These are all implemented using slices of the appropriate ElementStore type. Where necessary, if a vector (slice) type is to be returned, it must be handled by the user by passing in a mutable reference. Also note that some operations (such as scaling a vector) are done in-place, so if the previous values need to be saved, they should be copied first.

See the GaloisField documentation for a full list of method signatures (prefixed with `vec_`).

# Crate Name

* The crate name is deliberately hyperbolic:

Noun guff - unacceptable behavior (especially ludicrously false statements)

## Modules

A set of “good” optimised routines in native Rust

A collection of tables supporting optimised maths

## Structs

A type implementing (default) maths in GF(24)

A type implementing (default) maths in GF(28)

A type implementing (default) maths in GF(216)

A type implementing (default) maths in GF(232)

## Traits

A typing trait meant to map to a primitive unsigned integer type such as u8, u16 or u32.

Collection of methods needed to implement maths in GF(2x). Provides (slow) default implementations that can be overriden by optimised versions.

## Functions

Create a new GF(24) field with a supplied field polynomial (using the default implementation)

Create a new GF(28) field with a supplied field polynomial (using the default implementation)

Create a new GF(216) field with a supplied field polynomial (using the default implementation)

Create a new GF(232) field with a supplied field polynomial (using the default implementation)