biodream 0.2.5

Zero-copy, streaming-capable toolkit for reading and writing BIOPAC AcqKnowledge (.acq) files
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! Marker types — event annotations on physiological recordings.

use alloc::string::String;
use core::fmt;

/// Unix timestamp (seconds since 1970-01-01 00:00:00 UTC).
///
/// BIOPAC uses 1970-01-01 as its epoch reference (`REF_DATE` in bioread).
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Timestamp(pub i64);

impl Timestamp {
    /// Construct a timestamp from seconds since the Unix epoch.
    #[inline]
    pub const fn from_secs(secs: i64) -> Self {
        Self(secs)
    }

    /// Return the number of seconds since the Unix epoch.
    #[inline]
    pub const fn as_secs(self) -> i64 {
        self.0
    }
}

impl fmt::Display for Timestamp {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}s (unix)", self.0)
    }
}

/// Marker style, derived from the 4-character style code in the file.
///
/// Known codes from bioread:
/// - `"apnd"` → [`Append`](MarkerStyle::Append)
/// - `"usr1"`–`"usr8"` → [`UserEvent`](MarkerStyle::UserEvent)
/// - `"wave"` → [`Waveform`](MarkerStyle::Waveform)
/// - `"glbl"` → [`GlobalEvent`](MarkerStyle::GlobalEvent)
/// - anything else → [`Unknown`](MarkerStyle::Unknown)
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum MarkerStyle {
    /// Segment append / splice point (`"apnd"`).
    Append,
    /// User-defined event (`"usr1"`–`"usr8"`).
    UserEvent,
    /// Waveform marker (`"wave"`).
    Waveform,
    /// Global event marker (`"glbl"`).
    GlobalEvent,
    /// Style code not recognised by this library.
    Unknown(String),
}

impl MarkerStyle {
    /// Parse a 4-character style code from the marker header.
    pub fn from_code(code: &str) -> Self {
        match code.trim_end_matches('\0') {
            "apnd" => Self::Append,
            s if s.starts_with("usr") => Self::UserEvent,
            "wave" => Self::Waveform,
            "glbl" => Self::GlobalEvent,
            other => Self::Unknown(other.into()),
        }
    }
}

impl fmt::Display for MarkerStyle {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Append => write!(f, "Append"),
            Self::UserEvent => write!(f, "UserEvent"),
            Self::Waveform => write!(f, "Waveform"),
            Self::GlobalEvent => write!(f, "GlobalEvent"),
            Self::Unknown(s) => write!(f, "Unknown({s})"),
        }
    }
}

/// A single event marker on the timeline of a recording.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Marker {
    /// Human-readable label (from marker text).
    pub label: String,
    /// Global sample index at which this marker occurs.
    pub global_sample_index: usize,
    /// Which channel this marker is attached to, or `None` for a global marker.
    ///
    /// Corresponds to `nChannel == -1` in the file (global) or the channel's
    /// display-order index.
    pub channel: Option<usize>,
    /// Visual style of the marker.
    pub style: MarkerStyle,
    /// Timestamp when the marker was created (v4.4.0+ files only).
    pub created_at: Option<Timestamp>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn marker_style_apnd() {
        assert_eq!(MarkerStyle::from_code("apnd"), MarkerStyle::Append);
    }

    #[test]
    fn marker_style_user_events() {
        assert_eq!(MarkerStyle::from_code("usr1"), MarkerStyle::UserEvent);
        assert_eq!(MarkerStyle::from_code("usr8"), MarkerStyle::UserEvent);
    }

    #[test]
    fn marker_style_unknown() {
        let s = MarkerStyle::from_code("xyzw");
        assert!(matches!(s, MarkerStyle::Unknown(_)));
    }

    #[test]
    fn marker_style_unknown_with_null_padding() {
        // Style codes from the file may be null-padded.
        let s = MarkerStyle::from_code("apnd\0");
        assert_eq!(s, MarkerStyle::Append);
    }

    #[test]
    fn timestamp_round_trip() {
        let ts = Timestamp::from_secs(1_700_000_000);
        assert_eq!(ts.as_secs(), 1_700_000_000);
    }
}