Struct TimeSignature 

pub struct TimeSignature { /* private fields */ }

A time signature, such as 4/4 or 6/8.

use music21_rs::TimeSignature;

let six_eight = TimeSignature::from_ratio_string("6/8")?;
assert_eq!(six_eight.beat_count(), 2);
assert_eq!(six_eight.beat_quarter_length()?, 1.5);
assert_eq!(six_eight.classification(), "Compound Duple");

Not Copy, Eq or Hash: a meter is about to carry the partitions it is felt in, and those weigh their parts in floats.

Implementations

impl TimeSignature

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

Creates a time signature from a numerator and denominator.

Both must be non-zero. The denominator need not be a power of two — music21 accepts irrational meters such as 4/3, and so does this.

pub fn display_sequence(&self) -> &MeterTerminal

How the bar is written, before anything divides it: music21’s displaySequence. A meter written additively as "3/8+2/8" is two parts here, and that is what makes the beats fall where they are written rather than where the numerator alone would put them.

pub fn beat_sequence(&self) -> &MeterTerminal

How the bar is counted: music21’s beatSequence, one part per beat, each divided again into what the beat is felt in.

pub fn beam_sequence(&self) -> &MeterTerminal

How the bar is beamed: music21’s beamSequence, the groups a run of short notes is written in.

pub fn accent_sequence(&self) -> &MeterTerminal

How the bar is weighted: music21’s accentSequence, one part per accent partition, each carrying the weight Self::accent_weights gives it.

pub fn favors_compound(&self) -> bool

Whether the bar is felt in compound beats: music21’s favorCompound, which is what counts a 6/8 in two and a slow 6/8 in six.

pub fn beat_sequence_mut(&mut self) -> &mut MeterTerminal

The beats, to partition: music21 divides a meter by reaching into the sequence it carries, as ts.beatSequence.partition(2).

pub fn beam_sequence_mut(&mut self) -> &mut MeterTerminal

The beams, to partition.

pub fn accent_sequence_mut(&mut self) -> &mut MeterTerminal

The accent partitions, to partition or to weigh.

pub fn display_sequence_mut(&mut self) -> &mut MeterTerminal

How the bar is written, to partition.

pub fn set_display(&mut self, value: &str) -> Result<()>

Writes the bar a different way without changing what it counts: music21’s setDisplay.

A bar of 3/4 set to display as "2/8+2/8+2/8" is still three quarters long and still counted in three; what changes is how it is written. The value has to come to the same length as the bar, since a bar cannot be written as something it is not.

pub fn divide_beats(&mut self, count: UnsignedIntegerType) -> Result<()>

Divides the beats into count parts, leaving each part undivided: the divisions a meter is built with.

This is not Self::set_beat_count: music21 partitions the beats here and stops, so TimeSignature("6/8", 2) is {3/8+3/8} where counting a 6/8 in two gives {{1/8+1/8+1/8}+{1/8+1/8+1/8}}.

pub fn set_beat_count(&mut self, count: UnsignedIntegerType) -> Result<()>

Counts the bar in a different number of beats: music21’s settable beatCount.

The beats are repartitioned and each divided again, so a 6/8 counted in six is six eighths rather than two dotted quarters. A count the bar cannot be divided into is an error.

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

Parses a "numerator/denominator" string such as "6/8".

music21 writes more than a bare ratio here. A word before the ratio says how the beat is felt — "slow 6/8" is counted in six and "fast 6/8" in two — and a meter can be written additively, as "3/8+2/8" or "3+2/8", where a numerator with no denominator of its own takes the next one written. What the parts add up to is the meter this returns; how they are grouped is Self::parts.

pub fn parts( ratio: &str, ) -> Result<Vec<(UnsignedIntegerType, UnsignedIntegerType)>>

The (numerator, denominator) pairs a meter string is written in, in the order written: music21’s slashMixedToFraction.

"3/8+2/8" is two parts and "6/8" is one. A part written as a bare numerator takes the denominator of the next part that has one, which is how "3+2/8" is two eighth-note parts; a string whose last part says no denominator at all says nothing about how it is measured, and is refused.

pub fn common() -> Self

Returns common time, 4/4.

pub fn cut() -> Self

Returns cut time, 2/2.

pub fn numerator(&self) -> UnsignedIntegerType

Returns the numerator.

pub fn denominator(&self) -> UnsignedIntegerType

Returns the denominator.

pub fn ratio_string(&self) -> String

Returns the "numerator/denominator" spelling.

pub fn bar_quarter_length(&self) -> FloatType

Returns the length of one bar in quarter lengths.

pub fn bar_duration(&self) -> Duration

Returns the length of one bar as a Duration.

pub fn beat_count(&self) -> UnsignedIntegerType

Returns how many beats one bar carries.

This is music21’s beatCount, which follows the numerator rather than the denominator — except at 3, where 3/4 is three beats but 3/8 is one.

pub fn beat_count_name(&self) -> String

Returns music21’s name for the beat count, such as "Duple".

Counts above eight are spelled as "<n>-uple", as music21 does.

pub fn beat_quarter_length(&self) -> Result<FloatType>

Returns the length of one beat in quarter lengths.

Every meter this type can express has a uniform beat, so unlike music21’s beatDuration this never fails. music21 only reports a non-uniform beat for a hand-partitioned MeterSequence, which has no counterpart here.

pub fn beat_duration(&self) -> Result<Duration>

Returns the length of one beat as a Duration.

pub fn beat_division(&self) -> BeatDivision

Returns how the beat subdivides.

pub fn beat_division_count(&self) -> UnsignedIntegerType

Returns the number of divisions in one beat.

pub fn is_compound(&self) -> bool

