Struct Position 

pub struct Position {
    pub units: Amount,
    pub cost: Option<Cost>,
}

A position is units of a currency held at an optional cost.

For simple currencies (cash), positions typically have no cost. For investments (stocks, crypto), positions track the cost basis for capital gains calculations.

Examples

use rustledger_core::{Amount, Cost, Position};
use rust_decimal_macros::dec;
use chrono::NaiveDate;

// Simple position (no cost)
let cash = Position::simple(Amount::new(dec!(1000.00), "USD"));
assert!(cash.cost.is_none());

// Position with cost (lot)
let cost = Cost::new(dec!(150.00), "USD")
    .with_date(NaiveDate::from_ymd_opt(2024, 1, 15).unwrap());
let stock = Position::with_cost(
    Amount::new(dec!(10), "AAPL"),
    cost
);
assert!(stock.cost.is_some());

Fields

units: Amount

The units held (number + currency/commodity)

cost: Option<Cost>

The cost basis (if tracked)

Implementations

impl Position

pub const fn simple(units: Amount) -> Self

Create a new position without cost tracking.

Use this for simple currency positions like cash.

pub const fn with_cost(units: Amount, cost: Cost) -> Self

Create a new position with cost tracking.

Use this for investment positions (stocks, crypto, etc.) where cost basis matters.

pub const fn is_empty(&self) -> bool

Check if this position is empty (zero units).

pub fn currency(&self) -> &str

Get the currency of this position’s units.

pub fn cost_currency(&self) -> Option<&str>

Get the cost currency, if this position has a cost.

pub fn book_value(&self) -> Option<Amount>

Calculate the book value (total cost) of this position.

Returns None if there is no cost.

pub fn matches_cost_spec(&self, spec: &CostSpec) -> bool

Check if this position matches a cost specification.

Returns true if:

• Both have no cost, or
• The position’s cost matches the spec

pub fn neg(&self) -> Self

Negate this position (reverse the sign of units).

pub fn can_reduce(&self, reduction: &Amount) -> bool

Check if this position can be reduced by another amount.

A position can be reduced if:

• The currencies match
• The reduction is in the opposite direction (selling what you have)

pub fn reduce(&self, reduction: Decimal) -> Option<Self>

Reduce this position by some units.

Returns Some(remaining) if the reduction is valid, None otherwise. The reduction must be in the opposite direction of the position.

pub fn split(&self, take_units: Decimal) -> (Self, Self)

Split this position, taking some units and leaving the rest.

Returns (taken, remaining) where taken has the specified units and remaining has the rest. Both share the same cost.

Trait Implementations

impl Archive for Position

where Amount: Archive, Option<Cost>: Archive,

const COPY_OPTIMIZATION: CopyOptimization<Self>

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

type Archived = ArchivedPosition

The archived representation of this type.

type Resolver = PositionResolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Creates the archived version of this value at the given position and writes it to the given output.

impl Clone for Position

fn clone(&self) -> Position

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Position

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Position

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<__D: Fallible + ?Sized> Deserialize<Position, __D> for Archived<Position>

where Amount: Archive, <Amount as Archive>::Archived: Deserialize<Amount, __D>, Option<Cost>: Archive, <Option<Cost> as Archive>::Archived: Deserialize<Option<Cost>, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<Position, <__D as Fallible>::Error>

Deserializes using the given deserializer

impl Display for Position

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

Formats the value using the given formatter.

impl FromIterator<Position> for Inventory

fn from_iter<I: IntoIterator<Item = Position>>(iter: I) -> Self

Creates a value from an iterator.

impl Hash for Position

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Position

fn eq(&self, other: &Position) -> 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<__S: Fallible + ?Sized> Serialize<__S> for Position

where Amount: Serialize<__S>, Option<Cost>: Serialize<__S>,

fn serialize( &self, serializer: &mut __S, ) -> Result<<Self as Archive>::Resolver, <__S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

impl Serialize for Position

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Position

impl StructuralPartialEq for Position