From aa706c4f01d4cfa7a85c1d3315c7df22a42a3bd1 Mon Sep 17 00:00:00 2001 From: Kartal Kaan Bozdogan Date: Wed, 9 Oct 2024 19:03:39 +0200 Subject: [PATCH] computed_collections: Dart docs --- packages/computed_collections/README.md | 4 +- .../computed_collections/lib/computedmap.dart | 66 ++++++++++++++++--- 2 files changed, 58 insertions(+), 12 deletions(-) diff --git a/packages/computed_collections/README.md b/packages/computed_collections/README.md index f81b73e..030c93e 100644 --- a/packages/computed_collections/README.md +++ b/packages/computed_collections/README.md @@ -178,8 +178,8 @@ Below is a list of reactive operators on reactive maps along with a high-level d | **`.cast`** | Reactively casts the entries of a reactive map. | | **`.containsKey`** | Returns a computation representing if a reactive map contains a given key. | | **`.containsValue`** | Returns a computation representing if a reactive map contains a given value. | -| **`.map`** | Reactively maps each entries of a reactive map by a given synchronous function. | -| **`.mapComputed`** | Reactively maps each entries of a reactive map by a given reactive convertion computation. | +| **`.map`** | Reactively maps each entry of a reactive map by a given synchronous function. | +| **`.mapComputed`** | Reactively maps each entry of a reactive map by a given reactive convertion computation. | | **`.mapValues`** | Reactively maps all values of a reactive map by a given synchronous function. | | **`.mapValuesComputed`** | Reactively maps all values of a reactive map by a given reactive convertion computation. | | **`.putIfAbsent`** | Reactively adds a given key to a reactive map, if it does not already exist. | diff --git a/packages/computed_collections/lib/computedmap.dart b/packages/computed_collections/lib/computedmap.dart index 5426b0a..e040126 100644 --- a/packages/computed_collections/lib/computedmap.dart +++ b/packages/computed_collections/lib/computedmap.dart @@ -16,32 +16,37 @@ import 'src/ss.dart'; /// - Has value semantics thanks to immutability (using fast_immutable_collections). /// - Supports reactive operations consuming and emitting [ComputedMap]s. abstract class ComputedMap { - /// Constructs a constant computed map from a given [IMap]. + /// Constructs a constant [ComputedMap] from a given [IMap]. factory ComputedMap.fromIMap(IMap m) => ConstComputedMap(m); + + /// Constructs a [ComputedMap] that tracks [stream]. Initialized to the empty map. factory ComputedMap.fromChangeStream(Computed> stream) => ChangeStreamComputedMap(stream); + + /// Like [ComputedMap.fromChangeStream], but lets the change stream computation depend on the snapshot of the map. factory ComputedMap.fromChangeStreamWithPrev( ChangeEvent Function(IMap?) f) => ChangeStreamWithPrevComputedMap(f); - /// Constructs a computed map from the given snapshot stream. + /// Constructs a [ComputedMap] from the given snapshot stream. /// /// The returned map internally computes a change stream by comparing /// each new snapshot to the previous one. factory ComputedMap.fromSnapshotStream(Computed> stream) => SnapshotStreamComputedMap(stream); - /// Constructs a constant computed map defined by the given function over the given key domain. + /// Constructs a constant [ComputedMap] defined by [f] over the key domain [domain]. /// - /// The main advantage over `fromIMap` is that only the reactively + /// The main advantage over [ComputedMap.fromIMap] is that only the reactively /// used keys are computed. /// /// Make sure either: - /// - the domain is finite or - /// - `.snapshot` is never used. + /// - [domain] is finite or + /// - [snapshot] is never used. factory ComputedMap.fromPiecewise(Iterable domain, V Function(K key) f) => PiecewiseComputedMap(domain, f); + /// Like .fromPiecewise, but the values are defined by reactive computations. factory ComputedMap.fromPiecewiseComputed( Iterable domain, Computed Function(K key) f) => ComputedMap.fromPiecewise(domain, f).mapValuesComputed((_, c) => c); @@ -52,40 +57,81 @@ abstract class ComputedMap { /// A computation representing the snapshot of this map. Computed> get snapshot; + /// Returns a computation representing the given key of this map. Computed operator [](K key); + /// A computation representing the emptyness of this map. Computed get isEmpty; + + /// Opposite of [isEmpty]. Computed get isNotEmpty; + + /// A computation representing the length of this map. Computed get length; + /// Reactively adds the pair [key], [value] to this reactive map. ComputedMap add( K key, V value); // Note that the computed variant is trivial + + /// Reactively adds [other] to this reactive map. ComputedMap addAllComputed(ComputedMap other); + + /// Reactively adds [other] to this reactive map. ComputedMap addAll(IMap other); + + /// Reactively casts the entries of this reactive map. ComputedMap cast(); + + /// Returns a computation representing if this reactive map contains [key]. Computed containsKey(K key); // Not that the computed variant is trivial + + /// Returns a computation representing if this reactive map contains [value]. Computed containsValue( V value); // Not that the computed variant is trivial + + /// Reactively maps each entry of this reactive map by [convert]. ComputedMap mapComputed( Computed> Function(K key, V value) convert); + + /// Reactively maps each entry of this reactive map by [convert]. ComputedMap map( MapEntry Function(K key, V value) convert); + + /// Reactively maps all values of this reactive map by [convert]. ComputedMap mapValuesComputed( Computed Function(K key, V value) convert); + + /// Reactively maps all values of this reactive map by [convert]. ComputedMap mapValues(V2 Function(K key, V value) convert); + + /// Reactively adds [key] to this reactive map using the value returned by [ifAbsent], if [key] does not already exist. ComputedMap putIfAbsent( K key, V Function() ifAbsent); // Not that the computed variant is trivial + + /// Reactively removes [key] from this reactive map. ComputedMap remove(K key); // Not that the computed variant is trivial + + /// Reactively removes all entries satisfying [test] from this reactive map. ComputedMap removeWhereComputed( Computed Function(K key, V value) test); + + /// Reactively removes all entries satisfying [test] from this reactive map. ComputedMap removeWhere(bool Function(K key, V value) test); + + /// Reactively updates the value for [key]. + /// + /// Uses [ifAbsent] if [key] does not already exist. ComputedMap update( // Note that the computed variant is trivial K key, V Function(V value) update, {V Function()? ifAbsent}); + + /// A special case of [mapValuesComputed] where the input and output types are the same. ComputedMap updateAllComputed( Computed Function(K key, V value) update); + + /// A special case of [mapValues] where the input and output types are the same. ComputedMap updateAll(V Function(K key, V value) update); /// Groups this map using the given key function as a [ComputedMap]. @@ -95,7 +141,7 @@ abstract class ComputedMap { ComputedMap> groupBy( K2 Function(K key, V value) key); - /// As with [groupBy], but groups the elements by the value of a computation. + /// As with [groupBy], but groups the elements by the reactive value of a computation. ComputedMap> groupByComputed( Computed Function(K key, V value) key); @@ -105,16 +151,16 @@ abstract class ComputedMap { /// The values are records containing the corresponding values from both maps. ComputedMap join(ComputedMap other); - /// Returns the left join of this with [other] as a [ComputedMap]. + /// Returns the left join of this [ComputedMap] with [other] as a [ComputedMap]. /// /// The returned map has the same set of keys as this. /// The values are records containing the corresponding values from both maps, /// and null, if the key does not exist on [other]. ComputedMap lookup(ComputedMap other); - /// Returns the cartesian product of this with [other] as a [ComputedMap]. + /// Returns the cartesian product of this [ComputedMap] with [other] as a [ComputedMap]. /// - /// The returned map has all the key combinations of this map with [other]. + /// The returned map has all the key combinations of this [ComputedMap] with [other]. /// The values are records containing the corresponding values from both maps. ComputedMap<(K, K2), (V, V2)> cartesianProduct( ComputedMap other);