Struct audio_core::Channel

pub struct Channel<'a, T> { /* fields omitted */ }

The buffer of a single channel.

This doesn’t provide direct access to the underlying buffer, but rather allows us to copy data usinga number of utility functions.

See Channels::channel.

Implementations

impl<'a, T> Channel<'a, T>

pub fn linear(buf: &'a [T]) -> Self

Construct a linear channel buffer.

The buffer provided as-is constitutes the frames of the channel.

Examples

use audio::Channel;

let buf = &mut [1, 3, 5, 7];
let channel = Channel::linear(buf);

assert_eq!(channel[1], 3);
assert_eq!(channel[2], 5);

pub fn interleaved(buf: &'a [T], channels: usize, channel: usize) -> Self

Construct an interleaved channel buffer.

The provided buffer must be the complete buffer, which includes all other channels. The provided channels argument is the total number of channels in this buffer, and channel indicates which specific channel this buffer belongs to.

Note that this is typically not used directly, but instead through an abstraction which makes sure to provide the correct parameters.

Examples

use audio::Channel;

let buf = &[1, 2, 3, 4, 5, 6, 7, 8];
let channel = Channel::interleaved(buf, 2, 1);

assert_eq!(channel[1], 4);
assert_eq!(channel[2], 6);

pub fn frames(&self) -> usize

Access the number of frames on the current channel.

Examples

use audio::Channels;

fn test(buf: &dyn Channels<f32>) {
    let left = buf.channel(0);
    let right = buf.channel(1);

    assert_eq!(left.frames(), 16);
    assert_eq!(right.frames(), 16);
}

test(&audio::dynamic![[0.0; 16]; 2]);
test(&audio::sequential![[0.0; 16]; 2]);
test(&audio::interleaved![[0.0; 16]; 2]);

pub fn iter(self) -> Iter<'a, T>

Construct an iterator over the channel.

Examples

use audio::{Channels as _, ChannelsMut as _};

let mut left = audio::interleaved![[0.0f32; 4]; 2];
let mut right = audio::dynamic![[0.0f32; 4]; 2];

for (l, r) in left.channel_mut(0).iter_mut().zip(right.channel_mut(0)) {
    *l = 1.0;
    *r = 1.0;
}

assert!(left.channel(0).iter().eq(right.channel(0).iter()));

assert_eq!(left.as_slice(), &[1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0]);
assert_eq!(&right[0], &[1.0, 1.0, 1.0, 1.0]);
assert_eq!(&right[1], &[0.0, 0.0, 0.0, 0.0]);

pub fn as_ref(&self) -> Channel<'_, T>

Construct a new Channel reference with a lifetime associated with the current channel instance instead of the underlying buffer.

Most of the time it is not necessary to use this, since Channel implements Copy and its lifetime would coerce to any compatible lifetime. This method is currently just here for completeness sake.

Both of these work equally well:

use audio::Channel;

struct Foo<'a> {
    channel: Channel<'a, i16>,
}

impl<'a> Foo<'a> {
    fn channel(&self) -> Channel<'_, i16> {
        self.channel.as_ref()
    }

    fn coerced_channel(&self) -> Channel<'_, i16> {
        self.channel
    }
}

pub fn skip(self, n: usize) -> Self

Construct a channel buffer where the first n frames are skipped.

Examples

use audio::{Channels as _, ChannelsMut as _};

let mut from = audio::interleaved![[0.0f32; 4]; 2];
*from.frame_mut(0, 2).unwrap() = 1.0;
*from.frame_mut(0, 3).unwrap() = 1.0;

let mut to = audio::interleaved![[0.0f32; 4]; 2];

