Struct Price 

pub struct Price(/* private fields */);

A strictly positive price value backed by Decimal.

Example

use fin_primitives::types::Price;
use rust_decimal_macros::dec;
let p = Price::new(dec!(100.50)).unwrap();
assert_eq!(p.value(), dec!(100.50));

Implementations

impl Price

pub fn new(d: Decimal) -> Result<Self, FinError>

Construct a validated Price.

Errors

Returns FinError::InvalidPrice if d <= 0.

pub fn value(&self) -> Decimal

Returns the inner Decimal value.

pub fn to_f64(&self) -> f64

Converts to f64 with possible precision loss.

pub fn from_f64(f: f64) -> Option<Self>

Constructs a Price from an f64. Returns None if f is not finite or <= 0.

pub fn to_string_with_dp(&self, dp: u32) -> String

Returns a String representation rounded to dp decimal places.

Useful for display/logging without losing the underlying decimal precision.

impl Price

pub fn pct_change_to(self, other: Price) -> Decimal

Returns the percentage change from self to other: (other - self) / self * 100.

Positive values indicate a price increase; negative values indicate a decrease.

pub fn mid(self, other: Price) -> Price

Returns the midpoint between self and other: (self + other) / 2.

impl Price

pub fn abs_diff(self, other: Price) -> Decimal

Returns the absolute difference between self and other: |self - other|.

pub fn snap_to_tick(self, tick_size: Decimal) -> Option<Price>

Rounds this price to the nearest multiple of tick_size.

Returns None if tick_size <= 0 or if the rounded value is not a valid Price (i.e. the result is zero or negative).

Example

use fin_primitives::types::Price;
use rust_decimal_macros::dec;

let p = Price::new(dec!(10.3)).unwrap();
let snapped = p.snap_to_tick(dec!(0.5)).unwrap();
assert_eq!(snapped.value(), dec!(10.5));

pub fn clamp(self, lo: Price, hi: Price) -> Price

Clamps this price to the inclusive range [lo, hi].

Returns lo if self < lo, hi if self > hi, otherwise self.

impl Price

pub fn round_to(self, dp: u32) -> Option<Price>

Rounds this price to dp decimal places using banker’s rounding.

Returns None if the rounded value is zero or negative (invalid price).

pub fn round_half_up(self, dp: u32) -> Option<Price>

Rounds this price to dp decimal places using round-half-up (conventional rounding).

Unlike round_to which uses banker’s rounding, this always rounds 0.5 away from zero. Returns None if the rounded result is zero or negative.

impl Price

pub fn checked_add(self, other: Price) -> Option<Price>

Adds other to self, returning the result as a Price, or None on overflow.

Useful when combining two price levels and needing a validated result.

impl Price

pub fn checked_mul(self, qty: Quantity) -> Option<Decimal>

Multiplies this price by qty, returning None if the result overflows.

Prefer this over the * operator when overflow is a concern (e.g., large notional values with many decimal digits).

impl Price

pub fn midpoint(bid: Price, ask: Price) -> Decimal

Returns the midpoint between bid and ask: (bid + ask) / 2.

Useful for computing the theoretical fair value between two prices.

pub fn pct_move(self, pct: Decimal) -> Option<Price>

Applies a percentage move to this price: self * (1 + pct / 100).

Returns None if the result is not a valid price (e.g., a large negative pct would drive the price to zero or below).

pub fn lerp(self, other: Price, t: Decimal) -> Option<Price>

Linearly interpolates between self and other by factor t in [0, 1].

Returns self + (other - self) * t. Returns None if t is outside [0, 1] or if the result is not a valid price (i.e., not strictly positive).

pub fn is_within_pct(self, other: Price, pct: Decimal) -> bool

Returns true if other is within pct percent of self.

Computes |self - other| / self * 100 <= pct. Returns false if pct is negative.

pub fn distance_pct(self, other: Price) -> Decimal

Signed percentage distance from self to other: (other - self) / self * 100.

Positive when other > self, negative when other < self.

pub fn round_to_tick(self, tick_size: Decimal) -> Option<Price>

Rounds this price to the nearest multiple of tick_size using standard rounding.

Equivalent to snap_to_tick but named for readability at call sites that want explicit rounding (e.g. order routing) vs. snapping (e.g. display). Returns None if tick_size <= 0 or the result is zero/negative.

Trait Implementations

impl Add for Price

Price + Price yields a raw Decimal (sum is not necessarily a valid price in all contexts).

type Output = Decimal

The resulting type after applying the + operator.

fn add(self, rhs: Price) -> Decimal

Performs the + operation.

impl Clone for Price

fn clone(&self) -> Price

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Price

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Price

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Price

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Mul<Decimal> for Price

Price * Decimal scales a price; returns None if the result is not a valid Price.

type Output = Option<Price>

The resulting type after applying the * operator.

fn mul(self, rhs: Decimal) -> Option<Price>

Performs the * operation.

impl Mul<Quantity> for Price

Price * Quantity yields the notional value as Decimal.

type Output = Decimal

The resulting type after applying the * operator.

fn mul(self, rhs: Quantity) -> Decimal

Performs the * operation.

impl Ord for Price

fn cmp(&self, other: &Price) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Price

fn eq(&self, other: &Price) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Price

fn partial_cmp(&self, other: &Price) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Price

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub for Price

Price - Price yields a raw Decimal (difference may be zero or negative).

type Output = Decimal

The resulting type after applying the - operator.

fn sub(self, rhs: Price) -> Decimal

Performs the - operation.

impl Copy for Price

impl Eq for Price

impl StructuralPartialEq for Price