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)


A set of “good” optimised routines in native Rust

A collection of tables supporting optimised maths


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)


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.


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)