Struct MeterTerminal 

pub struct MeterTerminal { /* private fields */ }

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

Implementations

impl MeterTerminal

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

A span of numerator/denominator, undivided, weighing one.

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 set_summed_numerator(&mut self, summed: bool)

Says whether the numerators are written summed.

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 set_weight(&mut self, weight: FloatType)

Sets how strongly this span is felt.

A span with parts shares the weight out among them in proportion to how long each is, as music21 does: the four quarters of a bar weighing one take a quarter each, where {3/4+1/4} takes three quarters and a quarter.

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

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

pub fn parts_mut(&mut self) -> &mut Vec<MeterTerminal>

The same, to be changed.

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 partition_by_parts(&mut self, parts: &[&str]) -> Result<()>

Divides this span into the parts named, as ["2/8", "3/8"].

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

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

Divides this span into count parts, the way music21 divides it.

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 partition_by_list( &mut self, numerators: &[UnsignedIntegerType], ) -> Result<()>

Divides this span by a list of numerators, as [3, 1] for {3/4+1/4}.

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 subdivide(&mut self, count: usize) -> Result<()>

Divides this span into count parts and leaves those parts divided as they were: music21’s MeterTerminal.subdivide.

pub fn subdivide_partitions_equal( &mut self, divisions: Option<usize>, ) -> Result<()>

Divides every part of this span again, the way music21 divides it when nobody has said how: music21’s subdividePartitionsEqual.

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 subdivide_nested_hierarchy( &mut self, depth: usize, first_partition_form: Option<UnsignedIntegerType>, normalize_denominators: bool, ) -> Result<()>

Nests this span down to a depth: music21’s subdivideNestedHierarchy.

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_rs::meter::MeterTerminal;

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

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

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_rs::meter::MeterTerminal;

let beats = MeterTerminal::from_partition_string("3/8+2/8")?;
let mut bar = MeterTerminal::new(5, 8)?;
bar.subdivide_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 set_level_weight( &mut self, level: usize, weights: &[FloatType], ) -> Result<()>

Weighs the terminals of a level, looping the weights given over them: the write half of music21’s setAccentWeight.

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.

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

This span divided into the one span another sequence is: music21’s subdivideByOther. The other becomes the only part of the answer, so what the other was divided into is a level further down; a span of another length is an error, since a division cannot relength the bar.

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

Divides this span the way another sequence is divided: music21’s partitionByOtherMeterSequence. The two have to be written over the same ratio, and this span keeps the weight it 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 PartialEq for MeterTerminal

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.

impl StructuralPartialEq for MeterTerminal