Struct Scale 

pub struct Scale { /* private fields */ }

A named scale realized from a tonic pitch.

use music21_rs::{Pitch, Scale, ScaleType};

let scale = Scale::new(ScaleType::Octatonic, Pitch::from_name("C4")?);
let names: Vec<String> = scale.pitches()?.iter().map(|p| p.name()).collect();

assert_eq!(names, ["C", "D", "E-", "F", "G-", "A-", "A", "B", "C"]);

Implementations

impl Scale

pub fn roman_numeral(&self, degree: u8) -> Result<RomanNumeral>

The roman numeral on a degree of this scale: music21’s romanNumeral, the triad that degree carries read against the major key of the tonic, whatever its case would say.

pub fn tune(&self, stream: &mut Stream) -> Result<()>

Moves every note and chord of a stream onto this scale: music21’s tune. A pitch whose name, or any enharmonic of it within two accidentals, is a name of the scale’s octave from the tonic becomes that scale pitch in its own octave, spelled as it was where the scale pitch has such a spelling; a pitch the scale has no name for is left alone. Nested streams are tuned too.

pub fn scala_data(&self) -> Result<ScalaScale>

This scale written as a Scala file writes one: music21’s getScalaData, each degree as the cents above the tonic, with the interval the scale closes on as the period.

pub fn new(scale_type: ScaleType, tonic: Pitch) -> Self

Builds a scale of the given type on a tonic.

pub fn from_pitches(pitches: &[Pitch]) -> Result<Self>

A scale given by the notes of one octave of it rather than by a name: music21’s ConcreteScale(pitches=[...]).

The first pitch is the tonic, the steps are the intervals between neighbours, and the scale closes back on the octave, so the notes repeat an octave higher as any scale’s do.

pub fn descending(&self) -> Scale

This scale as it sounds coming down, which for most is itself.

pub fn pitches_descending(&self) -> Result<Vec<Pitch>>

The scale coming down: highest note first, through the collection it uses descending.

pub fn pitches_between_descending( &self, minimum: &Pitch, maximum: &Pitch, ) -> Result<Vec<Pitch>>

A range of the scale coming down, highest note first.

pub fn is_custom(&self) -> bool

Whether this scale was given by its notes rather than by a name.

pub fn set_tonic(&mut self, tonic: Pitch)

Moves the scale to a new tonic, keeping its pattern of steps.

pub fn derive_ranked_by( &self, pitches: &[Pitch], limit: Option<usize>, comparison: DegreeComparison, ) -> Result<Vec<(usize, Scale)>>

The scales of this pattern that contain the most of pitches, best first: music21’s deriveRanked on the scale rather than on the type, which is what a scale given by its notes has to use.

pub fn degree_count(&self) -> usize

Returns the number of distinct degrees: music21’s getDegreeMaxUnique, seven for a major scale and twelve for the chromatic.

pub fn scale_type(&self) -> ScaleType

Returns the scale type.

pub fn tonic(&self) -> &Pitch

Returns the tonic pitch.

pub fn pitches(&self) -> Result<Vec<Pitch>>

Returns the pitches of one octave, from the tonic through its octave.

The result has degree_count() + 1 entries, since the closing octave is included the way music21’s getPitches includes it.

A tonic with no octave is realized in octave 4, which is what music21 does: the scale on a bare G runs G4 A4 B-4 C5 …. The tonic itself keeps its own spelling — Scale::tonic still has no octave — because the octave belongs to the realization and not to the scale.

pub fn realized_tonic(&self) -> Pitch

The tonic as the scale sounds it: music21’s getTonic, which is the tonic in octave 4 when it was given without one.

pub fn relative_major(&self) -> Result<Scale>

The major scale written with the same key signature as this one: music21’s getRelativeMajor.

A mode is written with the signature of the major scale it is a rotation of, so D dorian is C major and E minor is G major. Only the seven-note modes have one.

pub fn relative_minor(&self) -> Result<Scale>

The minor scale written with the same key signature: music21’s getRelativeMinor.

pub fn parallel_major(&self) -> Scale

The major scale on the same tonic: music21’s getParallelMajor.

pub fn parallel_minor(&self) -> Scale

The minor scale on the same tonic: music21’s getParallelMinor.

pub fn named_degrees(&self) -> Option<Vec<IntegerType>>

