Struct ScalaArchive 

pub struct ScalaArchive { /* private fields */ }

A searchable collection of Scala scales, keyed by file name.

This is the runtime counterpart to music21’s scale.scala module, whose search and getPaths helpers index the Scala scale archive. The archive itself is not bundled with this crate — see the note below — so the caller supplies the files and this type indexes whatever it is given, which also keeps the crate free of file IO and usable from wasm.

use music21_rs::ScalaArchive;

let mut archive = ScalaArchive::new();
archive.insert("mbira_banda.scl", b"Mbira Banda\n 1\n 2/1\n")?;
archive.insert("slendro5_2.scl", b"Slendro\n 1\n 2/1\n")?;

assert_eq!(archive.search("mbira"), ["mbira_banda.scl"]);
assert!(archive.get("slendro5_2.scl").is_some());

Implementations

impl ScalaArchive

pub fn new() -> Self

Creates an empty archive.

pub fn insert( &mut self, file_name: impl Into<String>, bytes: &[u8], ) -> Result<Option<ScalaScale>>

Parses and indexes one .scl file under the given name.

The name is the file name as music21 refers to it, such as "partch_43.scl". Returns the scale it replaced, if any.

pub fn insert_scale( &mut self, file_name: impl Into<String>, scale: ScalaScale, ) -> Option<ScalaScale>

Indexes an already-parsed scale under the given name.

pub fn get(&self, file_name: &str) -> Option<&ScalaScale>

Returns the scale stored under a file name.

pub fn names(&self) -> impl Iterator<Item = &str>

Returns every indexed file name, in sorted order.

pub fn iter(&self) -> impl Iterator<Item = (&str, &ScalaScale)>

Returns every indexed scale with its file name, in sorted order.

pub fn len(&self) -> usize

Returns the number of indexed scales.

pub fn is_empty(&self) -> bool

Returns whether the archive is empty.

pub fn bundled() -> Self

Builds an archive from the .scl files bundled with the crate.

Only available under the non-default scala-archive feature, which adds roughly a megabyte of scale data to the build. Without it, supply the files yourself with ScalaArchive::insert.

Use ScalaArchive::bundled_with_failures to see any scale that fails to load rather than silently dropping it.

pub fn bundled_with_failures() -> (Self, Vec<(&'static str, Error)>)

Builds an archive from the bundled files, reporting the ones that fail.

The failures are a fixed property of the bundled data, so the returned list is the same on every call.

pub fn bundled_len() -> usize

Returns the number of .scl files bundled with the crate.

Counts files without parsing them, so this includes the one that ScalaArchive::bundled skips.

pub fn search(&self, target: &str) -> Vec<&str>

Finds file names matching a search string, as music21’s scale.scala.search does.

Spaces in the target are ignored, an exact file-name match is preferred, and the remaining matches are substring hits against the name with its extension dropped and against a form with _ and - removed. Results are sorted.

Trait Implementations

impl Clone for ScalaArchive

fn clone(&self) -> ScalaArchive

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ScalaArchive

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

Formats the value using the given formatter.

impl Default for ScalaArchive

fn default() -> ScalaArchive

Returns the “default value” for a type.

impl Extend<(String, ScalaScale)> for ScalaArchive

fn extend<T: IntoIterator<Item = (String, ScalaScale)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl FromIterator<(String, ScalaScale)> for ScalaArchive

fn from_iter<T: IntoIterator<Item = (String, ScalaScale)>>(iter: T) -> Self

Creates a value from an iterator.

impl PartialEq for ScalaArchive

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for ScalaArchive