Module units 

Unit newtypes: a value is checked once, when it is built, and is valid by type afterwards.

Every type holds an f64 that is never NaN or infinite. Each constructor rejects a value outside the type’s range with a RangeError that names the type and the range. Zero is stored as +0.0, so -0.0 never reaches a report.

• Hz and Seconds: zero or more.
• Semitones, Cents, Octaves and Decibels: any finite value.
• Normalized: a knob position, 0.0 to 1.0.
• MidiPitch: a fractional MIDI note, 0.0 to 127.0.
• Correlation: -1.0 to 1.0.
• Degrees: any finite angle.
• Bpm: a tempo, 4 to 1000.
• Ratio: zero or more.
• Percent: 0 to 100 as Percent<Unipolar>, -100 to 100 as Percent<Bipolar>.

A JSON number deserializes through the same check, so a value from layers.json is valid by type too.

A unit string such as "1.2 kHz" parses with str::parse: a number, optional whitespace and a suffix. Each type takes only its own suffixes, matched case-sensitively. A bare number, an unknown suffix and a suffix of another unit return a ParseUnitError that lists the accepted suffixes. Display prints the first suffix in a form that parses back to the same value.

Type	Suffixes
Hz	Hz, kHz
Seconds	s, ms
Cents	ct
Semitones	st
Octaves	oct
Decibels	dB
Percent	%
MidiPitch	midi

use sound_to_patch::units::{Bipolar, Hz, Percent, Seconds};

let cutoff: Hz = "1.2 kHz".parse()?;
let pre_delay: Seconds = "20 ms".parse()?;
let amount: Percent<Bipolar> = "-40%".parse()?;
assert_eq!(cutoff.to_string(), "1200 Hz");
assert!("1.2 s".parse::<Hz>().is_err());

A conversion between two unit types is a From impl when every input has a valid output, such as Hz::from a MidiPitch, and a TryFrom impl otherwise, such as MidiPitch::try_from a Hz. A ratio or a gain has no unit type and goes through named methods: Cents::to_ratio, Cents::from_ratio, Semitones::to_ratio, Octaves::to_ratio, Decibels::to_amplitude_gain, Decibels::from_amplitude_gain, Decibels::to_power_ratio and Decibels::from_power_ratio.

No Milliseconds type exists: Seconds::from_millis converts at the boundary. No unit type exists for a knob whose law is not measured, such as the filter cutoff: such a knob takes a Normalized position.

Structs

Bpm

A tempo in beats per minute, from 4 to 1000 inclusive.

Cents

An interval in cents, a hundredth of a semitone: any finite value, sign allowed.

Correlation

A Pearson correlation from -1.0 to 1.0 inclusive, such as the correlation of two stereo channels.

Decibels

A level in decibels: any finite value. A negative value is common, because levels are often relative to a peak.

Degrees

An angle in degrees, such as a phase difference: any finite value, sign allowed.

Hz

A frequency in hertz: a finite value of zero or more.

MidiPitch

A MIDI note number from 0.0 to 127.0 inclusive. Fractional values carry a pitch between notes, such as a pitch track gives.

Normalized

A knob position from 0.0 to 1.0 inclusive.

Octaves

An interval in octaves: any finite value, sign allowed.

ParseUnitError

A unit string that does not parse into its unit type.

Percent

A percentage. The polarity fixes the range: Percent<Unipolar> takes 0 to 100, Percent<Bipolar> takes -100 to 100.

RangeError

A value outside the range a unit type or a conversion accepts.

Ratio

A ratio of two values of the same unit, zero or more, such as a spectral centroid over the fundamental.

Seconds

A duration in seconds: a finite value of zero or more.

Semitones

An interval in semitones: any finite value, sign allowed.

Enums

Bipolar

-100 to 100 percent, for controls that go both ways, such as a modulation amount.

Unipolar

0 to 100 percent, for controls that go one way from zero.

Traits

Polarity

The range of a Percent: Unipolar or Bipolar.