remove Tuple interfaces

docs/_indicators/BasicQuote.md → docs/_indicators/Use.md

@@ -1,19 +1,19 @@
 ---
-title: Basic quote transforms
+title: Basic quote transform
 description: Basic quote transforms (e.g. HL2, OHL3, etc.) and isolation of individual price quote candle parts from a full OHLCV quote.
-permalink: /indicators/BasicQuote/
+permalink: /indicators/Use/
 type: price-transform
 layout: indicator
 ---
 
 # {{ page.title }}
 
-Returns a basic quote transform (e.g. HL2, OHL3, etc.) and isolation of individual price quote candle parts from a full OHLCV quote.
+Returns a reusable (chainable) basic quote transform (e.g. HL2, OHL3, etc.) by isolating a single value or calculated value from the full OHLCV quote candle parts.
 
 ```csharp
 // C# usage syntax
-IEnumerable<BasicResult> results =
-  quotes.GetBaseQuote(candlePart);
+IEnumerable<Reusable> results =
+  quotes.Use(candlePart);
 ```
 
 ## Parameters
@@ -31,14 +31,14 @@ You must have at least 1 period of `quotes`.
 ## Response
 
 ```csharp
-IEnumerable<BasicResult>
+IEnumerable<Reusable>
 ```
 
 - This method returns a time series of all available indicator values for the `quotes` provided.
 - It always returns the same number of elements as there are in the historical quotes.
 - It does not return a single incremental indicator value.
 
-### BasicResult
+### `Reusable` type
 
 **`Timestamp`** _`DateTime`_ - date from evaluated `TQuote`
 
