lib: add RawDecoder::new_boxed

Cargo.toml

@@ -32,6 +32,7 @@ mp1-mp2 = []
 nightly-docs = [] # internal
 simd = []
 std = []
+new-boxed = ["std"]
 
 [package.metadata.docs.rs]
 features = ["nightly-docs", "std"]

README.md

@@ -55,3 +55,4 @@ https://github.com/rust-lang/cargo/issues/4328#issuecomment-652075026).**
 - `mp1-mp2`: Includes MP1 and MP2 decoding code.
 - `simd` *(default)*: Enables handwritten SIMD optimizations on eligible targets.
 - `std`: Adds things that require `std`,
+- `new-boxed`: Adds RawDecoder::new_boxed. Requires nightly and `std`.

src/lib.rs

@@ -35,6 +35,7 @@
 
 #![cfg_attr(feature = "nightly-docs", feature(doc_cfg))]
 #![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(feature = "new-boxed", feature(new_uninit))]
 
 #[doc(hidden)]
 pub mod ffi;
@@ -188,6 +189,7 @@ pub struct DecoderOwned<T> {
 /// # Ok(())
 /// # }
 /// ```
+#[repr(transparent)]
 pub struct RawDecoder(MaybeUninit<ffi::mp3dec_t>);
 
 /// Conditional type used to represent one PCM sample in output data.
@@ -374,6 +376,19 @@ impl RawDecoder {
         Self(decoder)
     }
 
+    /// Construct a new `RawDecoder` on the heap without copying from the stack.
+    ///
+    /// Currently requires nightly.
+    #[cfg(feature = "new-boxed")]
+    pub fn new_boxed() -> Box<Self> {
+        let mut decoder: Box<MaybeUninit<ffi::mp3dec_t>> = Box::new_uninit();
+        unsafe {
+            ffi::mp3dec_init(decoder.as_mut_ptr());
+        }
+        let ptr = Box::into_raw(decoder) as *mut RawDecoder;
+        unsafe { Box::from_raw(ptr) }
+    }
+
     /// Reads the next frame, skipping over potential garbage data.
     ///
     /// If the frame contains audio data, [`samples`](Audio::samples) should be used