Struct Xstep 

pub struct Xstep<T>
where
    T: Copy + TryInto<Positive> + AddAssign + Display,
{ /* private fields */ }

Represents a step in a time series with an indexed value at a specific time point.

This struct encapsulates a value at a specific point in a time series, tracking not only the value itself but also its position (index), the time unit it belongs to, and its associated datetime. It’s designed to be used in financial and statistical analysis where tracking values across time is essential.

The generic parameter T allows for different value types while ensuring they can be incrementally accumulated (via AddAssign) and converted to a Positive type for calculations that require non-negative values.

Type Parameters

• T - The type of the value being stored, which must implement AddAssign, be convertible to Positive, and be Copy.

Fields

• index - An integer representing the position of this step in a sequence.

• value - The actual data value at this time step, of generic type T.

• time_unit - Defines the time granularity (e.g., day, hour, minute) for this step.

• datetime - The specific expiration date associated with this time step, which can be either a relative number of days or an absolute datetime.

Implementations

impl<T> Xstep<T>

where T: Copy + TryInto<Positive> + AddAssign + Display,

Implementation for the Xstep<T> struct, which represents a time step in a simulation.

The Xstep<T> struct is designed to handle sequential time steps in financial simulations, allowing for forward and backward movement in time. The struct maintains an index counter, a value of type T, a time unit, and an expiration date.

Type Parameters

• T - A type that implements AddAssign, can be converted into Positive, and is Copy. This typically represents a numeric value used for calculating time differences.

Examples

// Create a step with 7 days as the value, using days as the time unit
use optionstratlib_core::model::Positive;
use optionstratlib_core::pos_or_panic;
use optionstratlib_core::model::ExpirationDate;
use optionstratlib_simulation::simulation::steps::Xstep;
use optionstratlib_core::utils::TimeFrame;
let step = Xstep::new(pos_or_panic!(7.0), TimeFrame::Day, ExpirationDate::Days(pos_or_panic!(30.0)));

// Move to the next step (forward in time)
let next_step = step.next();

// Move to the previous step (backward in time)
let prev_step = step.previous();

pub fn new(value: T, time_unit: TimeFrame, datetime: ExpirationDate) -> Self

Creates a new Xstep with the specified value, time unit, and datetime.

Parameters

• value - The step size value
• time_unit - The time unit for this step (e.g., Day, Week, Month)
• datetime - The expiration date. Stored as-is when the variant is ExpirationDate::Days; ExpirationDate::DateTime is normalized to Days via ExpirationDate::get_days. If that conversion fails (past date / invalid datetime), the step falls back to ExpirationDate::Days(Positive::ZERO) and emits tracing::error!.

Returns

A new Xstep<T> instance initialized with the provided parameters and index set to 0.

pub fn index(&self) -> &i32

Returns a reference to the index of the time step.

The index represents the position of this step in a sequence of time steps.

Returns

• &i32 - A reference to the index value.

pub fn step_size_in_time(&self) -> &T

Returns a reference to the step size in time units.

This represents the magnitude of this time step in the context of its time frame, such as the number of days, hours, or other time units.

Returns

• &T - A reference to the step size value.

pub fn time_unit(&self) -> &TimeFrame

Returns a reference to the time unit associated with this step.

The time unit defines the granularity of the time measurement (e.g., day, hour, minute).

Returns

• &TimeFrame - A reference to the time unit enumeration.

pub fn datetime(&self) -> &ExpirationDate

Returns a reference to the datetime associated with this step.

This represents the specific point in time (as an expiration date) that this step corresponds to, which can be either a relative value or an absolute datetime.

Returns

• &ExpirationDate - A reference to the expiration date.

pub fn days_left(&self) -> Result<Positive, SimulationError>

Calculates the number of days left until the expiry date associated with this step.

This method delegates to the underlying ExpirationDate component to determine the days remaining until expiration. It provides a consistent way to access time-to-expiry regardless of how the date was originally specified (as days or as an absolute datetime).

Returns

• Result<Positive, SimulationError> - A positive decimal value representing the number of days until expiration, or an error if the calculation cannot be performed.

Errors

Returns SimulationError::ExpirationDate when the stored ExpirationDate cannot be resolved to a non-negative day count (e.g. the datetime is in the past).

pub fn next(&self) -> Result<Self, SimulationError>

Generates the next step by reducing the expiration days by the step value.

This method calculates a new Xstep instance with its index incremented by 1, and the expiration date reduced by the equivalent of value in days.

Returns

A new Xstep<T> instance with updated index and datetime values.

Errors

Returns SimulationError::ExpirationReached when the current step is already at expiration (no forward step is possible), SimulationError::ExpirationDate when the underlying ExpirationDate::get_days call fails, SimulationError::PositiveError when the step cannot be expressed in days (a custom time unit with no periods in a year, or a step beyond the Positive range), and SimulationError::StepError when the step index overflows i32::MAX.

pub fn previous(&self) -> Result<Self, SimulationError>

Generates the previous step by increasing the expiration days by the step value.

This method calculates a new Xstep instance with its index decremented by 1, and the expiration date increased by the equivalent of value in days.

Returns

A new Xstep<T> instance with updated index and datetime values.

Errors

Returns SimulationError::ExpirationDate when the underlying ExpirationDate::get_days call fails, SimulationError::StepError when the step-size conversion to Positive fails or when the step index underflows i32::MIN, and SimulationError::PositiveError when the step cannot be expressed in days or rewinding the expiration leaves the representable Positive range.

Trait Implementations

impl<T> Clone for Xstep<T>

where T: Copy + TryInto<Positive> + AddAssign + Display + Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Copy for Xstep<T>

where T: Copy + TryInto<Positive> + AddAssign + Display + Copy,

impl<T> Debug for Xstep<T>

where T: Copy + TryInto<Positive> + AddAssign + Display + Debug,

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

Formats the value using the given formatter.

impl<T> Display for Xstep<T>

where T: Copy + TryInto<Positive> + AddAssign + Display,

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

Formats the value using the given formatter.

impl<T> Serialize for Xstep<T>

where T: Copy + TryInto<Positive> + AddAssign + Display + Serialize,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.