Struct MonoidalString 

pub struct MonoidalString<C, M: ?Sized> { /* private fields */ }

Creates free-arithmetic constructions based upon free-multiplication of letters of type C that uses a Vec<C> internally

Basic Construction

Given type parameters C and M, the construction goes as follows:

• Internally, each instance contains a list of values of type C
• By default, multiplication is given by concatenating the internal Vec’s of each argument
• Then, with the above as a base, the given type M can modify that operation by applying a multiplication rule to the internal list every time another C is appended to it

With this system, using different M rules and C types, a number of variants can be defined:

• FreeMonoid<C> is created by using the default multiplication with any C
• FreeGroup<C> is made by wrapping it in a FreeInv<C> to allow each C to be inverted and by and modifying M to make inverses cancel
• FreePowMonoid<C,P> is constructed by wrapping each C in a FreePow<C> to raise each element to a symbolic power P and by having M combine any adjacent elements with equal base by adding their exponents

Other impls

In addition to the basic multiplication traits, MonoidalString implements a number of other notable traits depending on the type arguments:

• Div, DivAssign, Inv, etc. These apply whenever M implements
• Index wraps the internal list’s implementation InvMonoidRule<C> to provide a way to invert C elements
• MulAssociative and MulCommutative whenever M implements AssociativeMonoidRule or CommutativeMonoidRule
• PartialEq with any type that implements Borrow<[C]>. This is in order to make it possible to test equality with other structures (like Vec<C> and [C]) that are lists of C’s
• PartialOrd and Ord implement lexicographic ordering
• Extend, FromIterator, and Product all are implemented by applying the multiplication rule to an Iterator of C’s.

A note on IterMut

The method [MonoidalString.iter_mut()] will give an valid iterator over mutable references to each element of the object, but it is of note that because of the nature of some of the MonoidRule’s, the method will reallocate internal storage and iterate through every element, even if dropped.

The reason for this is that if it did not, it would be possible to modify a MonoidalString into an invalid state. Hence, to mitigate this, the iterator must remultiply every element again as it iterates over the references.

Implementations

impl<C, M: ?Sized> MonoidalString<C, M>

pub fn len(&self) -> usize

Returns the number of letters in this monoidal-string

Examples

use maths_traits::algebra::One;
use free_algebra::FreeMonoid;

let x = FreeMonoid::one();
let y = x.clone() * 'a' * 'a';

assert_eq!(x.len(), 0);
assert_eq!(y.len(), 2);

pub fn iter(&self) -> Iter<'_, C>

Produces an iterator over references to the letters in this element

Examples

use maths_traits::algebra::One;
use free_algebra::FreeMonoid;

let x = FreeMonoid::one() * 'a' * 'b' * 'c';
let mut iter = x.iter();

assert_eq!(iter.next(), Some(&'a'));
assert_eq!(iter.next(), Some(&'b'));
assert_eq!(iter.next(), Some(&'c'));
assert_eq!(iter.next(), None);

pub fn iter_mut(&mut self) -> IterMut<'_, C, M>

where M: MonoidRule<C>,

Produces an iterator over mutable references to the letters in this element

Note that the potential for modification does mean that the element needs to be remultiplied as letters are changed, so a potential reallocation of space may occur.

Examples

use free_algebra::{FreePow, FreePowMonoid};

let x = FreePow('a',1) * FreePow('b',1) * FreePow('c',1);
let mut y = x.clone();

for FreePow(c,p) in y.iter_mut() {
    *c = 'a';
}

assert_eq!(x, [FreePow('a',1), FreePow('b',1), FreePow('c',1)]);
assert_eq!(y, [FreePow('a',3)]);

pub fn reverse(self) -> Self

where Self: Product<C>,

Reverses the letters in this element and remultiplies

Examples

use maths_traits::algebra::One;
use free_algebra::FreeMonoid;

let x = FreeMonoid::one() * 'a' * 'b' * 'c';
let y = x.clone().reverse();

assert_eq!(x, ['a', 'b', 'c']);
assert_eq!(y, ['c', 'b', 'a']);

pub fn commutator(self, rhs: Self) -> Self

where Self: MulMonoid + Inv<Output = Self>,

Computes the multiplicative commutator [a,b] = a⁻¹b⁻¹ab

Examples

use free_algebra::FreeGroup;
use free_algebra::FreeInv::*;

let x:FreeGroup<_> = Id('a').into();
let y:FreeGroup<_> = Id('b').into();

assert_eq!(x, [Id('a')]);
assert_eq!(y, [Id('b')]);
assert_eq!(x.commutator(y), [Inv('a'), Inv('b'), Id('a'), Id('b')]);

A property of significance for this product is that when the arguments commute, the output is always 1.

use maths_traits::algebra::One;
use free_algebra::{FreePowMonoid, FreePow};

let x:FreePowMonoid<_,_> = FreePow('a', 2).into();
let y:FreePowMonoid<_,_> = FreePow('a', -24).into();

