Add packed 24-bit sample types (S24_3LE and friends)

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Unreleased
 
+- Add packed 24-bit sample types `I24LE3`, `I24BE3`, `U24LE3` and `U24BE3` to
+  `dasp_sample::types`, corresponding to the `S24_3LE`, `S24_3BE`, `U24_3LE`
+  and `U24_3BE` formats. Unlike `I24`/`U24`, which store their value in a
+  four-byte container, these store it in exactly three bytes with an alignment
+  of one, so a buffer of packed 24-bit PCM can be reinterpreted as a slice of
+  samples without a copy. They implement `Sample`, `Frame` and the full set of
+  `FromSample`/`ToSample` conversions. `Sample::Signed` and `Sample::Float` are
+  `I24LE3`/`i32` and `f32`, mirroring the padded types, so `I24LE3` and `I24BE3`
+  are `SignedSample` as every other signed sample type is, while `U24LE3` and
+  `U24BE3` are not, as no unsigned type is. They carry the same arithmetic
+  operators (`Add`, `Sub`, `Mul`, `Div`, `Rem`, and `Neg` on the signed pair)
+  with the same debug-panic/release-wrap contract, the same `From` conversions,
+  and `I48`/`U48` accept them as sources. The bitwise and shift operators are
+  not mirrored, being bit manipulation whose meaning does not carry from a
+  four-byte container to a three-byte one.
+
+  Having no spare byte to store one, they wrap out-of-range values modulo 2^24
+  where `I24`/`U24` keep them. Only conversions from `f32`/`f64` outside the
+  documented `-1.0 <= v < 1.0` range can reach this: every integer conversion
+  into 24 bits is a shift that fits by construction. This is the same wrapping
+  `impl From<i32> for I24` already does, and no attempt is made here to settle
+  the wider question of overflow behaviour raised in #39 and #73.
+- Bump `dasp_sample` and `dasp_frame` to 0.11.1, and raise `dasp_frame`'s
+  requirement on `dasp_sample` to `0.11.1`, as it now references the packed
+  types by name and would not build against 0.11.0.
 - Renamed `window-hanning` to `window-hann`
 - Made `IntoInterleavedSamples` and `IntoInterleavedSamplesIterator` stop
   yielding samples when the underlying signal gets exhausted. This is a breaking

README.md

@@ -52,7 +52,8 @@ Use the **Sample** trait to convert between and remain generic over any
 bit-depth in an optimal, performance-sensitive manner. Implementations are
 provided for all signed integer, unsigned integer and floating point primitive
 types along with some custom types including 11, 20, 24 and 48-bit signed and
-unsigned unpacked integers. For example:
+unsigned unpacked integers, and 24-bit signed and unsigned integers packed into
+exactly three bytes in either byte order. For example:
 
 ```rust
 assert_eq!((-1.0).to_sample::<u8>(), 0);

dasp_frame/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "dasp_frame"
 description = "An abstraction for audio PCM DSP frames, along with useful conversions and operations."
-version = "0.11.0"
+version = "0.11.1"
 authors = ["mitchmindtree <mitchell.nordine@gmail.com>"]
 readme = "../README.md"
 keywords = ["dsp", "frame", "channel", "pcm", "audio"]
@@ -11,7 +11,7 @@ homepage = "https://github.com/rustaudio/dasp"
 edition = "2018"
 
 [dependencies]
-dasp_sample = { version = "0.11", path = "../dasp_sample", default-features = false }
+dasp_sample = { version = "0.11.1", path = "../dasp_sample", default-features = false }
 
 [features]
 default = ["std"]

dasp_frame/src/lib.rs

@@ -569,6 +569,12 @@ impl_frame_for_sample! {
     dasp_sample::types::U24
     dasp_sample::types::U48
 }
+impl_frame_for_sample! {
+    dasp_sample::types::I24LE3
+    dasp_sample::types::I24BE3
+    dasp_sample::types::U24LE3
+    dasp_sample::types::U24BE3
+}
 
 impl<F> Iterator for Channels<F>
 where

dasp_graph/Cargo.toml

@@ -21,10 +21,10 @@ node-signal = ["dasp_frame", "dasp_signal"]
 node-sum = ["dasp_slice"]
 
 [dependencies]
-dasp_frame = { version = "0.11", default-features = false, features = ["std"], optional = true }
-dasp_ring_buffer = { version = "0.11", default-features = false, features = ["std"], optional = true }
-dasp_signal = { version = "0.11", default-features = false, features = ["std"], optional = true }
-dasp_slice = { version = "0.11", default-features = false, features = ["std"], optional = true }
+dasp_frame = { version = "0.11", path = "../dasp_frame", default-features = false, features = ["std"], optional = true }
+dasp_ring_buffer = { version = "0.11", path = "../dasp_ring_buffer", default-features = false, features = ["std"], optional = true }
+dasp_signal = { version = "0.11", path = "../dasp_signal", default-features = false, features = ["std"], optional = true }
+dasp_slice = { version = "0.11", path = "../dasp_slice", default-features = false, features = ["std"], optional = true }
 petgraph = { version = "0.5", default-features = false }
 
 [dev-dependencies]

dasp_sample/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "dasp_sample"
 description = "An abstraction for audio PCM DSP samples, along with useful conversions and operations."
-version = "0.11.0"
+version = "0.11.1"
 authors = ["mitchmindtree <mitchell.nordine@gmail.com>"]
 readme = "../README.md"
 keywords = ["dsp", "bit-depth", "sample", "pcm", "audio"]