optionstratlib 0.17.2

OptionStratLib is a comprehensive Rust library for options trading and strategy development across multiple asset classes.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

use crate::error::InterpolationError;

/// A trait that provides functionality for performing linear interpolation.
///
/// # Overview
/// The `LinearInterpolation` trait defines the behavior for linearly interpolating
/// values along a curve or dataset. It allows implementors to compute the interpolated
/// point for a given input using linear methods.
///
/// Linear interpolation is a simple and widely-used technique in which new data points
/// can be estimated within the range of a discrete set of known data points by connecting
/// adjacent points with straight lines.
///
/// # Associated Types
///
/// - **`Point`**: Represents the type of the interpolated data point (e.g., coordinates,
///   numerical values, or other types).
/// - **`Input`**: Represents the type of the input value used to calculate the interpolation (e.g., a single
///   number such as an `f64` or a high-precision number like `Decimal`).
/// - **`Error`**: Defines the error type returned if interpolation cannot be performed due to invalid input
///   or other constraints (e.g., insufficient points for interpolation).
///
/// # Required Method
///
/// ## `linear_interpolate`
///
/// This method calculates the interpolated value for a given input.
///
/// - **Input:**  
///   Requires a value of type `Input` (e.g., a numerical value or coordinate) for which
///   the corresponding interpolated `Point` should be calculated.
///
/// - **Returns:**  
///   - On success, returns a `Result` containing the interpolated value of type `Point`.  
///   - On failure, returns a `Result` containing an error of type `Self::Error` that describes
///     the reason for failure (e.g., invalid input or insufficient data points).
///
/// # Typical Usage
/// This trait is abstract and should be implemented for data structures representing curves
/// or data sets where linear interpolation is required. Examples include interpolating
/// between points on a 2D curve, estimating values in a time series, or refining graphical
/// data.
///
/// # Example Use Case (General)
/// This trait can be used to:
/// - Estimate missing values in a dataset.
/// - Provide smooth transitions between adjacent points on a graph.
/// - Implement real-time interpolations for dynamic systems, such as animations or simulations.
///
/// # Notes on Implementation
/// - Implementors of this trait must ensure that the interpolation logic respects the
///   shape and constraints of the data being used. This involves:
///   - Validating input values.
///   - Handling boundary conditions (e.g., extrapolation or edge points).
///
/// - High precision or custom input/output types (e.g., `Decimal`) can be used when necessary
///   to avoid issues related to floating-point errors in sensitive calculations.
///
/// # Example Implementation Outline
/// 1. Access two known points adjacent to the input value.
/// 2. Compute the slope and intercept of the line between the two points.
/// 3. Evaluate the equation of the line at the given input to determine the interpolated point.
///
/// # Errors
/// When implementing this trait, common errors that may be returned include:
/// - Insufficient data points for interpolation.
/// - Out-of-bounds input values or indices.
/// - Invalid data point structures or internal state errors.
///
/// # See Also
/// - [`crate::geometrics::CubicInterpolation`]: An alternative interpolation method using cubic polynomials.
/// - [`crate::geometrics::InterpolationType`]: Enum representing supported interpolation methods in the library.
///
/// The `LinearInterpolation` trait is part of a modular design and is often re-exported
/// in higher-level library components for ease of use.
pub trait LinearInterpolation<Point, Input> {
    /// Performs linear interpolation for a given input value.
    ///
    /// # Parameters
    /// - `x`: The input value of type `Input` for which the interpolated point should be calculated.
    ///
    /// # Returns
    /// - `Ok(Point)`: The calculated interpolated value of type `Point`.
    /// - `Err(Self::Error)`: An error indicating the reason why interpolation failed.
    ///
    /// # Errors
    ///
    /// Returns [`InterpolationError::EmptyData`] when the sample is
    /// empty, [`InterpolationError::OutOfRange`] when `x` falls
    /// outside the sample domain, and
    /// [`InterpolationError::DegenerateInterval`] when two
    /// bracketing samples share the same `x` coordinate.
    fn linear_interpolate(&self, x: Input) -> Result<Point, InterpolationError>;
}