Struct Duration 

pub struct Duration { /* private fields */ }

Rhythmic duration measured in quarter lengths.

A quarter note has a quarter length of 1.0; an eighth note is 0.5; a whole note is 4.0.

Implementations

impl Duration

pub fn new(quarter_length: FloatType) -> Result<Self>

Creates a duration from a quarter-length value.

pub fn grace(&self) -> Option<&Grace>

How this grace note is written, or nothing where this is not the duration of a grace note: music21’s isGrace and what its GraceDuration says.

pub fn is_grace(&self) -> bool

Whether this is the duration of a grace note: music21’s isGrace.

pub fn set_grace(&mut self, grace: Option<Grace>)

Says how this grace note is written. A duration is made a grace note’s by Duration::grace_duration, which gives it no length.

pub fn quarter() -> Self

Returns a quarter-note duration.

pub fn half() -> Self

Returns a half-note duration.

pub fn whole() -> Self

Returns a whole-note duration.

pub fn eighth() -> Self

Returns an eighth-note duration.

pub fn from_type(duration_type: DurationType) -> Self

Creates a duration from a note-value type.

pub fn from_type_with_dots(duration_type: DurationType, dots: u32) -> Self

Creates a duration from a note-value type carrying augmentation dots.

pub fn type_and_dots(&self) -> Option<(DurationType, u32)>

Returns the note-value type and dot count that together make exactly this length, such as a half note with one dot for 3.0. None for a length no single dotted note value has, such as a tuplet or a tie.

Where the written values have been said, it is the one value there is, whatever the length: an unlinked duration written as a half is a half however long it sounds.

pub fn dots(&self) -> u32

Returns the augmentation dots on this duration, or 0 when it is not a single dotted note value.

pub fn set_dots(&mut self, dots: u32) -> Result<()>

Writes every value of the duration with so many dots, each keeping its note value and the whole its tuplets: music21’s dots setter. The length becomes what the values then come to, and a duration still worked out from its length is then taken as written so.

Errors

A value written as no note value at all, which cannot take dots.

pub fn ordinal(&self) -> Option<usize>

music21’s ordinal for the duration’s type, or None where music21 says complex or the duration is zero: a duration whose quarter length is not a single dotted note value.

pub fn augment_or_diminish(&self, factor: FloatType) -> Result<Duration>

Returns the duration scaled by a positive factor: music21’s augmentOrDiminish, so a quarter by two is a half.

An unlinked duration stays unlinked and keeps its written values; only its length is scaled, and it is not snapped to a fraction.

pub fn tuplet(&self) -> Option<Tuplet>

The tuplet this length is written as, if any: the first of quarter_length_to_tuplet.

A length that is already a plain written value is that value rather than a tuplet of some other one, so a quarter answers None: music21 tries the exact match before it tries any ratio, and a plain quarter is a quarter even though it is also two thirds of a dotted quarter in a triplet.

pub fn tuplets(&self) -> Vec<Tuplet>

The tuplets this length is written inside: the ones a caller set, or the one read off the length when nobody has.

This is music21’s tuplets, which is likewise inferred until it is assigned. Setting it to nothing is not the same as never setting it: two thirds of a quarter reads as a quarter triplet on its own, and stays two thirds of a quarter written as no tuplet once told so.

pub fn aggregate_tuplet_multiplier(&self) -> FractionType

What the written values are multiplied by to give the sounding length: music21’s aggregateTupletMultiplier, every tuplet’s ratio multiplied together, so a triplet inside a quintuplet is 8/15.

pub fn quarter_length_no_tuplets(&self) -> FloatType

The total of the written values, before any tuplet shortens them: music21’s quarterLengthNoTuplets.

pub fn set_tuplets(&mut self, tuplets: Vec<Tuplet>)

Says what tuplets this length is written inside, keeping the written values and changing the sounding length to match: music21’s tuplets setter.

pub fn append_tuplet(&mut self, tuplet: Tuplet)

Writes this length inside one more tuplet, shortening it by that tuplet’s ratio: music21’s appendTuplet.

pub fn components(&self) -> Vec<(DurationType, u32)>

The written note values this length is made of, tied together: music21’s components.

This is the first half of quarter_conversion, read over the written length. A length whose tuplets a caller has set is read as the tie those tuplets leave, without looking for a tuplet of its own.

Where the written values have been said these are they, less any with no type; Duration::written_values keeps those too.

pub fn written_values(&self) -> Vec<DurationTuple>

The written values with the length of each: music21’s components as the DurationTuples they are there.

A length no tie of note values reaches is one value with no type, as it is upstream, and nought is no values at all.

pub fn consolidate(&mut self)

One written value for the whole length, losing how it had been written: music21’s consolidate.

The value is the one the written total comes to, before any tuplet, and has no type where no single note value does. A duration already written as one value is left alone.

use music21_rs::{Duration, DurationType};

let mut duration = Duration::quarter();
duration.add_duration_tuple(DurationType::Half, 0);
duration.add_duration_tuple(DurationType::Quarter, 0);
assert_eq!(duration.components().len(), 3);
duration.consolidate();
assert_eq!(duration.components(), [(DurationType::Whole, 0)]);

