Crate decimal_bytes 

decimal-bytes

Arbitrary precision decimals with lexicographically sortable byte encoding.

This crate provides two decimal types optimized for database storage:

• Decimal: Variable-length arbitrary precision (up to 131,072 digits)
• Decimal64: Fixed 8-byte representation with embedded scale (precision ≤ 16 digits)

Both types support PostgreSQL special values (NaN, ±Infinity) with correct sort ordering.

When to Use Which

Type	Precision	Scale	Storage	Best For
Decimal64	≤ 16 digits	0-18 (embedded)	8 bytes	Financial data, self-contained values
Decimal	Unlimited	Unlimited	Variable	Scientific, very large numbers

Decimal64 Example

use decimal_bytes::Decimal64;

// Create with embedded scale
let price = Decimal64::new("99.99", 2).unwrap();
assert_eq!(price.to_string(), "99.99");
assert_eq!(price.scale(), 2);  // Scale is embedded!

// With precision and scale (PostgreSQL NUMERIC semantics)
let d = Decimal64::with_precision_scale("123.456", Some(5), Some(2)).unwrap();
assert_eq!(d.to_string(), "123.46"); // Rounded

// Parse with automatic scale detection
let d: Decimal64 = "123.456".parse().unwrap();
assert_eq!(d.scale(), 3);

// Special values
let inf = Decimal64::infinity();
let nan = Decimal64::nan();
assert!(price < inf);
assert!(inf < nan);

Decimal Example (Arbitrary Precision)

use decimal_bytes::Decimal;
use std::str::FromStr;

// Create decimals
let a = Decimal::from_str("123.456").unwrap();
let b = Decimal::from_str("123.457").unwrap();

// Byte comparison matches numerical comparison
assert!(a.as_bytes() < b.as_bytes());
assert!(a < b);

// Special values (PostgreSQL compatible)
let inf = Decimal::infinity();
let nan = Decimal::nan();
assert!(a < inf);
assert!(inf < nan);

Sort Order

The lexicographic byte order matches PostgreSQL NUMERIC:

-Infinity < negative numbers < zero < positive numbers < +Infinity < NaN

Both Decimal and Decimal64 support this sort order including special values.

Special Value Semantics (PostgreSQL vs IEEE 754)

The Decimal type follows PostgreSQL semantics for special values:

Behavior	PostgreSQL / decimal-bytes	IEEE 754 float
NaN == NaN	true	false
NaN ordering	Greatest value (> Infinity)	Unordered
Infinity == Infinity	true	true

use decimal_bytes::Decimal;

let nan1 = Decimal::nan();
let nan2 = Decimal::nan();
let inf = Decimal::infinity();

// NaN equals itself (PostgreSQL behavior, unlike IEEE 754)
assert_eq!(nan1, nan2);

// NaN is greater than everything, including Infinity
assert!(nan1 > inf);

This makes Decimal suitable for use in indexes, sorting, and deduplication where consistent ordering and equality semantics are required.

Structs

Decimal

An arbitrary precision decimal number stored as sortable bytes.

Decimal64

A fixed-precision decimal stored as a 64-bit integer with embedded scale.

Enums

DecimalError

Errors that can occur during decimal encoding/decoding.

SpecialValue

Special decimal values (IEEE 754 / PostgreSQL compatible)

Constants

MAX_DECIMAL64_PRECISION

Maximum precision that fits in 56-bit value (16 digits).

MAX_DECIMAL64_SCALE

Maximum scale supported (0-18).