Trait sample::Sample [−] [src]

pub trait Sample: Copy + Clone + PartialOrd + PartialEq {
    type Signed: SignedSample + Duplex<Self>;
    type Float: FloatSample + Duplex<Self>;
    fn equilibrium() -> Self;

    fn identity() -> Self::Float { ... }
    fn to_sample<S>(self) -> S where Self: ToSample<S> { ... }
    fn from_sample<S>(s: S) -> Self where Self: FromSample<S> { ... }
    fn to_signed_sample(self) -> Self::Signed { ... }
    fn to_float_sample(self) -> Self::Float { ... }
    fn add_amp(self, amp: Self::Signed) -> Self { ... }
    fn mul_amp(self, amp: Self::Float) -> Self { ... }
}

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

extern crate sample;

use 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: SignedSample + Duplex<Self>

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: FloatSample + Duplex<Self>

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).

Required Methods

fn 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

extern crate sample;

use 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.

Provided Methods

fn 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

extern crate sample;

use 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());
}

fn to_sample<S>(self) -> S where Self: ToSample<S>

Convert self to any type that implements FromSample<Self>.

Example

extern crate sample;

use 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>

Create a Self from any type that implements ToSample<Self>.

Example

extern crate sample;

use 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

extern crate sample;

use 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

extern crate sample;

use 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

extern crate sample;

use 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 the Sample::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

extern crate sample;

use 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);
}

Implementors