Enum SignalValue 

pub enum SignalValue {
    Scalar(Decimal),
    Unavailable,
}

The output value of a signal computation.

Variants

Scalar(Decimal)

A computed scalar value.

Unavailable

The signal does not yet have enough data to produce a value.

Implementations

impl SignalValue

pub fn as_decimal(&self) -> Option<Decimal>

Returns the inner Decimal if this is Scalar, or None if Unavailable.

Eliminates match boilerplate at call sites.

pub fn is_scalar(&self) -> bool

Returns true if this value is Scalar.

pub fn is_unavailable(&self) -> bool

Returns true if this value is Unavailable.

pub fn scalar_or(&self, default: Decimal) -> Decimal

Returns the inner Decimal if Scalar, otherwise returns default.

pub fn zip_with( self, other: SignalValue, f: impl FnOnce(Decimal, Decimal) -> Decimal, ) -> SignalValue

Combine two SignalValues with f, returning Unavailable if either is unavailable.

Mirrors Option::zip combined with map. Useful for computing derived values that require two ready signals (e.g. a spread = signal_a - signal_b).

Example

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let a = SignalValue::Scalar(dec!(10));
let b = SignalValue::Scalar(dec!(3));
let diff = a.zip_with(b, |x, y| x - y);
assert_eq!(diff, SignalValue::Scalar(dec!(7)));

pub fn map(self, f: impl FnOnce(Decimal) -> Decimal) -> SignalValue

Apply f to the inner value if Scalar, returning a new SignalValue.

If Unavailable, returns Unavailable without calling f. This mirrors Option::map and enables functional chaining without explicit match.

Example

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let v = SignalValue::Scalar(dec!(100));
let scaled = v.map(|x| x * dec!(2));
assert_eq!(scaled, SignalValue::Scalar(dec!(200)));

pub fn and_then(self, f: impl FnOnce(Decimal) -> SignalValue) -> SignalValue

Applies f to the inner value if Scalar, where f returns a SignalValue.

If Unavailable, returns Unavailable without calling f. This mirrors Option::and_then and enables chaining operations that may themselves produce Unavailable (e.g., clamping, conditional transforms).

Example

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let v = SignalValue::Scalar(dec!(50));
// Only return a value if it's above 30.
let r = v.and_then(|x| if x > dec!(30) { SignalValue::Scalar(x) } else { SignalValue::Unavailable });
assert_eq!(r, SignalValue::Scalar(dec!(50)));

pub fn negate(self) -> SignalValue

Negates the scalar value: returns Scalar(-x) if Scalar(x), else Unavailable.

Useful for inverting oscillator signals (e.g. turning a sell signal into a buy signal by negating the output) without requiring an explicit map(|x| -x).

pub fn offset(self, delta: Decimal) -> SignalValue

Adds delta to the scalar value.

Returns SignalValue::Unavailable unchanged.

pub fn min_with(self, other: SignalValue) -> SignalValue

Returns the smaller of self and other. Unavailable loses to any Scalar.

pub fn max_with(self, other: SignalValue) -> SignalValue

Returns the larger of self and other. Unavailable loses to any Scalar.

pub fn abs(self) -> SignalValue

Returns the absolute value of the scalar: Scalar(|x|) or Unavailable.

Useful when you only care about the magnitude of a signal (e.g. absolute momentum).

pub fn mul(self, factor: Decimal) -> SignalValue

Scales the scalar by factor: Scalar(x) * factor = Scalar(x * factor).

Returns Unavailable if the signal is Unavailable. Useful for weighting or inverting signals (e.g. signal.mul(Decimal::NEGATIVE_ONE)).

pub fn sub(self, other: SignalValue) -> SignalValue

Subtracts two signals: Scalar(a) - Scalar(b) = Scalar(a - b).

Returns Unavailable if either operand is Unavailable.

pub fn mul_signal(self, other: SignalValue) -> SignalValue

Multiplies two signals: Scalar(a) * Scalar(b) = Scalar(a * b).

Returns Unavailable if either operand is Unavailable.

pub fn add(self, other: SignalValue) -> SignalValue

Adds two signals: Scalar(a) + Scalar(b) = Scalar(a + b).

Returns Unavailable if either operand is Unavailable. Useful for combining multiple signal outputs without explicit pattern matching.

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

Clamps the scalar value to [lo, hi], returning Unavailable if Unavailable.

If Scalar(v), returns Scalar(v.clamp(lo, hi)). Useful for bounding oscillators such as RSI to valid ranges after arithmetic transforms.

Example

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let v = SignalValue::Scalar(dec!(105));
assert_eq!(v.clamp(dec!(0), dec!(100)), SignalValue::Scalar(dec!(100)));

pub fn div(self, other: SignalValue) -> SignalValue

Divides two signals: Scalar(a) / Scalar(b).

Returns Unavailable if either operand is Unavailable or b is zero.

