Struct ScalaScale 

pub struct ScalaScale { /* private fields */ }

A scale parsed from a Scala .scl file.

The stored degrees follow this crate’s convention rather than Scala’s: the implicit 1/1 unison is made explicit at index 0, and the final entry of the file — the interval the scale repeats at — is held separately as the period instead of being a degree. So a 12-note file yields 12 degrees plus a period, and degrees()[0] is always 1/1.

Implementations

impl ScalaScale

pub fn new( description: impl Into<String>, degrees: Vec<ScalaDegree>, period: ScalaDegree, ) -> Self

A scale from its parts: a description, the degrees with the unison at index 0, and the interval it repeats at.

pub fn parse(contents: &str) -> Result<Self>

Parses the contents of a .scl file.

Both ratio and cents degrees are accepted. Lines beginning with ! are comments; the first non-comment line is the description, the second is the degree count, and the rest are degrees.

pub fn parse_bytes(bytes: &[u8]) -> Result<Self>

Parses the raw bytes of a .scl file.

The Scala format is defined as latin-1 (ISO-8859-1), which music21’s scale.scala module states explicitly, and 73 of the ~3900 files it ships are not valid UTF-8. Bytes are therefore decoded as latin-1 rather than as UTF-8, so accented characters in description lines survive instead of becoming replacement characters. Degree lines are ASCII in either reading, so numbers are unaffected.

This crate does no file IO of its own, so read the file yourself:

use music21_rs::ScalaScale;

let bytes = std::fs::read("partch_43.scl")?;
let scale = ScalaScale::parse_bytes(&bytes)?;

pub fn description(&self) -> &str

Returns the scale’s description line.

pub fn degrees(&self) -> &[ScalaDegree]

Returns the degrees of one period, starting with 1/1.

pub fn period(&self) -> ScalaDegree

Returns the interval the scale repeats at.

This is usually an octave, but need not be — Bohlen-Pierce repeats at 3/1, and non-octave scales are common in the Scala archive.

pub fn len(&self) -> usize

Returns the number of degrees in one period.

pub fn is_empty(&self) -> bool

Returns whether the scale has no degrees.

A Scala file may declare zero degrees — the archive’s xxx.scl does, and music21 reads it as a scale with no pitches.

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

The cents of every degree the file writes: music21’s getCentsAboveTonic.

The unison is left out and the period is the last of them, which is how a .scl file writes a scale — twelve lines for a twelve-tone scale, the last of them the octave. cents_above_root is the other reading, the cents of an index counted from the root.

pub fn written_degrees(&self) -> Vec<ScalaDegree>

The degrees a .scl file writes for this scale: every degree above the unison, and the period last. A scale with no degrees writes none.

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

The width of each step in cents: music21’s getAdjacentCents.

One width per degree the file writes, the first being the step off the unison and the last the step that closes the period.

pub fn from_written_cents( description: impl Into<String>, cents: &[FloatType], ) -> Self

A scale from the cents of every degree a file writes, the period last: the reverse of written_cents.

pub fn from_adjacent_cents( description: impl Into<String>, widths: &[FloatType], ) -> Self

A scale from the width of each step, in cents: music21’s setAdjacentCents.

The last width closes the period, so [100.0; 12] is twelve-tone equal temperament.

pub fn interval_sequence(&self) -> Result<Vec<Interval>>

Each step of the scale as an interval: music21’s getIntervalSequence.

A step is measured in cents and an interval counts semitones, which ChromaticInterval counts fractionally — so a step of 137 cents is a second a little over a third of a semitone wide, and says so.

pub fn from_interval_sequence( description: impl Into<String>, steps: &[Interval], ) -> Self

A scale from an interval per step: music21’s setIntervalSequence.

pub fn file_string(&self, file_name: Option<&str>) -> String

The text of a .scl file for this scale: music21’s getFileString.

The name is written as the first comment where one is given, as the archive’s own files write it. A degree that was read as a ratio is written back as that ratio — both spellings are Scala, and only this one reads back as the scale it came from; music21 keeps cents alone and so cannot.

pub fn ratio_at(&self, index: IntegerType) -> FloatType

Returns the frequency ratio above the root for a degree index.

Indices outside one period wrap, shifting by the period for each wrap. Negative indices run below the root.

A scale with no degrees has nothing to wrap through, so every index returns the root ratio of 1.0.

pub fn cents_above_root(&self, index: IntegerType) -> FloatType

Returns the cents above the root for a degree index.

Note this is absolute distance from the scale root, unlike TuningSystem::cents_at, which reports deviation from equal temperament.

pub fn frequency_at(&self, root_hz: FloatType, index: IntegerType) -> FloatType

Returns the frequency in hertz for a degree index, given a root pitch.

A Scala scale fixes no absolute pitch, so the root is supplied by the caller.

Trait Implementations

impl Clone for ScalaScale

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 ScalaScale

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for ScalaScale

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 ScalaScale

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

Formats the value using the given formatter.

impl FromStr for ScalaScale

type Err = Error

The associated error which can be returned from parsing.

fn from_str(contents: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl PartialEq for ScalaScale

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for ScalaScale

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 ScalaScale