Module sortable 

Sortable numeric encoding for lexicographic key ordering.

This module provides utilities to encode signed integers and floating-point numbers into byte sequences that sort correctly when compared lexicographically (byte-by-byte). This is essential for key-value stores where keys are compared as raw bytes.

Why Sortable Encoding?

Standard binary representations don’t sort correctly:

• Signed integers: Two’s complement puts negative numbers after positive (e.g., -1 = 0xFF…FF sorts after 1 = 0x00…01)
• Floating point: IEEE 754 has complex sign/exponent/mantissa layout that doesn’t match numeric order (e.g., -0.5 sorts after 1.0 in raw bytes)

Encoding Schemes

Signed Integers (i64)

XOR with the sign bit mask (0x8000_0000_0000_0000):

• Flips the sign bit, making negative numbers have 0 in the high bit
• Negative numbers (originally 1xxx…) become (0xxx…) and sort first
• Positive numbers (originally 0xxx…) become (1xxx…) and sort second
• Preserves relative ordering within each group

Floating Point (f64)

IEEE 754 sortable encoding:

• If negative (sign bit set): flip ALL bits
• If positive (sign bit clear): flip only sign bit

This works because:

• Positive floats: flipping sign bit puts them in the 1xxx range
• Negative floats: flipping all bits reverses their order (more negative → smaller)
• Special values (NaN, infinity) are handled correctly

Usage

Encode values before writing to key bytes (big-endian for lexicographic order):

use common::serde::sortable::{encode_i64_sortable, decode_i64_sortable};

let value: i64 = -42;
let sortable = encode_i64_sortable(value);
let bytes = sortable.to_be_bytes(); // Use big-endian for keys

// Later, decode:
let recovered = decode_i64_sortable(u64::from_be_bytes(bytes));
assert_eq!(recovered, value);

Functions

decode_f64_sortable

Decode a sortable-encoded u64 back to the original f64 value.

decode_i64_sortable

Decode a sortable-encoded u64 back to the original i64 value.

encode_f64_sortable

Encode an f64 value for sortable byte comparison.

encode_i64_sortable

Encode an i64 value for sortable byte comparison.