[−][src]Trait dasp::Sample
A trait for working generically across different Sample format types.
Provides methods for converting to and from any type that implements the
FromSample trait and provides methods for performing signal
amplitude addition and multiplication.
Example
use dasp_sample::{I24, Sample}; fn main() { assert_eq!((-1.0).to_sample::<u8>(), 0); assert_eq!(0.0.to_sample::<u8>(), 128); assert_eq!(0i32.to_sample::<u32>(), 2_147_483_648); assert_eq!(I24::new(0).unwrap(), Sample::from_sample(0.0)); assert_eq!(0.0, Sample::EQUILIBRIUM); }
Associated Types
type Signed: Duplex<Self> + SignedSample
When summing two samples of a signal together, it is necessary for both samples to be
represented in some signed format. This associated Addition type represents the format to
which Self should be converted for optimal Addition performance.
For example, u32's optimal Addition type would be i32, u8's would be i8, f32's would be
f32, etc.
Specifying this as an associated type allows us to automatically determine the optimal,
lossless Addition format type for summing any two unique Sample types together.
As a user of the sample crate, you will never need to be concerned with this type unless
you are defining your own unique Sample type(s).
type Float: Duplex<Self> + FloatSample
When multiplying two samples of a signal together, it is necessary for both samples to be
represented in some signed, floating-point format. This associated Multiplication type
represents the format to which Self should be converted for optimal Multiplication
performance.
For example, u32's optimal Multiplication type would be f32, u64's would be f64, i8's
would be f32, etc.
Specifying this as an associated type allows us to automatically determine the optimal,
lossless Multiplication format type for multiplying any two unique Sample types together.
As a user of the sample crate, you will never need to be concerned with this type unless
you are defining your own unique Sample type(s).
Associated Constants
const EQUILIBRIUM: Self
The equilibrium value for the wave that this Sample type represents. This is normally the
value that is equal distance from both the min and max ranges of the sample.
Example
use dasp_sample::Sample; fn main() { assert_eq!(0.0, f32::EQUILIBRIUM); assert_eq!(0, i32::EQUILIBRIUM); assert_eq!(128, u8::EQUILIBRIUM); assert_eq!(32_768_u16, Sample::EQUILIBRIUM); }
Note: This will likely be changed to an "associated const" if the feature lands.
const IDENTITY: Self::Float
The multiplicative identity of the signal.
In other words: A value which when used to scale/multiply the amplitude or frequency of a signal, returns the same signal.
This is useful as a default, non-affecting amplitude or frequency multiplier.
Example
use dasp_sample::{Sample, U48}; fn main() { assert_eq!(1.0, f32::IDENTITY); assert_eq!(1.0, i8::IDENTITY); assert_eq!(1.0, u8::IDENTITY); assert_eq!(1.0, U48::IDENTITY); }
Provided methods
fn to_sample<S>(self) -> S where
Self: ToSample<S>,
Self: ToSample<S>,
Convert self to any type that implements FromSample<Self>.
Find more details on type-specific conversion ranges and caveats in the conv module.
Example
use dasp_sample::Sample; fn main() { assert_eq!(0.0.to_sample::<i32>(), 0); assert_eq!(0.0.to_sample::<u8>(), 128); assert_eq!((-1.0).to_sample::<u8>(), 0); }
fn from_sample<S>(s: S) -> Self where
Self: FromSample<S>,
Self: FromSample<S>,
Create a Self from any type that implements ToSample<Self>.
Find more details on type-specific conversion ranges and caveats in the conv module.
Example
use dasp_sample::{Sample, I24}; fn main() { assert_eq!(f32::from_sample(128_u8), 0.0); assert_eq!(i8::from_sample(-1.0), -128); assert_eq!(I24::from_sample(0.0), I24::new(0).unwrap()); }
fn to_signed_sample(self) -> Self::Signed
Converts self to the equivalent Sample in the associated Signed format.
This is a simple wrapper around Sample::to_sample which may provide extra convenience in
some cases, particularly for assisting type inference.
Example
use dasp_sample::Sample; fn main() { assert_eq!(128_u8.to_signed_sample(), 0i8); }
fn to_float_sample(self) -> Self::Float
Converts self to the equivalent Sample in the associated Float format.
This is a simple wrapper around Sample::to_sample which may provide extra convenience in
some cases, particularly for assisting type inference.
Example
use dasp_sample::Sample; fn main() { assert_eq!(128_u8.to_float_sample(), 0.0); }
fn add_amp(self, amp: Self::Signed) -> Self
Adds (or "offsets") the amplitude of the Sample by the given signed amplitude.
Self will be converted to Self::Signed, the addition will occur and then the result
will be converted back to Self. These conversions allow us to correctly handle the
addition of unsigned signal formats.
Example
use dasp_sample::Sample; fn main() { assert_eq!(0.25.add_amp(0.5), 0.75); assert_eq!(192u8.add_amp(-128), 64); }
fn mul_amp(self, amp: Self::Float) -> Self
Multiplies (or "scales") the amplitude of the Sample by the given float amplitude.
amp> 1.0 amplifies the sample.amp< 1.0 attenuates the sample.amp== 1.0 yields the same sample.amp== 0.0 yields theSample::EQUILIBRIUM.
Self will be converted to Self::Float, the multiplication will occur and then the
result will be converted back to Self. These conversions allow us to correctly handle the
multiplication of integral signal formats.
Example
use dasp_sample::Sample; fn main() { assert_eq!(64_i8.mul_amp(0.5), 32); assert_eq!(0.5.mul_amp(-2.0), -1.0); assert_eq!(64_u8.mul_amp(0.0), 128); }