The degree each of this scale’s notes stands on, in order from the tonic, where those are not simply the notes counted off.

Only a named pattern can say so — a collection given by its notes is counted — and only one of them does: see ScaleType::ascending_degrees.

pub fn pitch_on_degree(&self, degree: IntegerType) -> Result<Option<Pitch>>

Returns the pitch standing on a one-based scale degree, or nothing where the scale has no such degree.

Degree 1 is the tonic. Every other degree is read within the one octave the scale is realized in, so the eighth degree is the tonic again and not the octave above it, and the zeroth and the negative degrees count back round from the top. That is music21’s pitchFromDegree, which asks its interval network for the node the degree names and gets one of the nodes it has.

A scale that names its degrees has only the ones it names: Rag Asawari’s ascent has no third, and answers nothing when asked for one rather than handing back the note that would be third in line.

pub fn pitch_at_degree(&self, degree: IntegerType) -> Result<Pitch>

The pitch standing on a one-based scale degree, which the scale is expected to have: Self::pitch_on_degree is the one that says when it does not.

pub fn pitches_between( &self, minimum: &Pitch, maximum: &Pitch, ) -> Result<Vec<Pitch>>

Returns every pitch of the scale from minimum up to maximum, inclusive: music21’s getPitches given a range.

The scale is realized from the tonic in whatever octave puts it at or below the bottom of the range, then walked upward, so asking a C major scale for E-5 to G-7 starts at E5 — the first scale pitch that is not below the bottom — and not at a respelled E-5.

pub fn is_realizable(&self) -> bool

Whether the pattern can be walked at all.

A collection given by its notes may rise and fall back to where it began — A4 B4 C4 D4 E4 F4 G4 A4 does — and a pattern that goes nowhere cannot be realized over a range, however many times it is walked. music21 says so as well, out of the network it walks.

pub fn octave_duplicating(&self) -> bool

Whether the pattern repeats at the octave: music21’s octaveDuplicating. Every named scale does, and one given by its notes need not — a collection spanning two octaves before it comes back to its tonic is a pattern two octaves long.

pub fn final_pitch(&self) -> Result<Pitch>

The note the scale comes to rest on, as it sounds: music21’s getTonic, which is the fourth degree of a plagal mode.

pub fn dominant(&self) -> Result<Pitch>

The reciting tone: music21’s getDominant.

pub fn leading_tone(&self) -> Result<Pitch>

The seventh degree raised or lowered to sit a semitone below the final: music21’s getLeadingTone, which in a minor scale is not the seventh degree the scale itself has.

pub fn derive_by_degree(&self, degree: usize, pitch: &Pitch) -> Result<Scale>

Returns the scale of the same type on which pitch is the given degree: music21’s deriveByDegree, so the major scale with E as its fifth is A major. The pitch keeps its spelling; a pitch without an octave is read in octave 4, as music21 reads it, so the new tonic has one.

pub fn transpose(&self, interval: &Interval) -> Result<Scale>

Returns the same scale type on the tonic transposed by interval.

pub fn chord(&self) -> Result<Chord>

Returns one octave of the scale as a chord, tonic through octave: music21’s getChord.

pub fn pitches_from_scale_degrees( &self, degrees: &[usize], ) -> Result<Vec<Pitch>>

Returns the pitches at the given degrees within one octave of the tonic: music21’s pitchesFromScaleDegrees, which realizes tonic through octave once and so silently drops a degree beyond the octave.

pub fn pitches_from_scale_degrees_between( &self, degrees: &[usize], minimum: &Pitch, maximum: &Pitch, ) -> Result<Vec<Pitch>>

Every pitch of the named degrees between two pitches: music21’s pitchesFromScaleDegrees given a range, so the third and seventh of C major from c2 to c6 are D2 G2 D3 G3 D4 G4 D5 G5.

pub fn interval_between_degrees( &self, start: usize, end: usize, ) -> Result<Interval>

Returns the interval from one degree to another, both folded into the first octave the way music21’s pitchFromDegree folds them, so degree 9 of a seven-note scale is degree 2 and the interval from 2 to 9 is a unison.

pub fn is_next( &self, other: &Pitch, origin: &Pitch, steps: usize, ) -> Result<bool>

Returns whether other is the scale pitch steps degrees above origin, compared by name so the octave does not matter: music21’s isNext.

