Skip to main content

Crate decimix_finance

Crate decimix_finance 

Source
Expand description

§decimix-finance

Domain types for trading, built on decimix: Price, Qty, DeltaQty, Amt and Percentage.

Each wraps a 19-decimal-place number, and they can’t be mixed by accident: adding a price to a quantity doesn’t compile.

The names and meanings follow the FIX 5 datatypes, so a FIX field maps to the type of the same name:

FIX datatypeTypeMeaning
PricePricea price; may be negative
QtyQtya quantity; here, never negative
—DeltaQtya quantity that may be negative
AmtAmttypically price × quantity: a cash value
PercentagePercentagea fraction: 0.05 means 5%

FIX has no separate signed-quantity type; DeltaQty is this crate’s addition, so that Qty can promise it is never negative. FIX’s PriceOffset is not provided yet.

§Quantities: Qty and DeltaQty

A quantity comes in two forms. Qty can never be negative: an order size, a fill, a lot. DeltaQty is a quantity that can be: a position, a net fill, a change in either. Both are the same kind of thing, so the rules for quantities apply to both. The Quantity trait expresses that: price × quantity is defined once, for either form, rather than once per sign.

use decimix::{dec, udec};
use decimix_finance::{DeltaQty, Qty};

let ordered = Qty::new(udec!(1000));
let filled = Qty::new(udec!(250));
let leaves: Qty = ordered - filled; // panics if it would go negative
assert_eq!(leaves, Qty::new(udec!(750)));
let delta: DeltaQty = filled.signed_sub(ordered); // may be negative
assert_eq!(delta, DeltaQty::new(dec!(-750)));
assert_eq!(delta.unsigned_abs(), leaves);

§Price × quantity is an amount

Multiplying a price by either form of quantity gives an Amt: the cash value (the consideration), negative when the price or quantity is. Like every decimal product, it names its rounding.

use decimix::{Round, dec, udec};
use decimix_finance::{DeltaQty, Amt, Price, Qty, Percentage};

let px = Price::new(dec!(113.725));

let bought: Amt = px.mul(Qty::new(udec!(250)), Round::HalfEven);
assert_eq!(bought, Amt::new(dec!(28431.25)));

let short: Amt = px.mul(DeltaQty::new(dec!(-250)), Round::HalfEven);
assert_eq!(short, Amt::new(dec!(-28431.25)));

let fee = bought.mul(Percentage::new(dec!(0.0002)), Round::HalfEven);
assert_eq!(fee, Amt::new(dec!(5.68625)));

§What doesn’t compile, on purpose

A price times a quantity is neither a quantity nor a price:

ⓘ
use decimix::{Round, dec, udec};
use decimix_finance::{DeltaQty, Price, Qty};
let px = Price::new(dec!(1.5));
let a: DeltaQty = px.mul(Qty::new(udec!(2)), Round::HalfEven);
ⓘ
use decimix::{Round, dec, udec};
use decimix_finance::{Price, Qty};
let px = Price::new(dec!(1.5));
let p: Price = px.mul(Qty::new(udec!(2)), Round::HalfEven);

Price × price, and price × amount, mean nothing:

ⓘ
use decimix::{Round, dec};
use decimix_finance::Price;
let px = Price::new(dec!(1.5));
let x = px.mul(px, Round::HalfEven);
ⓘ
use decimix::{Round, dec};
use decimix_finance::{Amt, Price};
let x = Price::new(dec!(1.5)).mul(Amt::new(dec!(2)), Round::HalfEven);

Different kinds don’t add, and signed and unsigned quantities don’t mix without saying how:

ⓘ
use decimix::{dec, udec};
use decimix_finance::{Price, Qty};
let x = Price::new(dec!(1.5)) + Qty::new(udec!(2));
ⓘ
use decimix::{dec, udec};
use decimix_finance::{DeltaQty, Qty};
let x = DeltaQty::new(dec!(-1)) + Qty::new(udec!(2));
ⓘ
use decimix::udec;
use decimix_finance::Qty;
let q = -Qty::new(udec!(2));

Domain types have no f64 methods; floats go through the base type, where a lint can catch them:

ⓘ
use decimix::dec;
use decimix_finance::Price;
let f = Price::new(dec!(1.5)).to_f64_lossy();

Structs§

Amt
An amount of money: typically price × quantity (the consideration), or a fee, a P&L. FIX datatype Amt.
DeltaQty
A quantity that can be negative: a position, a net fill, a change in either. FIX has no datatype for this; it uses Qty for both.
Percentage
A percentage, held as a fraction: 0.05 means 5%, 0.9525 means 95.25%. FIX datatype Percentage. For fee rates, FX rates and other ratios.
Price
A price. May be negative (spreads, some futures and power markets). FIX datatype Price.
Qty
A quantity that can’t be negative: an order size, a fill, a lot. FIX datatype Qty.

Traits§

Quantity
Either form of quantity: Qty (never negative) or DeltaQty (may be).