audio_core/
read_buf.rs

1/// Trait used to govern sequential reading of an audio buffer.
2///
3/// This is the "in" part of "buffered I/O". It allows for buffers to govern
4/// which slice of frames in them has been read so that operations can be
5/// performed in multiple stages.
6///
7/// This can be accomplished manually using available buffer combinators such as
8/// [Buf::tail][crate::Buf::tail]. But buffered I/O allows us to do this in a
9/// much more structured fashion.
10///
11/// # Examples
12///
13/// ```
14/// use audio::ReadBuf;
15/// use audio::{io, wrap};
16/// # fn send_data(buf: &mut [i16]) {}
17///
18/// // A simple mutable buffer we want to write to. Fits 2 channels with 64
19/// // frames each.
20/// let mut to = [0i16; 128];
21///
22/// // A buffer we want to read from. 2 channels with 512 frames each.
23/// let from = audio::interleaved![[0i16; 512]; 2];
24/// let mut from = io::Read::new(from);
25///
26/// let mut steps = 0;
27///
28/// while from.has_remaining() {
29///     // Wrap the output buffer according to format so it can be written to
30///     // correctly.
31///     io::copy_remaining(&mut from, wrap::interleaved(&mut to[..], 2));
32///
33///     send_data(&mut to[..]);
34///
35///     steps += 1;
36/// }
37///
38/// // We needed to write 8 times to copy our entire buffer.
39/// assert_eq!(steps, 8);
40/// ```
41pub trait ReadBuf {
42    /// Test if there are any remaining frames to read.
43    ///
44    /// # Examples
45    ///
46    /// ```
47    /// use audio::ReadBuf;
48    ///
49    /// let mut buf = audio::wrap::interleaved(&[0, 1, 2, 3, 4, 5, 6, 7][..], 2);
50    ///
51    /// assert!(buf.has_remaining());
52    /// assert_eq!(buf.remaining(), 4);
53    /// buf.advance(4);
54    /// assert_eq!(buf.remaining(), 0);
55    /// ```
56    fn has_remaining(&self) -> bool {
57        self.remaining() > 0
58    }
59
60    /// Get the number of frames remaining that can be read from the buffer.
61    ///
62    /// # Examples
63    ///
64    /// ```
65    /// use audio::ReadBuf;
66    ///
67    /// let buf = audio::wrap::interleaved(&[0, 1, 2, 3, 4, 5, 6, 7][..], 2);
68    /// assert_eq!(buf.remaining(), 4);
69    /// ```
70    fn remaining(&self) -> usize;
71
72    /// Advance the read number of frames by `n`.
73    ///
74    /// # Examples
75    ///
76    /// ```
77    /// use audio::ReadBuf;
78    ///
79    /// let mut buf = audio::wrap::interleaved(&[0, 1, 2, 3, 4, 5, 6, 7][..], 2);
80    ///
81    /// assert_eq!(buf.remaining(), 4);
82    /// buf.advance(2);
83    /// assert_eq!(buf.remaining(), 2);
84    /// ```
85    fn advance(&mut self, n: usize);
86}
87
88impl<B> ReadBuf for &mut B
89where
90    B: ReadBuf,
91{
92    #[inline]
93    fn has_remaining(&self) -> bool {
94        (**self).has_remaining()
95    }
96
97    #[inline]
98    fn remaining(&self) -> usize {
99        (**self).remaining()
100    }
101
102    #[inline]
103    fn advance(&mut self, n: usize) {
104        (**self).advance(n);
105    }
106}
audio_core/read_buf.rs

audio_core/
read_buf.rs
