# [−][src]Trait sample::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

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

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

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

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

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