Struct MeterTerminal 

pub struct MeterTerminal { /* private fields */ }

One span of a bar: a ratio, and how strongly it is felt.

A span is a value: every method that divides or weighs it hands back a new span and leaves this one as it was, as music21’s immutable MeterTerminal and MeterSequence do.

Implementations

impl MeterTerminal

pub fn new( numerator: UnsignedIntegerType, denominator: UnsignedIntegerType, ) -> Result<Self>

A span of numerator/denominator, undivided, weighing one. A numerator of nought is a span of no length, which is what music21’s MeterTerminal() given nothing is.

pub fn from_ratio_string(ratio: &str) -> Result<Self>

The same, read from "3/8".

pub fn from_partition_string(written: &str) -> Result<Self>

A span written as parts joined by +, each part a ratio: music21’s MeterSequence('2/4+2/4'), which is a bar of four quarters divided in two. A part written as a bare numerator takes the denominator of the next part that gives one, so 3+2/8 is three eighths and two eighths.

The span itself is written over the denominator its parts share, or the least one they all divide into: 3/4+2/4+1/8 is 11/8.

A span written with a bare numerator is one whose numerators were summed, and says so: Self::summed_numerator.

pub fn summed_numerator(&self) -> bool

Whether this span was written with its numerators summed over one denominator, as 3+2/8 is and 3/8+2/8 is not: music21’s summedNumerator. The two are the same parts; what differs is how the meter is printed, and that a bar written this way is beamed in the parts it was written in.

pub fn with_summed_numerator(&self, summed: bool) -> Self

The same span, saying whether its numerators are written summed: music21’s modify(summedNumerator=...).

pub fn sequence( numerator: UnsignedIntegerType, denominator: UnsignedIntegerType, parts: Vec<Self>, ) -> Result<Self>

A span of numerator/denominator divided into parts, taken as given: music21’s makeSequence, which does not check that the parts come to the ratio. No parts at all is an undivided span.

pub fn with_weight(&self, weight: FloatType) -> Self

The same span with a different weight: music21’s MeterTerminal.modify(weight=...) and MeterSequence.withWeight.

pub fn from_parts_given(parts: Vec<Self>) -> Result<Self>

A span made of the parts given, which is what they come to: music21’s MeterSequence given a list of spans. The span is written over the denominator its parts share, or the least one they all divide into.

One part alone is that part, undivided, as music21 reads '4/4'.

pub fn numerator(&self) -> UnsignedIntegerType

The numerator this span is written with.

pub fn denominator(&self) -> UnsignedIntegerType

The denominator this span is written with.

pub fn quarter_length(&self) -> FloatType

How long this span is in quarter notes.

pub fn offset_to_address(&self, offset: FloatType) -> Result<Vec<usize>>

Every index it takes to reach the terminal sounding at an offset: music21’s offsetToAddress. Its length is how deep that terminal lies, so a span nothing divides answers one index.

pub fn weight(&self) -> FloatType

How strongly this span is felt: music21’s weight.

A span with parts weighs what its parts weigh together, so weight is kept on the terminals and read back up the tree.

pub fn parts(&self) -> &[MeterTerminal]

What this span is divided into. Empty where it is a leaf.

pub fn set_index(&self, index: usize, value: Self) -> Result<Self>

The same span with the part at index replaced by value, which has to be written over the same ratio: music21’s setIndex.

pub fn len(&self) -> usize

How many parts this span has at its top level, music21’s len.

pub fn is_empty(&self) -> bool

Whether this span is divided at all.

pub fn depth(&self) -> usize

How many levels of division this span has: music21’s depth. A leaf is nought.

pub fn flattened(&self) -> Vec<MeterTerminal>

Every leaf of this span, in order, which is what flatten is made of: music21’s _getFlatList.

pub fn flatten(&self) -> Result<Self>

This span divided into all of its leaves at once, however deeply each was divided: music21’s flatten.

pub fn flat_weights(&self) -> Vec<FloatType>

What each leaf of this span weighs: music21’s flatWeight.

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

Whether another span is written over the same ratio: music21’s ratioEqual. Two spans may weigh differently and be divided differently and still be the same meter.

pub fn partitioned_by_parts(&self, parts: &[&str]) -> Result<Self>

This span divided into the parts named, as ["2/8", "3/8"]: music21’s partitionedByList given ratios.

The parts must come to what this span already is; a partition that lengthened or shortened the bar would not be one.

pub fn partitioned_by_count( &self, count: usize, load_default: bool, ) -> Result<Self>

This span divided into count parts, the way music21 divides it: music21’s partitionedByCount.

The first of Self::partition_options with that many parts wins. A count nothing divides into leaves the first option standing, which is music21’s loadDefault.

pub fn partitioned_by_list( &self, numerators: &[UnsignedIntegerType], ) -> Result<Self>

This span divided by a list of numerators, as [3, 1] for {3/4+1/4}: music21’s partitionedByList.

music21 reads the list against this span’s own denominator where the numerators come to its numerator, and against a finer one where they come to a multiple of it — [1, 1, 1, 1] of a 2/4 bar is four eighths, not four quarters.

Failing both, it looks for a division of its own whose numerators are the ones asked for, which is how [1, 1] of a 4/4 bar comes out as two halves and [1] as a whole.

pub fn subdivided_partitions_equal( &self, divisions: Option<usize>, ) -> Result<Self>

This span with every part divided again, the way music21 divides it when nobody has said how: music21’s subdividedPartitionsEqual.

