src/portfolio.rs
Rama main · réplica de lectura del repositorio original.
//! Positions and the arithmetic over them.
//!
//! One line per ticker: how many units and what they cost on average.
//! Lots would be more faithful to a brokerage statement, but a single
//! average is what the config can hold without becoming a ledger, and it
//! answers the two questions a watchlist cannot: what is this worth, and
//! am I up on it.
//!
//! Deliberately free of I/O and of `App`: the views, the rail, the JSON
//! output and the tests all price the same numbers through here.
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use crate::domain::Quote;
use crate::market::{self, Session};
/// Price used to value holdings everywhere, independent of the chart's
/// extended-candle toggle. A missing or invalid extended print falls back
/// to the regular-session quote.
pub fn price(quote: &Quote) -> f64 {
price_at(quote, Utc::now())
}
pub fn price_at(quote: &Quote, now: DateTime<Utc>) -> f64 {
quote.extended_price_at(now).unwrap_or(quote.price)
}
/// During premarket the regular quote is yesterday's close; the source's
/// previous close still belongs to the session before that. After hours,
/// include both the regular day's move and the extended move.
pub fn day_change(quote: &Quote, now: DateTime<Utc>) -> Option<f64> {
let extended = quote.extended_price_at(now);
let previous = if extended.is_some()
&& !market::is_crypto("e.symbol)
&& quote
.timing
.extended
.and_then(market::window_at)
.map(|window| window.session)
.unwrap_or_else(|| market::clock_at(now).session)
== Session::Pre
{
Some(quote.extended_reference())
} else {
quote.prev_close
};
previous.map(|previous| extended.unwrap_or(quote.price) - previous)
}
/// One holding. `qty` may be negative (a short), in which case a rising
/// price loses money and the percentages below still read the way a
/// statement reads, because they measure against the money at risk.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Position {
pub symbol: String,
pub qty: f64,
pub avg_price: f64,
}
impl Position {
/// What the units cost in total.
pub fn cost(&self) -> f64 {
self.qty * self.avg_price
}
pub fn value(&self, price: f64) -> f64 {
self.qty * price
}
pub fn pnl(&self, price: f64) -> f64 {
self.value(price) - self.cost()
}
/// Against the absolute cost, so a short that gains reads positive.
/// None when the basis is zero: a percentage of nothing is not zero,
/// it is unanswerable.
pub fn pnl_pct(&self, price: f64) -> Option<f64> {
let cost = self.cost();
(cost != 0.0).then(|| self.pnl(price) / cost.abs() * 100.0)
}
/// Today's move on this holding, including extended trading when the
/// source reports it. None when there is no reference close.
pub fn day_pnl(&self, quote: &Quote, now: DateTime<Utc>) -> Option<f64> {
day_change(quote, now).map(|c| c * self.qty)
}
}
/// The bottom line of the portfolio view.
///
/// `value` and `pnl` cover only the rows that have a price: a holding
/// still waiting for its first poll must not be summed in as zero, and
/// `priced`/`total` is what lets the view say so out loud.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Totals {
pub value: f64,
pub cost: f64,
pub pnl: f64,
/// None when not one priced row stated a previous close.
pub day_pnl: Option<f64>,
pub priced: usize,
pub total: usize,
}
impl Totals {
pub fn pnl_pct(&self) -> Option<f64> {
(self.cost != 0.0).then(|| self.pnl / self.cost.abs() * 100.0)
}
}
/// Sum the rows the view is about to draw. Pass `None` for a position
/// whose quote has not arrived (or whose fetch failed).
pub fn totals<'a>(
rows: impl Iterator<Item = (&'a Position, Option<&'a Quote>)>,
now: DateTime<Utc>,
) -> Totals {
let mut t = Totals::default();
for (pos, quote) in rows {
t.total += 1;
let Some(quote) = quote else { continue };
t.priced += 1;
let price = price_at(quote, now);
t.value += pos.value(price);
t.cost += pos.cost();
t.pnl += pos.pnl(price);
if let Some(day) = pos.day_pnl(quote, now) {
*t.day_pnl.get_or_insert(0.0) += day;
}
}
t
}
/// A row's share of the portfolio, in percent. None when there is nothing
/// to take a share of.
pub fn weight(value: f64, total_value: f64) -> Option<f64> {
(total_value != 0.0).then(|| value / total_value * 100.0)
}
/// The symbols worth polling: the watchlist first, in its own order, then
/// anything held that is not on it. Both `main` (at startup) and `App`
/// (after an edit) build the poller's list through here.
pub fn polled_symbols(watchlist: &[String], positions: &[Position]) -> Vec<String> {
let mut out = watchlist.to_vec();
for p in positions {
if !out.contains(&p.symbol) {
out.push(p.symbol.clone());
}
}
out
}
/// What one line typed into the position prompt asks for.
#[derive(Clone, Debug, PartialEq)]
pub enum Entry {
Set {
symbol: String,
qty: f64,
avg_price: f64,
},
Clear {
symbol: String,
},
}
/// Parse the prompt line. `target` is the ticker the cursor is on, used
/// when the line names none.
///
/// Accepted: `12 182.31`, `12 @ 182.31`, `AAPL 12 182.31`, `AAPL` (clears
/// it), and an empty line (clears the target). `$` and thousands commas
/// are noise and are dropped. A zero quantity is a clear rather than a
/// holding of nothing.
pub fn parse_entry(input: &str, target: &str) -> Result<Entry, String> {
let cleaned = input.replace('@', " ").replace(['$', ','], "");
let words: Vec<&str> = cleaned.split_whitespace().collect();
let (symbol, qty, price) = match words.as_slice() {
[] => return clear(target),
// A lone word that is not a number names a ticker to forget.
[one] if one.parse::<f64>().is_err() => return clear(one),
[_] => return Err("give a quantity and an average price".to_string()),
[qty, price] => (target, *qty, *price),
[symbol, qty, price] => (*symbol, *qty, *price),
_ => return Err("too many words: SYMBOL QTY AVERAGE".to_string()),
};
let symbol = normalize_symbol(symbol)?;
let qty = number(qty, "quantity")?;
let avg_price = number(price, "average price")?;
// Nothing held is not a holding of nothing: it is a line to drop.
if qty == 0.0 {
return Ok(Entry::Clear { symbol });
}
if avg_price < 0.0 {
return Err("the average price cannot be negative".to_string());
}
Ok(Entry::Set {
symbol,
qty,
avg_price,
})
}
fn clear(symbol: &str) -> Result<Entry, String> {
Ok(Entry::Clear {
symbol: normalize_symbol(symbol)?,
})
}
fn normalize_symbol(raw: &str) -> Result<String, String> {
let symbol = crate::domain::normalize_symbol(raw)?;
if symbol.parse::<f64>().is_ok() {
return Err(format!("{symbol} is not a ticker"));
}
Ok(symbol)
}
fn number(raw: &str, what: &str) -> Result<f64, String> {
match raw.parse::<f64>() {
Ok(v) if v.is_finite() => Ok(v),
_ => Err(format!("{what}: {raw} is not a number")),
}
}
/// Money with thousands separators: a position is worth four or five
/// digits more often than a share price is, and `12430.00` is a number
/// nobody reads at a glance. Prices themselves keep `domain::fmt_price`.
pub fn fmt_money(v: f64) -> String {
let sign = if v < 0.0 { "-" } else { "" };
let raw = format!("{:.2}", v.abs());
let (int, frac) = raw.split_once('.').unwrap_or((raw.as_str(), "00"));
let mut grouped = String::with_capacity(int.len() + int.len() / 3);
for (i, c) in int.chars().enumerate() {
if i > 0 && (int.len() - i) % 3 == 0 {
grouped.push(',');
}
grouped.push(c);
}
format!("{sign}{grouped}.{frac}")
}
/// The same, with the sign always written: a P&L of zero is `+0.00`, the
/// way every change column in this app already reads.
pub fn fmt_signed(v: f64) -> String {
format!("{}{}", if v < 0.0 { "" } else { "+" }, fmt_money(v))
}
#[cfg(test)]
mod tests {
use super::*;
fn at(hour: u32) -> DateTime<Utc> {
chrono::NaiveDate::from_ymd_opt(2026, 9, 11)
.unwrap()
.and_hms_opt(hour, 30, 0)
.unwrap()
.and_utc()
}
fn quote(price: f64, prev_close: Option<f64>) -> Quote {
Quote {
name: None,
timing: Default::default(),
symbol: "AAPL".to_string(),
price,
prev_close,
currency: Some("USD".to_string()),
extended: None,
fifty_two_week: None,
day_range: None,
volume: None,
}
}
fn pos(qty: f64, avg_price: f64) -> Position {
Position {
symbol: "AAPL".to_string(),
qty,
avg_price,
}
}
#[test]
fn a_long_position_values_and_profits() {
let p = pos(10.0, 100.0);
assert_eq!(p.cost(), 1000.0);
assert_eq!(p.value(110.0), 1100.0);
assert_eq!(p.pnl(110.0), 100.0);
assert_eq!(p.pnl_pct(110.0), Some(10.0));
}
#[test]
fn a_short_gains_when_the_price_falls() {
let p = pos(-10.0, 100.0);
assert_eq!(p.pnl(90.0), 100.0);
// Measured against the money at risk, so the gain reads positive.
assert_eq!(p.pnl_pct(90.0), Some(10.0));
assert_eq!(p.pnl(110.0), -100.0);
}
#[test]
fn a_zero_basis_has_no_percentage() {
assert_eq!(pos(10.0, 0.0).pnl_pct(110.0), None);
assert_eq!(pos(10.0, 0.0).pnl(110.0), 1100.0);
}
#[test]
fn the_day_move_needs_a_previous_close() {
let p = pos(10.0, 100.0);
assert_eq!(p.day_pnl("e(110.0, Some(109.0)), at(15)), Some(10.0));
assert_eq!(p.day_pnl("e(110.0, None), at(15)), None);
}
#[test]
fn totals_skip_the_rows_without_a_price() {
let a = pos(10.0, 100.0);
let b = Position {
symbol: "MSFT".to_string(),
qty: 5.0,
avg_price: 400.0,
};
let qa = quote(110.0, Some(109.0));
let t = totals([(&a, Some(&qa)), (&b, None)].into_iter(), at(15));
assert_eq!(t.priced, 1);
assert_eq!(t.total, 2);
// The unpriced holding contributes neither value nor basis, so the
// percentage stays honest instead of counting 2000 as a 100% loss.
assert_eq!(t.value, 1100.0);
assert_eq!(t.cost, 1000.0);
assert_eq!(t.pnl, 100.0);
assert_eq!(t.pnl_pct(), Some(10.0));
assert_eq!(t.day_pnl, Some(10.0));
}
#[test]
fn totals_have_no_day_move_when_no_row_states_one() {
let a = pos(10.0, 100.0);
let qa = quote(110.0, None);
assert_eq!(totals([(&a, Some(&qa))].into_iter(), at(15)).day_pnl, None);
}
#[test]
fn extended_prices_value_longs_shorts_and_totals() {
let mut q = quote(89.12, Some(94.94));
q.extended = Some(91.28);
let long = pos(300.0, 90.26);
let short = pos(-100.0, 90.26);
let near = |actual: f64, expected: f64| {
assert!((actual - expected).abs() < 1e-8, "{actual} != {expected}")
};
near(long.pnl(price(&q)), 306.0);
near(short.pnl(price(&q)), -102.0);
let t = totals([(&long, Some(&q)), (&short, Some(&q))].into_iter(), at(10));
near(t.value, 18_256.0);
near(t.pnl, 204.0);
near(t.day_pnl.unwrap(), 432.0);
}
#[test]
fn premarket_resets_the_day_reference_but_after_hours_keeps_the_day() {
let mut q = quote(89.12, Some(94.94));
q.extended = Some(91.28);
let p = pos(300.0, 90.26);
assert!((p.day_pnl(&q, at(10)).unwrap() - 648.0).abs() < 1e-8);
assert!((p.day_pnl(&q, at(21)).unwrap() + 1098.0).abs() < 1e-8);
q.prev_close = None;
assert!((p.day_pnl(&q, at(10)).unwrap() - 648.0).abs() < 1e-8);
assert_eq!(p.day_pnl(&q, at(21)), None);
q.extended = Some(q.price);
q.timing.extended = Some(at(10).timestamp());
assert_eq!(p.day_pnl(&q, at(10)), Some(0.0));
}
#[test]
fn missing_or_invalid_extended_prices_fall_back_to_regular() {
let mut q = quote(110.0, Some(109.0));
for extended in [
None,
Some(0.0),
Some(-1.0),
Some(f64::NAN),
Some(f64::INFINITY),
] {
q.extended = extended;
assert_eq!(price(&q), 110.0);
assert_eq!(day_change(&q, at(10)), Some(1.0));
}
q.extended = Some(112.0);
assert_eq!(price(&q), 112.0);
q.extended = None; // the next regular-session response
assert_eq!(price(&q), 110.0);
}
#[test]
fn crypto_does_not_reset_its_day_at_the_us_premarket() {
let mut q = quote(100.0, Some(95.0));
q.symbol = "BTC-USD".into();
q.extended = Some(101.0);
assert_eq!(day_change(&q, at(10)), Some(6.0));
}
#[test]
fn weights_need_something_to_divide() {
assert_eq!(weight(250.0, 1000.0), Some(25.0));
assert_eq!(weight(0.0, 0.0), None);
}
#[test]
fn the_prompt_takes_every_shape_of_the_line() {
let set = |symbol: &str, qty: f64, avg_price: f64| Entry::Set {
symbol: symbol.to_string(),
qty,
avg_price,
};
assert_eq!(
parse_entry("12 182.31", "AAPL"),
Ok(set("AAPL", 12.0, 182.31))
);
assert_eq!(
parse_entry("12 @ 182.31", "AAPL"),
Ok(set("AAPL", 12.0, 182.31))
);
assert_eq!(
parse_entry("nvda 3 1,204.50", "AAPL"),
Ok(set("NVDA", 3.0, 1204.5))
);
assert_eq!(parse_entry(" 4 $99 ", "AAPL"), Ok(set("AAPL", 4.0, 99.0)));
assert_eq!(
parse_entry("0.25 64000", "BTC-USD"),
Ok(set("BTC-USD", 0.25, 64000.0))
);
assert_eq!(
parse_entry("-10 100", "AAPL"),
Ok(set("AAPL", -10.0, 100.0))
);
}
#[test]
fn the_prompt_clears_on_an_empty_line_a_bare_ticker_or_a_zero() {
let clear = |symbol: &str| {
Ok(Entry::Clear {
symbol: symbol.to_string(),
})
};
assert_eq!(parse_entry("", "AAPL"), clear("AAPL"));
assert_eq!(parse_entry(" ", "AAPL"), clear("AAPL"));
assert_eq!(parse_entry("msft", "AAPL"), clear("MSFT"));
assert_eq!(parse_entry("0 182.31", "AAPL"), clear("AAPL"));
}
#[test]
fn the_prompt_says_what_is_wrong() {
assert!(parse_entry("12", "AAPL").is_err());
assert!(parse_entry("abc 12", "AAPL").is_err());
assert!(parse_entry("12 -5", "AAPL").is_err());
assert!(parse_entry("AAPL 12 182.31 extra", "AAPL").is_err());
assert!(parse_entry("12 182.31", "").is_err());
}
#[test]
fn money_is_grouped_and_signed() {
assert_eq!(fmt_money(12430.0), "12,430.00");
assert_eq!(fmt_money(1234567.891), "1,234,567.89");
assert_eq!(fmt_money(-142.3), "-142.30");
assert_eq!(fmt_money(99.0), "99.00");
assert_eq!(fmt_signed(142.3), "+142.30");
assert_eq!(fmt_signed(-142.3), "-142.30");
assert_eq!(fmt_signed(0.0), "+0.00");
}
}