pub fn match_pitches( &self, pitches: &[Pitch], ) -> Result<(Vec<Pitch>, Vec<Pitch>)>

Splits pitches into those whose names the scale contains and those it does not: music21’s match. The matched list carries the scale’s own pitches, realized from the tonic in octave 4 when it has none, and the unmatched list carries the pitches as given.

pub fn match_pitches_by( &self, pitches: &[Pitch], comparison: DegreeComparison, ) -> Result<(Vec<Pitch>, Vec<Pitch>)>

The same, saying how a pitch is matched against a degree.

Both lists hold the pitches as given rather than the scale’s own — music21 hands its targets straight back — except that one with no octave is heard in octave 4, since that is where the scale sounds.

pub fn find_missing(&self, pitches: &[Pitch]) -> Result<Vec<Pitch>>

Returns the scale pitches, tonic through octave, whose pitch classes none of pitches has: music21’s findMissing, so C major against C E G is D4 F4 A4 B4.

pub fn solfeg( &self, pitch: &Pitch, variant: SolfegVariant, chromatic: bool, ) -> Result<String>

Returns the solfège syllable for a pitch, do through ti with the chromatic inflections (di, ra, …): music21’s solfeg. Without chromatic the plain syllable of the degree is returned whatever the accidental. Errors for degrees past seven and alterations past a double sharp or flat.

pub fn degree_of_by( &self, pitch: &Pitch, comparison: DegreeComparison, ) -> Result<Option<usize>>

Returns the one-based degree matching a pitch under the given comparison, or None when the scale does not have it.

pub fn degrees_of_by( &self, pitch: &Pitch, comparison: DegreeComparison, ) -> Result<Vec<usize>>

Every one-based degree the pitch stands on.

A scale may name the same note twice — Rag Marwa’s A is both its fifth degree and its seventh, since the pattern dips before it closes — and music21 chooses between them at random. The choosing is left to the caller; this says what there is to choose from.

pub fn degree_of(&self, pitch: &Pitch) -> Result<Option<usize>>

Returns the one-based degree whose pitch name matches, ignoring octave, or None when the pitch is not in the scale.

pub fn degree_of_pitch_class(&self, pitch: &Pitch) -> Result<Option<usize>>

Returns the one-based degree whose pitch class matches, so F- finds the E of C major.

pub fn next_pitch_above(&self, origin: &Pitch, steps: usize) -> Result<Pitch>

Returns the scale pitch steps degrees above origin. A pitch outside the scale first moves to the nearest scale pitch above it.

pub fn next_pitch_beside( &self, origin: &Pitch, steps: IntegerType, below: bool, ) -> Result<Pitch>

The same, told which side of a pitch outside the scale to start from: music21’s getNeighbor, where naming a side means stepping the whole way from the neighbour on it rather than counting the move onto the scale as one of the steps.

pub fn next_pitch_below(&self, origin: &Pitch, steps: usize) -> Result<Pitch>

Returns the scale pitch steps degrees below origin. A pitch outside the scale first moves to the nearest scale pitch below it.

pub fn degree_and_accidental_of( &self, pitch: &Pitch, ) -> Result<(usize, Option<Accidental>)>

Returns the degree a pitch sits on together with the accidental that separates it from the scale’s own spelling of that degree, so E- in C major is degree three with a flat. Errors when no degree shares the pitch’s letter.

pub fn places_of(&self, origin: &Pitch) -> Result<usize>

How many places in this scale’s realization stand on origin.

A scale may name the same note twice: Rag Marwa’s D- is both the note above its tonic and the one it passes through coming down from the octave, and where the next note is depends on which of them is meant. music21 chooses between them at random — the choosing is the caller’s, and Self::next_pitch_below_from takes it.

pub fn next_pitch_below_from( &self, origin: &Pitch, steps: usize, place: usize, ) -> Result<Pitch>

The note steps below origin, read as the place-th of the places this scale stands that note on. See Self::places_of.

pub fn next_pitch_above_from( &self, origin: &Pitch, steps: usize, place: usize, ) -> Result<Pitch>

The note steps above origin, read the same way.

Trait Implementations

impl Clone for Scale

fn clone(&self) -> Scale

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Scale

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Scale

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

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for Scale

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 Scale