to.channel_mut(0).copy_from(from.channel(0).skip(2));
assert_eq!(to.as_slice(), &[1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);

pub fn tail(self, n: usize) -> Self

Construct a channel buffer where the last n frames are included.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::interleaved![[1.0f32; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 2];

to.channel_mut(0).as_mut().tail(2).copy_from(from.channel(0));
assert_eq!(to.as_slice(), &[0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 1.0, 0.0]);

pub fn limit(self, limit: usize) -> Self

Limit the channel bufferto limit number of frames.

Examples

use audio::{Channels as _, ChannelsMut as _};

let from = audio::interleaved![[1.0f32; 4]; 2];
let mut to = audio::interleaved![[0.0f32; 4]; 2];

to.channel_mut(0).copy_from(from.channel(0).limit(2));
assert_eq!(to.as_slice(), &[1.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);

pub fn chunk(self, n: usize, len: usize) -> Self

Construct a range of frames corresponds to the chunk with len and position n.

Which is the range n * len .. n * len + len.

pub fn chunks(&self, chunk: usize) -> usize

How many chunks of the given size can you divide buf into.

This includes one extra chunk even if the chunk doesn’t divide the frame length evenly.

Examples

use audio::Channels;

fn test(buf: &dyn Channels<f32>) {
    let left = buf.channel(0);
    let right = buf.channel(1);

    assert_eq!(left.chunks(4), 4);
    assert_eq!(right.chunks(4), 4);

    assert_eq!(left.chunks(6), 3);
    assert_eq!(right.chunks(6), 3);
}

test(&audio::dynamic![[0.0; 16]; 2]);
test(&audio::sequential![[0.0; 16]; 2]);
test(&audio::interleaved![[0.0; 16]; 2]);

pub fn copy_into_slice(&self, out: &mut [T]) where
    T: Copy, 

Copy into the given slice of output.

Examples

use audio::Channels;

fn test(buf: &dyn Channels<f32>) {
    let channel = buf.channel(0);

    let mut buf = vec![0.0; 16];
    channel.copy_into_slice(&mut buf[..]);

    assert!(buf.iter().all(|f| *f == 1.0));
}

test(&audio::dynamic![[1.0; 16]; 2]);
test(&audio::sequential![[1.0; 16]; 2]);
test(&audio::interleaved![[1.0; 16]; 2]);

pub fn copy_into_iter<'out, I>(&self, iter: I) where
    I: IntoIterator<Item = &'out mut T>,
    T: 'out + Copy, 

Copy into the given iterator.

Examples

use audio::Channels;

fn test(buf: &dyn Channels<f32>) {
    let channel = buf.channel(0);

    let mut buf = vec![0.0; 16];

    // Copy into every other position in `buf`.
    channel.copy_into_iter(buf.iter_mut().step_by(2));

    for (n, f) in buf.into_iter().enumerate() {
        if n % 2 == 0 {
            assert_eq!(f, 1.0);
        } else {
            assert_eq!(f, 0.0);
        }
    }
}

test(&audio::dynamic![[1.0; 16]; 2]);
test(&audio::sequential![[1.0; 16]; 2]);
test(&audio::interleaved![[1.0; 16]; 2]);

Trait Implementations

impl<T> Clone for Channel<'_, T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Copy for Channel<'_, T>

impl<T> Debug for Channel<'_, T> where
    T: Copy + Debug, 

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

Formats the value using the given formatter.

impl<T> Eq for Channel<'_, T> where
    T: Copy + Eq, 

impl<T> Hash for Channel<'_, T> where
    T: Copy + Hash, 

fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T> Index<usize> for Channel<'_, T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a, T> IntoIterator for Channel<'a, T> where
    T: Copy, 

type Item = T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a Channel<'_, T> where
    T: Copy, 

type Item = T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Ord for Channel<'_, T> where
    T: Copy + Ord, 

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T> PartialEq<Channel<'_, T>> for Channel<'_, T> where
    T: Copy + PartialEq, 

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<Channel<'_, T>> for Channel<'_, T> where
    T: Copy + PartialOrd, 

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]pub fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]pub fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]pub fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]pub fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.