Enum CostNumber 

pub enum CostNumber {
    PerUnit {
        value: Decimal,
    },
    Total {
        value: Decimal,
    },
    PerUnitFromTotal(BookedCost),
}

A cost specification for matching or creating costs.

Unlike Cost, all fields are optional to allow partial matching. This is used in postings where the user may specify only some cost components (e.g., just the date to match a specific lot).

Matching Rules

A CostSpec matches a Cost if all specified fields match:

• If number is Some, it must equal the cost’s number
• If currency is Some, it must equal the cost’s currency
• If date is Some, it must equal the cost’s date
• If label is Some, it must equal the cost’s label

Examples

use rustledger_core::{Cost, CostSpec};
use rust_decimal_macros::dec;

let cost = Cost::new(dec!(150.00), "USD")
    .with_date(rustledger_core::naive_date(2024, 1, 15).unwrap());

// Match by date only
let spec = CostSpec::default().with_date(rustledger_core::naive_date(2024, 1, 15).unwrap());
assert!(spec.matches(&cost));

// Match by wrong date
let spec2 = CostSpec::default().with_date(rustledger_core::naive_date(2024, 1, 16).unwrap());
assert!(!spec2.matches(&cost));

The numeric component of a CostSpec.

Beancount cost specs name a number in one of two source-level shapes:

• {150.00 USD} — per-unit cost (Self::PerUnit)
• {{ 1500.00 USD }} — total cost for the posting’s units (Self::Total)

During booking the engine converts Total(t) into a third state, Self::PerUnitFromTotal, carrying both the derived per-unit value (for display, lot tracking) and the original total (for precision-preserving residual math — division-then-multiplication loses precision at the rust_decimal 28-digit ceiling).

A cost spec without a number at all (e.g. {} for a booking- deferred lot match) is represented by CostSpec.number: None.

Pre-#1164 the per-unit and total numbers were two independent Option<Decimal> fields on CostSpec. The invalid both-set state was prevented only by parser discipline and downstream defensive branches; the “booked from total” state was modeled accidentally by setting both fields, with the meaning encoded only in code comments. Folding the axes into one enum makes both the pre-booking invalid state unrepresentable AND the post-booking derived state explicit.

Variants

PerUnit

Per-unit cost as written: {150.00 USD}. Booking leaves this shape unchanged.

Fields

value: Decimal

Per-unit value.

Total

Total cost as written: {{ 1500.00 USD }}. Booking rewrites this to Self::PerUnitFromTotal once units are known.

Fields

value: Decimal

Total value.

PerUnitFromTotal(BookedCost)

Post-booking state: a per-unit value derived from a {{ total USD }} spec at booking time, with the source total preserved for exact residual math. Pre-#1164 this was modeled implicitly by setting both number_per and number_total on CostSpec. The payload is a separate BookedCost struct so the booking-time invariant lives on a named type with constructor methods that enforce it.

Implementations

impl CostNumber

pub const fn per_unit(&self) -> Option<Decimal>

Return the per-unit value if this number carries one.

• Self::PerUnit → Some(its Decimal)
• Self::PerUnitFromTotal → Some(per_unit)
• Self::Total → None (booking hasn’t computed per-unit yet)

pub const fn total(&self) -> Option<Decimal>

Return the total value if this number carries one.

• Self::Total → Some(its Decimal)
• Self::PerUnitFromTotal → Some(total)
• Self::PerUnit → None

Trait Implementations

impl Archive for CostNumber

where AsDecimal: ArchiveWith<Decimal>, BookedCost: Archive,

type Archived = ArchivedCostNumber

The archived representation of this type.

type Resolver = CostNumberResolver

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 as Archive>::Resolver, out: Place<<Self as Archive>::Archived>, )

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

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.

impl Clone for CostNumber

fn clone(&self) -> CostNumber

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for CostNumber

impl Debug for CostNumber

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for CostNumber

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<CostNumber, __D> for Archived<CostNumber>

where AsDecimal: ArchiveWith<Decimal> + DeserializeWith<<AsDecimal as ArchiveWith<Decimal>>::Archived, Decimal, __D>, BookedCost: Archive, <BookedCost as Archive>::Archived: Deserialize<BookedCost, __D>,

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

Deserializes using the given deserializer

impl Eq for CostNumber

impl Hash for CostNumber

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 CostNumber

fn eq(&self, other: &CostNumber) -> 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 Serialize for CostNumber

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<__S: Fallible + ?Sized> Serialize<__S> for CostNumber

where AsDecimal: SerializeWith<Decimal, __S>, BookedCost: 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 ShiftSpans for CostNumber

fn shift_spans<F: Fn(&mut Span)>(&mut self, shift: &F)

Apply shift to every Span reachable in self.

impl StructuralPartialEq for CostNumber