Skip to content

Commit e591393

Browse files
xperiandriclaude
andcommitted
fixup! docs: FrozenSet in the changelog and the collection table
The changelog lists the new `ofReadOnlySpan` and `ofSpan` of `FrozenSet` and the members of `CustomComparerFrozenSet`. It says what a user of the BCL type does differently: the replacements of `Create(comparer, ...)` and `ToFrozenSet(source, comparer)`, a `null` comparer, `TryGetValue`, `Items` and `CopyTo`, the sequence forms of the relations, `Add` and `Remove` through `union` and `difference`, the mutating interface members, which element stays when the comparer finds two equal, and the alternate lookups. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
1 parent c73ad52 commit e591393

1 file changed

Lines changed: 31 additions & 7 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -57,15 +57,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
5757
a `null` comparer throws `ArgumentNullException`.
5858
* `FrozenSet` works on `System.Collections.Frozen.FrozenSet<'T>` with the functions of the FSharp.Core `Set` module that
5959
read a set or transform a whole set, with their semantics, argument order and exceptions, plus `choose`, `comparer`,
60-
`forComparer`, `overlaps`, `setEquals`, `symmetricDifference`, `toFlatList`, which returns the elements without a copy,
61-
and `tryGetValue`. A frozen set is built once: the module has no function that adds or removes an element, and every
62-
transformation builds a new frozen set.
60+
`forComparer`, `ofReadOnlySpan`, `ofSpan`, `overlaps`, `setEquals`, `symmetricDifference`, `toFlatList`, which returns
61+
the elements without a copy, and `tryGetValue`. A frozen set is built once: the module has no function that adds or
62+
removes an element, and every transformation builds a new frozen set. `FrozenSet.union set (FrozenSet.singleton value)`
63+
and `FrozenSet.difference set (FrozenSet.singleton value)` do what `Set.add` and `Set.remove` do, each as an O(n)
64+
rebuild that compares in the comparer of `set`.
65+
* `FrozenSet.ofReadOnlySpan` and `ofSpan` create a frozen set from a span. They wrap `FrozenSet.Create`, and of the
66+
elements that the comparer finds equal the first stays.
6367
* `FrozenSet.forComparer comparer` creates the `CustomComparerFrozenSet` struct, whose members `empty`, `ofArray`,
64-
`ofList`, `ofSeq` and `singleton` create frozen sets that compare with the comparer, as in
65-
`(FrozenSet.forComparer StringComparer.OrdinalIgnoreCase).ofSeq names`. `ofSeq` also gives an existing frozen set the
66-
comparer. A `null` comparer throws `ArgumentNullException`.
68+
`ofList`, `ofReadOnlySpan`, `ofSeq`, `ofSpan` and `singleton` create frozen sets that compare with the comparer, as in
69+
`(FrozenSet.forComparer StringComparer.OrdinalIgnoreCase).ofSeq names`. They replace the BCL methods
70+
`FrozenSet.Create(comparer, ...)` and `ToFrozenSet(source, comparer)`; `ToFrozenSet` has no `optimizeForReading`
71+
parameter in the package that the library references, so nothing is lost. `ofSeq` also gives an existing frozen set the
72+
comparer, as `ToFrozenSet` does: the frozen set itself comes back when its comparer equals the comparer of the struct.
73+
A `null` comparer throws `ArgumentNullException`, where the BCL methods take it as the default comparer:
74+
`FrozenSet.ofSeq set` gives a frozen set the default comparer, and the default value of the struct has the BCL meaning.
75+
* The members of `FrozenSet<'T>` map to the module as follows. `TryGetValue(x, out v)` is `tryGetValue x set`, which
76+
returns a `voption` (`Option.FrozenSet.tryGetValue` returns an `option`). `Items` is `toFlatList`, and `CopyTo` is
77+
`toFlatList` followed by `FlatList.blit` or `FlatList.asSpan`. `IsSubsetOf`, `IsProperSubsetOf`, `IsSupersetOf`,
78+
`IsProperSupersetOf`, `Overlaps` and `SetEquals` take frozen sets in the module, as the `Set` functions do: pass
79+
`FrozenSet.ofSeq elements`, or `(FrozenSet.forComparer (FrozenSet.comparer set)).ofSeq elements` to give the elements
80+
the comparer of the first frozen set; `Overlaps` and `IsSupersetOf` with a sequence are `Seq.exists` and `Seq.forall`
81+
with `FrozenSet.contains`. The mutating members of the interfaces, such as `ISet<T>.UnionWith` and `ICollection<T>.Add`,
82+
throw `NotSupportedException` on the BCL type and have no function.
83+
* `FrozenSet`: the element that stays when the comparer finds two elements equal follows the BCL. `union` keeps the
84+
element of the first frozen set, `intersect` keeps the elements of the second one, as `ImmutableHashSet.Intersect` and
85+
`ImmutableSortedSet.Intersect` do, because `FrozenSet<'T>` has no such member, and the creation functions keep the
86+
first element of their input. `isProperSuperset` counts the elements of the second frozen set that the comparer of the
87+
first one finds equal once, as `FrozenSet<'T>.IsProperSupersetOf` does.
6788
* On `net10.0`, `FrozenSet.alternateLookup` and `FrozenSet.tryAlternateLookup` return the alternate lookup of a frozen set
68-
whose comparer compares the elements with values of another type.
89+
whose comparer compares the elements with values of another type. They are `GetAlternateLookup` and
90+
`TryGetAlternateLookup`. The alternate type comes first, as in `FrozenSet.alternateLookup<int, _> set`, and a lookup by a
91+
`ReadOnlySpan<char>` calls the BCL method directly, because an F# generic function cannot be instantiated with a
92+
byref-like type.
6993
* The `FSharp.Collections.Immutable.Option.FrozenSet` and `FSharp.Collections.Immutable.Tuple.FrozenSet` modules repeat
7094
`choose`, `tryGetValue` and `tryAlternateLookup` with options, and `partition` and `partitionWith` with reference tuples.
7195
* `frozenSet { }` builds a frozen set, and `FrozenSetCE` created with an equality comparer builds frozen sets that compare

0 commit comments

Comments
 (0)