rd-rds 0.0.1

Read-only reader for the subset of R's RDS serialization format used by installed-package help databases
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

use crate::{ByteCursor, Error};

/// The serialized RDS stream header.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Header {
    pub format_version: u32,
    pub writer_version: RVersion,
    pub minimum_reader_version: RVersion,
    pub native_encoding: Option<String>,
}

impl Header {
    pub fn parse(cursor: &mut ByteCursor<'_>) -> Result<Self, Error> {
        let marker_offset = cursor.position();
        let marker = cursor.read_exact(2)?;
        if marker != b"X\n" {
            return Err(Error::UnsupportedMarker {
                marker: [marker[0], marker[1]],
                offset: marker_offset,
            });
        }

        let version_offset = cursor.position();
        let format_version = cursor.read_be_u32()?;
        if format_version != 2 && format_version != 3 {
            return Err(Error::UnsupportedVersion {
                version: format_version,
                offset: version_offset,
            });
        }

        let writer_version = RVersion::from_raw(cursor.read_be_u32()?);
        let minimum_reader_version = RVersion::from_raw(cursor.read_be_u32()?);

        let native_encoding = if format_version == 3 {
            let byte_len = cursor.read_be_u32()? as usize;
            let encoding_offset = cursor.position();
            let encoding = cursor.read_exact(byte_len)?;
            Some(
                String::from_utf8(encoding.to_vec()).map_err(|_| Error::InvalidUtf8 {
                    offset: encoding_offset,
                })?,
            )
        } else {
            None
        };

        Ok(Self {
            format_version,
            writer_version,
            minimum_reader_version,
            native_encoding,
        })
    }
}

/// An R version encoded in the serializer's packed `major * 65536 + minor * 256 + patch` form.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RVersion {
    raw: u32,
}

impl RVersion {
    pub fn from_raw(raw: u32) -> Self {
        Self { raw }
    }

    pub fn raw(self) -> u32 {
        self.raw
    }

    pub fn components(self) -> (u32, u32, u32) {
        (self.raw >> 16, (self.raw >> 8) & 0xff, self.raw & 0xff)
    }
}

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

    #[test]
    fn truncated_input_returns_offset() {
        let mut cursor = ByteCursor::new(b"X\n");
        let err = Header::parse(&mut cursor).unwrap_err();
        assert!(matches!(
            err,
            Error::UnexpectedEof {
                offset: 2,
                needed: 4,
                remaining: 0
            }
        ));
    }

    #[test]
    fn wrong_marker_is_reported() {
        let mut cursor = ByteCursor::new(b"A\n\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x00");
        let err = Header::parse(&mut cursor).unwrap_err();
        assert!(matches!(
            err,
            Error::UnsupportedMarker {
                marker: [b'A', b'\n'],
                offset: 0
            }
        ));
    }

    #[test]
    fn unsupported_version_is_reported() {
        let mut cursor = ByteCursor::new(b"X\n\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00");
        let err = Header::parse(&mut cursor).unwrap_err();
        assert!(matches!(
            err,
            Error::UnsupportedVersion {
                version: 4,
                offset: 2
            }
        ));
    }
}