divisions says how many parts each part becomes; None asks for the division each part conventionally takes — two for a part written in a binary numerator, three for one written in three, and threes for the compound numerators. A part nothing divides into is an error, which is what music21 raises and what a meter written in notes shorter than a 128th is forgiven.

pub fn subdivided_nested_hierarchy( &self, depth: usize, first_partition_form: Option<UnsignedIntegerType>, normalize_denominators: bool, ) -> Result<Self>

This span nested down to a depth: music21’s subdividedNestedHierarchy.

The whole span becomes one part, that part is divided by two, by three or by its own numerator, and every division after that is by two or three again — so a bar of four quarters at depth two is two halves of two quarters each. Whatever partitions the span had are gone.

normalize_denominators keeps the parts of a level written over one denominator: where they differ, the longer ones are divided again until they agree, which is why six eighths come out as sixteenths.

use music21::meter::MeterTerminal;

let bar = MeterTerminal::new(4, 4)?.subdivided_nested_hierarchy(2, None, true)?;
assert_eq!(bar.to_string(), "{{{1/4+1/4}+{1/4+1/4}}}");

pub fn subdivided_nested_hierarchy_by( &self, depth: usize, first_partition_form: &Self, normalize_denominators: bool, ) -> Result<Self>

The same, with the first division taken from another sequence rather than from a count: music21’s subdivideNestedHierarchy handed a MeterSequence as its firstPartitionForm.

This is how a bar whose beats are not all one length is nested — the five eighths of 3+2/8 divide first into a three and a two, which no count can say. The form has to come to the same length as this span.

use music21::meter::MeterTerminal;

let beats = MeterTerminal::from_partition_string("3/8+2/8")?;
let bar = MeterTerminal::new(5, 8)?.subdivided_nested_hierarchy_by(2, &beats, true)?;
assert_eq!(bar.to_string(), "{{{1/8+1/8+1/8}+{1/8+1/8}}}");

pub fn partition_options(&self) -> Vec<Vec<String>>

The ways music21 conventionally divides this meter, in the order it prefers them: music21’s getPartitionOptions.

pub fn level_list(&self, level: usize, flat: bool) -> Vec<MeterTerminal>

The terminals at one level of this sequence: music21’s getLevelList.

A part that is not divided is taken as it stands. A part that is gets recursed into while there are levels left to descend, and at the level asked for is either kept whole or, when flat, flattened into a single terminal carrying that part’s own weight.

pub fn level(&self, level: usize, flat: bool) -> Result<Self>

One level of this sequence as a sequence of its own: music21’s getLevel.

pub fn level_span(&self, level: usize) -> Vec<(FloatType, FloatType)>

Where each terminal of a level starts and ends, in quarter lengths from the start of this span: music21’s getLevelSpan.

pub fn offset_to_depth( &self, offset: FloatType, align: OffsetAlign, ) -> Result<usize>

How many levels of this sequence start at an offset: music21’s offsetToDepth.

A level counts when one of its parts begins where the offset does. Under OffsetAlign::Quantize the offset is first moved back to the start of the finest part holding it, so an offset inside a part still counts the levels that part begins.

pub fn with_level_weight( &self, level: usize, weights: &[FloatType], ) -> Result<Self>

This span with the terminals of a level weighed, looping the weights given over them: music21’s withLevelWeight.

A level with no terminals, or no weights to give it, is an error rather than a silent nothing.

pub fn is_uniform_partition(&self, depth: usize) -> bool

Whether every part of a level is the same ratio: music21’s isUniformPartition.

pub fn partition_display(&self) -> String

The parts written out without the braces around them: music21’s partitionDisplay, so a bar of 2/4+6/8 reads as it was written.

pub fn subdivide_by_count(&self, count: usize) -> Result<Self>

This span divided into count parts, as a new sequence: music21’s subdivideByCount. The weight of this span goes with it, and a count it cannot be divided into is an error.

pub fn partitioned_by_other(&self, other: &Self) -> Result<Self>

This span divided the way another sequence is divided: music21’s partitionedByOtherMeterSequence. The two have to be written over the same ratio, and the answer keeps the weight this span had.

pub fn level_weight(&self, level: usize) -> Vec<FloatType>

What each terminal of a level weighs: music21’s getLevelWeight.

pub fn subdivide_by_list( &self, numerators: &[UnsignedIntegerType], ) -> Result<Self>

This span divided by a list of numerators, as a new sequence: music21’s subdivideByList.

pub fn offset_to_index(&self, offset: FloatType) -> Result<usize>

Which part an offset in quarter notes falls in: music21’s offsetToIndex. An offset outside the span is an error.

pub fn offset_to_span( &self, offset: FloatType, permit_meter_modulus: bool, ) -> Result<(FloatType, FloatType)>

Where the part an offset falls in begins and ends: music21’s offsetToSpan. With permit_meter_modulus an offset past the end of the span is read within it.

pub fn offset_to_weight(&self, offset: FloatType) -> Result<FloatType>

The weight of the part an offset falls in: music21’s offsetToWeight.

pub fn partition_string(&self) -> String

How this span is written: 3/4 undivided, {1/4+1/4+1/4} divided.

Trait Implementations

impl Clone for MeterTerminal

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MeterTerminal

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MeterTerminal

Available on crate feature serde only.

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for MeterTerminal

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

Formats the value using the given formatter.

impl Hash for MeterTerminal

fn hash<H: Hasher>(&self, state: &mut H)

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 PartialEq for MeterTerminal

Two spans are equal when they are written over the same ratio, written the same way and divided into equal parts; a span nothing divides weighs the same as well. A span with parts weighs what they weigh, so its own weight is not compared twice.

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for MeterTerminal

Available on crate feature serde only.

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.