pub fn slice_component_at_position(&mut self, position: FloatType) -> Result<()>

Cuts the written value sounding at a position in two, leaving the whole length as it was: music21’s sliceComponentAtPosition.

The position is counted in the written values. One that falls on the join between two values, or at either end, cuts nothing and is an error.

pub fn set_dot_groups(&mut self, groups: Vec<u32>)

Writes the duration with dots above its dots: music21’s dotGroups setter. Each group lengthens the value as dots do, so a half under [1, 1] lasts four and a half quarters. The plain dots come off the written values, since the groups now say how the note is dotted.

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

The same length written as a tie of singly dotted values, for a reader with no dot groups: music21’s splitDotGroups.

Each group after the first ties on every value so far at the next note value down, so a half under [1, 1] is a dotted half tied to a dotted quarter. It is an error for a duration that is not one written value.

pub fn linked(&self) -> bool

Whether the written values and the sounding length move together: music21’s linked, true unless a caller has said otherwise.

pub fn set_linked(&mut self, linked: bool)

Links or unlinks the written values and the length: music21’s linked setter.

Unlinking keeps the values the duration is written as today, and Duration::set_quarter_length then changes how long it sounds without touching them. Linking again keeps the length and reads the values off it afresh.

pub fn grace_duration(&self) -> Duration

The same written values sounding for no time, unlinked from their length: the duration of a grace note, music21’s getGraceDuration.

A duration with no written values is written as an eighth, since a grace note has to be written as something. The tuplets are dropped, as they are upstream.

use music21_rs::{Duration, DurationType};

let grace = Duration::new(1.25)?.grace_duration();
assert_eq!(grace.quarter_length(), 0.0);
assert!(!grace.linked());
assert_eq!(
    grace.components(),
    [(DurationType::Quarter, 0), (DurationType::Sixteenth, 0)]
);

pub fn expression_is_inferred(&self) -> bool

Whether the way this length is written was worked out from the length rather than said: music21’s expressionIsInferred.

A duration made from a length is inferred, and one made from a note value is not. Making notation may write an inferred length another way, cutting it to finish a tuplet or joining it with its neighbours; one that was said is left as it was written.

use music21_rs::{Duration, DurationType};

assert!(Duration::new(0.5)?.expression_is_inferred());
assert!(!Duration::from_type(DurationType::Eighth).expression_is_inferred());

pub fn set_expression_is_inferred(&mut self, inferred: bool)

Says whether the way this length is written may be worked out again from the length.

pub fn is_complex(&self) -> bool

Whether the length needs more than one written value, tied: music21’s isComplex.

pub fn dot_groups(&self) -> Vec<u32>

The dots on the written value, as the one dot group the crate keeps: music21’s dotGroups, which can also write one length twice over where a mensural notation asks for it.

pub fn clear(&mut self)

Takes the length away: music21’s clear, which empties the written values so the duration sounds for no time. The tuplets it was told stay.

pub fn add_duration_tuple(&mut self, duration_type: DurationType, dots: u32)

Ties one more written value onto the end: music21’s addDurationTuple, which lengthens the duration by that value inside whatever tuplets it is written in.

The values are kept as they were added from then on, so a quarter with a half and a quarter tied on is three values and not a whole until it is consolidated.

pub fn component_index_at_qtr_position( &self, position: FloatType, ) -> Result<usize>

Which written value is sounding at a position within the duration: music21’s componentIndexAtQtrPosition. The positions are counted in the written values, before any tuplet scales them, and the start and the very end answer the first and the last value.

pub fn component_start_time(&self, index: usize) -> Result<FloatType>

Where a written value starts within the duration, counted in the written values: music21’s componentStartTime. An index past the values is an error.

pub fn full_name(&self) -> String

Returns music21’s fullName for a single written note value, such as "Dotted Quarter", "Double Dotted Half", "Imperfect Longa" or "Quarter Triplet (2/3 QL)".

A length that has to be written as a tie names each of its values and joins them, "Quarter tied to 16th (1 1/4 total QL)". A length no note value reaches is "Inexpressible" and a zero one is "Zero Duration (0 total QL)", both as music21 names them.

pub fn duration_type(&self) -> Option<DurationType>

Returns the note-value type whose undotted length this duration is.

Returns None for a length that is not a plain note value, such as a dotted or tuplet duration.

pub fn quarter_length(&self) -> FloatType

Returns the duration in quarter lengths.

pub fn set_quarter_length(&mut self, quarter_length: FloatType) -> Result<()>

Updates the duration in quarter lengths.

The written values are read off the new length, unless the duration is unlinked and keeps the ones it has.

Trait Implementations

impl Clone for Duration

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 Duration

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

Formats the value using the given formatter.

impl Default for Duration

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Duration

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 Eq for Duration

impl From<Duration> for Rest

fn from(value: Duration) -> Self

Converts to this type from the input type.

impl Hash for Duration

Hashes what equality compares, the quarter length.

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 Duration

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for Duration

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 TryFrom<f64> for Duration

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: FloatType) -> Result<Self>

Performs the conversion.

impl TryFrom<i32> for Duration

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: IntegerType) -> Result<Self>

Performs the conversion.