pub fn is_positive(&self) -> bool

Returns true if the scalar value is strictly positive. Unavailable returns false.

pub fn is_negative(&self) -> bool

Returns true if the scalar value is strictly negative. Unavailable returns false.

pub fn if_unavailable(self, default: Decimal) -> Decimal

Returns default if this is Unavailable; otherwise returns the scalar value.

pub fn is_above(&self, threshold: Decimal) -> bool

Returns true if the scalar value is strictly above threshold.

Unavailable always returns false.

pub fn is_below(&self, threshold: Decimal) -> bool

Returns true if the scalar value is strictly below threshold.

Unavailable always returns false.

pub fn round(self, dp: u32) -> SignalValue

Rounds the scalar to dp decimal places using banker’s rounding.

Returns Unavailable unchanged.

pub fn to_option(self) -> Option<Decimal>

Converts to Option<Decimal>: Some(d) for Scalar(d), None for Unavailable.

pub fn as_f64(&self) -> Option<f64>

Converts to Option<f64>: Some(f64) for Scalar, None for Unavailable.

Precision may be lost in the Decimal → f64 conversion.

pub fn max(self, other: SignalValue) -> SignalValue

Returns the element-wise maximum of two signals.

Scalar(a).max(Scalar(b)) = Scalar(max(a, b)). Returns Unavailable if either operand is Unavailable.

pub fn min(self, other: SignalValue) -> SignalValue

Returns the element-wise minimum of two signals.

Scalar(a).min(Scalar(b)) = Scalar(min(a, b)). Returns Unavailable if either operand is Unavailable.

pub fn signum(self) -> SignalValue

Returns Scalar(-1), Scalar(0), or Scalar(1) based on the sign of the value.

Returns Unavailable if the value is unavailable.

pub fn sqrt(self) -> SignalValue

Returns the square root of the scalar value.

Uses f64 intermediate computation. Returns Unavailable if the value is negative or unavailable.

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let v = SignalValue::Scalar(dec!(4));
if let SignalValue::Scalar(r) = v.sqrt() {
    assert!((r - dec!(2)).abs() < dec!(0.00001));
}

pub fn pow(self, exp: u32) -> SignalValue

Raises the scalar value to an integer power.

Returns Unavailable if the value is unavailable.

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

assert_eq!(SignalValue::Scalar(dec!(3)).pow(2), SignalValue::Scalar(dec!(9)));

pub fn ln(self) -> SignalValue

Returns the natural logarithm of the scalar value.

Returns Unavailable if the value is ≤ 0 or unavailable.

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let v = SignalValue::Scalar(dec!(1));
assert_eq!(v.ln(), SignalValue::Scalar(dec!(0)));
assert_eq!(SignalValue::Scalar(dec!(-1)).ln(), SignalValue::Unavailable);

pub fn cross_above(self, threshold: Decimal, prev: SignalValue) -> bool

Returns true if this value is above threshold while prev was at or below it.

Detects an upward crossing of a threshold level. Both values must be scalar.

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let prev = SignalValue::Scalar(dec!(49));
let curr = SignalValue::Scalar(dec!(51));
assert!(curr.cross_above(dec!(50), prev));

pub fn cross_below(self, threshold: Decimal, prev: SignalValue) -> bool

Returns true if this value is below threshold while prev was at or above it.

Detects a downward crossing of a threshold level. Both values must be scalar.

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let prev = SignalValue::Scalar(dec!(51));
let curr = SignalValue::Scalar(dec!(49));
assert!(curr.cross_below(dec!(50), prev));

pub fn pct_of(self, other: SignalValue) -> SignalValue

Returns this scalar as a percentage of other.

result = (self / other) × 100

Returns Unavailable if either value is unavailable or other is zero.

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let v = SignalValue::Scalar(dec!(50));
let base = SignalValue::Scalar(dec!(200));
assert_eq!(v.pct_of(base), SignalValue::Scalar(dec!(25)));

pub fn threshold_cross( self, threshold: Decimal, prev: SignalValue, ) -> SignalValue

Returns -1, 0, or +1 depending on how this value crosses threshold from prev.

• +1 if prev <= threshold and self > threshold (upward crossing)
• -1 if prev >= threshold and self < threshold (downward crossing)
• 0 otherwise (no crossing, or either value is unavailable)

use fin_primitives::signals::SignalValue;
use rust_decimal_macros::dec;

let prev = SignalValue::Scalar(dec!(49));
let curr = SignalValue::Scalar(dec!(51));
assert_eq!(curr.threshold_cross(dec!(50), prev), SignalValue::Scalar(dec!(1)));

pub fn exp(self) -> SignalValue

Returns e^x. Returns Unavailable if the value is Unavailable or if x > 700 (overflow guard — e^709 ≈ f64::MAX).

pub fn floor(self) -> SignalValue