assert!(x.commutator(y).is_one());

Trait Implementations

impl<C, M: ?Sized> AsRef<[C]> for MonoidalString<C, M>

fn as_ref(&self) -> &[C]

Converts this type into a shared reference of the (usually inferred) input type.

impl<C, M: ?Sized> Borrow<[C]> for MonoidalString<C, M>

fn borrow(&self) -> &[C]

Immutably borrows from an owned value.

impl<C, M: ?Sized> Clone for MonoidalString<C, M>

where C: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, other: &Self)

Performs copy-assignment from source.

impl<C, M: ?Sized> Debug for MonoidalString<C, M>

where C: Debug,

fn fmt(&self, __f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C, M: ?Sized> Default for MonoidalString<C, M>

fn default() -> Self

Returns the “default value” for a type.

impl<C: Display, M: ?Sized> Display for MonoidalString<C, M>

Formats the MonoidalString as a sequence of factors separated by *’s

Examples

use maths_traits::algebra::One;
use free_algebra::FreeMonoid;

let x = FreeMonoid::one() * 'a' * 'b' * 'c';
assert_eq!(format!("{}", x), "a*b*c");

use maths_traits::algebra::*;
use free_algebra::FreeInv::*;

let y = Id('a') * Inv('b') * Inv('a') * Id('c');
assert_eq!(format!("{}", y), "a*b⁻¹*a⁻¹*c");

Note that if the “alternate” flag # is used, then the *’s will be dropped.

use maths_traits::algebra::One;
use free_algebra::FreeMonoid;

let x = FreeMonoid::one() * 'a' * 'b' * 'c';
assert_eq!(format!("{:#}", x), "abc");

use maths_traits::algebra::*;
use free_algebra::FreeInv::*;

let y = Id('a') * Inv('b') * Inv('a') * Id('c');
assert_eq!(format!("{:#}", y), "ab⁻¹a⁻¹c");

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Eq> Div<MonoidalString<FreeInv<T>, InvRule>> for FreeInv<T>

type Output = MonoidalString<FreeInv<T>, InvRule>

The resulting type after applying the / operator.

fn div(self, rhs: FreeGroup<T>) -> FreeGroup<T>

Performs the / operation.

impl<C: Eq, P: Add<Output = P> + Neg<Output = P> + Zero> Div<MonoidalString<FreePow<C, P>, PowRule>> for FreePow<C, P>

type Output = MonoidalString<FreePow<C, P>, PowRule>

The resulting type after applying the / operator.

fn div(self, rhs: FreePowMonoid<C, P>) -> FreePowMonoid<C, P>

Performs the / operation.

impl<'a, RHS, C, M> Div<RHS> for &'a MonoidalString<C, M>

where M: ?Sized, MonoidalString<C, M>: Clone + Div<RHS>,

type Output = <MonoidalString<C, M> as Div<RHS>>::Output

The resulting type after applying the / operator.

fn div(self, rhs: RHS) -> Self::Output

Performs the / operation.

impl<RHS, C, M> Div<RHS> for MonoidalString<C, M>

where M: ?Sized, Self: DivAssign<RHS>,

type Output = MonoidalString<C, M>

The resulting type after applying the / operator.

fn div(self, rhs: RHS) -> Self

Performs the / operation.

impl<'a, C, M> DivAssign<&'a C> for MonoidalString<C, M>

where M: ?Sized, Self: DivAssign<C>, C: Clone,

fn div_assign(&mut self, rhs: &'a C)

Performs the /= operation.

impl<'a, C, M> DivAssign<&'a MonoidalString<C, M>> for MonoidalString<C, M>

where M: ?Sized, Self: DivAssign<Self> + Clone,

fn div_assign(&mut self, rhs: &'a Self)

Performs the /= operation.

impl<C, M: InvMonoidRule<C> + ?Sized> DivAssign<C> for MonoidalString<C, M>

fn div_assign(&mut self, rhs: C)

Performs the /= operation.

impl<C, M: InvMonoidRule<C> + ?Sized> DivAssign for MonoidalString<C, M>

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl<C, M: MonoidRule<C> + ?Sized> Extend<C> for MonoidalString<C, M>

fn extend<I: IntoIterator<Item = C>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<C, M: ?Sized> From<C> for MonoidalString<C, M>

fn from(c: C) -> Self

Converts to this type from the input type.

impl<C, M: ?Sized, T> FromIterator<T> for MonoidalString<C, M>

where Self: Product<T>,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<C, M: ?Sized> Hash for MonoidalString<C, M>

where C: Hash,

fn hash<__HCM>(&self, __state: &mut __HCM)

where __HCM: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<C, M: ?Sized, I> Index<I> for MonoidalString<C, M>

where Vec<C>: Index<I>,

type Output = <Vec<C> as Index<I>>::Output

The returned type after indexing.

fn index(&self, i: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<C, M: ?Sized> IntoIterator for MonoidalString<C, M>

type Item = C

The type of the elements being iterated over.

type IntoIter = <Vec<C> as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<C>

Creates an iterator from a value.

impl<'a, C, M: InvMonoidRule<C> + ?Sized> Inv for &'a MonoidalString<C, M>

where MonoidalString<C, M>: Clone,

type Output = MonoidalString<C, M>

The result after applying the operator.

fn inv(self) -> Self::Output

Returns the multiplicative inverse of self.

impl<C, M: InvMonoidRule<C> + ?Sized> Inv for MonoidalString<C, M>

type Output = MonoidalString<C, M>

The result after applying the operator.

fn inv(self) -> Self

Returns the multiplicative inverse of self.

impl<T: Eq> Mul<MonoidalString<FreeInv<T>, InvRule>> for FreeInv<T>

type Output = MonoidalString<FreeInv<T>, InvRule>

The resulting type after applying the * operator.

fn mul(self, rhs: FreeGroup<T>) -> FreeGroup<T>

Performs the * operation.

impl<C: Eq, P: Add<Output = P>> Mul<MonoidalString<FreePow<C, P>, PowRule>> for FreePow<C, P>

type Output = MonoidalString<FreePow<C, P>, PowRule>

The resulting type after applying the * operator.

fn mul(self, rhs: FreePowMonoid<C, P>) -> FreePowMonoid<C, P>

Performs the * operation.

impl<'a, RHS, C, M> Mul<RHS> for &'a MonoidalString<C, M>

where M: ?Sized, MonoidalString<C, M>: Clone + Mul<RHS>,

type Output = <MonoidalString<C, M> as Mul<RHS>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: RHS) -> Self::Output

Performs the * operation.

impl<RHS, C, M> Mul<RHS> for MonoidalString<C, M>

where M: ?Sized, Self: MulAssign<RHS>,

type Output = MonoidalString<C, M>

The resulting type after applying the * operator.

fn mul(self, rhs: RHS) -> Self

Performs the * operation.

impl<'a, C, M> MulAssign<&'a C> for MonoidalString<C, M>

where M: ?Sized, Self: MulAssign<C>, C: Clone,

fn mul_assign(&mut self, rhs: &'a C)

Performs the *= operation.

impl<'a, C, M> MulAssign<&'a MonoidalString<C, M>> for MonoidalString<C, M>

where M: ?Sized, Self: MulAssign<Self> + Clone,

fn mul_assign(&mut self, rhs: &'a Self)

Performs the *= operation.

impl<C, M: MonoidRule<C> + ?Sized> MulAssign<C> for MonoidalString<C, M>

fn mul_assign(&mut self, rhs: C)

Performs the *= operation.

impl<C, M: MonoidRule<C> + ?Sized> MulAssign for MonoidalString<C, M>

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl<C, M: MonoidRule<C> + ?Sized> One for MonoidalString<C, M>

fn one() -> Self

Returns the multiplicative identity element of Self, 1.

fn is_one(&self) -> bool

Returns true if self is equal to the multiplicative identity.

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

impl<C: Ord, M: ?Sized> Ord for MonoidalString<C, M>

fn cmp(&self, rhs: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<C: PartialEq, M: ?Sized, V: Borrow<[C]>> PartialEq<V> for MonoidalString<C, M>

fn eq(&self, rhs: &V) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, rhs: &V) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C: PartialOrd, M: ?Sized> PartialOrd for MonoidalString<C, M>

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, rhs: &Self) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, rhs: &Self) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, rhs: &Self) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, rhs: &Self) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Z: IntegerSubset, C: Clone, M: MonoidRule<C> + ?Sized> Pow<Z> for MonoidalString<C, M>

where Self: PowMarker<Z> + MulAssociative,

type Output = MonoidalString<C, M>

The result after applying the operator.

default fn pow(self, p: Z) -> Self

Returns self to the power rhs.

impl<Z: IntegerSubset, C: Clone, M: InvMonoidRule<C> + ?Sized> Pow<Z> for MonoidalString<C, M>

where Self: PowMarker<Z> + MulAssociative,

fn pow(self, p: Z) -> Self

Returns self to the power rhs.

type Output

The result after applying the operator.

impl<C, M: MonoidRule<C> + ?Sized> Product<C> for MonoidalString<C, M>

fn product<I: Iterator<Item = C>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by multiplying the items.

impl<C, M: MonoidRule<C> + ?Sized> Product for MonoidalString<C, M>

fn product<I: Iterator<Item = Self>>(iter: I) -> Self

Takes an iterator and generates Self from the elements by multiplying the items.

impl<C: Eq, M: ?Sized> Eq for MonoidalString<C, M>

impl<C, M: AssociativeMonoidRule<C> + ?Sized> MulAssociative for MonoidalString<C, M>

impl<C, M: CommutativeMonoidRule<C> + ?Sized> MulCommutative for MonoidalString<C, M>