Returns true when beats divide in three.

pub fn classification(&self) -> String

Returns music21’s classification, such as "Compound Duple".

pub fn beat_division_count_name(&self) -> &'static str

Returns music21’s beatDivisionCountName: Simple, Compound or Other.

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

Returns whether two time signatures have the same numerator and denominator: music21’s ratioEqual, so 4/4 and 2/2 differ.

pub fn beat_length_to_quarter_length_ratio(&self) -> FloatType

Returns how many quarter lengths one unit of the denominator lasts: 0.5 in 6/8, 2.0 in 2/2.

pub fn quarter_length_to_beat_length_ratio(&self) -> FloatType

Returns how many denominator units make one quarter length, the inverse of Self::beat_length_to_quarter_length_ratio.

pub fn beat_division_quarter_lengths(&self) -> Result<Vec<FloatType>>

Returns the quarter length of each division of one beat, in order: two eighths in 4/4, three in 6/8, the whole dotted-quarter beat in 3/8 where the beat does not divide.

pub fn beat_division_durations(&self) -> Result<Vec<Duration>>

Returns Self::beat_division_quarter_lengths as durations: music21’s beatDivisionDurations.

pub fn beat_sub_division_durations(&self) -> Result<Vec<Duration>>

Returns each division of the beat halved: music21’s beatSubDivisionDurations, four sixteenths in 4/4.

pub fn offset_from_beat(&self, beat: FloatType) -> Result<FloatType>

Returns the quarter-length offset of a one-based, possibly fractional beat: music21’s getOffsetFromBeat, so beat 2.5 of 4/4 is 1.5 and beat 1.5 of 6/8 is 0.75. A beat past the bar is an error.

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

Returns the one-based beat containing offset and how far into that beat it lies, in quarter lengths: music21’s getBeatProgress.

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

Returns the position within the bar as a fractional beat: music21’s getBeatProportion, 2.5 for the second eighth of beat two in 4/4 and 1.333… for the second eighth of 6/8.

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

Returns Self::beat_proportion the way music21’s getBeatProportionStr writes it: the beat alone on the beat, otherwise the beat and the fraction of it elapsed, 2 1/2, with the fraction’s denominator limited to 16.

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

How long the beat holding an offset is: music21’s getBeatDuration.

A meter written additively answers differently along the bar — the first beat of 2/4+3/8 is two quarters long and the second is three eighths.

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

Returns the quarter-length offset of each beat within one bar.

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

Returns the one-based beat containing offset quarter lengths into a bar.

Matches music21’s getBeat. Offsets at or beyond the end of the bar are rejected rather than wrapping.

impl TimeSignature

pub fn accent_partition_quarter_length(&self) -> FloatType

The length of one partition of music21’s default accent hierarchy, the finest level the accent weights are given at.

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

The accent weight of every partition of the bar, music21’s default accentSequence: 1.0 on the downbeat, halving with every level of the hierarchy a partition’s start is not a boundary of, so 4/4 reads 1.0, 0.125, 0.25, 0.125, 0.5, 0.125, 0.25, 0.125.

pub fn accent(&self, offset: FloatType) -> bool

Whether an offset in quarter lengths starts an accent partition: music21’s getAccent, which is false for any offset off the grid, beyond the bar included.

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

The accent weight at an offset in quarter lengths: music21’s getAccentWeight, the weight of the partition the offset falls in. An offset outside the bar is an error.

pub fn accent_weight_at_level( &self, offset: FloatType, level: usize, force_position_match: bool, permit_meter_modulus: bool, ) -> Result<FloatType>

The accent weight at an offset, read at a level of the accent sequence: music21’s getAccentWeight with its level.

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

Weighs the accent partitions of a level, looping the weights given over them: music21’s setAccentWeight.

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

Self::accent_weight with music21’s two options. With force_position_match an offset that does not start a partition answers half the smallest weight rather than its partition’s; with permit_meter_modulus an offset beyond the bar is read within it.

pub fn average_beat_strength( &self, stream: &Stream, notes_only: bool, ) -> FloatType

The mean accent weight of what a stream holds: music21’s averageBeatStrength, each element weighed where it falls in the bar, with an element off the accent grid counting half the smallest weight. notes_only weighs the notes, chords and rests alone; an empty stream weighs nothing.

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

How many levels of the beat hierarchy start at an offset: music21’s getBeatDepth, which quantizes the offset to the beat’s division and then counts the beat level and the division level. A meter of one beat has one level and answers one everywhere in the bar; an offset outside the bar is an error.

impl TimeSignature

pub fn beams_for( &self, notes: &[BeamedNote], measure_start_offset: FloatType, measure_padding: Option<FloatType>, ) -> Result<Vec<Option<Beams>>>

Beams a run of notes: music21’s getBeams.

The notes are taken as adjoining, which is how music21 takes them — their offsets are read only against measure_start_offset, for a run that begins part way through a bar. measure_padding is the measure’s paddingRight where the run came from one, and None where it did not; a run that ends an incomplete measure does not get its last beam stopped.

A run of one is beamed as nothing at all, as music21 does.

Trait Implementations

impl Clone for TimeSignature

fn clone(&self) -> TimeSignature

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TimeSignature

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

Formats the value using the given formatter.

impl Default for TimeSignature

fn default() -> Self

Returns 4/4, matching music21’s default TimeSignature().

impl<'de> Deserialize<'de> for TimeSignature

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 TimeSignature

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

Formats the value using the given formatter.

impl From<TimeSignature> for StreamElement

fn from(value: TimeSignature) -> Self

Converts to this type from the input type.

impl PartialEq for TimeSignature

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for TimeSignature

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 TimeSignature