Trait ALPFloat 

pub trait ALPFloat:
    Sealed
    + Float
    + Display
    + 'static {
    type ALPInt: PrimInt + Display + ToPrimitive;

    const FRACTIONAL_BITS: u8;
    const MAX_EXPONENT: u8;
    const SWEET: Self;
    const F10: &'static [Self];
    const IF10: &'static [Self];

    // Required methods
    fn as_int(self) -> Self::ALPInt;
    fn from_int(n: Self::ALPInt) -> Self;
    fn is_eq(self, other: Self) -> bool;

    // Provided methods
    fn fast_round(self) -> Self { ... }
    fn find_best_exponents(values: &[Self]) -> Exponents { ... }
    fn estimate_encoded_size_for_exponents(
        values: &[Self],
        exponents: Exponents,
    ) -> usize { ... }
    fn estimate_encoded_size(
        encoded: &[Self::ALPInt],
        patches: &[Self],
    ) -> usize { ... }
    fn encode(
        values: &[Self],
        exponents: Option<Exponents>,
    ) -> (Exponents, Vec<Self::ALPInt>, Vec<u64>, Vec<Self>, Vec<u64>) { ... }
    fn encode_into(
        values: &[Self],
        exponents: Option<Exponents>,
        encoded: &mut [MaybeUninit<Self::ALPInt>],
        patch_indices: &mut Vec<u64>,
        patch_values: &mut Vec<Self>,
        chunk_offsets: &mut Vec<u64>,
    ) -> Exponents { ... }
    fn encode_above(value: Self, exponents: Exponents) -> Self::ALPInt { ... }
    fn encode_below(value: Self, exponents: Exponents) -> Self::ALPInt { ... }
    fn encode_single(value: Self, exponents: Exponents) -> Option<Self::ALPInt> { ... }
    fn decode(encoded: &[Self::ALPInt], exponents: Exponents) -> Vec<Self> { ... }
    fn decode_into(
        encoded: &[Self::ALPInt],
        exponents: Exponents,
        output: &mut [Self],
    ) { ... }
    fn decode_slice_inplace(encoded: &mut [Self::ALPInt], exponents: Exponents) { ... }
    fn decode_single(encoded: Self::ALPInt, exponents: Exponents) -> Self { ... }
    fn encode_single_unchecked(
        value: Self,
        exponents: Exponents,
    ) -> Self::ALPInt { ... }
}

Main trait for classic-ALP encodable floating-point numbers.

We limit this to the IEEE 754 single-precision (f32) and double-precision (f64) floating-point types.

Required Associated Constants

const FRACTIONAL_BITS: u8

Number of fractional (mantissa) bits the type holds.

const MAX_EXPONENT: u8

Exclusive upper bound on the exponents Self::find_best_exponents tries, set by the largest power of ten Self::ALPInt can hold.

const SWEET: Self

The value Self::fast_round adds and subtracts to round without branching: the smallest magnitude above which the type holds no fractional part at all.

const F10: &'static [Self]

Powers of ten, 10^i at index i.

const IF10: &'static [Self]

Inverse powers of ten, 10^-i at index i.

Required Associated Types

type ALPInt: PrimInt + Display + ToPrimitive

The signed integer type of the same width, which values of this type encode to.

Required Methods

fn as_int(self) -> Self::ALPInt

Casts the primitive float to the target integer type, equivalent to calling as.

fn from_int(n: Self::ALPInt) -> Self

Converts from the integer type back to the float type using as.

fn is_eq(self, other: Self) -> bool

Compares bit-wise, so that NaNs and signed zeros are distinct values.

Provided Methods

fn fast_round(self) -> Self

Rounds to the nearest floating integer by shifting in and out of the low precision range.

fn find_best_exponents(values: &[Self]) -> Exponents

Finds the exponent pair with the smallest estimated encoded size.

Inputs longer than a few dozen values are sampled rather than scanned in full, since the number of decimal digits a column uses is a property of the column rather than of any one value.

