Merge branch 'release/0.3.0'

Author: Ben Leadbetter

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.3.0
+docs: fix further readme typos
+feat: utility messages are integrated into top level aggregate
+fix: ⚠️  hide some leaked private types and constants
+revert: ⚠️  remove jr timestamp headers and trait
+
 # 0.2.4
 ci: add standard cargo github actions
 docs: fix various typos
@@ -22,4 +28,4 @@ fix: repository url must be http
 refactor: repo is handled as a cargo workspace
 
 # 0.2.1
-fix: default fetures build
+fix: default features build

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "midi2"
-version = "0.2.4"
+version = "0.3.0"
 description = "Ergonomic, versatile, strong types wrapping MIDI 2.0 message data."
 edition = "2021"
 readme = "README.md"
@@ -31,10 +31,11 @@ sysex7 = []
 sysex8 = []
 system-common = []
 ump-stream = []
+utility = []
 
 [dependencies]
 derive_more = { version = "0.99.17", features = ["from"], default-features = false }
-midi2_proc = { version = "0.2.4", path = "midi2_proc" }
+midi2_proc = { version = "0.3.0", path = "midi2_proc" }
 ux = "0.1.6"
 
 [dev-dependencies]

README.md

@@ -58,7 +58,7 @@ assert_eq!(
 All message wrappers are grouped into aggregate enum types.
 There's a top level enum type which can represent all messages,
 and there's sub enum types for each different UMP type specified
-by the MIDI 2.0 documentation.
+by the MIDI 2.0 specification.
 
 ```rust
 fn handle_message(buffer: &[u32]) {
@@ -146,26 +146,6 @@ assert_eq!(
 );
 ```
 
-## Jitter Ruduction Support
-
-All ump messages have an optional jitter reduction header
-prepended before its message packets.
-
-```rust
-use midi2::prelude::*;
-
-let mut message = channel_voice1::ChannelPressure::new_arr();
-assert_eq!(message.data(), &[0x20D0_0000]);
-
-message.set_jitter_reduction(Some(JitterReduction::Timestamp(0x1234)));
-assert_eq!(message.data(), &[0x0020_1234, 0x20D0_0000]);
-```
-
-NOTE: For this reason all messages need an extra `u32` at the
-start of their buffers to accomodate the header data.
-For example, the minimum size buffer for a ChannelVoice2 message 
-is 3, rather than 2.
-
 ## Almost Entirely `#![no_std]` Friendly
 
 `#![no_std]` is a first class use case in midi2.
@@ -176,7 +156,7 @@ You'll want to setup midi2 without default features to compile
 without the `std` feature.
 
 ```toml
-midi2 = { version = "0.2.4", default-features = false, features = ["channel-voice2", "sysex7"],  }
+midi2 = { version = "0.3.0", default-features = false, features = ["channel-voice2", "sysex7"],  }
 ```
 
 ### Generic Representation
@@ -188,15 +168,15 @@ represent messages within a fixed size array.
 ```rust
 use midi2::prelude::*;
 
-let mut message = sysex8::Sysex8::<[u32; 17]>::try_new()
+let mut message = sysex8::Sysex8::<[u32; 16]>::try_new()
     .expect("Buffer is large enough for min message size");
 
 // in this mode methods which would require a 
 // buffer resize are fallible
 assert_eq!(message.try_set_payload(0..50), Ok(()));
 
 // if there's not enough room in the buffer to 
-// accomodate the resize then an overflow error is returned.
+// accommodate the resize then an overflow error is returned.
 assert_eq!(message.try_set_payload(0..60), Err(midi2::error::BufferOverflow));
 ```
 
@@ -239,18 +219,21 @@ To remedy this messages can be `rebuffered` into a different
 generic backing buffer type.
 
 ```rust
-use midi2::prelude::*;
+use midi2::{
+    prelude::*,
+    channel_voice2::NoteOn,
+};
 
-let mut owned: UmpMessage::<[u32; 5]> = {
-    let buffer = [0x1AF3_4F00_u32];
+let mut owned: NoteOn::<[u32; 4]> = {
+    let buffer = [0x4898_5E03_u32, 0x6A14_E98A];
     // the borrowed message is imutable and cannot outlive `buffer`
-    let borrowed = UmpMessage::try_from(&buffer[..]).expect("Data is valid");
+    let borrowed = NoteOn::try_from(&buffer[..]).expect("Data is valid");
     borrowed.try_rebuffer_into().expect("Buffer is large enough")
 };
 
 // the owned message is mutable an liberated from the buffer lifetime.
-owned.set_jitter_reduction(Some(JitterReduction::Timestamp(0x1234)));
-assert_eq!(owned.data(), &[0x0020_1234, 0x1AF3_4F00])
+owned.set_channel(u4::new(0x9));
+assert_eq!(owned.data(), &[0x4899_5E03, 0x6A14_E98A])
 ```
 
 ## Support For Classical MIDI Byte Stream Messages
@@ -268,7 +251,7 @@ message.set_pressure(u7::new(0x09));
 assert_eq!(message.data(), &[0xD6, 0x09]);
 ```
 
-Messages represented in bytes can be transformed to ump and back using convertion traits.
+Messages represented in bytes can be transformed to ump and back using conversion traits.
 
 ```rust
 use midi2::{
@@ -277,7 +260,7 @@ use midi2::{
 };
 
 let message = ChannelPressure::new_arr_bytes();
-let message: ChannelPressure<[u32; 5]> = message.try_into_ump().
+let message: ChannelPressure<[u32; 4]> = message.try_into_ump().
     expect("Buffer is large enough");
 
 assert_eq!(message.data(), &[0x20D0_0000]);

midi2_proc/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "midi2_proc"
 description = "Internal procedural macro crate. Only intended for use with midi2"
-version = "0.2.4"
+version = "0.3.0"
 edition = "2021"
 readme = "README.md"
 license = "MIT OR Apache-2.0"

midi2_proc/src/generate_message.rs

@@ -16,10 +16,7 @@ struct Property {
 
 impl Property {
     fn implement_via_trait(&self) -> bool {
-        self.is_group()
-            || self.is_channel()
-            || self.is_sysex_payload()
-            || self.is_jitter_reduction()
+        self.is_group() || self.is_channel() || self.is_sysex_payload()
     }
     fn is_group(&self) -> bool {
         self.ident == "group"
@@ -30,9 +27,6 @@ impl Property {
     fn is_sysex_payload(&self) -> bool {
         self.ident == "sysex_payload"
     }
-    fn is_jitter_reduction(&self) -> bool {
-        self.ident == "jitter_reduction"
-    }
 }
 
 fn has_attr(field: &syn::Field, id: &str) -> bool {
@@ -350,7 +344,7 @@ fn secondary_new_arr_impl(root_ident: &syn::Ident, properties: &Vec<Property>) -
 }
 
 fn arr_type_ump() -> TokenStream {
-    quote! { [u32; 5] }
+    quote! { [u32; 4] }
 }
 
 fn arr_type_bytes() -> TokenStream {
@@ -362,20 +356,7 @@ fn size_impl(root_ident: &syn::Ident, args: &GenerateMessageArgs) -> TokenStream
     quote! {
         impl<B: #constraint> crate::traits::Size<B> for #root_ident<B> {
             fn size(&self) -> usize {
-                match <B::Unit as crate::buffer::UnitPrivate>::UNIT_ID {
-                    crate::buffer::UNIT_ID_U32 => {
-                        // account for jitter reduction header
-                        use crate::buffer::UmpPrivate;
-                        <Self as crate::traits::MinSize<B>>::min_size()
-                            + self.buffer_access().specialise_u32().jitter_reduction().len()
-                    }
-                    crate::buffer::UNIT_ID_U8 => {
-                        // simple case
-                        // no jitter reduction logic here
-                        <Self as crate::traits::MinSize<B>>::min_size()
-                    }
-                    _ => unreachable!(),
-                }
+                <Self as crate::traits::MinSize<B>>::min_size()
             }
         }
     }
@@ -426,32 +407,7 @@ fn data_impl(root_ident: &syn::Ident, args: &GenerateMessageArgs) -> TokenStream
     quote! {
         impl<B: #constraint> crate::traits::Data<B> for #root_ident<B> {
             fn data(&self) -> &[B::Unit] {
-                match <B::Unit as crate::buffer::UnitPrivate>::UNIT_ID {
-                    crate::buffer::UNIT_ID_U32 => {
-                        use crate::buffer::UmpPrivate;
-                        use crate::detail::BitOps;
-
-                        // account for jitter reduction header
-                        let buffer = self.buffer_access().specialise_u32();
-                        let jr_slice = buffer.jitter_reduction();
-                        let jr_offset = match jr_slice.len() {
-                            0 => 0,
-                            _ => {
-                                match u8::from(jr_slice[0].nibble(2)) {
-                                    0 => 1, // the jr header is noop - skip from the data slice
-                                    _ => 0, // the jr header has data - include it!
-                                }
-                            }
-                        };
-                        &self.buffer_access().buffer()[jr_offset..self.size()]
-                    }
-                    crate::buffer::UNIT_ID_U8 => {
-                        // simple case
-                        // no jitter reduction logic here
-                        &self.buffer_access().buffer()[..self.size()]
-                    }
-                    _ => unreachable!(),
-                }
+                &self.buffer_access().buffer()[..self.size()]
             }
         }
     }
@@ -502,34 +458,9 @@ fn rebuffer_from_impl(root_ident: &syn::Ident, args: &GenerateMessageArgs) -> To
         {
             fn rebuffer_from(other: #root_ident<A>) -> Self {
                 let mut buffer = <B as crate::buffer::BufferDefault>::default();
-                match <B::Unit as crate::buffer::UnitPrivate>::UNIT_ID {
-                    crate::buffer::UNIT_ID_U32 => {
-                        // account for jitter reduction header
-                        use crate::buffer::UmpPrivate;
-                        let message_size = other.data().len();
-                        let jr_offset: usize = match other.data()
-                            .specialise_u32()
-                            .jitter_reduction()
-                            .len() {
-                            0 => {
-                                // other message had no jitter reduction header
-                                // -> we add it in on our side
-                                1
-                            },
-                            _ => 0,
-                        };
-                        buffer.resize(message_size + jr_offset);
-                        buffer.buffer_mut()[jr_offset..(message_size + jr_offset)].copy_from_slice(other.data());
-                    }
-                    crate::buffer::UNIT_ID_U8 => {
-                        // simple case
-                        // no jitter reduction logic here
-                        let message_size = other.data().len();
-                        buffer.resize(message_size);
-                        buffer.buffer_mut()[..message_size].copy_from_slice(other.data());
-                    }
-                    _ => unreachable!(),
-                }
+                let message_size = other.data().len();
+                buffer.resize(message_size);
+                buffer.buffer_mut()[..message_size].copy_from_slice(other.data());
                 #root_ident(buffer)
             }
         }
@@ -543,34 +474,9 @@ fn try_rebuffer_from_impl(root_ident: &syn::Ident, args: &GenerateMessageArgs) -
         {
             fn try_rebuffer_from(other: #root_ident<A>) -> core::result::Result<Self, crate::error::BufferOverflow> {
                 let mut buffer = <B as crate::buffer::BufferDefault>::default();
-                match <B::Unit as crate::buffer::UnitPrivate>::UNIT_ID {
-                    crate::buffer::UNIT_ID_U32 => {
-                        // account for jitter reduction header
-                        use crate::buffer::UmpPrivate;
-                        let message_size = other.data().len();
-                        let jr_offset: usize = match other.data()
-                            .specialise_u32()
-                            .jitter_reduction()
-                            .len() {
-                            0 => {
-                                // other message had no jitter reduction header
-                                // -> we add it in on our side
-                                1
-                            },
-                            _ => 0,
-                        };
-                        buffer.try_resize(message_size + jr_offset)?;
-                        buffer.buffer_mut()[jr_offset..(message_size + jr_offset)].copy_from_slice(other.data());
-                    }
-                    crate::buffer::UNIT_ID_U8 => {
-                        // simple case
-                        // no jitter reduction logic here
-                        let message_size = other.data().len();
-                        buffer.try_resize(message_size)?;
-                        buffer.buffer_mut()[..message_size].copy_from_slice(other.data());
-                    }
-                    _ => unreachable!(),
-                }
+                let message_size = other.data().len();
+                buffer.try_resize(message_size)?;
+                buffer.buffer_mut()[..message_size].copy_from_slice(other.data());
                 Ok(#root_ident(buffer))
             }
         }
@@ -594,13 +500,7 @@ fn new_impl(
             pub fn new() -> #root_ident<B>
             {
                 let mut buffer = <B as crate::buffer::BufferDefault>::default();
-                let jr_offset = match <B::Unit as crate::buffer::UnitPrivate>::UNIT_ID {
-                    // account for jitter reduction header
-                    crate::buffer::UNIT_ID_U32 => 1,
-                    crate::buffer::UNIT_ID_U8 => 0,
-                    _ => unreachable!(),
-                };
-                buffer.resize(<Self as crate::traits::MinSize<B>>::min_size() + jr_offset);
+                buffer.resize(<Self as crate::traits::MinSize<B>>::min_size());
                 #initialise_properties
                 #root_ident::<B>(buffer)
             }
@@ -625,13 +525,7 @@ fn try_new_impl(
             pub fn try_new() -> core::result::Result<#root_ident<B>, crate::error::BufferOverflow>
             {
                 let mut buffer = <B as crate::buffer::BufferDefault>::default();
-                let jr_offset = match <B::Unit as crate::buffer::UnitPrivate>::UNIT_ID {
-                    // account for jitter reduction header
-                    crate::buffer::UNIT_ID_U32 => 1,
-                    crate::buffer::UNIT_ID_U8 => 0,
-                    _ => unreachable!(),
-                };
-                buffer.try_resize(<Self as crate::traits::MinSize<B>>::min_size() + jr_offset)?;
+                buffer.try_resize(<Self as crate::traits::MinSize<B>>::min_size())?;
                 #initialise_properties
                 Ok(#root_ident::<B>(buffer))
             }
@@ -681,17 +575,6 @@ fn grouped_impl(root_ident: &syn::Ident, property: &Property) -> TokenStream {
     }
 }
 
-fn jitter_reduction_impl(root_ident: &syn::Ident, property: &Property) -> TokenStream {
-    let setter = property_setter(property, false);
-    let getter = property_getter(property, false);
-    quote! {
-        impl<B: crate::buffer::Ump> crate::traits::JitterReduced<B> for #root_ident<B> {
-            #getter
-            #setter
-        }
-    }
-}
-
 fn channeled_impl(
     root_ident: &syn::Ident,
     property: &Property,
@@ -721,10 +604,7 @@ fn from_bytes_impl(root_ident: &syn::Ident, properties: &Vec<Property>) -> Token
         {
             fn from_bytes(other: #root_ident<A>) -> Self {
                 let mut buffer = <B as crate::buffer::BufferDefault>::default();
-                buffer.resize(
-                    <#root_ident<B> as crate::traits::MinSize<B>>::min_size()
-                    + crate::buffer::OFFSET_FOR_JITTER_REDUCTION
-                );
+                buffer.resize(<#root_ident<B> as crate::traits::MinSize<B>>::min_size());
                 #convert_properties
                 Self(buffer)
             }
@@ -745,10 +625,7 @@ fn try_from_bytes_impl(root_ident: &syn::Ident, properties: &Vec<Property>) -> T
         {
             fn try_from_bytes(other: #root_ident<A>) -> core::result::Result<Self, crate::error::BufferOverflow> {
                 let mut buffer = <B as crate::buffer::BufferDefault>::default();
-                buffer.try_resize(
-                    <#root_ident<B> as crate::traits::MinSize<B>>::min_size()
-                    + crate::buffer::OFFSET_FOR_JITTER_REDUCTION
-                )?;
+                buffer.try_resize(<#root_ident<B> as crate::traits::MinSize<B>>::min_size())?;
                 #convert_properties
                 Ok(Self(buffer))
             }
@@ -860,9 +737,6 @@ pub fn generate_message(attrs: TokenStream1, item: TokenStream1) -> TokenStream1
     if args.fixed_size {
         tokens.extend(size_impl(root_ident, &args))
     }
-    if let Some(property) = properties.iter().find(|p| p.is_jitter_reduction()) {
-        tokens.extend(jitter_reduction_impl(root_ident, property));
-    }
     if let Some(property) = properties.iter().find(|p| p.is_group()) {
         tokens.extend(grouped_impl(root_ident, property));
     }