Struct PositionRef 

pub struct PositionRef<'a>(/* private fields */);

Lifetime-scoped read borrow of a cached position.

Returned by crate::cache::Cache::position. The borrow drops with the enclosing scope, which makes any attempt to hold it across a cache mutation panic at runtime: a loud failure beats the silent staleness that a stored clone would produce.

Method calls on the inner [Position] resolve via Deref; comparisons against &Position or owned Position values are direct (position_ref == &position); Display and Debug forward to the inner record. Use cloned when an owned snapshot is required (for example, before crossing a boundary that may dispatch events).

Implementations

impl<'a> PositionRef<'a>

pub fn new(inner: Ref<'a, Position>) -> Self

Wraps the given Ref borrow.

pub fn cloned(&self) -> Position

Returns an owned snapshot of the borrowed position.

Mirrors Option::cloned and Iterator::cloned; the snapshot will not reflect later mutations of the underlying cell.

Methods from Deref<Target = Position>

pub fn clone_without_events(&self) -> Position

Returns a copy without stored events, adjustments, replay events, fill voids, or trade IDs.

Warning

Use this copy only as transient read state. Applying events or caching this copy can bypass replay and duplicate-fill checks and discard position history.

pub fn clone_for_snapshot(&self) -> Position

Returns a snapshot copy without durable replay or fill-void history.

pub fn check_accounting(&self) -> Result<(), CorrectnessError>

Checks that stored domain inputs fit the exact Decimal accounting bounds.

Errors

Returns an error if a stored price, quantity, or monetary input loses precision or overflows.

pub fn has_replay_trade_id(&self, trade_id: TradeId) -> bool

Returns whether durable replay history contains trade_id.

pub fn accepts_price_restatement(&self, fill: &OrderFilled) -> bool

Returns whether the fill can restate an opening trade’s price in the current episode.

The order, trade, side, and quantity must match the recorded opening fill.

pub fn fill_fragments( &self, client_order_id: ClientOrderId, trade_id: TradeId, ) -> Vec<&OrderFilled>

Returns durable fill fragments matching an order trade in local application order.

pub fn try_realized_pnl( &self, last: Price, quantity: Quantity, ) -> Result<Money, CorrectnessError>

Returns the realized PnL increment for reducing this position at last.

Carries the position’s existing fractional PnL into the native Money rounding.

Errors

Returns an error if inverse prices are invalid, precision is unsupported, or arithmetic overflows.

pub fn try_calculate_pnl( &self, avg_px_open: Decimal, avg_px_close: Decimal, quantity: Quantity, ) -> Result<Money, CorrectnessError>

Calculates PnL using Decimal prices and exact quantity.

Errors

Returns an error if inverse prices are invalid, arithmetic overflows, or precision is unsupported.

pub fn calculate_pnl( &self, avg_px_open: Decimal, avg_px_close: Decimal, quantity: Quantity, ) -> Result<Money, CorrectnessError>

Calculates PnL using Decimal prices and exact quantity.

Errors

Returns an error if [Self::try_calculate_pnl] fails.

pub fn try_total_pnl(&self, last: Price) -> Result<Money, CorrectnessError>

Returns total PnL at the given price.

Errors

Returns an error if the PnL cannot be calculated or represented.

pub fn total_pnl(&self, last: Price) -> Result<Money, CorrectnessError>

Returns total PnL at the given price.

Errors

Returns an error if [Self::try_total_pnl] fails.

pub fn try_unrealized_pnl(&self, last: Price) -> Result<Money, CorrectnessError>

Returns unrealized PnL at the given price.

Errors

Returns an error if the PnL cannot be calculated or represented.

pub fn unrealized_pnl(&self, last: Price) -> Result<Money, CorrectnessError>

Returns unrealized PnL at the given price.

Errors

Returns an error if [Self::try_unrealized_pnl] fails.

pub fn closing_order_side(&self) -> Option<OrderSide>

Returns the order side required to close this position.

pub fn is_opposite_side(&self, side: OrderSide) -> bool

Returns whether the given order side is opposite to the position entry side.

pub fn symbol(&self) -> Symbol

Returns the instrument symbol.

pub fn venue(&self) -> Venue

Returns the trading venue.

pub fn event_count(&self) -> usize

Returns the count of order fill events applied to this position.

pub fn client_order_ids(&self) -> Vec<ClientOrderId>

Returns unique client order IDs from all fill events, sorted.

pub fn venue_order_ids(&self) -> Vec<VenueOrderId>

Returns unique venue order IDs from all fill events, sorted.

pub fn trade_ids(&self) -> Vec<TradeId>

Returns unique trade IDs from all fill events, sorted.

pub fn try_notional_value(&self, last: Price) -> Result<Money, Error>

Calculates the notional value based on the last price.

Errors

Returns an error if this is an inverse position without a base currency, the price is not positive for a non-premium inverse position, or the result cannot be represented as [Money].

pub fn notional_value(&self, last: Price) -> Money

Calculates the notional value based on the last price.

Panics

Panics if [Position::try_notional_value] returns an error.

pub fn last_event(&self) -> Option<OrderFilled>

Returns the last OrderFilled event for the position (if any after purging).

pub fn last_trade_id(&self) -> Option<TradeId>

Returns the last TradeId for the position (if any after purging).

pub fn is_long(&self) -> bool

Returns whether the position is long (positive quantity).

pub fn is_short(&self) -> bool

Returns whether the position is short (negative quantity).

pub fn is_open(&self) -> bool

Returns whether the position is currently open (has quantity and no close timestamp).

pub fn is_closed(&self) -> bool

Returns whether the position is closed (flat with a close timestamp).

pub fn is_settled(&self) -> bool

Returns whether an authoritative instrument close settled the current cycle.

Reads the replay history, so it is false for a copy made by [Self::clone_without_events] or [Self::clone_for_snapshot].

pub fn requires_replay_state(&self) -> bool

Returns whether replaying the position’s fills alone cannot rebuild its state.

Fill voids, settlements, and price restatements change state without a new quantity-bearing fill, so persistence must store the complete replay state. Retained virtual position cycles also require the complete replay state.

pub fn signed_decimal_qty(&self) -> Decimal

Returns the signed quantity as a Decimal.

Uses the authoritative Decimal signed quantity, as the quantity field may have reduced precision based on the instrument’s size_precision.

pub fn commissions(&self) -> Vec<Money>

Returns the cumulative commissions for the position as a vector.

Trait Implementations

impl AsRef<Position> for PositionRef<'_>

fn as_ref(&self) -> &Position

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for PositionRef<'_>

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

Formats the value using the given formatter.

impl Deref for PositionRef<'_>

type Target = Position

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Display for PositionRef<'_>

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

Formats the value using the given formatter.

impl<'a> From<Ref<'a, Position>> for PositionRef<'a>

fn from(inner: Ref<'a, Position>) -> Self

Converts to this type from the input type.

impl PartialEq for PositionRef<'_>

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

Equality operator ==.

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

Inequality operator !=.

impl PartialEq<&Position> for PositionRef<'_>

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

Equality operator ==.

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

Inequality operator !=.

impl PartialEq<Position> for PositionRef<'_>

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

Equality operator ==.

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

Inequality operator !=.