fastalp 0.1.26

High-performance lossless floating-point compression in pure Rust / 基于 ALP 算法的高性能无损浮点数压缩库
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

mod f32;
mod f64;

use crate::params::bits_needed;

/// ALP floating-point abstraction trait (unifies zero-cost f32 and f64 compression).
/// ALP 浮点数抽象特征（统一 f32 / f64 零成本编解码）
pub trait AlpFloat: Copy + Default + PartialEq + PartialOrd + Send + Sync + 'static {
  type Int: Copy + Default + PartialEq + Eq + PartialOrd + Ord + Send + Sync + 'static;
  type RawBits: Copy + Default + PartialEq + Eq + Send + Sync + 'static;

  const TYPE_BYTE: u8;
  const TYPE_RAW_BYTE: u8;
  const TYPE_DELTA_BYTE: u8;
  const TYPE_DEC_BYTE: u8;
  const TYPE_DEC_DELTA_BYTE: u8;
  const MAX_EXPONENT: u8;
  const MAX_FAC: u8;
  const MAX_BIT_WIDTH: u8;
  const MAGIC_NUMBER: Self;
  const ENCODING_UPPER_LIMIT: Self;
  const EXCEPTION_PENALTY: usize;
  const EXC_ENTRY_SIZE: usize;
  const EXC_ENTRY_SIZE_U32: usize;
  const BASE_SIZE: usize;
  const ZERO: Self;
  const ZERO_INT: Self::Int;
  const MIN_INT: Self::Int;
  const MAX_INT: Self::Int;

  fn exp_factor(exp: u8, fac: u8) -> Self;
  fn fac_int(fac: u8) -> i64;
  fn frac_exp(exp: u8) -> Self;

  fn is_impossible(self) -> bool;
  fn try_encode_fast(self, exp_factor: Self, fac_int: i64, frac_exp: Self) -> Option<Self::Int>;
  fn try_encode_div(self, exp_factor: Self) -> Option<Self::Int>;
  fn fast_round_to_int(self, exp_factor: Self) -> Self::Int;
  fn decode_from_int(encoded: Self::Int, fac_int: i64, frac_exp: Self) -> Self;
  fn decode_from_offset(offset: u64, base: Self::Int, fac_int: i64, frac_exp: Self) -> Self;
  fn decode_from_int_div(encoded: Self::Int, exp_factor: Self) -> Self;
  fn decode_from_offset_div(offset: u64, base: Self::Int, exp_factor: Self) -> Self;

  fn int_diff_to_u64(val: Self::Int, base: Self::Int) -> u64;
  fn u64_to_int_add(offset: u64, base: Self::Int) -> Self::Int;
  fn calc_range(min_val: Self::Int, max_val: Self::Int) -> u64;

  fn int_sub(a: Self::Int, b: Self::Int) -> Self::Int;
  fn int_add(a: Self::Int, b: Self::Int) -> Self::Int;

  #[inline(always)]
  fn bits_needed(max_offset: u64) -> u8 {
    bits_needed(max_offset)
  }

  fn to_raw_bits(self) -> Self::RawBits;
  fn from_raw_bits(bits: Self::RawBits) -> Self;

  /// Strictly checks whether two floating-point values are bitwise identical (distinguishes +0.0 and -0.0).
  /// 基于底层二进制比特位严格判断两浮点数是否完全相同（可区分 +0.0 与 -0.0）
  #[inline(always)]
  fn is_exact_same(self, other: Self) -> bool {
    self.to_raw_bits() == other.to_raw_bits()
  }

  fn write_base(base: Self::Int, dst: &mut Vec<u8>);
  fn read_base(src: &[u8]) -> Self::Int;

  fn write_exception(pos: u16, bits: Self::RawBits, dst: &mut Vec<u8>);
  fn read_exception(chunk: &[u8]) -> (usize, Self);

  fn write_exception_u32(pos: u32, bits: Self::RawBits, dst: &mut Vec<u8>);
  fn read_exception_u32(chunk: &[u8]) -> (usize, Self);

  /// Decodes a floating-point value from offset and base when factor is 1 (scale = 10^-exp).
  /// 当因子为 1 时根据基准值与逆缩放因子快速解码浮点数
  fn decode_from_offset_fac1(offset: u64, base: Self::Int, frac_exp: Self) -> Self;

  #[inline(always)]
  fn build_lut<const N: usize>(base: Self::Int, fac_int: i64, frac_exp: Self) -> [Self; N] {
    let mut lut = [Self::ZERO; N];
    for (i, slot) in lut.iter_mut().enumerate() {
      *slot = Self::decode_from_offset(i as u64, base, fac_int, frac_exp);
    }
    lut
  }

  #[inline(always)]
  fn build_lut_div<const N: usize>(base: Self::Int, exp_factor: Self) -> [Self; N] {
    let mut lut = [Self::ZERO; N];
    for (i, slot) in lut.iter_mut().enumerate() {
      *slot = Self::decode_from_offset_div(i as u64, base, exp_factor);
    }
    lut
  }
}