Struct Sieve 

pub struct Sieve { /* private fields */ }

A parsed Xenakis sieve.

use music21_rs::Sieve;

// Every third semitone: a cycle of minor thirds.
let sieve = Sieve::parse("3@0")?;
assert_eq!(sieve.period(), 3);
assert_eq!(sieve.interval_widths()?, [3]);

// The major scale, as Xenakis would write it.
let major = Sieve::parse("(-3@2 & 4) | (-3@1 & 4@1) | (3@2 & 4@2) | (-3 & 4@3)")?;
assert_eq!(major.interval_widths()?, [2, 2, 1, 2, 2, 2, 1]);

Implementations

impl Sieve

pub fn parse(expression: &str) -> Result<Self>

Parses a sieve expression such as "3@0|4@1".

A bare modulus means a shift of zero, so "5" is "5@0". Whitespace is ignored, {} and () both group, and & binds tighter than ^, which binds tighter than | — matching music21, where 3@0|4@0&6@0 parses as 3@0|{4@0&6@0}.

pub fn contains(&self, z: IntegerType) -> bool

Returns whether an integer is in the sieve.

pub fn period(&self) -> UnsignedIntegerType

Returns the period: the least common multiple of every modulus.

The sieve’s membership pattern repeats with this length.

pub fn segment(&self, low: IntegerType, high: IntegerType) -> Vec<IntegerType>

Returns the members of the sieve in low..=high.

pub fn interval_widths(&self) -> Result<Vec<IntegerType>>

Returns the widths between consecutive members of one period.

This is music21’s PitchSieve.getIntervalSequence, in semitones: the sieve is evaluated over 0..=period and the consecutive differences taken. A sieve with fewer than two members in that window has no widths and is an error, exactly as music21 raises for 3@1.

pub fn shifted(&self, n: IntegerType) -> Self

The same sieve with every residual’s shift moved on by n.

This is the n music21 takes beside a range when it reads a segment.

pub fn segment_binary( &self, low: IntegerType, high: IntegerType, ) -> Vec<IntegerType>

The sieve over low..=high as ones and noughts, one per integer in the range rather than one per member.

music21’s segmentFormat='binary'.

pub fn segment_widths( &self, low: IntegerType, high: IntegerType, ) -> Vec<IntegerType>

The widths between consecutive members over low..=high, one shorter than the segment itself.

music21’s segmentFormat='width'. Unlike Sieve::interval_widths this reads whatever range it is given rather than one period, so it says nothing about where the pattern repeats.

pub fn segment_unit( &self, low: IntegerType, high: IntegerType, ) -> Vec<FloatType>

Each member’s place in low..=high as a fraction of the way across it, so the range’s own ends are nought and one.

music21’s segmentFormat='unit'. A range with no width answers nought for every member, as music21 does rather than dividing by it.

pub fn collect( &self, n: IntegerType, z_minimum: IntegerType, length: usize, ) -> Result<Vec<IntegerType>>

The first length members at or above z_minimum, reading the sieve shifted on by n.

music21’s collect, which walks upward a hundred integers at a time until it has enough. The walk is bounded, so a sieve with too few members to fill the length is an error rather than a loop that never ends.

pub fn intersection(&self, other: &Self) -> Self

The members of both sieves, written the way music21 writes a combined sieve: each side in braces around the operator.

Note the order. music21’s a & b answers {b}&{a}, so the facade calls this the other way round; the crate keeps the order a reader would expect.

pub fn union(&self, other: &Self) -> Self

The members of either sieve. See Sieve::intersection for the bracketing and the order.

pub fn symmetric_difference(&self, other: &Self) -> Self

The members of one sieve or the other but not both. See Sieve::intersection for the bracketing and the order.

Trait Implementations

impl Clone for Sieve

fn clone(&self) -> Sieve

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Sieve

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

Formats the value using the given formatter.

impl Display for Sieve

Writes the sieve as music21 writes it: the expression it was given, with each residual normalized to modulus@shift and the groups it was written with kept.

use music21_rs::Sieve;

assert_eq!(Sieve::parse("3@11")?.to_string(), "3@2");
assert_eq!(Sieve::parse("(5|2)&4&8")?.to_string(), "{5@0|2@0}&4@0&8@0");

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

Formats the value using the given formatter.

impl Eq for Sieve

impl PartialEq for Sieve

fn eq(&self, other: &Sieve) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Sieve