Struct free_algebra::monoid::MonoidalString

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

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.

Methods

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);

Important traits for IterMut<'a, C, M>

impl<'a, C, M: MonoidRule<C> + ?Sized> Iterator for IterMut<'a, C, M> type Item = &'a mut C;

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]

Performs the conversion.

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

fn from(c: C) -> Self

Performs the conversion.

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.

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

type Item = C

The type of the elements being iterated over.

type IntoIter = IntoIter<C>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<C>

Creates an iterator from a value.

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

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

fn default() -> Self

Returns the "default value" for a type.

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

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<C: PartialOrd, M: ?Sized> PartialOrd<MonoidalString<C, M>> 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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

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<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<T: Eq> Div<MonoidalString<FreeInv<T>, InvRule>> for FreeInv<T>

type Output = FreeGroup<T>

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 = FreePowMonoid<C, P>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<RHS, C, M> Div<RHS> for MonoidalString<C, M> where
    M: ?Sized,
    Self: DivAssign<RHS>, 

type Output = Self

The resulting type after applying the / operator.

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

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<T: Eq> Mul<MonoidalString<FreeInv<T>, InvRule>> for FreeInv<T>

type Output = FreeGroup<T>

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 = FreePowMonoid<C, P>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<RHS, C, M> Mul<RHS> for MonoidalString<C, M> where
    M: ?Sized,
    Self: MulAssign<RHS>, 

type Output = Self

The resulting type after applying the * operator.

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

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<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<MonoidalString<C, M>> for MonoidalString<C, M>

fn mul_assign(&mut self, 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>,
    Self: Clone, 

fn mul_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<MonoidalString<C, M>> for MonoidalString<C, M>

fn div_assign(&mut self, 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>,
    Self: Clone, 

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

Performs the /= operation.

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

Feeds a slice of this type into the given [Hasher].

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: MonoidRule<C> + ?Sized> Product<C> for MonoidalString<C, M>

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

Method which takes an iterator and generates Self from the elements by multiplying the items.

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

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

Method which takes an iterator and generates Self from the elements by multiplying the items.

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

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

Immutably borrows from an owned value.

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, M: InvMonoidRule<C> + ?Sized> Inv for MonoidalString<C, M>

type Output = Self

The result after applying the operator.

fn inv(self) -> Self

Returns the multiplicative inverse of self.

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<Z: IntegerSubset, C: Clone, M: MonoidRule<C> + ?Sized> Pow<Z> for MonoidalString<C, M> where
    Self: PowMarker<Z> + MulAssociative, 

type Output = Self

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: AssociativeMonoidRule<C> + ?Sized> MulAssociative for MonoidalString<C, M>

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