diff --git a/src/DynamicData/Cache/ObservableCacheEx.cs b/src/DynamicData/Cache/ObservableCacheEx.cs index e532d15d..2f91f6a8 100644 --- a/src/DynamicData/Cache/ObservableCacheEx.cs +++ b/src/DynamicData/Cache/ObservableCacheEx.cs @@ -41,15 +41,6 @@ public static partial class ObservableCacheEx /// This is a thin wrapper around Rx's Do operator. The adaptor receives each changeset /// as a side effect; the changeset itself is forwarded downstream unmodified. /// - /// - /// EventBehavior - /// AddPassed to the adaptor, then forwarded. - /// UpdatePassed to the adaptor, then forwarded. - /// RemovePassed to the adaptor, then forwarded. - /// RefreshPassed to the adaptor, then forwarded. - /// OnErrorForwarded to the downstream observer. The adaptor is not called. - /// OnCompletedForwarded to the downstream observer. - /// /// /// or is . /// @@ -488,7 +479,6 @@ public static IObservable> AutoRefreshOnObservableUpdateBuffered and included in the merged changeset. /// RemoveBuffered and included in the merged changeset. /// RefreshBuffered and included in the merged changeset. - /// OnErrorForwarded to the downstream observer. /// OnCompletedAny remaining buffered changes are flushed, then completion is forwarded. /// /// Worth noting: The merged changeset may contain contradictory changes (e.g., Add then Remove for the same key). Downstream operators handle this correctly, but raw inspection of the changeset may be surprising. @@ -546,8 +536,8 @@ public static IObservable> BatchIf(this /// UpdateBuffered while paused; forwarded immediately while active. /// RemoveBuffered while paused; forwarded immediately while active. /// RefreshBuffered while paused; forwarded immediately while active. - /// OnErrorForwarded to the downstream observer. Buffered data is lost. - /// OnCompletedForwarded. Any remaining buffered data is flushed before completion. + /// OnErrorBuffered data is lost. + /// OnCompletedAny remaining buffered data is flushed before completion. /// /// Worth noting: If the source completes while paused, buffered data IS flushed before OnCompleted. However, if the source errors while paused, buffered data is lost. /// @@ -935,8 +925,6 @@ public static IObservable> BufferInitialUpdateCalls on the new value and emits an Update. /// RemoveEmits a Remove. The converter is not called. /// RefreshForwarded as Refresh. The converter is not called. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// /// @@ -967,8 +955,6 @@ public static IObservable> CastUpdate is called on the current item. An Update is emitted with the destination key. If the key selector produces a different destination key for the updated value than it did for the original value, downstream consumers will see an Update for a key that may not match the original Add. /// Remove is called on the item. A Remove is emitted with the destination key. /// Refresh is called on the item. A Refresh is emitted with the destination key. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// /// @@ -1069,8 +1055,6 @@ public static void Clear(this LockFreeObservableCacheUpdateThe previous item is removed from and the current item is added. Forwarded as Update. /// RemoveThe item is removed from . Forwarded as Remove. /// RefreshIgnored ( has no concept of refresh). Forwarded as Refresh. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// public static IObservable> Clone(this IObservable> source, ICollection target) @@ -1145,15 +1129,6 @@ public static IObservable> ConvertThe source to defer until the first changeset arrives. /// An observable that begins emitting changesets once the first non-empty changeset is received. /// - /// - /// EventBehavior - /// AddForwarded as Add once the initial non-empty changeset has been received. - /// UpdateForwarded as Update once loaded. - /// RemoveForwarded as Remove once loaded. - /// RefreshForwarded as Refresh once loaded. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. - /// /// Worth noting: Blocks indefinitely if the cache or stream never receives any data. Ensure the source will eventually emit at least one changeset. /// /// @@ -1314,8 +1289,6 @@ public static void EditDiff(this ISourceCache sour /// UpdateItems present in both snapshots that differ (per ) produce an Update. /// RemoveItems in the previous snapshot whose key is absent from the new snapshot produce a Remove. /// RefreshNot produced by this operator. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// /// or is . @@ -1347,8 +1320,6 @@ public static IObservable> EditDiff(thi /// UpdateEmitted when the source produces Some(value) and an item was already tracked with a different value (per ). /// RemoveEmitted when the source produces None and an item was previously tracked. /// RefreshNot produced by this operator. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// /// or is . @@ -1377,8 +1348,7 @@ public static IObservable> EditDiff(thi /// UpdateForwarded as Update if the key is unique within the changeset. /// RemoveForwarded as Remove if the key is unique within the changeset. /// RefreshForwarded as Refresh if the key is unique within the changeset. - /// OnErrorForwarded. Also emitted with if duplicate keys are detected in a changeset. - /// OnCompletedForwarded to the downstream observer. + /// OnErrorAlso emitted with if duplicate keys are detected in a changeset. /// /// public static IObservable> EnsureUniqueKeys(this IObservable> source) @@ -1509,8 +1479,8 @@ public static IObservable> Except(this /// UpdateResets the removal timer for the item. Forwarded as Update. /// RemoveCancels the removal timer. Forwarded as Remove. /// RefreshForwarded as Refresh. No timer change. - /// OnErrorForwarded. All pending timers are cancelled. - /// OnCompletedForwarded. All pending timers are cancelled. + /// OnErrorAll pending timers are cancelled. + /// OnCompletedAll pending timers are cancelled. /// /// Worth noting: A return from means "never expire". Update changes reset the expiration timer. /// @@ -1623,8 +1593,6 @@ public static IObservable>> ExpireAfter< /// UpdateFour outcomes: if both old and new values pass, an Update is emitted. If only the new value passes, an Add is emitted. If only the old value passed, a Remove is emitted. If neither passes, the change is dropped. /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. /// RefreshThe predicate is re-evaluated. If the item now passes but previously did not, an Add is emitted. If it still passes, a Refresh is forwarded. If it no longer passes, a Remove is emitted. If it still fails, the change is dropped. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// Worth noting: Refresh events trigger re-evaluation, which can promote or demote items. Pair with for property-change-driven filtering. /// @@ -1683,8 +1651,6 @@ public static IObservable> Filter( /// UpdateRe-evaluated. Four outcomes as with the static overload. /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. /// RefreshRe-evaluated against the current state. May produce Add, Refresh, Remove, or be dropped. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// Worth noting: should emit an initial value immediately. Each emission triggers a full re-evaluation of all items, which can be expensive for large collections. /// @@ -1754,8 +1720,6 @@ public static IObservable> Filter( /// UpdateFour outcomes: if both old and new values pass, an Update is emitted. If only the new value passes, an Add is emitted. If only the old value passed, a Remove is emitted. If neither passes, the change is dropped. /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. /// RefreshDropped. Because items are assumed immutable, there is nothing to re-evaluate. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// public static IObservable> FilterImmutable( @@ -2137,8 +2101,6 @@ public static IObservable> GroupUpdateThe group key is re-evaluated. If unchanged, an Update is emitted within the same group. If the key changed, the item is removed from the old group (emitting Remove) and added to the new group (emitting Add). An empty old group is removed. /// RemoveThe item is removed from its group. If the group becomes empty, the group itself is removed from the output. /// RefreshThe group key is re-evaluated. If unchanged, a Refresh is forwarded within the group. If the key changed, the item moves between groups (Remove from old, Add to new). - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// /// Worth noting: Each group is a live sub-cache that can be subscribed to independently. Subscribers @@ -2201,8 +2163,6 @@ public static IObservable> GroupUpdateGroup key re-evaluated. Item may move between groups if the key changed. /// RemoveItem removed from its group. Empty groups are removed. /// RefreshGroup key re-evaluated. Item may move between groups. - /// OnErrorForwarded from source or from . - /// OnCompletedForwarded when the source completes. /// /// /// @@ -2380,8 +2340,6 @@ public static IObservable> Gr /// UpdateIf group key unchanged, group snapshot re-emitted. If changed, item moves between groups; both affected groups emit new snapshots. /// RemoveItem removed from group. Updated snapshot emitted. Empty groups are removed. /// RefreshGroup key re-evaluated. If changed, item moves; affected group snapshots emitted. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// /// @@ -2632,8 +2590,6 @@ public static IObservable> InnerJoinManyUpdateForwarded unchanged. /// RemoveForwarded unchanged. /// RefreshCalls Evaluate() on the item, then forwards the change. - /// OnErrorForwarded to subscribers. - /// OnCompletedForwarded to subscribers. /// /// public static IObservable> InvokeEvaluate(this IObservable> source) @@ -2814,8 +2770,6 @@ public static IObservable> LeftJoinManyUpdateForwarded unchanged. /// RemoveForwarded unchanged. /// RefreshForwarded unchanged. - /// OnErrorForwarded to subscribers. - /// OnCompletedForwarded to subscribers. /// /// /// is . @@ -2904,7 +2858,6 @@ public static IObservable>> LimitSizeTo< /// RemoveDisposes the child subscription for the removed item. /// RefreshNo effect on subscriptions. The child observable continues unchanged. /// OnErrorErrors from child observables are silently swallowed (the child is unsubscribed). Errors from the source changeset stream terminate the merged output. - /// OnCompletedThe output completes only when the source completes and all active child observables have also completed. /// /// Worth noting: The output is a plain , not a changeset stream. If you need merged changesets, use instead. /// @@ -2970,7 +2923,6 @@ public static IObservable MergeMany(t /// UpdateIf the updating source currently owns the downstream value for this key, an Update is emitted. If a comparer is provided and the update causes a different source's value to become the best candidate, an Update is emitted with that other source's value. /// RemoveIf the removed value was the one published downstream, the operator scans all remaining sources for the same key. If another source still holds that key, an Update is emitted with the replacement value (selected by comparer if provided, otherwise the next available). If no other source holds the key, a Remove is emitted. /// RefreshIf the refreshed item matches the currently published value, the Refresh is forwarded. With a comparer, all sources are re-evaluated first; if a different value now wins, an Update is emitted instead of the Refresh. - /// OnErrorAn error from any source (outer or inner) terminates the entire merged output. /// OnCompletedFor dynamic overloads, the output completes when the outer observable completes and all subscribed inner observables have also completed. For static overloads, completion depends on the completable parameter (default ). /// /// @@ -3834,8 +3786,6 @@ public static IObservable> NotEmpty(thi /// UpdateRe-evaluated. If the new item is , emit accordingly. If the old item was downstream but the new one is not, emit Remove. /// RemoveIf the item was downstream, emit Remove. /// RefreshIf the item is downstream, forwarded as Refresh. - /// OnErrorForwarded to subscribers. - /// OnCompletedForwarded to subscribers. /// /// /// is . @@ -4071,8 +4021,6 @@ public static IObservable> OnItemUpdatedUpdateIf the item is currently downstream, an Update is emitted. /// RemoveReference count decremented. If the count reaches zero (no source holds the key), a Remove is emitted. Otherwise no emission. /// RefreshIf the item is downstream, a Refresh is forwarded. - /// OnErrorAn error from any source terminates the combined output. - /// OnCompletedThe output completes when all sources have completed. /// /// /// or is . @@ -4224,6 +4172,7 @@ public static IDisposable PopulateFrom(this ISourceCache or is . /// /// + /// public static IDisposable PopulateInto(this IObservable> source, ISourceCache destination) where TObject : notnull where TKey : notnull @@ -4273,15 +4222,6 @@ public static IDisposable PopulateInto(this IObservableA function that projects the current snapshot to a result value. /// An observable that emits a projected value after each changeset. /// - /// - /// EventBehavior - /// AddCache updated, then invoked and result emitted. - /// UpdateCache updated, then invoked and result emitted. - /// RemoveCache updated, then invoked and result emitted. - /// RefreshCache updated, then invoked and result emitted. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. - /// /// Worth noting: The selector is called on every changeset, which can be chatty. The exposes the full cache state for LINQ-style queries. /// /// or is . @@ -4362,11 +4302,6 @@ public static IObservable> RefCount(thi /// The item to refresh. /// /// Convenience method that wraps a Refresh inside . A Refresh does not change data in the cache; it signals downstream operators (such as or ) to re-evaluate the item. - /// - /// EventBehavior - /// RefreshProduced for the specified item. Downstream operators re-evaluate this item against their current logic (filter predicate, sort comparer, group key selector, etc.). - /// OtherNo Add, Update, or Remove events are produced by this method. - /// /// /// is . /// @@ -4422,11 +4357,6 @@ public static void Refresh(this ISourceCache sourc /// The item to remove. /// /// Convenience method that wraps a single-item removal inside . The key is extracted from the item using the cache's key selector. - /// - /// EventBehavior - /// RemoveProduced if the key exists in the cache. The removed value is included in the changeset. - /// OtherNo Add, Update, or Refresh events are produced by this method. - /// /// /// is . /// @@ -4892,6 +4822,7 @@ public static IObservable> SortBy /// The type of the key. /// The source to prepend an empty changeset to. /// An observable that emits an empty changeset first, then all source changesets. + /// public static IObservable> StartWithEmpty(this IObservable> source) where TObject : notnull where TKey : notnull => source.StartWith(ChangeSet.Empty); @@ -5074,15 +5005,6 @@ public static IObservable> Switch(this /// An of changeset streams. The operator subscribes to the latest inner stream. /// A changeset stream reflecting the items from the most recently emitted inner source. /// - /// - /// EventBehavior - /// AddForwarded from the active inner source. - /// UpdateForwarded from the active inner source. - /// RemoveForwarded from the active inner source. - /// RefreshForwarded from the active inner source. - /// OnErrorAn error from any inner source or the outer source terminates the stream. - /// OnCompletedCompletes when the outer source and the current inner source have both completed. - /// /// On switch: Remove is emitted for all items from the previous source, then Add for all items from the new source. /// Worth noting: Each switch clears the entire downstream cache before populating from the new source. Subscribers see a full remove-then-add reset on every switch. /// @@ -5102,6 +5024,7 @@ public static IObservable> Switch(this /// The type of the key. /// The source to materialize into a collection on each change. /// An observable which emits the read only collection. + /// public static IObservable> ToCollection(this IObservable> source) where TObject : notnull where TKey : notnull => source.QueryWhenChanged(query => new ReadOnlyCollectionLight(query.Items)); @@ -5195,8 +5118,6 @@ public static IObservable> ToObservableChangeSetUpdateEmits Optional.Some(newValue) if the new value differs from the previous per . Otherwise suppressed. /// RemoveEmits . /// RefreshEmits Optional.Some(value) if the value differs from the last emission per . Otherwise suppressed. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// Worth noting: No emission occurs if the key is not present at subscription time. To get an initial None when the key is absent, use the overload with initialOptionalWhenMissing: true. /// @@ -5254,6 +5175,7 @@ public static IObservable> ToObservableOptional /// The sort function. /// The sort order. Defaults to ascending. /// An observable which emits the read only collection. + /// public static IObservable> ToSortedCollection(this IObservable> source, Func sort, SortDirection sortOrder = SortDirection.Ascending) where TObject : notnull where TKey : notnull @@ -6279,8 +6201,6 @@ static IEnumerable> ReplaceMoves(IChangeSet /// UpdateThe item is replaced in the collection snapshot. Condition recalculated. /// RemovePer-item subscription disposed. Condition recalculated over remaining items. /// RefreshNo effect on per-item subscriptions. Condition not recalculated unless the per-item observable emits. - /// OnErrorAn error from any per-item observable terminates the entire stream. Source errors also terminate. - /// OnCompletedCompletes when the source and all per-item observables have completed. /// /// Worth noting: Items whose per-item observable has not yet emitted are treated as not satisfying the condition. An empty cache is vacuously . The result uses DistinctUntilChanged, so duplicate bool values are suppressed. /// @@ -6332,8 +6252,6 @@ public static IObservable TrueForAll(this IObservab /// UpdateThe item is replaced in the collection snapshot. Condition recalculated. /// RemovePer-item subscription disposed. Condition recalculated over remaining items. /// RefreshNo effect on per-item subscriptions. Condition not recalculated unless the per-item observable emits. - /// OnErrorAn error from any per-item observable terminates the entire stream. Source errors also terminate. - /// OnCompletedCompletes when the source and all per-item observables have completed. /// /// Worth noting: Items whose per-item observable has not yet emitted are treated as not satisfying the condition. An empty cache yields . The result uses DistinctUntilChanged, so duplicate bool values are suppressed. /// @@ -6421,8 +6339,6 @@ public static IObservable> Watch(this IObse /// UpdateEmits the new value. /// RemoveEmits the removed item's value (not None; use if you need removal detection). /// RefreshEmits the current value. - /// OnErrorForwarded to the downstream observer. - /// OnCompletedForwarded to the downstream observer. /// /// Worth noting: No emission occurs if the key is not present at subscription time. Changes to other keys are ignored entirely. /// @@ -6473,7 +6389,6 @@ public static IObservable WatchValue(this IObservableRemoveDisposes the item's PropertyChanged subscription. /// RefreshNo effect on subscriptions. /// OnErrorErrors from individual property subscriptions are silently ignored. Source errors terminate the stream. - /// OnCompletedCompletes when the source changeset stream completes. /// /// /// @@ -6513,7 +6428,6 @@ public static IObservable WatchValue(this IObservableRemoveDisposes the item's property subscription. No further emissions for this item. /// RefreshNo effect on subscriptions. The existing property subscription continues. /// OnErrorPer-item property subscription errors are silently ignored. Source errors terminate the stream. - /// OnCompletedCompletes when the source changeset stream completes. /// /// /// @@ -6551,7 +6465,6 @@ public static IObservable> WhenPropertyChangedRemoveDisposes the property subscription. /// RefreshNo effect on subscriptions. /// OnErrorPer-item errors silently ignored. Source errors terminate the stream. - /// OnCompletedCompletes when the source completes. /// /// /// @@ -6648,8 +6561,6 @@ public static IObservable> WhereReasonsAreNotUpdateIf the item is currently downstream (count is 1), an Update is emitted. /// RemoveReference count decremented. If the count drops to exactly 1, an Add is emitted (the item is now exclusive to one source). If it drops to 0, a Remove is emitted. /// RefreshIf the item is downstream, a Refresh is forwarded. - /// OnErrorAn error from any source terminates the combined output. - /// OnCompletedThe output completes when all sources have completed. /// /// /// or is . diff --git a/src/DynamicData/List/ListFilterPolicy.cs b/src/DynamicData/List/ListFilterPolicy.cs index 69099808..8b347a76 100644 --- a/src/DynamicData/List/ListFilterPolicy.cs +++ b/src/DynamicData/List/ListFilterPolicy.cs @@ -10,14 +10,20 @@ namespace DynamicData; public enum ListFilterPolicy { /// - /// Clear all items and replace with matches - optimised for large data sets. - /// This option preserves order. + /// Clears all items and replaces with the new matches. Preserves order. + /// + /// Useful when downstream consumers (such as UI bindings) handle full resets more efficiently than individual + /// Add/Remove changes, or when the change set is expected to be very large relative to the source. + /// /// ClearAndReplace, /// - /// Calculate diff set - optimised for general filtering. - /// This option does not preserve order. + /// Calculates the minimal diff between the previous and new result sets. Does not preserve order. + /// + /// Generally preferred for performance: only items whose inclusion status actually changed produce an Add or Remove. + /// Recommended for most scenarios. + /// /// CalculateDiff } diff --git a/src/DynamicData/List/ObservableListEx.cs b/src/DynamicData/List/ObservableListEx.cs index 2f871bf4..37f3a396 100644 --- a/src/DynamicData/List/ObservableListEx.cs +++ b/src/DynamicData/List/ObservableListEx.cs @@ -1,4 +1,4 @@ -// Copyright (c) 2011-2025 Roland Pheasant. All rights reserved. +// Copyright (c) 2011-2025 Roland Pheasant. All rights reserved. // Roland Pheasant licenses this file to you under the MIT license. // See the LICENSE file in the project root for full license information. @@ -24,17 +24,21 @@ namespace DynamicData; public static class ObservableListEx { /// - /// Injects a side effect into a change set observable. + /// Injects a side effect into a changeset stream via an . + /// The adaptor's Adapt method is invoked for each changeset before it is forwarded downstream unchanged. /// - /// The type of the item. - /// The source. - /// The adaptor. - /// An observable which emits the change set. - /// - /// source - /// or - /// adaptor. - /// + /// The type of items in the list. + /// The source to observe and adapt. + /// The adaptor whose Adapt method is invoked for each changeset. + /// A list changeset stream identical to the source, with the adaptor side effect applied. + /// or is . + /// + /// + /// This is the primary extension point for custom UI binding adaptors (e.g., + /// delegates to this operator). If the adaptor throws, the exception propagates downstream as OnError. + /// + /// + /// public static IObservable> Adapt(this IObservable> source, IChangeSetAdaptor adaptor) where T : notnull { @@ -55,16 +59,21 @@ public static IObservable> Adapt(this IObservable } /// - /// Adds a key to the change set result which enables all observable cache features of dynamic data. + /// Adds a key to each item in a list changeset, converting it to a cache changeset that supports all keyed DynamicData operators. /// + /// The type of items in the list. + /// The type of the key. + /// The source to add keys to, converting to a cache changeset. + /// A function to extract a unique key from each item. + /// A cache changeset stream with keyed items. + /// or is . /// - /// All indexed changes are dropped i.e. sorting is not supported by this function. + /// + /// All index information is dropped during conversion because cache changesets are unordered by default. + /// Use this when you need to transition from list-based pipelines to cache-based operators (Filter by key, Join, Group, etc.). + /// /// - /// The type of object. - /// The type of key. - /// The source. - /// The key selector. - /// An observable which emits the change set. + /// public static IObservable> AddKey(this IObservable> source, Func keySelector) where TObject : notnull where TKey : notnull @@ -76,13 +85,33 @@ public static IObservable> AddKey(this } /// - /// Apply a logical And operator between the collections. - /// Items which are in all of the sources are included in the result. + /// Applies a logical AND (intersection) between multiple list changeset streams. + /// Only items present in ALL sources appear in the result. /// - /// The type of the item. - /// The source. - /// The others. - /// An observable which emits the change set. + /// The type of items in the lists. + /// The first source to intersect. + /// The additional changeset streams to intersect with. + /// A list changeset stream containing items that exist in every source. + /// is . + /// + /// + /// Uses reference counting per item across all sources. An item appears downstream only when + /// its reference count is non-zero in ALL sources. Item identity is determined by the default equality comparer. + /// + /// + /// EventBehavior + /// Add/AddRangeThe item's reference count is incremented in its source tracker. If the item is now present in all sources, an Add is emitted. + /// ReplaceThe old item's reference count is decremented and the new item's is incremented. Depending on whether each is present in ALL sources, this emits an Add, Remove, Replace, or nothing. + /// Remove/RemoveRange/ClearThe item's reference count is decremented. If it was in the result and is no longer in all sources, a Remove is emitted. + /// RefreshForwarded as Refresh if the item is currently in the result. + /// MovedIgnored (set operations are position-independent). + /// + /// Worth noting: Item identity uses object equality, not position. Duplicate items in a single source are reference-counted independently. + /// + /// + /// + /// + /// public static IObservable> And(this IObservable> source, params IObservable>[] others) where T : notnull { @@ -91,53 +120,49 @@ public static IObservable> And(this IObservable> return source.Combine(CombineOperator.And, others); } - /// - /// Apply a logical And operator between the collections. - /// Items which are in all of the sources are included in the result. - /// - /// The type of the item. - /// The sources. - /// An observable which emits the change set. + /// + /// A of changeset streams to intersect. + /// + /// + /// This overload accepts a pre-built collection of sources instead of a params array. + /// public static IObservable> And(this ICollection>> sources) where T : notnull => sources.Combine(CombineOperator.And); - /// - /// Dynamically apply a logical And operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. - /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// + /// An of changeset streams. Sources can be added or removed dynamically. + /// + /// + /// This overload supports dynamic source management: adding or removing changeset streams from the observable list triggers re-evaluation. + /// public static IObservable> And(this IObservableList>> sources) where T : notnull => sources.Combine(CombineOperator.And); - /// - /// Dynamically apply a logical And operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. - /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// + /// An of . Each inner list's changes are connected automatically. + /// + /// + /// This overload accepts instances directly, calling Connect() internally. + /// public static IObservable> And(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.And); - /// - /// Dynamically apply a logical And operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. - /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// + /// An of . Each inner list's changes are connected automatically. + /// + /// + /// This overload accepts instances directly, calling Connect() internally. + /// public static IObservable> And(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.And); /// - /// Converts the source list to an read only observable list. + /// Wraps a as a read-only , hiding mutation methods. /// - /// The type of the item. - /// The source. - /// An observable list. - /// source. + /// The type of items in the list. + /// The mutable source list to wrap. + /// A read-only observable list that mirrors the source. + /// is . public static IObservableList AsObservableList(this ISourceList source) where T : notnull { @@ -147,12 +172,21 @@ public static IObservableList AsObservableList(this ISourceList source) } /// - /// Converts the source observable to an read only observable list. + /// Materializes a changeset stream into a read-only . + /// The list is kept in sync with the source stream for the lifetime of the subscription. /// - /// The type of the item. - /// The source. - /// An observable list. - /// source. + /// The type of items in the list. + /// The source to materialize into a read-only list. + /// A read-only observable list reflecting the current state of the stream. + /// is . + /// + /// + /// This is the primary way to multicast a changeset pipeline. Materializing once into an , + /// then calling Connect() on the result for each downstream consumer, ensures the upstream operators are evaluated only once + /// regardless of how many subscribers consume the result. + /// + /// + /// public static IObservableList AsObservableList(this IObservable> source) where T : notnull { @@ -162,14 +196,36 @@ public static IObservableList AsObservableList(this IObservable - /// Automatically refresh downstream operators when any property changes. + /// Monitors all properties on each item (via ) and emits Refresh + /// changes when any property changes, causing downstream operators to re-evaluate. /// - /// The type of object. - /// The source observable. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements have successive property changes. - /// When observing on multiple property changes, apply a throttle to prevent excessive refresh invocations. - /// The scheduler. - /// An observable change set with additional refresh changes. + /// The type of items, which must implement . + /// The source to monitor for property-driven refresh signals. + /// An optional buffer duration to batch multiple refresh signals into a single changeset. + /// An optional throttle applied to each item's property change notifications. + /// The scheduler for throttle and buffer timing. Defaults to . + /// A list changeset stream with additional Refresh changes injected when properties change. + /// is . + /// + /// + /// Wraps using WhenAnyPropertyChanged() as the re-evaluator. + /// Pair with or + /// to get reactive re-evaluation on property changes. + /// + /// + /// EventBehavior + /// Add/AddRangeSubscribes to PropertyChanged on each new item. The original change is forwarded. + /// ReplaceUnsubscribes from the old item, subscribes to the new. The original change is forwarded. + /// Remove/RemoveRange/ClearUnsubscribes from removed items. The original change is forwarded. + /// Moved/RefreshForwarded unchanged. + /// Property changesA Refresh change is emitted for the item whose property changed. + /// + /// Worth noting: Each item generates a subscription. For large lists with frequent property changes, use and to reduce churn. + /// + /// + /// + /// + /// public static IObservable> AutoRefresh(this IObservable> source, TimeSpan? changeSetBuffer = null, TimeSpan? propertyChangeThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged { @@ -190,16 +246,11 @@ public static IObservable> AutoRefresh(this IObserv } /// - /// Automatically refresh downstream operators when properties change. + /// Monitors a single property (selected by ) on each item via + /// and emits Refresh changes when that property changes, causing downstream operators to re-evaluate. More efficient than + /// the all-properties overload when only one property (of type ) affects downstream behavior. /// - /// The type of object. - /// The type of property. - /// The source observable. - /// Specify a property to observe changes. When it changes a Refresh is invoked. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements have successive property changes. - /// When observing on multiple property changes, apply a throttle to prevent excessive refresh invocations. - /// The scheduler. - /// An observable change set with additional refresh changes. + /// public static IObservable> AutoRefresh(this IObservable> source, Expression> propertyAccessor, TimeSpan? changeSetBuffer = null, TimeSpan? propertyChangeThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged { @@ -221,15 +272,34 @@ public static IObservable> AutoRefresh(t } /// - /// Automatically refresh downstream operator. The refresh is triggered when the observable receives a notification. + /// Monitors each item with a custom observable and emits Refresh changes whenever that observable fires, + /// causing downstream operators (Filter, Sort, Group) to re-evaluate. /// - /// The type of object. - /// A ignored type used for specifying what to auto refresh on. - /// The source observable change set. - /// An observable which acts on items within the collection and produces a value when the item should be refreshed. - /// Batch up changes by specifying the buffer. This greatly increases performance when many elements require a refresh. - /// The scheduler. - /// An observable change set with additional refresh changes. + /// The type of items in the list. + /// The type emitted by the re-evaluator observable (value is ignored). + /// The source to monitor for observable-driven refresh signals. + /// A factory that, given an item, returns an observable whose emissions trigger a Refresh for that item. + /// An optional buffer duration to batch refresh signals into a single changeset. + /// The for buffering. + /// A list changeset stream with additional Refresh changes injected when per-item observables fire. + /// or is . + /// + /// + /// This is the general-purpose refresh mechanism. + /// is a convenience wrapper that uses WhenAnyPropertyChanged() as the re-evaluator. + /// + /// + /// EventBehavior + /// Add/AddRangeSubscribes to the re-evaluator observable for each new item. The original change is forwarded. + /// ReplaceUnsubscribes from the old item's observable, subscribes to the new. The original change is forwarded. + /// Remove/RemoveRange/ClearUnsubscribes from removed items. The original change is forwarded. + /// Moved/RefreshForwarded unchanged. + /// Re-evaluator firesThe item's current index is looked up and a Refresh change is emitted. + /// + /// + /// + /// + /// public static IObservable> AutoRefreshOnObservable(this IObservable> source, Func> reevaluator, TimeSpan? changeSetBuffer = null, IScheduler? scheduler = null) where TObject : notnull { @@ -240,18 +310,36 @@ public static IObservable> AutoRefreshOnObservable - /// Binds a clone of the observable change set to the target observable collection. + /// Applies changeset mutations to a target for UI data binding. /// - /// The type of the item. - /// The source. - /// The target collection. - /// The reset threshold. - /// An observable which emits the change set. - /// - /// source - /// or - /// targetCollection. - /// + /// The type of items in the list. + /// The source to bind to a collection. + /// The target collection to keep in sync. + /// When a changeset exceeds this many changes, the collection is reset instead of applying individual changes. + /// A continuation of the source changeset stream (allows further chaining). + /// or is . + /// + /// + /// Delegates to with an internal collection adaptor. + /// Each changeset is applied to the target collection on the calling thread. For UI binding, ensure the source is + /// observed on the UI thread (e.g., via ObserveOn). + /// + /// + /// EventBehavior + /// AddItem inserted at the specified index in the target collection. + /// AddRangeItems inserted as a range. If the count exceeds , the collection is cleared and repopulated. + /// ReplaceItem at the specified index is replaced. + /// RemoveItem at the specified index is removed. + /// RemoveRange/ClearItems removed from the collection. + /// MovedItem is moved between positions in the collection. + /// RefreshDepends on the adaptor implementation. + /// + /// + /// + /// + /// + /// + /// public static IObservable> Bind(this IObservable> source, IObservableCollection targetCollection, int resetThreshold = BindingOptions.DefaultResetThreshold) where T : notnull { @@ -270,18 +358,9 @@ public static IObservable> Bind(this IObservable> } /// - /// Binds a clone of the observable change set to the target observable collection. + /// Binds the source changeset stream to , with fine-grained control over reset threshold and other behaviors. /// - /// The type of the item. - /// The source. - /// The target collection. - /// The binding options. - /// An observable which emits the change set. - /// - /// source - /// or - /// targetCollection. - /// + /// public static IObservable> Bind(this IObservable> source, IObservableCollection targetCollection, BindingOptions options) where T : notnull { @@ -293,13 +372,15 @@ public static IObservable> Bind(this IObservable> } /// - /// Creates a binding to a readonly observable collection which is specified as an 'out' parameter. + /// Constructs a and binds the changeset stream to it. + /// Use this overload when you need a read-only view (typically for UI binding) without managing the backing collection yourself. + /// The created collection is returned via the output parameter. /// - /// The type of the item. - /// The source. - /// The resulting read only observable collection. - /// The reset threshold. - /// A continuation of the source stream. + /// + /// + /// + /// The created collection is backed by an internal ObservableCollectionExtended<T>. Callers receive only the read-only wrapper. + /// public static IObservable> Bind(this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, int resetThreshold = BindingOptions.DefaultResetThreshold) where T : notnull { @@ -316,13 +397,15 @@ public static IObservable> Bind(this IObservable> } /// - /// Creates a binding to a readonly observable collection which is specified as an 'out' parameter. + /// Constructs a and binds the changeset stream to it, + /// with fine-grained control over reset threshold and other behaviors. + /// The created collection is returned via the output parameter. /// - /// The type of the item. - /// The source. - /// The resulting read only observable collection. - /// The binding options. - /// A continuation of the source stream. + /// + /// + /// + /// The created collection is backed by an internal ObservableCollectionExtended<T>. Callers receive only the read-only wrapper. + /// public static IObservable> Bind(this IObservable> source, out ReadOnlyObservableCollection readOnlyObservableCollection, BindingOptions options) where T : notnull { @@ -338,18 +421,9 @@ public static IObservable> Bind(this IObservable> #if SUPPORTS_BINDINGLIST /// - /// Binds a clone of the observable change set to the target observable collection. + /// Binds the source changeset stream to a WinForms , keeping in sync. /// - /// The type of the item. - /// The source. - /// The target binding list. - /// The reset threshold. - /// - /// source - /// or - /// targetCollection. - /// - /// An observable which emits the change set. + /// public static IObservable> Bind<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.All)] T>(this IObservable> source, BindingList bindingList, int resetThreshold = BindingOptions.DefaultResetThreshold) where T : notnull { @@ -361,30 +435,19 @@ public static IObservable> Bind(this IObservable> #endif - /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// The scheduler. - /// An observable which emits the change set. - /// source. + /// + /// + /// + /// This overload starts unpaused and has no timeout. + /// public static IObservable> BufferIf(this IObservable> source, IObservable pauseIfTrueSelector, IScheduler? scheduler = null) where T : notnull => BufferIf(source, pauseIfTrueSelector, false, scheduler); - /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// if set to true [initial pause state]. - /// The scheduler. - /// An observable which emits the change set. - /// source. + /// + /// + /// + /// This overload allows setting the initial pause state but has no timeout. + /// public static IObservable> BufferIf(this IObservable> source, IObservable pauseIfTrueSelector, bool initialPauseState, IScheduler? scheduler = null) where T : notnull { @@ -394,32 +457,42 @@ public static IObservable> BufferIf(this IObservable - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. - /// - /// The type of the object. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// Specify a time to ensure the buffer window does not stay open for too long. - /// The scheduler. - /// An observable which emits the change set. - /// source. + /// + /// + /// + /// This overload starts unpaused and accepts a timeout but not an explicit initial pause state. + /// public static IObservable> BufferIf(this IObservable> source, IObservable pauseIfTrueSelector, TimeSpan? timeOut, IScheduler? scheduler = null) where T : notnull => BufferIf(source, pauseIfTrueSelector, false, timeOut, scheduler); /// - /// Batches the underlying updates if a pause signal (i.e when the buffer selector return true) has been received. - /// When a resume signal has been received the batched updates will be fired. + /// Buffers changeset notifications while a pause signal is active, then flushes all buffered changes when resumed. /// - /// The type of the object. - /// The source. - /// When true, observable begins to buffer and when false, window closes and buffered result if notified. - /// if set to true [initial pause state]. - /// Specify a time to ensure the buffer window does not stay open for too long. - /// The scheduler. - /// An observable which emits the change set. - /// source. + /// The type of items in the list. + /// The source to conditionally buffer. + /// An of that controls buffering: pauses (buffers), resumes (flushes). + /// The initial pause state. When , buffering starts immediately. + /// An optional maximum duration to keep the buffer open. After this time, the buffer is flushed regardless of pause state. + /// The for timeout scheduling. + /// A list changeset stream that buffers during pause and emits combined changesets on resume. + /// or is . + /// + /// + /// All changeset events are buffered at the changeset level (not individual changes) while paused. + /// On resume, all buffered changesets are emitted as a single combined changeset. If the buffer is empty on resume, + /// no emission occurs. + /// + /// + /// EventBehavior + /// Any (while paused)Accumulated in an internal buffer. Not emitted downstream. + /// Any (while active)Passed through immediately. + /// Pause selector emits falseAll buffered changesets are flushed downstream as one combined changeset. + /// Timeout firesAutomatically resumes and flushes the buffer. + /// OnErrorForwarded immediately (not buffered). + /// OnCompletedForwarded immediately. + /// + /// Worth noting: Each pause/resume cycle re-arms the timeout. Rapid toggling can create many small buffer windows. + /// public static IObservable> BufferIf(this IObservable> source, IObservable pauseIfTrueSelector, bool initialPauseState, TimeSpan? timeOut, IScheduler? scheduler = null) where T : notnull { @@ -430,13 +503,21 @@ public static IObservable> BufferIf(this IObservable - /// Buffers changes for an initial period only. After the period has elapsed, not further buffering occurs. + /// Buffers changesets during an initial time window, then emits a single combined changeset and passes through subsequent changes. /// - /// The type of object. - /// The source change set. - /// The period to buffer, measure from the time that the first item arrives. - /// The scheduler to buffer on. - /// An observable which emits the change set. + /// The type of items in the list. + /// The source to buffer during the initial loading period. + /// The time period (measured from first emission) during which changes are buffered. + /// The for timing the buffer window. + /// A list changeset stream where the initial burst is combined into one changeset. + /// + /// + /// For a configured duration after the first emission, all changesets are buffered and combined into a single emission. + /// After this initial window, subsequent changesets pass through immediately. + /// + /// + /// + /// public static IObservable> BufferInitial(this IObservable> source, TimeSpan initialBuffer, IScheduler? scheduler = null) where TObject : notnull => source.DeferUntilLoaded().Publish( shared => @@ -447,11 +528,14 @@ public static IObservable> BufferInitial(this IObse }); /// - /// Cast the changes to another form. + /// Casts each item in the changeset from object to using a direct cast. /// - /// The type of the destination. - /// The source. - /// An observable which emits the change set. + /// The target type to cast to. + /// The source of object items. + /// A list changeset stream of cast items. + /// is . + /// + /// public static IObservable> Cast(this IObservable> source) where TDestination : notnull { @@ -461,14 +545,17 @@ public static IObservable> Cast(this IObs } /// - /// Cast the changes to another form. - /// Alas, I had to add the converter due to type inference issues. The converter can be avoided by CastToObject() first. + /// Transforms each item in the changeset using a conversion function. /// - /// The type of the object. - /// The type of the destination. - /// The source. - /// The conversion factory. - /// An observable which emits the change set. + /// The source item type. + /// The destination item type. + /// The source to cast. + /// A function to convert each item from to . + /// A list changeset stream of converted items. + /// or is . + /// Use this overload when type inference requires explicit specification of both source and destination types. Alternatively, call first, then the single-type-parameter overload. + /// + /// public static IObservable> Cast(this IObservable> source, Func conversionFactory) where TSource : notnull where TDestination : notnull @@ -481,22 +568,28 @@ public static IObservable> Cast( } /// - /// Cast the underlying type of an object. Use before a Cast function. + /// Casts each item in the changeset to object. Typically used before to work around type inference limitations. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// The source item type (must be a reference type). + /// The source to cast to object. + /// A list changeset stream of object items. + /// public static IObservable> CastToObject(this IObservable> source) where T : class => source.Select(changes => changes.Transform(t => (object)t)); /// - /// Clones the target list as a side effect of the stream. + /// Applies each changeset to the target list as a side effect, keeping it synchronized with the source. /// - /// The type of the item. - /// The source. - /// The target of the clone. - /// An observable which emits the change set. - /// source. + /// The type of items in the list. + /// The source to clone. + /// The target list to clone changes into. + /// A continuation of the source changeset stream. + /// is . + /// + /// Lower-level than . Uses .Clone() to apply all changeset operations directly. + /// + /// + /// public static IObservable> Clone(this IObservable> source, IList target) where T : notnull { @@ -509,10 +602,10 @@ public static IObservable> Clone(this IObservable /// Convert the object using the specified conversion function. /// This is a lighter equivalent of Transform and is designed to be used with non-disposable objects. /// - /// The type of the object. - /// The type of the destination. - /// The source. - /// The conversion factory. + /// The type of items in the list. + /// The type of the destination items. + /// The source to convert. + /// The conversion factory. /// An observable which emits the change set. [Obsolete("Prefer Cast as it is does the same thing but is semantically correct")] public static IObservable> Convert(this IObservable> source, Func conversionFactory) @@ -527,11 +620,20 @@ public static IObservable> Convert - /// Defer the subscription until the stream has been inflated with data. + /// Defers downstream delivery until the source emits its first changeset, then forwards all subsequent changesets. /// /// The type of the object. - /// The source. - /// An observable which emits the change set. + /// The source to defer until the first changeset arrives. + /// A list changeset stream that begins emitting only after the source has produced its first changeset. + /// is . + /// + /// + /// Subscribes to the source immediately but buffers internally until the first changeset arrives, at which point it emits + /// the initial data and all subsequent changesets. This is useful when downstream consumers should not receive an empty initial state. + /// + /// + /// + /// public static IObservable> DeferUntilLoaded(this IObservable> source) where T : notnull { @@ -540,12 +642,11 @@ public static IObservable> DeferUntilLoaded(this IObservable(source).Run(); } - /// - /// Defer the subscription until the cache has been inflated with data. - /// - /// The type of the object. - /// The source. - /// An observable which emits the change set. + /// + /// + /// + /// Convenience overload that calls source.Connect().DeferUntilLoaded(). + /// public static IObservable> DeferUntilLoaded(this IObservableList source) where T : notnull { @@ -555,16 +656,32 @@ public static IObservable> DeferUntilLoaded(this IObservableLis } /// - /// Disposes each item when no longer required. - /// - /// Individual items are disposed after removal or replacement changes have been sent downstream. - /// All items previously-published on the stream are disposed after the stream finalizes. - /// + /// Disposes items that implement when they are removed, replaced, or cleared from the stream. + /// All remaining tracked items are disposed when the stream finalizes (OnCompleted, OnError, or subscription disposal). /// /// The type of the object. - /// The source. - /// A continuation of the original stream. - /// source. + /// The source to track for disposal on removal. + /// A continuation of the source changeset stream with disposal side effects applied. + /// is . + /// + /// + /// Items are cast to and disposed after the changeset has been forwarded downstream. + /// Items that do not implement are silently ignored. + /// + /// + /// EventBehavior + /// Add/AddRangeItems are tracked for future disposal. Changeset forwarded. + /// ReplaceThe previous (replaced) item is disposed after the changeset is forwarded. The new item is tracked. + /// Remove/RemoveRangeRemoved items are disposed after the changeset is forwarded. + /// ClearAll tracked items are disposed after the changeset is forwarded. + /// Moved/RefreshForwarded. No disposal occurs. + /// OnError/OnCompleted/DisposalAll remaining tracked items are disposed during finalization. + /// + /// Worth noting: Disposal happens after the changeset is delivered downstream, so subscribers see the change before items are disposed. + /// + /// + /// + /// public static IObservable> DisposeMany(this IObservable> source) where T : notnull { @@ -574,18 +691,29 @@ public static IObservable> DisposeMany(this IObservable - /// Selects distinct values from the source, using the specified value selector. + /// Extracts distinct values from source items using , with reference counting to track when values enter and leave the result set. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// An observable which emits the change set. - /// - /// source - /// or - /// valueSelector. - /// + /// The type of items in the source list. + /// The type of distinct values produced. + /// The source to extract distinct values. + /// A function that extracts the value to track from each source item. + /// A list changeset stream of distinct values. + /// or is . + /// + /// + /// Maintains an internal reference count per distinct value. A value is included when its count first exceeds zero + /// and removed when its count drops back to zero. + /// + /// + /// EventBehavior + /// Add/AddRangeValue extracted. If first occurrence, an Add is emitted. Otherwise the reference count is incremented silently. + /// ReplaceOld value's reference count decremented (removed if zero), new value's count incremented (added if first). If the value did not change, no emission. + /// Remove/RemoveRangeReference count decremented. If the count reaches zero, a Remove is emitted for that distinct value. + /// RefreshValue is re-extracted. If changed, old value decremented and new value incremented (same as Replace logic). + /// ClearAll reference counts cleared. Remove emitted for every tracked distinct value. + /// + /// + /// public static IObservable> DistinctValues(this IObservable> source, Func valueSelector) where TObject : notnull where TValue : notnull @@ -598,13 +726,36 @@ public static IObservable> DistinctValues(th } /// - /// Apply a logical Except operator between the collections. - /// Items which are in the source and not in the others are included in the result. + /// Applies a logical set-difference (Except) between the source and other streams. + /// Items present in the first source but not in any of the are included in the result. /// /// The type of the item. - /// The source. - /// The others. - /// An observable which emits the change set. + /// The primary from which other streams are subtracted. + /// The other changeset streams to exclude from the result. + /// A list changeset stream containing items from that are not in any of . + /// is . + /// + /// + /// Item identity is determined by the default equality comparer for . Across all sources, items are tracked + /// by reference-counted equality (not by index position). + /// The first source has a special role: only items from it can appear in the result, and only if they do not exist in any other source. + /// + /// + /// EventBehavior + /// Add/AddRange (first source)If the item does not exist in any other source, an Add is emitted. + /// Add/AddRange (other source)If the item was in the result (from first source), a Remove is emitted. + /// Remove/RemoveRange/Clear (first source)If the item was in the result, a Remove is emitted. + /// Remove/RemoveRange/Clear (other source)If the item exists in the first source and no longer in any other, an Add is emitted. + /// ReplaceTreated as a Remove of the old item plus an Add of the new item, with set logic re-evaluated. + /// MovedIgnored by the set logic (no positional semantics). + /// RefreshForwarded if the item is currently in the result set. + /// + /// Worth noting: Unlike , the first source is asymmetric: only its items can appear in the result. + /// + /// + /// + /// + /// public static IObservable> Except(this IObservable> source, params IObservable>[] others) where T : notnull { @@ -613,52 +764,61 @@ public static IObservable> Except(this IObservable - /// Apply a logical Except operator between the collections. - /// Items which are in the source and not in the others are included in the result. - /// - /// The type of the item. - /// The sources. - /// An observable which emits the change set. + /// + /// + /// + /// Static overload accepting a pre-built collection of sources. The first item in the collection is the primary source. + /// public static IObservable> Except(this ICollection>> sources) where T : notnull => sources.Combine(CombineOperator.Except); - /// - /// Dynamically apply a logical Except operator. Items from the first observable list are included when an equivalent item does not exist in the other sources. - /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// + /// + /// + /// Dynamic overload: sources can be added or removed from the at runtime. The first source in the list acts as the primary. + /// public static IObservable> Except(this IObservableList>> sources) where T : notnull => sources.Combine(CombineOperator.Except); - /// - /// Dynamically apply a logical Except operator. Items from the first observable list are included when an equivalent item does not exist in the other sources. - /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// + /// + /// + /// Dynamic overload accepting of . Each inner list's Connect() is used as a source. + /// public static IObservable> Except(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.Except); - /// - /// Dynamically apply a logical Except operator. Items from the first observable list are included when an equivalent item does not exist in the other sources. - /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// + /// + /// + /// Dynamic overload accepting of . Each inner list's Connect() is used as a source. + /// public static IObservable> Except(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.Except); /// - /// Removes items from the cache according to the value specified by the time selector function. + /// Automatically removes items from the list after the duration returned by . + /// Returns an observable of the items that were expired and removed. /// /// The type of the item. - /// The source. - /// Selector returning when to expire the item. Return null for non-expiring item. - /// Enter the polling interval to optimise expiry timers, if omitted 1 timer is created for each unique expiry time. - /// The scheduler. - /// An observable which emits the enumerable of items. + /// The source list to apply time-based expiration to. + /// A function returning the time-to-live for each item. Return for items that should never expire. + /// An optional polling interval to batch expiry checks. If omitted, a separate timer is created for each unique expiry time. + /// The scheduler for scheduling expiry timers. Defaults to . + /// An observable that emits collections of items each time expired items are removed from the source list. + /// + /// + /// This operator acts directly on an , not on a changeset stream. It monitors items as they are added, + /// schedules their removal, and physically removes them from the source list when their time expires. + /// + /// + /// When is specified, all items due for removal are batched into a single removal at each polling tick, + /// which can improve performance when many items expire around the same time. + /// + /// Worth noting: The returned observable emits the expired items (not changesets). Subscribe to this observable to trigger the expiry mechanism; if not subscribed, no items will be removed. + /// + /// + /// public static IObservable> ExpireAfter( this ISourceList source, Func timeSelector, @@ -672,14 +832,38 @@ public static IObservable> ExpireAfter( scheduler: scheduler); /// - /// Filters items, statically, in a list stream, based on a given predicate. + /// Filters items from the source list changeset stream using a static predicate. + /// Only items satisfying are included downstream. /// /// The type of items in the list. - /// The list stream whose items are to be filtered. - /// A static predicate to be used to determine which items should be included or excluded by the filter. - /// A list stream, containing only the items matched by . - /// Throws for and . - /// Note that, unlike some other overloads of this operator, ordering of items is preserved. + /// The source to filter. + /// A predicate that determines which items are included. Items returning appear downstream; items returning are excluded. + /// A list changeset stream containing only items that satisfy . + /// Thrown when or is . + /// + /// + /// Use this overload when you need only a single predicate function for the lifetime of the subscription; + /// unlike the dynamic-predicate and state-driven overloads, the predicate function itself never changes. + /// Note that this does not mean an item's inclusion is fixed: Refresh events can re-evaluate each item against the predicate + /// and promote a previously-excluded item to included (or vice versa). + /// Item ordering is preserved. + /// + /// + /// EventBehavior + /// AddThe predicate is evaluated. If the item passes, an Add is emitted at the calculated downstream index. Otherwise dropped. + /// AddRangeEach item in the range is evaluated. Matching items are emitted as an AddRange. + /// ReplaceThe predicate is re-evaluated. Four outcomes: both pass produces Replace; new passes but old didn't produces Add; old passed but new doesn't produces Remove; neither passes is dropped. + /// RemoveIf the item was included downstream, a Remove is emitted. Otherwise dropped. + /// RemoveRangeIncluded items in the range are emitted as individual Remove changes. + /// RefreshThe predicate is re-evaluated. If the item now passes but previously did not, an Add is emitted. If it previously passed but no longer does, a Remove is emitted. If still passes, the Refresh is forwarded. If still fails, dropped. + /// ClearAll downstream items are cleared. + /// + /// Worth noting: Refresh events trigger re-evaluation, which can promote or demote items (turning a Refresh into an Add or Remove). Pair with for property-change-driven filtering. + /// + /// + /// + /// + /// public static IObservable> Filter( this IObservable> source, Func predicate) @@ -690,16 +874,34 @@ public static IObservable> Filter( suppressEmptyChangesets: true); /// - /// Filters source using the specified filter observable predicate. + /// Filters items using a dynamically changing predicate. + /// When emits a new function, all items are re-evaluated. /// /// The type of the item. - /// The source. - /// The predicate which indicates which items should be included. - /// Should the filter clear and replace, or calculate a diff-set. - /// An observable which emits the change set. - /// source - /// or - /// filterController. + /// The source to filter. + /// An that emits new predicate functions. Each emission triggers a full re-evaluation of all items. + /// The that controls re-filtering behavior when the predicate changes. + /// A list changeset stream containing only items that satisfy the most recent predicate. + /// + /// + /// Each time emits, every item is re-evaluated against the new predicate. + /// + /// + /// EventBehavior + /// AddThe current predicate is evaluated. If the item passes, an Add is emitted. Otherwise dropped. + /// AddRangeEach item is evaluated. Matching items are emitted as AddRange. + /// ReplaceRe-evaluated. Same four-outcome logic as the static overload (Replace, Add, Remove, or dropped). + /// RemoveIf the item was downstream, a Remove is emitted. Otherwise dropped. + /// RefreshRe-evaluated. If inclusion status changed, an Add or Remove is emitted. If unchanged, Refresh forwarded or dropped. + /// ClearAll downstream items are cleared. + /// Predicate changedAll items are re-evaluated against the new predicate. The output is shaped by . + /// OnCompletedIndependent completion of does not terminate the filter. + /// + /// Worth noting: No items are included until emits its first function. + /// + /// or is . + /// + /// public static IObservable> Filter(this IObservable> source, IObservable> predicate, ListFilterPolicy filterPolicy = ListFilterPolicy.CalculateDiff) where T : notnull { @@ -711,20 +913,35 @@ public static IObservable> Filter(this IObservable - /// Creates a filtered stream which can be dynamically filtered, based on state values passed through to a static filtering predicate. + /// Filters items using a predicate that receives external state. When emits a new state value, + /// all items are re-evaluated against using the updated state. /// /// The type of the item. /// The type of state value required by . - /// The source. - /// A stream of state values to be passed to . - /// A static predicate to be used to determine which items should be included or excluded by the filter. - /// The policy that the operator should use when performing re-filtering operations. - /// By default empty changeset notifications are suppressed for performance reasons. Set to false to publish empty changesets. Doing so can be useful for monitoring loading status. - /// An observable which emits change sets. - /// Throws for , , and . + /// The source to filter. + /// An stream of state values to be passed to . + /// A static predicate receiving the current state and an item, returning to include or to exclude. The function itself does not change; only the state value passed to it changes. + /// The that controls re-filtering behavior when the state changes. + /// When (default), empty changesets are suppressed. Set to to publish empty changesets (useful for monitoring loading status). + /// A list changeset stream containing only items satisfying with the current state. + /// , , or is . /// - /// Usually, should emit an initial value, immediately upon subscription. This is because cannot be invoked until the first state value is received, and accordingly, the operator will treat all items as excluded until then. Each value emitted by will trigger a full re-filtering of the entire collection, according to . + /// + /// The predicate cannot be invoked until the first state value is received. Until then, all items are treated as excluded. + /// Each subsequent state emission triggers a full re-evaluation of all items according to . + /// + /// + /// EventBehavior + /// Add/AddRangeEvaluated using current state. Matching items emitted as Add/AddRange. + /// ReplaceRe-evaluated. Same four-outcome logic as the static filter (Replace, Add, Remove, or dropped). + /// Remove/RemoveRangeIf the item was downstream, a Remove is emitted. + /// RefreshRe-evaluated against current state. Inclusion status may change. + /// ClearAll downstream items are cleared. + /// State changedAll items are re-evaluated with the new state value. The output is shaped by . + /// /// + /// + /// public static IObservable> Filter( this IObservable> source, IObservable predicateState, @@ -740,15 +957,38 @@ public static IObservable> Filter( suppressEmptyChangeSets: suppressEmptyChangeSets); /// - /// Filters source on the specified observable property using the specified predicate. - /// The filter will automatically reapply when a property changes. + /// Filters each item using a per-item of that dynamically controls inclusion. + /// When an item's observable emits the item enters the result; when it emits the item is removed. /// - /// The type of the object. - /// The source. - /// The filter property selector. When the observable changes the filter will be re-evaluated. - /// The property changed throttle. - /// The scheduler used when throttling. - /// An observable which emits the change set. + /// The type of items in the list. + /// The source to filter by property value. + /// A function that returns an observable of for each item, controlling its inclusion. + /// An optional throttle duration applied to each per-item observable to reduce re-evaluation frequency. + /// The used when throttling. Defaults to the system default scheduler. + /// A list changeset stream containing only items whose per-item observable most recently emitted . + /// or is . + /// + /// + /// Each item in the source gets its own subscription to the observable returned by . + /// The item's inclusion is determined by the most recent boolean value emitted by that observable. + /// + /// + /// Event (source)Behavior + /// Add/AddRangeSubscribes to the per-item observable. Item is included when it first emits . + /// ReplaceOld subscription disposed, new subscription created for the replacement item. + /// Remove/RemoveRange/ClearSubscription disposed. If the item was downstream, a Remove is emitted. + /// RefreshForwarded if the item is currently included. + /// + /// + /// Event (per-item observable)Behavior + /// Emits If not already included, an Add is emitted downstream. + /// Emits If currently included, a Remove is emitted downstream. + /// + /// + /// + /// + /// + /// public static IObservable> FilterOnObservable(this IObservable> source, Func> objectFilterObservable, TimeSpan? propertyChangedThrottle = null, IScheduler? scheduler = null) where TObject : notnull { @@ -758,17 +998,21 @@ public static IObservable> FilterOnObservable(this } /// - /// Filters source on the specified property using the specified predicate. - /// The filter will automatically reapply when a property changes. + /// Filters items based on a property value, automatically re-evaluating when the specified property changes on any item. /// - /// The type of the object. + /// The type of the object. Must implement . /// The type of the property. - /// The source. - /// The property selector. When the property changes the filter specified will be re-evaluated. - /// A predicate based on the object which contains the changed property. - /// The property changed throttle. - /// The scheduler used when throttling. - /// An observable which emits the change set. + /// The source to filter by property value. + /// selecting the property to monitor for changes. + /// A predicate evaluated against the item to determine inclusion. + /// An optional throttle duration for property change notifications. + /// The used when throttling. + /// A list changeset stream of items satisfying the predicate, re-evaluated on property changes. + /// + /// Deprecated. Use followed by instead. + /// + /// + /// [Obsolete("Use AutoRefresh(), followed by Filter() instead")] public static IObservable> FilterOnProperty(this IObservable> source, Expression> propertySelector, Func predicate, TimeSpan? propertyChangedThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged @@ -783,21 +1027,43 @@ public static IObservable> FilterOnProperty - /// Convert the result of a buffer operation to a change set. + /// Flattens buffered changesets (e.g. from ) back into single changesets. + /// Empty buffers are dropped. /// /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// The of buffered changeset lists. + /// A list changeset stream with all buffered changes concatenated into single changesets. + /// + /// Use this after applying Observable.Buffer() to a changeset stream to re-merge the batched changesets into a single stream. + /// + /// + /// public static IObservable> FlattenBufferResult(this IObservable>> source) where T : notnull => source.Where(x => x.Count != 0).Select(updates => new ChangeSet(updates.SelectMany(u => u))); /// - /// Provides a call back for each item change. + /// Invokes once for every in each changeset. Range changes + /// (AddRange, RemoveRange, Clear) are delivered as a single ; they are not flattened into per-item changes. + /// The changeset is forwarded downstream unchanged. /// - /// The type of the object. - /// The source. - /// The action. - /// An observable which emits the change set. + /// The type of items in the list. + /// The source to observe each change in. + /// The action invoked for each . + /// A continuation of the source changeset stream. + /// or is . + /// + /// This is a side-effect operator. It does not modify the changeset. If you need each individual item from range operations flattened out, use instead. + /// + /// EventBehavior + /// Add/Replace/Remove/Moved/RefreshCallback invoked with the (single-item change). Changeset forwarded. + /// AddRange/RemoveRange/ClearCallback invoked once with the containing the range (accessible via Range property). Changeset forwarded. + /// OnErrorIf the callback throws, the exception propagates as OnError. + /// + /// + /// + /// + /// + /// public static IObservable> ForEachChange(this IObservable> source, Action> action) where TObject : notnull { @@ -809,13 +1075,21 @@ public static IObservable> ForEachChange(this IObse } /// - /// Provides a call back for each item change. - /// Range changes are flattened, so there is only need to check for Add, Replace, Remove and Clear. + /// Invokes for every individual in each changeset. + /// Range changes are flattened into individual item changes first, so the callback only receives Add, Replace, Remove, and Refresh. /// - /// The type of the object. - /// The source. - /// The action. - /// An observable which emits the change set. + /// The type of items in the list. + /// The source to observe each item-level change in. + /// The action invoked for each individual item change. + /// A continuation of the source changeset stream. + /// or is . + /// + /// + /// Unlike , this operator flattens + /// AddRange, RemoveRange, and Clear into individual entries before invoking the callback. + /// + /// + /// public static IObservable> ForEachItemChange(this IObservable> source, Action> action) where TObject : notnull { @@ -827,20 +1101,33 @@ public static IObservable> ForEachItemChange(this I } /// - /// Groups the source on the value returned by group selector factory. The groupings contains an inner observable list. + /// Groups source items by the value returned by . Each group is an + /// containing an inner observable list of its members. /// - /// The type of the object. - /// The type of the group. - /// The source. - /// The group selector. - /// Force the grouping function to recalculate the group value. - /// For example if you have a time based grouping with values like `Last Minute', 'Last Hour', 'Today' etc regrouper is used to refresh these groupings. - /// An observable which emits the change set. - /// - /// source - /// or - /// groupSelector. - /// + /// The type of items in the list. + /// The type of the group key. + /// The source to group. + /// A function that returns the group key for each item. + /// An optional of that forces all items to be re-evaluated against when it fires. Useful for time-based groupings (e.g., "Last Hour", "Today"). + /// A list changeset stream of objects, each containing the items belonging to that group. + /// or is . + /// + /// + /// Groups are created lazily and removed when empty. Each group exposes an inner observable list that receives incremental updates. + /// + /// + /// EventBehavior + /// Add/AddRangeGroup key evaluated. Item added to its group. If the group is new, an Add of the group is emitted. + /// ReplaceGroup key re-evaluated. If the group changed, the item is removed from the old group and added to the new one. Empty old groups are removed. + /// Remove/RemoveRange/ClearItem removed from its group. Empty groups are removed from the result. + /// RefreshGroup key re-evaluated. If changed, the item moves between groups. + /// MovedNot handled by group logic. + /// Regrouper firesAll items re-evaluated. Items that changed group key are moved between groups. Empty groups removed, new groups added. + /// + /// + /// + /// + /// public static IObservable>> GroupOn(this IObservable> source, Func groupSelector, IObservable? regrouper = null) where TObject : notnull where TGroup : notnull @@ -853,17 +1140,26 @@ public static IObservable>> GroupOn - /// Groups the source using the property specified by the property selector. The resulting groupings contains an inner observable list. - /// Groups are re-applied when the property value changed. - /// When there are likely to be a large number of group property changes specify a throttle to improve performance. + /// Groups items by a property value, automatically re-grouping when the specified property changes on any item. + /// Each group contains an inner observable list. /// - /// The type of the object. - /// The type of the group. - /// The source. - /// The property selector used to group the items. - /// The property changed throttle. - /// The scheduler. - /// An observable which emits the change set. + /// The type of the object. Must implement . + /// The type of the group key. + /// The source to group by property value. + /// selecting the property whose value determines the group key. + /// An optional throttle duration for property change notifications. + /// The used when throttling. + /// A list changeset stream of objects. + /// or is . + /// + /// + /// Convenience operator equivalent to .AutoRefresh(propertySelector).GroupOn(item => property). + /// Property changes trigger re-evaluation of the group key, potentially moving items between groups. + /// + /// + /// + /// + /// public static IObservable>> GroupOnProperty(this IObservable> source, Expression> propertySelector, TimeSpan? propertyChangedThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged where TGroup : notnull @@ -876,17 +1172,27 @@ public static IObservable>> GroupOnProperty - /// Groups the source using the property specified by the property selector. The resulting groupings are immutable. - /// Groups are re-applied when the property value changed. - /// When there are likely to be a large number of group property changes specify a throttle to improve performance. + /// Groups items by a property value, automatically re-grouping when the specified property changes. + /// Each group emits immutable snapshots (not live observable lists). /// - /// The type of the object. - /// The type of the group. - /// The source. - /// The property selector used to group the items. - /// The property changed throttle. - /// The scheduler. - /// An observable which emits the change set. + /// The type of the object. Must implement . + /// The type of the group key. + /// The source to group by property value with immutable snapshots. + /// selecting the property whose value determines the group key. + /// An optional throttle duration for property change notifications. + /// The used when throttling. + /// A list changeset stream of immutable group snapshots. + /// or is . + /// + /// + /// Combines + /// with . + /// Unlike , + /// this produces immutable snapshots per group rather than live inner observable lists. + /// + /// + /// + /// public static IObservable>> GroupOnPropertyWithImmutableState(this IObservable> source, Expression> propertySelector, TimeSpan? propertyChangedThrottle = null, IScheduler? scheduler = null) where TObject : INotifyPropertyChanged where TGroup : notnull @@ -899,20 +1205,25 @@ public static IObservable>> GroupOnProperty - /// Groups the source on the value returned by group selector factory. Each update produces immutable grouping. + /// Groups source items by the value returned by . Each update produces immutable grouping snapshots + /// rather than live inner observable lists. /// - /// The type of the object. + /// The type of items in the list. /// The type of the group key. - /// The source. - /// The group selector key. - /// Force the grouping function to recalculate the group value. - /// For example if you have a time based grouping with values like `Last Minute', 'Last Hour', 'Today' etc regrouper is used to refresh these groupings. - /// An observable which emits the change set. - /// - /// source - /// or - /// groupSelectorKey. - /// + /// The source to group with immutable snapshots. + /// A function that returns the group key for each item. + /// An optional of that forces all items to be re-evaluated when it fires. + /// A list changeset stream of immutable snapshots. + /// or is . + /// + /// + /// Works like + /// but each affected group emits a new immutable snapshot on every change rather than updating a live inner list. + /// This is useful when consumers need thread-safe, point-in-time snapshots of each group. + /// + /// + /// + /// public static IObservable>> GroupWithImmutableState(this IObservable> source, Func groupSelectorKey, IObservable? regrouper = null) where TObject : notnull where TGroupKey : notnull @@ -925,16 +1236,26 @@ public static IObservable>> GroupOnProperty - /// Limits the size of the source cache to the specified limit. - /// Notifies which items have been removed from the source list. + /// Limits the source list to a maximum number of items using FIFO eviction. + /// When the list exceeds , the oldest items are removed. + /// Returns an observable of the items that were removed. /// /// The type of the item. - /// The source. - /// The size limit. - /// The scheduler. - /// An observable which emits a enumerable of items. - /// source. - /// sizeLimit cannot be zero. + /// The source list to apply size limits to. + /// The maximum number of items allowed. Must be greater than zero. + /// The scheduler for scheduling size checks. Defaults to . + /// An observable that emits collections of items each time excess items are removed from the source list. + /// is . + /// is zero or negative. + /// + /// + /// This operator acts directly on an . It subscribes to the source's changes, + /// tracks insertion order using an internal Transform, and removes the oldest items when the size limit is exceeded. + /// + /// Worth noting: The returned observable emits the removed items (not changesets). Subscribe to this observable to activate the size-limiting mechanism. Removal is performed synchronously under a lock shared with the change tracking. + /// + /// + /// public static IObservable> LimitSizeTo(this ISourceList source, int sizeLimit, IScheduler? scheduler = null) where T : notnull { @@ -952,17 +1273,29 @@ public static IObservable> LimitSizeTo(this ISourceList sou } /// - /// Dynamically merges the observable which is selected from each item in the stream, and un-merges the item - /// when it is no longer part of the stream. + /// Subscribes to a per-item observable for each item in the source and merges all emissions into a single stream. + /// This is NOT a changeset operator: it returns a flat observable of values. /// - /// The type of the object. - /// The type of the destination. - /// The source. - /// The observable selector. - /// An observable which emits the destination value. - /// source - /// or - /// observableSelector. + /// The type of items in the source list. + /// The type of values emitted by per-item observables. + /// The source whose items each produce an observable. + /// A function that returns an observable for each source item. + /// An observable that emits values from all per-item observables, merged together. + /// or is . + /// + /// + /// Event (source)Subscription behavior + /// Add/AddRangeSubscribes to the per-item observable. Emissions are merged into the output. + /// ReplaceOld subscription disposed, new subscription created for the replacement item. + /// Remove/RemoveRange/ClearSubscription disposed. + /// Refresh/MovedNo effect on subscriptions. + /// OnCompleted (source)Completes only after the source and all active inner observables have completed. + /// + /// + /// + /// + /// + /// public static IObservable MergeMany(this IObservable> source, Func> observableSelector) where T : notnull { @@ -973,14 +1306,13 @@ public static IObservable MergeMany(this IObserva return new MergeMany(source, observableSelector).Run(); } + /// /// - /// Operator similiar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events. + /// Merges multiple list changeset streams from an observable-of-observables into a single unified changeset stream. + /// Unlike , list merging performs no key-based deduplication. /// - /// The type of the object. - /// The Source Observable ChangeSet. - /// instance to determine if two elements are the same. - /// The result from merging the changesets together. - /// Parameter was null. + /// The source of nested changeset observables. + /// An optional used by the merge tracker to compare items. public static IObservable> MergeChangeSets(this IObservable>> source, IEqualityComparer? equalityComparer = null) where TObject : notnull { @@ -989,17 +1321,15 @@ public static IObservable> MergeChangeSets(this IOb return new MergeChangeSets(source, equalityComparer).Run(); } + /// /// - /// Operator similiar to Merge except it is ChangeSet aware. Merges both observable changesets into a single stream of ChangeSet events. + /// Merges two list changeset streams into a single unified stream. /// - /// The type of the object. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSet. - /// instance to determine if two elements are the same. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The first to merge. + /// The second to merge with. + /// An optional used to compare items. + /// An optional for scheduling enumeration. + /// When (default), the result completes when all sources complete. public static IObservable> MergeChangeSets(this IObservable> source, IObservable> other, IEqualityComparer? equalityComparer = null, IScheduler? scheduler = null, bool completable = true) where TObject : notnull { @@ -1009,17 +1339,15 @@ public static IObservable> MergeChangeSets(this IOb return new[] { source, other }.MergeChangeSets(equalityComparer, scheduler, completable); } + /// /// - /// Operator similiar to Merge except it is ChangeSet aware. Merges the source changeset and the collection of other changesets together into a single stream of ChangeSet events. + /// Merges the source list changeset stream with additional changeset streams into a single unified stream. /// - /// The type of the object. - /// The Source Observable ChangeSet. - /// The Other Observable ChangeSets. - /// instance to determine if two elements are the same. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The primary source to merge. + /// The additional of list changeset streams to merge with. + /// An optional used to compare items. + /// An optional for scheduling enumeration. + /// When (default), the result completes when all sources complete. public static IObservable> MergeChangeSets(this IObservable> source, IEnumerable>> others, IEqualityComparer? equalityComparer = null, IScheduler? scheduler = null, bool completable = true) where TObject : notnull { @@ -1030,15 +1358,33 @@ public static IObservable> MergeChangeSets(this IOb } /// - /// Operator similiar to Merge except it is ChangeSet aware. All of the observable changesets are merged together into a single stream of ChangeSet events. + /// Merges a collection of list changeset streams into a single unified changeset stream. + /// This is the canonical list MergeChangeSets overload: other overloads accepting , , or pair/params variants ultimately produce equivalent behavior. /// - /// The type of the object. - /// The Source Observable ChangeSet. - /// instance to determine if two elements are the same. - /// (Optional) instance to use when enumerating the collection. - /// Whether or not the result Observable should complete if all the changesets complete. - /// The result from merging the changesets together. - /// Parameter was null. + /// The type of items in the list. + /// The collection of list changeset streams to merge. + /// An optional used by the merge tracker to compare items. Defaults to when . + /// An optional for scheduling enumeration. + /// When (default), the result completes when all sources complete. + /// A single list changeset stream containing all changes from all sources. + /// is . + /// + /// + /// All changes from inner streams are forwarded to the output. There is no key-based deduplication (unlike ): if the same item appears in multiple inner streams, it will appear multiple times in the merged output. + /// + /// + /// EventBehavior + /// Add/AddRangeForwarded to the merged output. + /// ReplaceThe old value is replaced by the new value in the merged output. If the old value is not found (by ), the new value is added instead. + /// Remove/RemoveRange/ClearForwarded to the merged output. + /// RefreshForwarded to the merged output. + /// MovedIgnored. + /// + /// + /// + /// + /// + /// public static IObservable> MergeChangeSets(this IEnumerable>> source, IEqualityComparer? equalityComparer = null, IScheduler? scheduler = null, bool completable = true) where TObject : notnull { @@ -1047,14 +1393,10 @@ public static IObservable> MergeChangeSets(this IEn return new MergeChangeSets(source, equalityComparer, completable, scheduler).Run(); } + /// /// - /// Merges all of the Cache Observable ChangeSets into a single ChangeSets that correctly handles removal of the parent items. + /// Merges list changeset streams from an into a single stream. Sources can be added or removed dynamically. /// - /// The type of the object. - /// The SourceList of Observable Cache ChangeSets. - /// Optional instance to determine if two elements are the same. - /// The result from merging the child changesets together. - /// Parameter was null. public static IObservable> MergeChangeSets(this IObservableList>> source, IEqualityComparer? equalityComparer = null) where TObject : notnull { @@ -1063,14 +1405,11 @@ public static IObservable> MergeChangeSets(this IOb return source.Connect().MergeChangeSets(equalityComparer); } + /// /// - /// Merges each Observable ChangeSet in the ObservableList into a single stream of ChangeSets that correctly handles removal of the parent items. + /// Merges list changeset streams from a list-of-list-changeset-observables into a single stream. + /// Each inner list changeset observable in the source list is merged, and parent item removal triggers child cleanup. /// - /// The type of the object. - /// The List Observable ChangeSet of Cache Observable ChangeSets. - /// Optional instance to determine if two elements are the same. - /// The result from merging the child changesets together. - /// Parameter was null. public static IObservable> MergeChangeSets(this IObservable>>> source, IEqualityComparer? equalityComparer = null) where TObject : notnull { @@ -1080,14 +1419,29 @@ public static IObservable> MergeChangeSets(this IOb } /// - /// Merges each Observable ChangeSet in the ObservableList into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// Merges cache changeset streams from an into a single cache changeset stream. + /// Uses to resolve conflicts when the same key appears in multiple child streams. /// - /// The type of the object. + /// The type of items in the list. /// The type of the object key. - /// The SourceList of Observable Cache ChangeSets. - /// instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The of cache changeset observables. + /// to resolve which value wins when the same key appears in multiple sources. + /// A single cache changeset stream with key-based deduplication. + /// is . + /// + /// Sources can be added or removed dynamically from the observable list. Parent item removal triggers cleanup of all child items from that source. + /// + /// EventBehavior + /// Add (child)If the destination key is new, an Add is emitted. If another source already contributed a child with the same key, resolves the conflict (lowest-ordered value wins). The losing value is tracked internally but not emitted. + /// Update (child)If this source currently owns the destination key downstream, an Update is emitted. Otherwise re-evaluates all sources; a different source's value may win, producing an Update to that value instead. + /// Remove (child)If this source's value was the one published downstream for that destination key, the operator scans other sources for the same key. If found, an Update is emitted with the replacement (per ). Otherwise a Remove is emitted. + /// Refresh (child)If the child item is the one currently published downstream, the Refresh is forwarded. Otherwise re-evaluates all sources; if a different value now wins, an Update is emitted instead. + /// Source list AddSubscribes to the new child changeset stream and merges its keys into the output. + /// Source list RemoveDisposes that source's subscription. All keys it contributed are removed. For keys also contributed by other sources, the next-best value (per ) is promoted as an Update, not an Add. + /// + /// + /// + /// public static IObservable> MergeChangeSets(this IObservableList>> source, IComparer comparer) where TObject : notnull where TKey : notnull @@ -1097,16 +1451,13 @@ public static IObservable> MergeChangeSets /// - /// Merges all of the Cache Observable ChangeSets into a single ChangeSets while correctly handling multiple Keys and removal of the parent items. + /// Merges cache changeset streams from an into a single cache changeset stream, with optional equality and ordering comparers. /// - /// The type of the object. - /// The type of the object key. - /// The SourceList of Observable Cache ChangeSets. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The of cache changeset observables. + /// An optional to determine if two elements are the same. + /// An optional to resolve conflicts when the same key appears in multiple sources. public static IObservable> MergeChangeSets(this IObservableList>> source, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TObject : notnull where TKey : notnull @@ -1116,15 +1467,12 @@ public static IObservable> MergeChangeSets /// - /// Merges all of the Cache Observable ChangeSets into a single ChangeSets while correctly handling multiple Keys and removal of the parent items. + /// Merges cache changeset streams from a list changeset of cache changeset observables, using a comparer for conflict resolution. /// - /// The type of the object. - /// The type of the object key. - /// The List Observable ChangeSet of Cache Observable ChangeSets. - /// instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The source whose items are cache changeset observables. + /// to resolve which value wins when the same key appears in multiple sources. public static IObservable> MergeChangeSets(this IObservable>>> source, IComparer comparer) where TObject : notnull where TKey : notnull @@ -1134,16 +1482,13 @@ public static IObservable> MergeChangeSets /// - /// Merges each Observable ChangeSet in the ObservableList into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// Merges cache changeset streams from a list changeset of cache changeset observables, with optional equality and ordering comparers. /// - /// The type of the object. - /// The type of the object key. - /// The List Observable ChangeSet of Cache Observable ChangeSets. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The source whose items are cache changeset observables. + /// An optional to determine if two elements are the same. + /// An optional to resolve conflicts when the same key appears in multiple sources. public static IObservable> MergeChangeSets(this IObservable>>> source, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TObject : notnull where TKey : notnull @@ -1154,15 +1499,32 @@ public static IObservable> MergeChangeSets - /// Operator similiar to MergeMany except it is List ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles removal of the parent items and other changes to the source list. + /// Transforms each source item into a child list changeset stream using , + /// then merges all child streams into a single flat list changeset stream. Parent item removal cleans up all associated children. /// - /// The type of the object. - /// The type of the destination. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// Optional instance to determine if two elements are the same. - /// The result from merging the children list changesets together. - /// Parameter was null. + /// The type of items in the source list. + /// The type of items in the child changeset streams. + /// The source whose items each produce a child changeset stream. + /// A function that returns a child list changeset stream for each source item. + /// An optional used to compare child items. + /// A single list changeset stream containing all items from all child streams. + /// or is . + /// + /// + /// Internally subscribes to each child stream when a source item is added and disposes the subscription when it is removed. + /// All child items from a removed parent are removed from the merged output. + /// + /// + /// Event (source)Behavior + /// Add/AddRangeSubscribes to the child stream. Child emissions are merged into the output. + /// ReplaceOld child subscription disposed (and its items removed from output). New child subscription created. + /// Remove/RemoveRange/ClearChild subscription disposed. All child items from that parent are removed. + /// + /// + /// + /// + /// + /// public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IEqualityComparer? equalityComparer = null) where TObject : notnull where TDestination : notnull @@ -1181,16 +1543,22 @@ public static IObservable> MergeManyChangeSets - /// Operator similiar to MergeMany except it is Cache ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// Transforms each source item into a child cache changeset stream and merges all children into a single cache changeset stream. + /// Uses to resolve key conflicts when the same key appears in multiple child streams. /// - /// The type of the object. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source list. + /// The type of items in the child cache changeset streams. + /// The type of the key in the child cache changesets. + /// The source whose items each produce a child changeset stream. + /// A function that returns a child cache changeset stream for each source item. + /// to resolve which value wins when the same key appears from multiple children. + /// A single cache changeset stream with key-based deduplication. + /// , , or is . + /// + /// + /// Delegates to with a equality comparer. + /// + /// public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IComparer comparer) where TObject : notnull where TDestination : notnull @@ -1204,17 +1572,42 @@ public static IObservable> MergeManyCh } /// - /// Operator similiar to MergeMany except it is Cache ChangeSet aware. It uses to transform each item in the source into a child and merges the result children together into a single stream of ChangeSets that correctly handles multiple Keys and removal of the parent items. + /// Transforms each source item into a child cache changeset stream and merges all children into a single cache changeset stream. + /// This is the primary list-to-cache MergeManyChangeSets overload. /// - /// The type of the object. - /// The type of the destination. - /// The type of the destination key. - /// The Source Observable ChangeSet. - /// Factory Function used to create child changesets. - /// Optional instance to determine if two elements are the same. - /// Optional instance to determine which element to emit if the same key is emitted from multiple child changesets. - /// The result from merging the child changesets together. - /// Parameter was null. + /// The type of items in the source list. + /// The type of items in the child cache changeset streams. + /// The type of the key in the child cache changesets. + /// The source whose items each produce a child changeset stream. + /// A function that returns a child cache changeset stream for each source item. + /// An optional to determine if two elements are the same. + /// An optional to resolve conflicts when the same key appears from multiple children. + /// A single cache changeset stream with key-based deduplication. + /// or is . + /// + /// + /// Each source item produces a keyed child stream via . All child items are tracked by key. + /// When a parent item is removed, all its child items are removed from the merged output. + /// When the same key appears from multiple children, determines which value wins. + /// + /// + /// Event (source)Behavior + /// Add/AddRangeSubscribes to the child cache stream. Child key/value pairs are merged into the output cache. + /// ReplaceOld child subscription disposed (and its keys removed from output). New child subscription created. + /// Remove/RemoveRange/ClearChild subscription disposed. All keys originating from that child are removed from the output. + /// Moved/RefreshIgnored; this operator emits a cache changeset and source ordering/refresh does not affect key membership. + /// + /// + /// Error and completion: + /// + /// + /// EventBehavior + /// OnErrorAn error from the source (parent) stream or from any child changeset stream terminates the entire output. Unlike , child errors are NOT swallowed. + /// OnCompletedThe output completes when the source (parent) stream completes and all active child changeset streams have also completed. + /// + /// + /// + /// public static IObservable> MergeManyChangeSets(this IObservable> source, Func>> observableSelector, IEqualityComparer? equalityComparer = null, IComparer? comparer = null) where TObject : notnull where TDestination : notnull @@ -1227,12 +1620,14 @@ public static IObservable> MergeManyCh } /// - /// Prevents an empty notification. + /// Suppresses empty changesets from the stream. Only changesets with at least one change are forwarded. /// /// The type of the item. - /// The source. - /// An observable which emits the change set. - /// source. + /// The source to suppress empty changesets. + /// A list changeset stream with empty changesets filtered out. + /// is . + /// + /// public static IObservable> NotEmpty(this IObservable> source) where T : notnull { @@ -1242,14 +1637,30 @@ public static IObservable> NotEmpty(this IObservable - /// Invokes a given action for every item added to the source list stream. + /// Invokes for every item added to the source list stream. + /// Triggers on , , and the new item of . /// /// The type of items in the list. - /// The list stream whose items are to be passed to . - /// The action to invoke upon each added item. - /// A list stream, containing all items in , with changes published after has been invoked. - /// Throws for and . - /// Note that "added" items includes items from , , and changes. + /// The source to observe item additions in. + /// The action to invoke for each added item. + /// A continuation of the source changeset stream, with the side effect applied before forwarding. + /// or is . + /// + /// The action fires before the changeset is forwarded downstream. + /// + /// EventBehavior + /// AddCallback invoked with the added item. Changeset forwarded. + /// AddRangeCallback invoked for each item in the range. Changeset forwarded. + /// ReplaceCallback invoked for the new (replacement) item. Changeset forwarded. + /// Remove/RemoveRange/ClearNo callback. Changeset forwarded. + /// Moved/RefreshNo callback. Changeset forwarded. + /// OnErrorIf the callback throws, the exception propagates as OnError. + /// + /// + /// + /// + /// + /// public static IObservable> OnItemAdded( this IObservable> source, Action addAction) @@ -1259,14 +1670,17 @@ public static IObservable> OnItemAdded( addAction: addAction); /// - /// Invokes a given action for every item refreshed within the source list stream. + /// Invokes for every item with a change in the source stream. /// /// The type of items in the list. - /// The list stream whose items are to be passed to . - /// The action to invoke upon each refreshed item. - /// A list stream, containing all items in , with changes published after has been invoked. - /// Throws for and . - /// Note that "refreshed" items refers to items from changes. + /// The source to observe item refresh events in. + /// The action to invoke for each refreshed item. + /// A continuation of the source changeset stream, with the side effect applied before forwarding. + /// or is . + /// + /// + /// + /// public static IObservable> OnItemRefreshed( this IObservable> source, Action refreshAction) @@ -1276,15 +1690,36 @@ public static IObservable> OnItemRefreshed( refreshAction: refreshAction); /// - /// Invokes a given action for every item removed from the source list stream. + /// Invokes for every item removed from the source list stream. + /// Triggers on , , , and the old item of . /// /// The type of items in the list. - /// The list stream whose items are to be passed to . - /// The action to invoke upon each removed item. - /// A flag indicating whether should be invoked upon teardown of the stream. This includes disposal of subscriptions, completion notifications, and error notifications. - /// A list stream, containing all items in , with changes published after has been invoked. - /// Throws for and . - /// Note that "removed" items includes items from , , , and changes. + /// The source to observe item removals in. + /// The action to invoke for each removed item. + /// When (default), is also invoked for all remaining tracked items upon stream disposal, completion, or error. + /// A continuation of the source changeset stream, with the side effect applied before forwarding. + /// or is . + /// + /// + /// When is , the operator tracks all items that have been added but not yet removed, + /// and fires for each of them during finalization. This is useful for resource cleanup patterns. + /// + /// + /// EventBehavior + /// Add/AddRangeTracked internally (when is ). No callback invoked. Changeset forwarded. + /// ReplaceCallback invoked for the previous (replaced) item. New item tracked. Changeset forwarded. + /// RemoveCallback invoked for the removed item. Changeset forwarded. + /// RemoveRange/ClearCallback invoked for each removed item. Changeset forwarded. + /// Moved/RefreshNo callback. Changeset forwarded. + /// OnErrorIf is , callback is invoked for all tracked items before the error propagates. + /// OnCompletedIf is , callback is invoked for all tracked items before completion propagates. + /// + /// Worth noting: When is (the default), disposing the subscription also invokes the callback for every item still in the list, not just items that were explicitly removed during the subscription. Exceptions in are not caught. + /// + /// + /// + /// + /// public static IObservable> OnItemRemoved( this IObservable> source, Action removeAction, @@ -1295,24 +1730,41 @@ public static IObservable> OnItemRemoved( removeAction: removeAction, invokeOnUnsubscribe: invokeOnUnsubscribe); + /// /// - /// Apply a logical Or operator between the collections. - /// Items which are in any of the sources are included in the result. + /// Applies a logical OR (union) between a pre-built collection of list changeset sources. Items present in any source are included. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// public static IObservable> Or(this ICollection>> sources) where T : notnull => sources.Combine(CombineOperator.Or); /// - /// Apply a logical Or operator between the collections. - /// Items which are in any of the sources are included in the result. + /// Applies a logical OR (union) between the source and other list changeset streams. + /// Items present in any of the sources are included in the result, using reference-counted equality. /// /// The type of the item. - /// The source. - /// The others. - /// An observable which emits the change set. + /// The primary source to union. + /// The other changeset streams to combine with. + /// A list changeset stream containing items that exist in at least one source. + /// is . + /// + /// + /// Item identity is determined by the default equality comparer for . Uses reference-counted equality: an item is included when it first appears in any source and removed when it no longer exists in any source. + /// Moved changes are ignored by the set logic. + /// + /// + /// EventBehavior + /// Add/AddRange (any source)If the item is new to the result, an Add is emitted. Otherwise the reference count is incremented. + /// Remove/RemoveRange/Clear (any source)Reference count decremented. If count reaches zero, a Remove is emitted. + /// ReplaceOld item reference count decremented, new item reference count incremented. Add/Remove emitted as needed. + /// RefreshForwarded if the item is in the result set. + /// MovedIgnored. + /// + /// + /// + /// + /// + /// public static IObservable> Or(this IObservable> source, params IObservable>[] others) where T : notnull { @@ -1321,43 +1773,46 @@ public static IObservable> Or(this IObservable> s return source.Combine(CombineOperator.Or, others); } + /// /// - /// Dynamically apply a logical Or operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. + /// Dynamic OR: sources can be added or removed from the at runtime. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. public static IObservable> Or(this IObservableList>> sources) where T : notnull => sources.Combine(CombineOperator.Or); + /// /// - /// Dynamically apply a logical Or operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. + /// Dynamic OR accepting of . Each inner list's Connect() is used as a source. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. public static IObservable> Or(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.Or); + /// /// - /// Dynamically apply a logical Or operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. + /// Dynamic OR accepting of . Each inner list's Connect() is used as a source. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. public static IObservable> Or(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.Or); /// - /// Applies paging to the data source. + /// Applies page-based windowing to the source list. Only items within the current page (determined by page number and page size from ) are included downstream. /// /// The type of the item. - /// The source. - /// Observable to control page requests. - /// An observable which emits the change set. + /// The source to page. + /// An observable of controlling which page to display (page number and page size). + /// An stream containing only items within the current page window. + /// or is . + /// + /// + /// Maintains the full source list internally and calculates the page window on each change or page request. + /// Items entering the page window produce Add; items leaving produce Remove. A new page request triggers + /// a full recalculation of the page contents. + /// + /// Worth noting: Duplicate items are removed from the result via Distinct() using the default equality comparer for , regardless of source order. The source should ideally be sorted before paging, since list order determines which items fall within each page window. + /// + /// + /// + /// public static IObservable> Page(this IObservable> source, IObservable requests) where T : notnull { @@ -1368,17 +1823,19 @@ public static IObservable> Page(this IObservable - /// list. + /// Subscribes to the source changeset stream and pipes all changes into the . /// /// The type of the object. - /// The source. - /// The destination. - /// An observable which emits the change set. - /// - /// source - /// or - /// destination. - /// + /// The source to pipe into a target list. + /// The destination to receive all changes. + /// An representing the subscription. Dispose to stop piping changes. + /// or is . + /// + /// Each changeset is applied to the destination using Clone() inside an Edit() call, producing a single batch update per changeset. + /// + /// + /// + /// public static IDisposable PopulateInto(this IObservable> source, ISourceList destination) where T : notnull { @@ -1389,18 +1846,21 @@ public static IDisposable PopulateInto(this IObservable> source } /// - /// The latest copy of the cache is exposed for querying after each modification to the underlying data. + /// Emits a projected value from the current list snapshot after every changeset. + /// The receives an representing the current state. /// - /// The type of the object. - /// The type of the destination. - /// The source. - /// The result selector. - /// An observable which emits the destination value. - /// - /// source - /// or - /// resultSelector. - /// + /// The type of items in the list. + /// The type of the projected result. + /// The source to project on each change. + /// A function projecting the current list snapshot to a result value. + /// An observable emitting the projected value after each changeset. + /// or is . + /// + /// Delegates to and applies via Select. + /// + /// + /// + /// public static IObservable QueryWhenChanged(this IObservable> source, Func, TDestination> resultSelector) where TObject : notnull { @@ -1411,12 +1871,20 @@ public static IObservable QueryWhenChanged( } /// - /// The latest copy of the cache is exposed for querying i) after each modification to the underlying data ii) upon subscription. + /// Emits an snapshot of the current list state after every changeset. + /// Maintains an internal list updated by cloning each changeset. /// - /// The type of the object. - /// The source. - /// An observable which emits the read only collection. - /// source. + /// The type of items in the list. + /// The source to project on each change. + /// An observable emitting the full list snapshot as after each change. + /// is . + /// + /// This is a non-changeset operator. It emits the entire collection state on each change, not incremental diffs. + /// Worth noting: A new snapshot is emitted on every changeset, which can be chatty. The collection is rebuilt by cloning each changeset into an internal list. For sorted output, use . + /// + /// + /// + /// public static IObservable> QueryWhenChanged(this IObservable> source) where T : notnull { @@ -1426,11 +1894,17 @@ public static IObservable> QueryWhenChanged(this IObse } /// - /// List equivalent to Publish().RefCount(). The source is cached so long as there is at least 1 subscriber. + /// Reference-counted materialization of the source changeset stream into an . + /// The shared list is created on the first subscriber and disposed when the last subscriber unsubscribes. /// /// The type of the item. - /// The source. - /// An observable which emits the change set. + /// The source to share via reference counting. + /// A list changeset stream backed by a shared, reference-counted . + /// is . + /// + /// Equivalent to Publish().RefCount() for changeset streams. The underlying list is created lazily on first subscription. + /// + /// public static IObservable> RefCount(this IObservable> source) where T : notnull { @@ -1440,12 +1914,16 @@ public static IObservable> RefCount(this IObservable - /// Removes the index from all changes. - /// NB: This operator has been introduced as a temporary fix for creating an Or operator using merge many. + /// Strips index information from all changes in the stream. /// /// The type of the object. - /// The source. - /// An observable which emits the change set. + /// The source to strip index information. + /// A list changeset stream with all index values removed from changes. + /// is . + /// + /// Removes index positions from every change in each changeset. This is useful when downstream operators do not require or support index-based operations. + /// + /// public static IObservable> RemoveIndex(this IObservable> source) where T : notnull { @@ -1455,16 +1933,16 @@ public static IObservable> RemoveIndex(this IObservable - /// Reverse sort of the change set. + /// Reverses the order of items in the changeset stream by transforming all indices: new_index = length - old_index - 1. /// /// The type of the item. - /// The source. - /// An observable which emits the change set. - /// - /// source - /// or - /// comparer. - /// + /// The source to reverse. + /// A list changeset stream with all index positions reversed. + /// is . + /// + /// This is a pure index transformation. The items themselves are unchanged; only their positional indices are inverted. + /// + /// public static IObservable> Reverse(this IObservable> source) where T : notnull { @@ -1475,12 +1953,24 @@ public static IObservable> Reverse(this IObservable - /// Defer the subscription until loaded and skip initial change set. + /// Skips the initial changeset (the snapshot emitted on subscription) and forwards all subsequent changesets. + /// Internally defers until loaded, then skips the first emission. /// /// The type of the object. - /// The source. - /// An observable which emits the change set. - /// source. + /// The source to skip the initial changeset. + /// A list changeset stream that omits the initial snapshot. + /// is . + /// + /// + /// Warning: This operator assumes the initial changeset is empty. If the source emits a non-empty + /// initial snapshot, those items are silently dropped while downstream consumers remain unaware of them. + /// Any later Refresh, Replace, Remove, or Moved change targeting one of those + /// dropped items will throw because the downstream collection has no record of them. Only use this against + /// a source you know starts empty (for example, a that has not yet been populated). + /// + /// + /// + /// public static IObservable> SkipInitial(this IObservable> source) where T : notnull { @@ -1490,19 +1980,37 @@ public static IObservable> SkipInitial(this IObservable - /// Sorts the sequence using the specified comparer. + /// Sorts the list using the specified comparer, maintaining a sorted output that incrementally updates as items change. /// /// The type of the item. - /// The source. - /// The comparer used for sorting. - /// For improved performance, specify SortOptions.UseBinarySearch. This can only be used when the values which are sorted on are immutable. - /// OnNext of this observable causes data to resort. This is required when the value which is sorted on mutable. - /// An observable comparer used to change the comparer on which the sorted list i. - /// Since sorting can be slow for large record sets, the reset threshold is used to force the list re-ordered. - /// An observable which emits the change set. - /// source - /// or - /// comparer. + /// The source to sort. + /// The used for sorting. + /// The for improved performance when sorted values are immutable. + /// An optional of that forces a full re-sort when it fires. Required when sorted property values are mutable. + /// An optional of that replaces the comparer, triggering a full re-sort. + /// When the number of changes exceeds this threshold, a full reset is performed instead of incremental updates. Default is 50. + /// A list changeset stream with items in sorted order. + /// or is . + /// + /// + /// Maintains an internal sorted list. Each incoming change is applied incrementally: adds are inserted at the correct sorted position, + /// removes are removed by index, and refreshes re-evaluate position (emitting Moved if changed). + /// + /// + /// EventBehavior + /// Add/AddRangeInserted at the correct sorted position. May trigger a full reset if the count exceeds . + /// ReplaceOld item removed, new item inserted at sorted position. + /// Remove/RemoveRange/ClearRemoved from sorted list. + /// RefreshSort position re-evaluated. If position changed, a Moved is emitted. + /// Comparer changedFull re-sort of all items. + /// Re-sort signalFull re-sort using the current comparer. + /// + /// Worth noting: is faster but requires that the values being sorted on never mutate. If they do, use the signal or . + /// + /// + /// + /// + /// public static IObservable> Sort(this IObservable> source, IComparer comparer, SortOptions options = SortOptions.None, IObservable? resort = null, IObservable>? comparerChanged = null, int resetThreshold = 50) where T : notnull { @@ -1512,19 +2020,18 @@ public static IObservable> Sort(this IObservable> return new Sort(source, comparer, options, resort, comparerChanged, resetThreshold).Run(); } + /// /// - /// Sorts the sequence using the specified observable comparer. + /// Sorts the list using an observable comparer. The initial comparer is taken from the first emission; subsequent emissions trigger a full re-sort. /// - /// The type of the item. - /// The source. - /// An observable comparer used to change the comparer on which the sorted list i. - /// For improved performance, specify SortOptions.UseBinarySearch. This can only be used when the values which are sorted on are immutable. - /// OnNext of this observable causes data to resort. This is required when the value which is sorted on mutable. - /// Since sorting can be slow for large record sets, the reset threshold is used to force the list re-ordered. - /// An observable which emits the change set. - /// source - /// or - /// comparer. + /// + /// Until emits its first comparer, items are sorted using . Downstream still receives changesets immediately; the initial ordering is whatever produces, then a full re-sort happens once the first comparer arrives. + /// + /// The source to sort. + /// An of that emits comparers. The first emission provides the initial sort order; subsequent emissions trigger re-sorts. + /// for controlling sort behavior. + /// An optional of to force a re-sort with the current comparer. + /// The threshold for triggering a full reset instead of incremental updates. public static IObservable> Sort(this IObservable> source, IObservable> comparerChanged, SortOptions options = SortOptions.None, IObservable? resort = null, int resetThreshold = 50) where T : notnull { @@ -1535,27 +2042,41 @@ public static IObservable> Sort(this IObservable> } /// - /// Prepends an empty change set to the source. + /// Prepends an empty changeset to the source stream. Useful for initializing downstream consumers that expect an initial emission. /// /// The type of item. - /// The source observable of change set values. - /// An observable which emits a change set. + /// The source to prepend an empty changeset to. + /// A list changeset stream that begins with an empty changeset. + /// + /// + /// public static IObservable> StartWithEmpty(this IObservable> source) where T : notnull => source.StartWith(ChangeSet.Empty); /// - /// Subscribes to each item when it is added to the stream and unsubscribes when it is removed. All items will be unsubscribed when the stream is disposed. + /// Creates an subscription for each item via when it is added. + /// The subscription is disposed when the item is removed or replaced. All subscriptions are disposed when the stream terminates. + /// The changeset is forwarded downstream unmodified. /// /// The type of the object. - /// The source. - /// The subscription function. - /// An observable which emits the change set. - /// source - /// or - /// subscriptionFactory. + /// The source to create a subscription for each item in. + /// A function that creates an for each item. + /// A continuation of the source changeset stream with per-item subscriptions managed as a side effect. + /// or is . /// - /// Subscribes to each item when it is added or updates and unsubscribes when it is removed. + /// + /// EventBehavior + /// Add/AddRangeSubscription created for each item via the factory. Changeset forwarded. + /// ReplaceOld item's subscription disposed, new subscription created. Changeset forwarded. + /// Remove/RemoveRange/ClearSubscriptions for removed items are disposed. Changeset forwarded. + /// Moved/RefreshForwarded. No subscription changes. + /// OnError/OnCompleted/DisposalAll active subscriptions are disposed. + /// /// + /// + /// + /// + /// public static IObservable> SubscribeMany(this IObservable> source, Func subscriptionFactory) where T : notnull { @@ -1566,26 +2087,28 @@ public static IObservable> SubscribeMany(this IObservable - /// Suppress refresh notifications. + /// Suppresses all changes from the stream. All other change reasons pass through. /// /// The type of the object. - /// The source observable change set. - /// An observable which emits the change set. + /// The source to strip refresh events. + /// A list changeset stream with Refresh changes removed. + /// + /// public static IObservable> SuppressRefresh(this IObservable> source) where T : notnull => source.WhereReasonsAreNot(ListChangeReason.Refresh); /// - /// Transforms an observable sequence of observable lists into a single sequence - /// producing values only from the most recent observable sequence. - /// Each time a new inner observable sequence is received, unsubscribe from the - /// previous inner observable sequence and clear the existing result set. + /// Subscribes to the latest inner , switching to each new source and clearing the result when switching. + /// This is the changeset-aware equivalent of Rx's , which cannot be applied directly to changeset streams. /// /// The type of the object. - /// The source. - /// - /// The observable sequence that at any point in time produces the elements of the most recent inner observable sequence that has been received. - /// - /// is null. + /// An observable that emits instances. Each emission triggers a switch to the new list. + /// A list changeset stream reflecting the most recently received inner list. + /// is . + /// + /// Convenience overload that calls Connect() on each inner list, then delegates to . + /// + /// public static IObservable> Switch(this IObservable> sources) where T : notnull { @@ -1595,17 +2118,20 @@ public static IObservable> Switch(this IObservable - /// Transforms an observable sequence of observable changes sets into an observable sequence - /// producing values only from the most recent observable sequence. - /// Each time a new inner observable sequence is received, unsubscribe from the - /// previous inner observable sequence and clear the existing result set. + /// Subscribes to the latest inner changeset stream, switching to each new source and clearing the destination when switching. + /// Previous subscriptions are disposed and the result set is emptied before subscribing to the new inner stream. /// /// The type of the object. - /// The source. - /// - /// The observable sequence that at any point in time produces the elements of the most recent inner observable sequence that has been received. - /// - /// is null. + /// An of changeset streams. The operator subscribes to the latest inner stream. + /// A list changeset stream reflecting the most recently received inner changeset stream. + /// is . + /// + /// + /// On each new inner stream, the operator clears the destination, disposes the previous subscription, and subscribes to the new stream. + /// This is the changeset-aware equivalent of Rx's Switch(). + /// + /// + /// public static IObservable> Switch(this IObservable>> sources) where T : notnull { @@ -1615,23 +2141,36 @@ public static IObservable> Switch(this IObservable - /// Converts the change set into a fully formed collection. Each change in the source results in a new collection. + /// Emits the full collection as an after every changeset. Equivalent to QueryWhenChanged(items => items). /// - /// The type of the object. - /// The source. - /// An observable which emits the read only collection. + /// The type of items in the list. + /// The source to materialize into a collection on each change. + /// An observable emitting the full collection snapshot after each change. + /// + /// + /// public static IObservable> ToCollection(this IObservable> source) where TObject : notnull => source.QueryWhenChanged(items => items); /// - /// Converts the observable to an observable change set. - /// Change set observes observable change events. + /// Bridges an into the DynamicData world by converting each emitted item into a list changeset. + /// Each emission becomes an Add operation in the resulting changeset stream. /// /// The type of the object. - /// The source. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source to convert into a changeset stream. + /// An optional for time-based operations (expiry, size limiting). + /// A list changeset stream where each source emission is an Add. + /// is . + /// + /// + /// This is the primary bridge from standard Rx into DynamicData's list changeset model. Each item emitted by + /// is added to an internal list and an Add changeset is emitted. The list grows unboundedly unless size or time limits + /// are specified via other overloads. + /// + /// Worth noting: Source completion and errors are propagated. The internal list is disposed on unsubscribe. + /// + /// + /// public static IObservable> ToObservableChangeSet( this IObservable source, IScheduler? scheduler = null) @@ -1642,16 +2181,14 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: -1, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set, allowing time expiry to be specified. - /// Change set observes observable change events. + /// Bridges an into a list changeset stream with per-item time-based expiry. + /// Expired items are automatically removed. /// - /// The type of the object. - /// The source. - /// Specify on a per object level the maximum time before an object expires from a cache. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source to convert into a changeset stream. + /// A function returning the time-to-live for each item. Return for non-expiring items. + /// An optional for expiry timers. public static IObservable> ToObservableChangeSet( this IObservable source, Func expireAfter, @@ -1663,16 +2200,14 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: -1, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set, with a specified limit of how large the list can be. - /// Change set observes observable change events. + /// Bridges an into a list changeset stream with FIFO size limiting. + /// When the list exceeds , the oldest items are removed. /// - /// The type of the object. - /// The source. - /// Remove the oldest items when the size has reached this limit. Supply -1 to disable size limiting. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source to convert into a changeset stream. + /// The maximum list size. Supply -1 to disable size limiting. + /// An optional for scheduling removals. public static IObservable> ToObservableChangeSet( this IObservable source, int limitSizeTo, @@ -1684,17 +2219,14 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: limitSizeTo, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set, allowing size and time limit to be specified. - /// Change set observes observable change events. + /// Bridges an into a list changeset stream with both time-based expiry and FIFO size limiting. /// - /// The type of the object. - /// The source. - /// Specify on a per object level the maximum time before an object expires from a cache. - /// Remove the oldest items when the size has reached this limit. Supply -1 to disable size limiting. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source to convert into a changeset stream. + /// A function returning the time-to-live for each item. Return for non-expiring items. + /// The maximum list size. Supply -1 to disable size limiting. + /// An optional for expiry timers and size-limit checks. public static IObservable> ToObservableChangeSet( this IObservable source, Func? expireAfter, @@ -1707,15 +2239,13 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: limitSizeTo, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set. - /// Change set observes observable change events. + /// Bridges an of batches into a list changeset stream. + /// Each emitted batch becomes an AddRange. /// - /// The type of the object. - /// The source. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source of to convert into a changeset stream. + /// An optional for time-based operations. public static IObservable> ToObservableChangeSet( this IObservable> source, IScheduler? scheduler = null) @@ -1726,16 +2256,13 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: -1, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set, allowing size and time limit to be specified. - /// Change set observes observable change events. + /// Bridges an of batches into a list changeset stream with FIFO size limiting. /// - /// The type of the object. - /// The source. - /// Remove the oldest items when the size has reached this limit. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source of to convert into a changeset stream. + /// The maximum list size. Oldest items are removed when the limit is exceeded. + /// An optional for scheduling removals. public static IObservable> ToObservableChangeSet( this IObservable> source, int limitSizeTo, @@ -1747,16 +2274,13 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: limitSizeTo, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set, allowing size to be specified. - /// Change set observes observable change events. + /// Bridges an of batches into a list changeset stream with time-based expiry. /// - /// The type of the object. - /// The source. - /// Specify on a per object level the maximum time before an object expires from a cache. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source. + /// The source of to convert into a changeset stream. + /// A function returning the time-to-live for each item. Return for non-expiring items. + /// An optional for expiry timers. public static IObservable> ToObservableChangeSet( this IObservable> source, Func expireAfter, @@ -1768,19 +2292,14 @@ public static IObservable> ToObservableChangeSet( limitSizeTo: -1, scheduler: scheduler); + /// /// - /// Converts the observable to an observable change set, allowing size and time limit to be specified. - /// Change set observes observable change events. + /// Bridges an of batches into a list changeset stream with both time-based expiry and FIFO size limiting. /// - /// The type of the object. - /// The source. - /// Specify on a per object level the maximum time before an object expires from a cache. - /// Remove the oldest items when the size has reached this limit. - /// The scheduler (only used for time expiry). - /// An observable which emits a change set. - /// source - /// or - /// keySelector. + /// The source of to convert into a changeset stream. + /// A function returning the time-to-live for each item. Return for non-expiring items. + /// The maximum list size. Oldest items removed when exceeded. + /// An optional for expiry timers and size-limit checks. public static IObservable> ToObservableChangeSet( this IObservable> source, Func? expireAfter, @@ -1794,12 +2313,20 @@ public static IObservable> ToObservableChangeSet( scheduler: scheduler); /// - /// Limits the size of the result set to the specified number of items. + /// Takes the first items from the source list. Implemented as Virtualise with a fixed window starting at index 0. /// /// The type of the item. - /// The source. - /// The number of items. - /// An observable which emits the change set. + /// The source to take the top items. + /// The maximum number of items to include. Must be greater than zero. + /// A virtual changeset stream containing at most items from the beginning of the source. + /// is . + /// is zero or negative. + /// + /// The source should ideally be sorted before applying Top, since list order determines which items appear. + /// + /// + /// + /// public static IObservable> Top(this IObservable> source, int numberOfItems) where T : notnull { @@ -1814,24 +2341,30 @@ public static IObservable> Top(this IObservable> } /// - /// Converts the change set into a fully formed sorted collection. Each change in the source results in a new sorted collection. + /// Emits a sorted after every changeset, sorted by the value returned by . /// - /// The type of the object. - /// The sort key. - /// The source. - /// The sort function. - /// The sort order. Defaults to ascending. - /// An observable which emits the read only collection. + /// The type of items in the list. + /// The type of the sort key. + /// The source to materialize into a sorted collection on each change. + /// A function extracting the sort key from each item. + /// The sort direction. Defaults to ascending. + /// An observable emitting a sorted collection snapshot after each change. + /// + /// + /// + /// public static IObservable> ToSortedCollection(this IObservable> source, Func sort, SortDirection sortOrder = SortDirection.Ascending) where TObject : notnull => source.QueryWhenChanged(query => sortOrder == SortDirection.Ascending ? new ReadOnlyCollectionLight(query.OrderBy(sort)) : new ReadOnlyCollectionLight(query.OrderByDescending(sort))); /// - /// Converts the change set into a fully formed sorted collection. Each change in the source results in a new sorted collection. + /// Emits a sorted after every changeset, sorted using the specified . /// - /// The type of the object. - /// The source. - /// The sort comparer. - /// An observable which emits the read only collection. + /// The type of items in the list. + /// The source to materialize into a sorted collection on each change. + /// The used for sorting. + /// An observable emitting a sorted collection snapshot after each change. + /// + /// public static IObservable> ToSortedCollection(this IObservable> source, IComparer comparer) where TObject : notnull => source.QueryWhenChanged( query => @@ -1842,19 +2375,38 @@ public static IObservable> ToSortedCollection - /// Projects each update item to a new form using the specified transform function. + /// Projects each item to a new form using a synchronous transform function. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// An observable which emits the change set. - /// - /// source - /// or - /// valueSelector. - /// + /// The type of the source items. + /// The type of the destination items. + /// The source to transform. + /// The transform function applied to each item. + /// When , Refresh events re-invoke the factory and emit an update. When (the default), Refresh is forwarded without re-transforming. + /// A list changeset stream of transformed items. + /// + /// + /// Maintains an internal list of transformed items. Each source changeset is + /// processed and a corresponding output changeset is produced with the transformed items. + /// + /// + /// EventBehavior + /// AddThe factory is called and an Add is emitted at the same index. + /// AddRangeThe factory is called for each item. An AddRange is emitted at the same start index. + /// ReplaceThe factory is called for the new item. A Replace is emitted at the same index. The previous transformed value is available to overloads that accept . + /// RemoveA Remove is emitted (no factory call). + /// RemoveRangeA RemoveRange is emitted. + /// MovedA Moved is emitted with updated indices (no factory call). Throws if the source change has no index information. + /// RefreshIf is (default), the Refresh is forwarded without re-transforming. If , the factory is re-invoked and the result replaces the current value. + /// ClearA Clear is emitted and the internal list is emptied. + /// OnErrorIf the factory throws, the exception propagates as OnError. + /// + /// Worth noting: By default, Refresh does NOT re-transform the item (it just forwards the signal). Set to if you need the factory re-invoked on Refresh. Add operations with out-of-bounds indices silently append to the end. + /// + /// or is . + /// + /// + /// + /// public static IObservable> Transform(this IObservable> source, Func transformFactory, bool transformOnRefresh = false) where TSource : notnull where TDestination : notnull @@ -1866,20 +2418,10 @@ public static IObservable> Transform((t, _, _) => transformFactory(t), transformOnRefresh); } + /// /// - /// Projects each update item to a new form using the specified transform function. + /// Projects each item using a transform function that also receives the item's index. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform function. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// public static IObservable> Transform(this IObservable> source, Func transformFactory, bool transformOnRefresh = false) where TSource : notnull where TDestination : notnull @@ -1890,21 +2432,11 @@ public static IObservable> Transform((t, _, idx) => transformFactory(t, idx), transformOnRefresh); } + /// /// - /// Projects each update item to a new form using the specified transform function. - /// *** Annoyingly when using this overload you will have to explicitly specify the generic type arguments as type inference fails. + /// Projects each item using a transform function that also receives the previously transformed value (if any). + /// Type arguments must be specified explicitly as type inference fails for this overload. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform function. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// public static IObservable> Transform(this IObservable> source, Func, TDestination> transformFactory, bool transformOnRefresh = false) where TSource : notnull where TDestination : notnull @@ -1915,21 +2447,11 @@ public static IObservable> Transform((t, previous, _) => transformFactory(t, previous), transformOnRefresh); } + /// /// - /// Projects each update item to a new form using the specified transform function. - /// *** Annoyingly when using this overload you will have to explicitly specify the generic type arguments as type inference fails. + /// Projects each item using a transform function that receives the source item, the previously transformed value, and the index. + /// Type arguments must be specified explicitly as type inference fails for this overload. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// public static IObservable> Transform(this IObservable> source, Func, int, TDestination> transformFactory, bool transformOnRefresh = false) where TSource : notnull where TDestination : notnull @@ -1941,19 +2463,32 @@ public static IObservable> Transform - /// Projects each update item to a new form using the specified transform function. + /// Projects each item to a new form using an async transform function. Behaves like but the factory returns a . /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// + /// The type of the source items. + /// The type of the destination items. + /// The source to transform asynchronously. + /// An async function that transforms each source item. + /// When , Refresh events re-invoke the factory. + /// A list changeset stream of asynchronously transformed items. + /// or is . + /// + /// Change handling is identical to the synchronous except the factory is awaited. Operations are serialized per changeset via a semaphore. + /// + /// EventBehavior + /// Add/AddRangeThe async factory is awaited for each item. An Add/AddRange is emitted with the transformed results. + /// ReplaceThe async factory is awaited for the new item. A Replace is emitted. + /// Remove/RemoveRangeEmitted without invoking the factory. + /// MovedEmitted with updated indices (no factory call). + /// RefreshIf is (default), forwarded without re-transforming. If , the factory is re-awaited. + /// ClearEmitted and internal list cleared. + /// OnErrorIf the async factory throws, the exception propagates as OnError. + /// OnCompletedForwarded after the last changeset is processed. + /// + /// Worth noting: All async transforms within a single changeset are serialized (not parallel). Each changeset is fully processed before the next begins. By default, Refresh does NOT re-transform. + /// + /// + /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync( this IObservable> source, @@ -1968,20 +2503,10 @@ public static IObservable> TransformAsync((t, _, _) => transformFactory(t), transformOnRefresh); } + /// /// - /// Projects each update item to a new form using the specified transform function. + /// Async transform overload receiving the source item and its index. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync( this IObservable> source, @@ -1996,20 +2521,10 @@ public static IObservable> TransformAsync((t, _, i) => transformFactory(t, i), transformOnRefresh); } + /// /// - /// Projects each update item to a new form using the specified transform function. + /// Async transform overload receiving the source item and the previously transformed value. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync( this IObservable> source, @@ -2024,20 +2539,10 @@ public static IObservable> TransformAsync((t, d, _) => transformFactory(t, d), transformOnRefresh); } + /// /// - /// Projects each update item to a new form using the specified transform function. + /// Async transform overload receiving the source item, previously transformed value, and index. This is the terminal overload that all other TransformAsync overloads delegate to. /// - /// The type of the source. - /// The type of the destination. - /// The source. - /// The transform factory. - /// Should a new transform be applied when a refresh event is received. - /// A an observable change set of the transformed object. - /// - /// source - /// or - /// valueSelector. - /// [System.Diagnostics.CodeAnalysis.SuppressMessage("Roslynator", "RCS1047:Non-asynchronous method name should not end with 'Async'.", Justification = "By Design.")] public static IObservable> TransformAsync( this IObservable> source, @@ -2053,19 +2558,28 @@ public static IObservable> TransformAsync - /// Equivalent to a select many transform. To work, the key must individually identify each child. + /// Flattens each source item into multiple destination items using . Each source item produces zero or more children, + /// all of which are merged into a single flat list changeset stream. /// - /// The type of the destination. - /// The type of the source. - /// The source. - /// The selector function which selects the enumerable. - /// Used when an item has been replaced to determine whether child items are the same as previous children. - /// An observable which emits the change set. - /// - /// source - /// or - /// manySelector. - /// + /// The type of the destination items. + /// The type of the source items. + /// The source to expand each item into multiple children. + /// A function that returns the child items for each source item. + /// An optional used during Replace to determine which child items changed between old and new parent values. + /// A list changeset stream of all child items from all source items. + /// or is . + /// + /// + /// EventBehavior + /// Add/AddRangeChildren expanded and added to the output. + /// ReplaceOld children diffed against new children (using ). Removed, added, or kept as appropriate. + /// Remove/RemoveRange/ClearAll children of the removed parents are removed from the output. + /// RefreshChildren re-expanded and diffed. + /// + /// + /// + /// + /// public static IObservable> TransformMany(this IObservable> source, Func> manySelector, IEqualityComparer? equalityComparer = null) where TDestination : notnull where TSource : notnull @@ -2076,52 +2590,47 @@ public static IObservable> TransformMany(source, manySelector, equalityComparer).Run(); } + /// /// - /// Flatten the nested observable collection, and observe subsequently observable collection changes. + /// Flattens each source item into children from an . The collection is observed for subsequent changes. /// - /// The type of the destination. - /// The type of the source. - /// The source. - /// The selector function which selects the enumerable. - /// Used when an item has been replaced to determine whether child items are the same as previous children. - /// An observable which emits the change set. public static IObservable> TransformMany(this IObservable> source, Func> manySelector, IEqualityComparer? equalityComparer = null) where TDestination : notnull where TSource : notnull => new TransformMany(source, manySelector, equalityComparer).Run(); + /// /// - /// Flatten the nested observable collection, and observe subsequently observable collection changes. + /// Flattens each source item into children from a . The collection is observed for subsequent changes. /// - /// The type of the destination. - /// The type of the source. - /// The source. - /// The selector function which selects the enumerable. - /// Used when an item has been replaced to determine whether child items are the same as previous children. - /// An observable which emits the change set. public static IObservable> TransformMany(this IObservable> source, Func> manySelector, IEqualityComparer? equalityComparer = null) where TDestination : notnull where TSource : notnull => new TransformMany(source, manySelector, equalityComparer).Run(); + /// /// - /// Flatten the nested observable list, and observe subsequent observable collection changes. + /// Flattens each source item into children from an . The inner list is observed for subsequent changes. /// - /// The type of the destination. - /// The type of the source. - /// The source. - /// The selector function which selects the enumerable. - /// Used when an item has been replaced to determine whether child items are the same as previous children. - /// An observable which emits the change set. public static IObservable> TransformMany(this IObservable> source, Func> manySelector, IEqualityComparer? equalityComparer = null) where TDestination : notnull where TSource : notnull => new TransformMany(source, manySelector, equalityComparer).Run(); /// - /// Virtualises the source using parameters provided via the requests observable. + /// Applies a sliding window to the source list using start index and size from . + /// Only items within the window are included downstream. /// /// The type of the item. - /// The source. - /// The requests. - /// An observable which emits the change set. + /// The source to virtualize. + /// An observable of specifying the start index and size of the window. + /// An stream containing only items within the current virtual window. + /// or is . + /// + /// + /// Like but uses absolute start index and size instead of page number and page size. + /// Internally maintains the full source list and recalculates the window on each change or request. + /// + /// + /// + /// public static IObservable> Virtualise(this IObservable> source, IObservable requests) where T : notnull { @@ -2133,12 +2642,22 @@ public static IObservable> Virtualise(this IObservable - /// Watches each item in the collection and notifies when any of them has changed. + /// Watches all items in the source list and emits the item when any of its properties change. + /// Requires to implement . + /// This is NOT a changeset operator: it returns a flat . /// - /// The type of the object. - /// The source. - /// specify properties to Monitor, or omit to monitor all property changes. - /// An observable which emits the object. + /// The type of the object. Must implement . + /// The source to observe property changes on items in. + /// An optional list of property names to monitor. If empty, all property changes are observed. + /// An observable emitting the item whenever any monitored property changes. + /// is . + /// + /// Implemented via . Subscriptions are managed per item: created on add, disposed on remove. + /// + /// + /// + /// + /// public static IObservable WhenAnyPropertyChanged(this IObservable> source, params string[] propertiesToMonitor) where TObject : INotifyPropertyChanged { @@ -2148,14 +2667,23 @@ public static IObservable> Virtualise(this IObservable - /// Watches each item in the collection and notifies when any of them has changed. + /// Watches a specific property on all items in the source list and emits a (item + value pair) when it changes. + /// Requires to implement . + /// This is NOT a changeset operator: it returns a flat . /// - /// The type of object. - /// The type of the value. - /// The source. - /// The property accessor. - /// If true the resulting observable includes the initial value. - /// An observable which emits the property value. + /// The type of item. Must implement . + /// The type of the property value. + /// The source to observe a specific property on items in. + /// An expression selecting the property to observe. + /// When (default), the current value is emitted immediately upon subscribing to each item. + /// An observable emitting whenever the property changes on any tracked item. + /// or is . + /// + /// Implemented via . + /// + /// + /// + /// public static IObservable> WhenPropertyChanged(this IObservable> source, Expression> propertyAccessor, bool notifyOnInitialValue = true) where TObject : INotifyPropertyChanged { @@ -2167,14 +2695,20 @@ public static IObservable> WhenPropertyChanged - /// Watches each item in the collection and notifies when any of them has changed. + /// Watches a specific property on all items and emits just the property value (without the sender) when it changes. + /// Requires to implement . + /// This is NOT a changeset operator: it returns a flat . /// - /// The type of object. - /// The type of the value. - /// The source. - /// The property accessor. - /// If true the resulting observable includes the initial value. - /// An observable which emits the value. + /// The type of item. Must implement . + /// The type of the property value. + /// The source to observe a specific property value on items in. + /// An expression selecting the property to observe. + /// When (default), the current value is emitted immediately upon subscribing to each item. + /// An observable emitting the property value whenever it changes on any tracked item. + /// or is . + /// + /// + /// public static IObservable WhenValueChanged(this IObservable> source, Expression> propertyAccessor, bool notifyOnInitialValue = true) where TObject : INotifyPropertyChanged { @@ -2186,13 +2720,22 @@ public static IObservable> WhenPropertyChanged - /// Includes changes for the specified reasons only. + /// Filters the changeset stream to include only changes with the specified values. + /// Index information is stripped from the output because removing some changes invalidates the original index positions. /// /// The type of the item. - /// The source. - /// The reasons. - /// An observable which emits the change set. - /// Must enter at least 1 reason. + /// The source to filter by change reason. + /// The change reasons to include. Must specify at least one. + /// A list changeset stream containing only changes with the specified reasons. + /// is . + /// is empty. + /// + /// Filters individual changes within each changeset. If filtering removes all changes from a changeset, the empty changeset is suppressed via . + /// Worth noting: Filtering out Remove changes can cause downstream operators to accumulate items indefinitely (memory leak). Index information is stripped because removing some changes invalidates the original index positions. + /// + /// + /// + /// public static IObservable> WhereReasonsAre(this IObservable> source, params ListChangeReason[] reasons) where T : notnull { @@ -2213,13 +2756,25 @@ public static IObservable> WhereReasonsAre(this IObservable - /// Excludes updates for the specified reasons. + /// Filters the changeset stream to exclude changes with the specified values. + /// Index information is stripped from the output because removing some changes invalidates the original index positions. + /// The exception is when only is excluded, since removing Refresh does not affect index calculations. /// /// The type of the item. - /// The source. - /// The reasons. - /// An observable which emits the change set. - /// Must enter at least 1 reason. + /// The source to filter by excluding change reasons. + /// The change reasons to exclude. Must specify at least one. + /// A list changeset stream with the specified change reasons removed. + /// is . + /// is empty. + /// + /// + /// Empty changesets (after filtering) are automatically suppressed. When only is excluded, + /// indices are preserved, since removing Refresh does not affect index calculations. + /// + /// + /// + /// + /// public static IObservable> WhereReasonsAreNot(this IObservable> source, params ListChangeReason[] reasons) where T : notnull { @@ -2250,13 +2805,33 @@ public static IObservable> WhereReasonsAreNot(this IObservable< } /// - /// Apply a logical Xor operator between the collections. - /// Items which are only in one of the sources are included in the result. + /// Applies a logical XOR (symmetric difference) between the source and other streams. + /// Items present in exactly one source are included in the result. /// /// The type of the item. - /// The source. - /// The others. - /// An observable which emits the change set. + /// The primary source to exclusively combine. + /// The other changeset streams to combine with. + /// A list changeset stream containing items that exist in exactly one source. + /// is . + /// + /// + /// Item identity is determined by the default equality comparer for . Uses reference-counted equality: an item is included when it exists in exactly one source. + /// If it appears in a second source, it is removed from the result. If it then leaves one source, + /// it re-enters the result. Moved changes are ignored. + /// + /// + /// EventBehavior + /// Add/AddRangeReference count updated. If the item is now in exactly one source, an Add is emitted. If now in two or more, a Remove is emitted. + /// Remove/RemoveRange/ClearReference count decremented. If now in exactly one source, an Add is emitted. If now in zero, a Remove is emitted. + /// ReplaceOld item reference count decremented, new item incremented, with Xor logic applied. + /// RefreshForwarded if item is in the result set. + /// MovedIgnored. + /// + /// + /// + /// + /// + /// public static IObservable> Xor(this IObservable> source, params IObservable>[] others) where T : notnull { @@ -2265,43 +2840,31 @@ public static IObservable> Xor(this IObservable> return source.Combine(CombineOperator.Xor, others); } + /// /// - /// Apply a logical Xor operator between the collections. - /// Items which are only in one of the sources are included in the result. + /// Applies a logical XOR between a pre-built collection of list changeset sources. /// - /// The type of the item. - /// The sources. - /// An observable which emits the change set. public static IObservable> Xor(this ICollection>> sources) where T : notnull => sources.Combine(CombineOperator.Xor); + /// /// - /// Dynamically apply a logical Xor operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. + /// Dynamic XOR: sources can be added or removed from the at runtime. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. public static IObservable> Xor(this IObservableList>> sources) where T : notnull => sources.Combine(CombineOperator.Xor); + /// /// - /// Dynamically apply a logical Xor operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. + /// Dynamic XOR accepting of . Each inner list's Connect() is used as a source. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. public static IObservable> Xor(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.Xor); + /// /// - /// Dynamically apply a logical Xor operator between the items in the outer observable list. - /// Items which are in any of the sources are included in the result. + /// Dynamic XOR accepting of . Each inner list's Connect() is used as a source. /// - /// The type of the item. - /// The source. - /// An observable which emits the change set. public static IObservable> Xor(this IObservableList> sources) where T : notnull => sources.Combine(CombineOperator.Xor);