@@ -56,11 +56,6 @@ Results can be further processed on `Value` with additional chain-enabled indica
 
 ```csharp
 // example
-var results = quotes
-    .GetBaseQuote(CandlePart.OHLC4)
-    .GetRsi(..);
-
-// and is equivalent to
 var results = quotes
     .Use(CandlePart.OHLC4)
     .GetRsi(..);

src/_common/Candles/Candles.Models.cs

@@ -29,6 +29,11 @@ readonly double IReusableResult.Value
     // directional info
     public readonly bool IsBullish => Close > Open;
     public readonly bool IsBearish => Close < Open;
+
+    // this is only an appropriate
+    // implementation for record types
+    public readonly bool Equals(IQuote? other)
+      => base.Equals(other);
 }
 
 public record struct CandleResult : IResult

src/_common/Generics/ISeries.cs

@@ -1,6 +1,16 @@
 namespace Skender.Stock.Indicators;
 
+/// <summary>
+/// Cacheable time-series result.
+/// </summary>
 public interface ISeries
 {
+    /// <summary>
+    /// Date/time of record.
+    /// </summary>
+    /// <remarks>
+    /// For <see cref="IQuote"/> types, this is the
+    /// Close date/time of the candle/bar.
+    /// </remarks>
     DateTime Timestamp { get; }
 }

src/_common/Generics/Pruning.cs

@@ -4,8 +4,6 @@ namespace Skender.Stock.Indicators;
 public static class Pruning
 {
     // REMOVE SPECIFIC PERIODS
-    /// <include file='./info.xml' path='info/type[@name="Prune"]/*' />
-    ///
     public static IEnumerable<T> RemoveWarmupPeriods<T>(
         this IEnumerable<T> series,
         int removePeriods)

src/_common/Generics/Seek.cs

@@ -27,21 +27,10 @@ public static class Seeking
     // May just use this (above) with a try/catch and `bool` primary return type.
 
     // FIND INDEX by DATE
-    /// <include file='./info.xml' path='info/type[@name="FindIndex"]/*' />
     public static int FindIndex<TSeries>(
         this List<TSeries> series,
         DateTime lookupDate)
         where TSeries : ISeries => series == null
             ? -1
             : series.FindIndex(x => x.Timestamp == lookupDate);
-
-    // FIND INDEX by DATE
-    /// <include file='./info.xml' path='info/type[@name="FindIndexChain"]/*' />
-    public static int FindIndex(
-        this List<(DateTime Timestamp, double Value)> tuple,
-        DateTime lookupDate)
-        => tuple == null
-            ? -1
-            : tuple.FindIndex(x => x.Timestamp == lookupDate);
-
 }

src/_common/Observables/AbstractCache.cs

@@ -39,11 +39,11 @@ internal AbstractCache(
 
     public bool IsFaulted { get; internal set; }
 
-    internal List<TSeries> Cache { get; set; }
+    internal List<TSeries> Cache { get; private set; }
 
-    internal TSeries LastArrival { get; set; } = new();
+    private TSeries LastArrival { get; set; } = new();
 
-    internal int OverflowCount { get; set; }
+    private int OverflowCount { get; set; }
 
 
     // METHODS
@@ -74,9 +74,6 @@ public void ClearCache()
     }
 
     /// <inheritdoc/>
-    /// <exception cref="InvalidOperationException">
-    /// `fromTimestamp` not found in cache
-    /// </exception>
     public void ClearCache(DateTime fromTimestamp)
     {
         int s = Cache.FindIndex(fromTimestamp);  // start of range
@@ -91,30 +88,21 @@ public void ClearCache(DateTime fromTimestamp)
         ClearCache(s);
     }
 
-    /// <summary>
-    /// Deletes all cache entries after `fromIndex` (inclusive)
-    /// </summary>
-    /// <param name="fromIndex">From index, inclusive</param>
-    internal void ClearCache(int fromIndex)
-        => ClearCache(fromIndex, toIndex: Math.Max(0, Cache.Count - 1));
+    /// <inheritdoc/>
+    public void ClearCache(int fromIndex)
+        => ClearCache(fromIndex, toIndex: Cache.Count - 1);
 
     /// <summary>
     /// Deletes cache entries between index range values.
     /// </summary>
     /// <remarks>
-    /// This is usually overridden/implemented in inheriting
-    /// classes due to unique requirements to notify subscribers.
+    /// This is overridden/implemented in inheriting class
+    /// due to unique requirement to notify subscribers.
     /// </remarks>
     /// <param name="fromIndex">First element to delete</param>
     /// <param name="toIndex">Last element to delete</param>
-    internal virtual void ClearCache(int fromIndex, int toIndex)
-    {
-        for (int i = toIndex; i >= fromIndex; i--)
-        {
-            TSeries r = Cache[i];
-            ModifyCache(Act.Delete, r);
-        }
-    }
+    protected abstract void ClearCache(
+        int fromIndex, int? toIndex = null);
 
     /// <summary>
     /// Analyze new arrival to determine caching instruction;
@@ -126,7 +114,7 @@ internal virtual void ClearCache(int fromIndex, int toIndex)
     /// <returns cref="Act">Action taken (outcome)</returns>
     /// <exception cref="ArgumentNullException"></exception>
     /// <exception cref="OverflowException"></exception>
-    internal Act CacheWithAnalysis(TSeries item)
+    protected Act CacheWithAnalysis(TSeries item)
     {
         // Currently, only inbound Quote is accepted as an
         // external chain entry point and is the only type
@@ -188,7 +176,7 @@ internal Act CacheWithAnalysis(TSeries item)
     /// <returns cref="Act">Action taken (outcome)</returns>
     /// <exception cref="ArgumentNullException"></exception>
     /// <exception cref="OverflowException"></exception>
-    internal Act PurgeWithAnalysis(TSeries item)
+    protected Act PurgeWithAnalysis(TSeries item)
     {
         // check format and overflow
         if (CheckOverflow(item) is Act.DoNothing)
@@ -223,7 +211,7 @@ internal Act PurgeWithAnalysis(TSeries item)
     /// </param>
     /// <returns cref="Act">Action taken (outcome)</returns>
     /// <exception cref="InvalidOperationException"></exception>
-    internal Act ModifyCache(Act act, TSeries item)
+    protected Act ModifyCache(Act act, TSeries item)
     {
         // execute action
         switch (act)
@@ -245,11 +233,10 @@ internal Act ModifyCache(Act act, TSeries item)
                     Cache.Insert(ao, item);
                 }
 
-                // failure to find should never happen
+                // failure to find old back-position
                 else
                 {
-                    throw new InvalidOperationException(
-                        "Cache insert target not found.");
+                    Cache.Add(item);
                 }
 
                 break;
@@ -259,11 +246,21 @@ internal Act ModifyCache(Act act, TSeries item)
                 // find
                 int uo = Cache.FindIndex(item.Timestamp);
 
-                // replace
-                Cache[uo] = uo != -1
-                    ? item
-                    : throw new InvalidOperationException(
+                // does not exist
+                if (uo == -1)
+                {
+                    throw new InvalidOperationException(
                         "Cache update target not found.");
+                }
+
+                // duplicate
+                if (item.Equals(Cache[uo]))
+                {
+                    return Act.DoNothing;
+                }
+
+                // replace
+                Cache[uo] = item;
 
                 break;
 

src/_common/Observables/AbstractChainInChainOut.cs

@@ -56,30 +56,28 @@ public void Reinitialize(bool withRebuild = true)
     // rebuild cache
     public void RebuildCache() => RebuildCache(0);
 
-    // rebuild cache from date
-    public void RebuildCache(DateTime fromTimestamp)
-        => RebuildCache(fromTimestamp, 0);
-
-    // rebuild cache from timestamp
-    private void RebuildCache(
-        DateTime fromTimestamp, int offset = 0)
+    /// <inheritdoc/>
+    public void RebuildCache(
+        DateTime fromTimestamp)
     {
         int fromIndex = Cache
-            .FindIndex(fromTimestamp);
+            .FindIndex(c => c.Timestamp >= fromTimestamp);
 
-        if (fromIndex == -1)
+        if (fromIndex != -1)
         {
-            throw new InvalidOperationException(
-                "Cache rebuild starting date not found.");
+            RebuildCache(fromIndex);
         }
-
-        RebuildCache(fromIndex, offset);
     }
 
+    /// <inheritdoc/>
+    public void RebuildCache(int fromIndex)
+        => RebuildCache(fromIndex, toIndex: Cache.Count - 1);
+
     // rebuild cache from index
-    private void RebuildCache(int fromIndex, int offset = 0)
+    protected override void RebuildCache(
+        int fromIndex, int? toIndex = null)
     {
-        ClearCache(fromIndex, offset);
-        Provider.Resend(fromIndex, this);
+        ClearCache(fromIndex, toIndex);
+        Provider.Resend(this, fromIndex, toIndex);
     }
 }

src/_common/Observables/AbstractChainInResultOut.cs

@@ -56,30 +56,28 @@ public void Reinitialize(bool withRebuild = true)
     // rebuild cache
     public void RebuildCache() => RebuildCache(0);
 
-    // rebuild cache from date
-    public void RebuildCache(DateTime fromTimestamp)
-        => RebuildCache(fromTimestamp, 0);
-
-    // rebuild cache from timestamp
-    private void RebuildCache(
-        DateTime fromTimestamp, int offset = 0)
+    /// <inheritdoc/>
+    public void RebuildCache(
+        DateTime fromTimestamp)
     {
         int fromIndex = Cache
-            .FindIndex(fromTimestamp);
+            .FindIndex(c => c.Timestamp >= fromTimestamp);
 
-        if (fromIndex == -1)
+        if (fromIndex != -1)
         {
-            throw new InvalidOperationException(
-                "Cache rebuild starting date not found.");
+            RebuildCache(fromIndex);
         }
-
-        RebuildCache(fromIndex, offset);
     }
 
+    /// <inheritdoc/>
+    public void RebuildCache(int fromIndex)
+        => RebuildCache(fromIndex, toIndex: Cache.Count - 1);
+
     // rebuild cache from index
-    private void RebuildCache(int fromIndex, int offset = 0)
+    protected override void RebuildCache(
+        int fromIndex, int? toIndex = null)
     {
-        ClearCache(fromIndex, offset);
-        Provider.Resend(fromIndex, this);
+        ClearCache(fromIndex, toIndex);
+        Provider.Resend(this, fromIndex, toIndex);
     }
 }