helgoboss_midi/
test_util.rs

1//! Contains convenience functions for creating messages with minimum boilerplate
2//!
3//! Intended to be used primarily in test or demo code.
4//!
5//! # Example
6//!
7//! ```
8//! use helgoboss_midi::test_util::*;
9//!
10//! let msg_1 = short(0x90, 4, 5);
11//! let msg_2 = note_on(3, 40, 100);
12//! let msg_3 = pitch_bend_change(4, 2478);
13//! let msg_4 = nrpn_14_bit(4, 380, 12000);
14//! let msg_5 = control_change_14_bit(2, 2, 2056);
15//! let ch = channel(3);
16//! let kn = key_number(64);
17//! ```
18use crate::{
19    Channel, ControlChange14BitMessage, ControllerNumber, KeyNumber, ParameterNumberMessage,
20    RawShortMessage, ShortMessageFactory, TimeCodeQuarterFrame, U14, U4, U7,
21};
22use core::convert::TryInto;
23
24type Msg = RawShortMessage;
25
26use channel as ch;
27use controller_number as cn;
28use key_number as kn;
29
30/// Creates a 4-bit integer value.
31///
32/// # Panics
33///
34/// Panics if the given value is greater than 15.
35pub fn u4(value: u8) -> U4 {
36    value.try_into().expect("not a valid 4-bit integer")
37}
38
39/// Creates a 7-bit integer value.
40///
41/// # Panics
42///
43/// Panics if the given value is greater than 127.
44pub fn u7(value: u8) -> U7 {
45    value.try_into().expect("not a valid 7-bit integer")
46}
47
48/// Creates a 14-bit integer value.
49///
50/// # Panics
51///
52/// Panics if the given value is higher than 16383.
53pub fn u14(value: u16) -> U14 {
54    value.try_into().expect("not a valid 14-bit integer")
55}
56
57/// Creates a channel.
58///
59/// # Panics
60///
61/// Panics if the given value is higher than 15.
62pub fn channel(value: u8) -> Channel {
63    value.try_into().expect("not a valid channel")
64}
65
66/// Creates a key number.
67///
68/// # Panics
69///
70/// Panics if the given value is higher than 127.
71pub fn key_number(value: u8) -> KeyNumber {
72    value.try_into().expect("not a valid key number")
73}
74
75/// Creates a controller number.
76///
77/// # Panics
78///
79/// Panics if the given value is higher than 127.
80pub fn controller_number(value: u8) -> ControllerNumber {
81    value.try_into().expect("not a valid controller number")
82}
83
84/// Creates a short message from raw bytes.
85///
86/// # Panics
87///
88/// Panics if one of the given values is out of range or if the status byte is invalid.
89pub fn short(status_byte: u8, data_byte_1: u8, data_byte_2: u8) -> Msg {
90    Msg::from_bytes((status_byte, u7(data_byte_1), u7(data_byte_2))).expect("invalid status byte")
91}
92
93/// Creates a Note On message.
94///
95/// # Panics
96///
97/// Panics if one of the given values is out of range.
98pub fn note_on(channel: u8, key_number: u8, velocity: u8) -> Msg {
99    Msg::note_on(ch(channel), kn(key_number), u7(velocity))
100}
101
102/// Creates a Note Off message.
103///
104/// # Panics
105///
106/// Panics if one of the given values is out of range.
107pub fn note_off(channel: u8, key_number: u8, velocity: u8) -> Msg {
108    Msg::note_off(ch(channel), kn(key_number), u7(velocity))
109}
110
111/// Creates a Control Change message.
112///
113/// # Panics
114///
115/// Panics if one of the given values is out of range.
116pub fn control_change(channel: u8, controller_number: u8, control_value: u8) -> Msg {
117    Msg::control_change(ch(channel), cn(controller_number), u7(control_value))
118}
119
120/// Creates a Program Change message.
121///
122/// # Panics
123///
124/// Panics if one of the given values is out of range.
125pub fn program_change(channel: u8, program_number: u8) -> Msg {
126    Msg::program_change(ch(channel), u7(program_number))
127}
128
129/// Creates a Polyphonic Key Pressure message.
130///
131/// # Panics
132///
133/// Panics if one of the given values is out of range.
134pub fn polyphonic_key_pressure(channel: u8, key_number: u8, pressure_amount: u8) -> Msg {
135    Msg::polyphonic_key_pressure(ch(channel), kn(key_number), u7(pressure_amount))
136}
137
138/// Creates a Channel Pressure message.
139///
140/// # Panics
141///
142/// Panics if one of the given values is out of range.
143pub fn channel_pressure(channel: u8, pressure_amount: u8) -> Msg {
144    Msg::channel_pressure(ch(channel), u7(pressure_amount))
145}
146
147/// Creates a Pitch Bend Change message.
148///
149/// # Panics
150///
151/// Panics if one of the given values is out of range.
152pub fn pitch_bend_change(channel: u8, pitch_bend_value: u16) -> Msg {
153    Msg::pitch_bend_change(ch(channel), u14(pitch_bend_value))
154}
155
156/// Creates a System Exclusive Start message.
157pub fn system_exclusive_start() -> Msg {
158    Msg::system_exclusive_start()
159}
160
161/// Creates a Time Code Quarter Frame message.
162pub fn time_code_quarter_frame(frame: TimeCodeQuarterFrame) -> Msg {
163    Msg::time_code_quarter_frame(frame)
164}
165
166/// Creates a Song Position Pointer message.
167///
168/// # Panics
169///
170/// Panics if the given value is out of range.
171pub fn song_position_pointer(position: u16) -> Msg {
172    Msg::song_position_pointer(u14(position))
173}
174
175/// Creates a Song Select message.
176///
177/// # Panics
178///
179/// Panics if the given value is out of range.
180pub fn song_select(song_number: u8) -> Msg {
181    Msg::song_select(u7(song_number))
182}
183
184/// Creates a Tune Request message.
185pub fn tune_request() -> Msg {
186    Msg::tune_request()
187}
188
189/// Creates a System Exclusive End message.
190pub fn system_exclusive_end() -> Msg {
191    Msg::system_exclusive_end()
192}
193
194/// Creates a Timing Clock message.
195pub fn timing_clock() -> Msg {
196    Msg::timing_clock()
197}
198
199/// Creates a start message.
200pub fn start() -> Msg {
201    Msg::start()
202}
203
204/// Creates a continue message.
205pub fn r#continue() -> Msg {
206    Msg::r#continue()
207}
208
209/// Creates a stop message.
210pub fn stop() -> Msg {
211    Msg::stop()
212}
213
214/// Creates an Active Sensing message.
215pub fn active_sensing() -> Msg {
216    Msg::active_sensing()
217}
218
219/// Creates a System Reset message.
220pub fn system_reset() -> Msg {
221    Msg::system_reset()
222}
223
224/// Creates a 14-bit Control Change message.
225///
226/// # Panics
227///
228/// Panics if one of the given values is out of range.
229pub fn control_change_14_bit(
230    channel: u8,
231    msb_controller_number: u8,
232    value: u16,
233) -> ControlChange14BitMessage {
234    ControlChange14BitMessage::new(ch(channel), cn(msb_controller_number), u14(value))
235}
236
237/// Creates a non-registered 7-bit Parameter Number message.
238///
239/// # Panics
240///
241/// Panics if one of the given values is out of range.
242pub fn nrpn(channel: u8, number: u16, value: u8) -> ParameterNumberMessage {
243    ParameterNumberMessage::non_registered_7_bit(ch(channel), u14(number), u7(value))
244}
245
246/// Creates an non-registered 14-bit Parameter Number message.
247///
248/// # Panics
249///
250/// Panics if one of the given values is out of range.
251pub fn nrpn_14_bit(channel: u8, number: u16, value: u16) -> ParameterNumberMessage {
252    ParameterNumberMessage::non_registered_14_bit(ch(channel), u14(number), u14(value))
253}
254
255/// Creates an registered 7-bit Parameter Number message.
256///
257/// # Panics
258///
259/// Panics if one of the given values is out of range.
260pub fn rpn(channel: u8, number: u16, value: u8) -> ParameterNumberMessage {
261    ParameterNumberMessage::registered_7_bit(ch(channel), u14(number), u7(value))
262}
263
264/// Creates an registered 14-bit Parameter Number message.
265///
266/// # Panics
267///
268/// Panics if one of the given values is out of range.
269pub fn rpn_14_bit(channel: u8, number: u16, value: u16) -> ParameterNumberMessage {
270    ParameterNumberMessage::registered_14_bit(ch(channel), u14(number), u14(value))
271}
helgoboss_midi/test_util.rs

helgoboss_midi/
test_util.rs
