pco 1.0.2

Good compression for numerical sequences
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
134
135
136
137
138
139
140
141

use std::fmt::Display;
use std::io::Write;

use crate::bit_reader::BitReader;
use crate::bit_writer::BitWriter;
use crate::errors::{PcoError, PcoResult};

/// The format version of pco used to compress a file.
///
/// During compression, this gets stored in the file.
/// Version can affect the encoding of the rest of the file, so older versions
/// of pco might return corruption errors when running on data compressed
/// by newer versions.
/// Pco will attempt to decompress if it's possible the library can read the
/// file (the library supports the file's major version), even if it's possible
/// the library will fail later in the file (which can happen if the library
/// doesn't yet support the file's minor version).
///
/// You will not need to manually instantiate this.
/// However, in some circumstances you may want to inspect this during
/// decompression.
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct FormatVersion {
  pub major: u8,
  pub minor: u8,
}

/// The default FormatVersion is used when compressing files.
impl Default for FormatVersion {
  fn default() -> Self {
    Self { major: 4, minor: 1 }
  }
}

impl Display for FormatVersion {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    write!(f, "{}.{}", self.major, self.minor)
  }
}

impl FormatVersion {
  pub(crate) const MAX_ENCODED_SIZE: usize = 2;

  /// Returns the max format version that can definitely be decompressed by the
  /// current library version.
  pub fn max_supported() -> Self {
    Self { major: 4, minor: 1 }
  }

  /// Returns whether this format version can definitely be read by the current
  /// library version, or None if it can maybe be decompressed without a
  /// guarantee.
  pub fn can_be_decompressed(&self) -> Option<bool> {
    let max_supported = FormatVersion::max_supported();
    if max_supported >= *self {
      Some(true)
    } else if max_supported.major >= self.major {
      None
    } else {
      Some(false)
    }
  }

  pub(crate) fn read_from(reader: &mut BitReader) -> PcoResult<Self> {
    let major = reader.read_aligned_bytes(1)?[0];
    let minor = if major >= 4 {
      reader.read_aligned_bytes(1)?[0]
    } else {
      0
    };
    let file_version = FormatVersion { major, minor };

    if file_version.can_be_decompressed() == Some(false) {
      return Err(PcoError::corruption(format!(
        "File's format version ({}) definitely cannot be decompressed by this \
        library version; its major version is less than the max supported {}. \
        Consider upgrading Pco.",
        file_version,
        FormatVersion::default(),
      )));
    }

    Ok(file_version)
  }

  pub(crate) fn write_to<W: Write>(&self, writer: &mut BitWriter<W>) -> PcoResult<usize> {
    assert!(self.major >= 4);
    writer.write_aligned_bytes(&[self.major, self.minor])?;
    Ok(2)
  }

  pub(crate) fn used_old_gcds(&self) -> bool {
    self.major == 0
  }

  pub(crate) fn supports_delta_variants(&self) -> bool {
    self.major >= 3
  }
}

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

  #[test]
  fn max_supported_exceeds_default() {
    assert!(FormatVersion::max_supported() >= FormatVersion::default());
  }

  #[test]
  fn ordering_properties() {
    let a = FormatVersion { major: 1, minor: 5 };
    let b = FormatVersion { major: 2, minor: 4 };
    let c = FormatVersion { major: 2, minor: 6 };

    assert!(a < b);
    assert!(b < c);
  }

  #[test]
  fn can_be_decompressed() {
    let past_version = FormatVersion {
      major: 0,
      minor: 50,
    };
    assert!(past_version.can_be_decompressed() == Some(true));

    let uncertain_version = FormatVersion {
      major: FormatVersion::max_supported().major,
      minor: 200,
    };
    assert!(uncertain_version.can_be_decompressed() == None);

    let future_version = FormatVersion {
      major: 200,
      minor: 0,
    };
    assert!(future_version.can_be_decompressed() == Some(false));
  }
}