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 symbol(&self) -> Option<&str>

How the signature is drawn where it is not drawn as numbers: music21’s symbol, common for the C of 4/4 or cut for the struck C of 2/2, and nothing where it is written as numbers.

pub fn set_symbol(&mut self, symbol: Option<String>)

Says how the signature is drawn, or that it is written as numbers.

pub fn is_restated(&self) -> bool

Whether this is the meter an earlier measure states, standing again in a later one, rather than a meter of its own.

music21 holds a meter as an object, and one object may stand in several measures: its ABC reader gives a measure the meter in force back, the very object, after cutting an overlong measure in two. music21’s makeTies then finds that meter only where it stands last, which decides where it cuts, so a reader that restates a meter says so here. Two meters differing only in this are equal.

pub fn set_restated(&mut self, restated: bool)

Says whether this is an earlier measure’s meter standing again.

pub fn symbolize_denominator(&self) -> bool

Whether the denominator is drawn as a note rather than a number: music21’s symbolizeDenominator.

pub fn set_symbolize_denominator(&mut self, symbolize: bool)

Says whether the denominator is drawn as a note.

pub fn color(&self) -> Option<&str>

The colour the signature is drawn in, if one was said. Two meters differing only in colour are equal.

pub fn set_color(&mut self, color: Option<String>)

Sets the colour the signature is drawn in.

pub fn is_hidden(&self) -> bool

Whether the signature is left off the page while still in force: music21’s style.hideObjectOnPrint. Two meters differing only in this are equal.

pub fn set_hidden(&mut self, hidden: bool)

Says whether the signature is left off the page.

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 summed_numerator(&self) -> bool

Whether the meter was written with its numerators summed over one denominator, 3+2/8, rather than part by part: music21’s summedNumerator, which it reads off how the bar is displayed.

pub fn set_summed_numerator(&mut self, summed: bool)

Says whether the numerators are written summed, which changes how the meter is printed and nothing about how it is counted.

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 offset_in_bar( &self, element_offset: FloatType, meter_offset: FloatType, ) -> FloatType

Where an element falls in the bar this meter measures: music21’s getMeasureOffsetOrMeterModulusOffset, given the two offsets music21 reads off the stream.

element_offset is the element’s offset in its measure, or in its stream where it has no measure; meter_offset is the meter’s own. Still inside the bar, the element’s offset is the answer. Past it, the meter’s place is taken off and the rest wraps at the bar:

  3/4 at 0:  element at 4.0  ->  (4.0 - 0.0) % 3.0 = 1.0
  3/4 at 1:  element at 2.5  ->  (2.5 - 1.0) % 3.0 = 1.5

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.

Read off the beat sequence as music21 reads it: the divisions of every beat must agree, but the beats need not, so 2+3/8 divides into eighths though its beats are a quarter and a dotted quarter.

Errors

Beats that divide differently, as the quarters and eighths of 2/4+3/8 do, which music21 refuses too.

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. Only the stream’s own elements are weighed, not what the measures or voices inside it hold; notes_only weighs its notes and chords alone. A stream with nothing to weigh 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) -> Self

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: &Self) -> 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