fn estimate_encoded_size_for_exponents( values: &[Self], exponents: Exponents, ) -> usize

Estimates the encoded size of values under exponents, matching a full Self::encode plus Self::estimate_encoded_size but without the per-candidate allocations.

fn estimate_encoded_size(encoded: &[Self::ALPInt], patches: &[Self]) -> usize

Estimates the bytes encoded and patches occupy once cascaded, assuming the encoded values get a frame of reference and are bit-packed, and the patches are stored as they are.

fn encode( values: &[Self], exponents: Option<Exponents>, ) -> (Exponents, Vec<Self::ALPInt>, Vec<u64>, Vec<Self>, Vec<u64>)

Encodes values, finding the best exponents if they are not provided.

Returns the exponents, the encoded values, the positions and values of the exceptions, and the offset into the exception positions at which each ENCODE_CHUNK_SIZE chunk begins.

Use Self::encode_into if the encoded values should land in a buffer you own, which is what you want if you intend to decode them in place later.

fn encode_into( values: &[Self], exponents: Option<Exponents>, encoded: &mut [MaybeUninit<Self::ALPInt>], patch_indices: &mut Vec<u64>, patch_values: &mut Vec<Self>, chunk_offsets: &mut Vec<u64>, ) -> Exponents

Encodes values into an output buffer owned by the caller, returning the exponents used.

encoded must hold exactly values.len() elements, all of which are initialized on return. The exception positions and values, plus one offset into the exception positions per ENCODE_CHUNK_SIZE chunk, are appended to the three vectors, which must start empty.

This exists so that the encoded values can be written straight into a buffer the caller controls (an arena, an aligned buffer, or anything else it will later decode in place), rather than into a Vec that has to be adopted or copied afterwards.

Panics

Panics if encoded is not the same length as values, or if any of patch_indices, patch_values or chunk_offsets is non-empty.

fn encode_above(value: Self, exponents: Exponents) -> Self::ALPInt

Encodes a single value, rounding up instead of to the nearest integer.

fn encode_below(value: Self, exponents: Exponents) -> Self::ALPInt

Encodes a single value, rounding down instead of to the nearest integer.

fn encode_single(value: Self, exponents: Exponents) -> Option<Self::ALPInt>

Encodes a single value, returning None if it does not round-trip under exponents.

fn decode(encoded: &[Self::ALPInt], exponents: Exponents) -> Vec<Self>

Decodes encoded into a newly allocated vector.

fn decode_into( encoded: &[Self::ALPInt], exponents: Exponents, output: &mut [Self], )

Decodes encoded into output.

Panics

Panics if encoded and output have different lengths.

fn decode_slice_inplace(encoded: &mut [Self::ALPInt], exponents: Exponents)

Decodes encoded in-place, reinterpreting the slice as floats of the same width.

fn decode_single(encoded: Self::ALPInt, exponents: Exponents) -> Self

Decodes a single value, undoing the scaling exponents applied.

fn encode_single_unchecked(value: Self, exponents: Exponents) -> Self::ALPInt

Encodes a single value without checking that it round-trips.

The returned value might decode to a different value than the one passed in. Use Self::encode_single for the checked version.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl ALPFloat for f32

const FRACTIONAL_BITS: u8 = 23

const MAX_EXPONENT: u8 = 10

const SWEET: f32

const F10: &'static [f32]

const IF10: &'static [f32]

type ALPInt = i32

fn as_int(self) -> <f32 as ALPFloat>::ALPInt

fn from_int(n: <f32 as ALPFloat>::ALPInt) -> f32

fn is_eq(self, other: f32) -> bool

impl ALPFloat for f64

const FRACTIONAL_BITS: u8 = 52

const MAX_EXPONENT: u8 = 18

const SWEET: f64

const F10: &'static [f64]

const IF10: &'static [f64]

type ALPInt = i64

fn as_int(self) -> <f64 as ALPFloat>::ALPInt

fn from_int(n: <f64 as ALPFloat>::ALPInt) -> f64

fn is_eq(self, other: f64) -> bool

Implementors