Returns the floor of the value (rounds toward negative infinity).

pub fn ceil(self) -> SignalValue

Returns the ceiling of the value (rounds toward positive infinity).

pub fn reciprocal(self) -> SignalValue

Returns 1 / self. Returns Unavailable if the value is zero or Unavailable.

pub fn to_percent(self, total: SignalValue) -> SignalValue

Returns (self / total) * 100. Returns Unavailable if total is zero or either value is Unavailable.

pub fn atan(self) -> SignalValue

Returns the arctangent of the value in radians. Returns Unavailable if unavailable.

pub fn tanh(self) -> SignalValue

Returns the hyperbolic tangent of the value. Returns Unavailable if unavailable.

tanh maps any real value to (-1, 1) — useful for normalising unbounded signals.

pub fn sinh(self) -> SignalValue

Returns the hyperbolic sine of the scalar value.

Returns SignalValue::Unavailable if the result is non-finite.

pub fn cosh(self) -> SignalValue

Returns the hyperbolic cosine of the scalar value.

Returns SignalValue::Unavailable if the result is non-finite.

pub fn round_to(self, dp: u32) -> SignalValue

Rounds the scalar to dp decimal places using banker’s rounding.

Returns SignalValue::Unavailable unchanged.

pub fn to_bool(&self) -> bool

Returns true if this is a Scalar with a non-zero value.

pub fn scale_by(self, factor: Decimal) -> SignalValue

Multiplies the scalar by factor, returning the product as a new SignalValue.

Returns SignalValue::Unavailable unchanged.

pub fn is_zero(&self) -> bool

Returns true if this is Scalar(0).

pub fn delta(self, other: SignalValue) -> SignalValue

Absolute difference between two SignalValues.

Returns Unavailable if either operand is Unavailable.

pub fn lerp(self, other: SignalValue, t: Decimal) -> SignalValue

Linear interpolation: self * (1 - t) + other * t.

t is clamped to [0, 1]. Returns Unavailable if either operand is Unavailable.

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

Returns true if self is a scalar strictly greater than other.

Returns false if either operand is Unavailable.

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

Returns true if self is a scalar strictly less than other.

Returns false if either operand is Unavailable.

pub fn eq_approx(&self, other: &SignalValue, tolerance: Decimal) -> bool

Returns true if both are scalars and |self - other| <= tolerance.

Returns false if either is Unavailable.

pub fn atan2(self, x: SignalValue) -> SignalValue

Two-argument arctangent: atan2(self, x) in radians.

Treats self as the y argument. Returns Unavailable if either is Unavailable.

pub fn sign_match(&self, other: &SignalValue) -> bool

Returns true if both scalars have the same sign (both positive or both negative).

Zero is treated as positive. Returns false if either is Unavailable.

pub fn add_scalar(self, delta: Decimal) -> SignalValue

Adds a raw Decimal to this scalar value.

Returns Unavailable if self is Unavailable.

pub fn map_or( self, default: Decimal, f: impl FnOnce(Decimal) -> Decimal, ) -> Decimal

Maps the scalar with f, falling back to default if Unavailable.

pub fn gte(&self, other: &SignalValue) -> bool

Returns true if self >= other (both scalar). Returns false if either is Unavailable.

pub fn lte(&self, other: &SignalValue) -> bool

Returns true if self <= other (both scalar). Returns false if either is Unavailable.

pub fn as_percent(self, base: Decimal) -> SignalValue

Express this scalar as a percentage of base: self / base * 100.

Returns Unavailable if self is Unavailable or base is zero.

pub fn within_range(&self, lo: Decimal, hi: Decimal) -> bool

Returns true if this scalar is in [lo, hi] (inclusive).

Returns false if Unavailable.

pub fn cap_at(self, max_val: Decimal) -> SignalValue

Caps the scalar at max_val. Returns Unavailable if self is Unavailable.

pub fn floor_at(self, min_val: Decimal) -> SignalValue

Floors the scalar at min_val. Returns Unavailable if self is Unavailable.

pub fn quantize(self, step: Decimal) -> SignalValue

Round the scalar to the nearest multiple of step. Returns Unavailable if unavailable or step is zero.

pub fn distance_to(self, other: SignalValue) -> SignalValue

Absolute difference between self and other. Returns Unavailable if either is unavailable.

pub fn blend(self, other: SignalValue, weight: Decimal) -> SignalValue

Weighted blend: self * (1 - weight) + other * weight, clamping weight to [0, 1]. Returns Unavailable if either operand is unavailable.

Trait Implementations

impl Clone for SignalValue

fn clone(&self) -> SignalValue

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SignalValue

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

Formats the value using the given formatter.

impl Display for SignalValue

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

Formats the value using the given formatter.

impl From<Decimal> for SignalValue

fn from(d: Decimal) -> Self

Converts to this type from the input type.

impl PartialEq for SignalValue

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