Skip to content

Commit b8fb3da

Browse files
xperiandriclaude
andcommitted
docs: SortedSet in the changelog and the collection table
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent dd39d1b commit b8fb3da

4 files changed

Lines changed: 65 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
8484
`tryGetValue` with options, and `partition` and `partitionWith` with reference tuples.
8585
* `hashSet { }` builds a hash set, and `HashSetCE` created with an equality comparer builds hash sets that compare with it;
8686
a `null` comparer throws `ArgumentNullException`.
87+
* `SortedSet` has every function of the FSharp.Core `Set` module, with its semantics, argument order and exceptions, plus
88+
`addRange`, `build`, `builder`, `choose`, `clear`, `comparer`, `forComparer`, `indexOf`, `item`, `ofBuilder`,
89+
`ofReadOnlySpan`, `ofSpan`, `overlaps`, `removeRange`, `rev`, `setEquals`, `symmetricDifference`, `toBuilder`,
90+
`tryGetValue`, `tryItem` and `update`.
91+
* `SortedSet.addRange elements set` and `removeRange elements set` take the place of the `Union` and `Except` members that
92+
take a sequence. The result keeps the comparer of the sorted set, and the input itself comes back when nothing changes.
93+
`removeRange` wraps `Except`. `addRange` adds the elements one by one, so an element of the sequence that the comparer
94+
finds equal to an element of the sorted set never replaces it, and of several equal elements of the sequence the first
95+
is added. `Union` does not promise that: when the sequence is large against the sorted set, it refills the tree from an
96+
unstable sort and can keep an element of the sequence instead.
97+
* `SortedSet.ofReadOnlySpan` and `ofSpan` create a sorted set from a span and keep the first of the elements that the
98+
comparer finds equal, where `ImmutableSortedSet.Create` with a span keeps an arbitrary one of them. `build` fills a
99+
builder with an action, and `update` applies an action to a builder of a sorted set and returns its contents, so that
100+
the in-place operations of the builder, such as `IntersectWith`, are one expression.
101+
* `SortedSet.forComparer comparer` creates the `CustomComparerSortedSet` struct, whose members `build`, `builder`, `empty`,
102+
`ofArray`, `ofList`, `ofReadOnlySpan`, `ofSeq`, `ofSpan` and `singleton` create sorted sets and builders that order
103+
their elements with the comparer, as in `(SortedSet.forComparer StringComparer.OrdinalIgnoreCase).ofSeq names`. They
104+
replace the BCL members `Create(comparer, ...)`, `CreateRange(comparer, items)`, `ToImmutableSortedSet(items, comparer)`
105+
and `CreateBuilder(comparer)`. `ofSeq` also gives an existing sorted set the comparer, as `WithComparer` does: the
106+
sorted set itself comes back for the same comparer instance, and an equal but distinct instance rebuilds it, keeping the
107+
first of the elements that the comparer finds equal. A `null` comparer throws `ArgumentNullException`.
108+
The element type needs no F# comparison. The default value of the struct orders with `Comparer<'T>.Default`, as the BCL
109+
does for a `null` comparer, so `WithComparer(null)` is `ofSeq` of the default value, where `SortedSet.ofSeq set` orders
110+
with F# generic comparison.
111+
* `SortedSet.add` and `remove` return the input itself when nothing changes, so a reference comparison of the input and
112+
the result tells whether `Add` changed anything, as the `bool` result of `Builder.Add` does. Sorted sets have no builder
113+
module: `builder`, `toBuilder` and `ofBuilder` are `CreateBuilder`, `ToBuilder` and `ToImmutable`, and the builder is
114+
used directly. The mutating members of the BCL interfaces, such as `ISet<T>.UnionWith` and `ICollection<T>.Add`, throw
115+
`NotSupportedException` on a sorted set and have no function.
116+
* `add`, `addRange`, `remove`, `removeRange`, `clear`, `update`, `filter` and `partition` of `SortedSet` keep the comparer
117+
of their input, and the set algebra keeps the comparer of the first sorted set. Every function throws
118+
`ArgumentNullException` for a `null` sorted set, sequence or array, and for a default flat list that is given as a
119+
sequence; `yield!` and `for` of `sortedSet { }` do the same. `unionMany` of an empty sequence returns an empty sorted
120+
set, as `Set.unionMany` does. `tryGetValue` returns a `voption`, `choose` takes a function that returns a `voption`,
121+
and `partition` and `partitionWith` return struct tuples.
122+
* The functions of `SortedSet` that create a sorted set without a comparer, `builder`, `build`, `unionMany` of no sets,
123+
`map`, `choose`, `partitionWith` and `sortedSet { }` order with F# generic comparison, as `Set` does, where the BCL
124+
orders with `Comparer<'T>.Default`. A sorted set thus enumerates its elements in the order of the F# set of the same
125+
elements: strings, and tuples and other values that contain strings, compare ordinally instead of in the order of the
126+
current culture. `SortedSet.forComparer Comparer<'T>.Default` orders as the BCL does.
127+
* The set algebra and the relations of `SortedSet` take sorted sets, as the `Set` functions do. The BCL members that take
128+
a sequence map as follows: `Union` and `Except` are `addRange` and `removeRange`, `Overlaps` and `IsSupersetOf` are
129+
`Seq.exists` and `Seq.forall` with `contains`, and the others take `SortedSet.ofSeq elements`, or
130+
`(SortedSet.forComparer (SortedSet.comparer set)).ofSeq elements` to give the elements the comparer of the first sorted
131+
set.
132+
* The element that stays when the comparer finds two elements equal follows the BCL: `union` keeps the element of the
133+
first sorted set, or of the larger one when both have the same comparer, `intersect` keeps the elements of the second
134+
one, and the creation functions keep the first element of their input, where `CreateRange` and `Create` with a span keep
135+
any of them. When the second sorted set of `union` has another comparer and is much larger, the BCL refills the tree
136+
from an unstable sort and either element can stay; only `addRange` keeps the element of the sorted set in every case.
137+
`isProperSuperset` is the exception: it counts the elements of the second sorted set that the comparer of the first one
138+
finds equal once, as the documentation of `IsProperSupersetOf` says, where the member counts each of them.
139+
* `SortedSet.minElement` and `maxElement` take the place of the properties `Min` and `Max`: they read the first and the
140+
last element in O(log n) and throw `ArgumentException` for an empty sorted set, as `Set.minElement` and
141+
`Set.maxElement` do, where the properties return `default`. `tryItem 0` and `tryItem (count - 1)` return a `voption`
142+
instead. `rev` is `Reverse`, `item` is the indexer and throws `ArgumentOutOfRangeException` like it, and `indexOf` is
143+
`IndexOf`, with the bitwise complement for a missing element. `ItemRef` has no function, because a curried function
144+
cannot return a `byref`.
145+
* The `FSharp.Collections.Immutable.Option.SortedSet` and `FSharp.Collections.Immutable.Tuple.SortedSet` modules repeat
146+
`choose`, `tryGetValue` and `tryItem` with options, and `partition` and `partitionWith` with reference tuples.
147+
* `sortedSet { }` builds a sorted set, and `SortedSetCE` created with a comparer builds sorted sets that order their
148+
elements with it; a `null` comparer throws `ArgumentNullException`.
87149

88150
### Changed
89151

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Please also join the [F# Open Source Group](http://fsharp.github.com)
1919
| `HashMap` | `ImmutableDictionary<'Key, 'Value>` | – |
2020
| `SortedMap` | `ImmutableSortedDictionary<'Key, 'Value>` | – |
2121
| `HashSet` | `ImmutableHashSet<'T>` | `hashSet { }` |
22-
| `SortedSet` | `ImmutableSortedSet<'T>` | – |
22+
| `SortedSet` | `ImmutableSortedSet<'T>` | `sortedSet { }` |
2323
| `ISet` | `IImmutableSet<'T>` | – |
2424
| `IIndexedSeq` | `IReadOnlyList<'T>` | – |
2525

‎docsSrc/Explanations/Background.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ While F# has its own built-in immutable collections, System.Collections.Immutabl
3333
| `HashMap` | `ImmutableDictionary<'Key, 'Value>` | – |
3434
| `SortedMap` | `ImmutableSortedDictionary<'Key, 'Value>` | – |
3535
| `HashSet` | `ImmutableHashSet<'T>` | `hashSet { }` |
36-
| `SortedSet` | `ImmutableSortedSet<'T>` | – |
36+
| `SortedSet` | `ImmutableSortedSet<'T>` | `sortedSet { }` |
3737
| `ISet` | `IImmutableSet<'T>` | – |
3838
| `IIndexedSeq` | `IReadOnlyList<'T>` | – |
3939

‎docsSrc/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ F# bindings for [System.Collections.Immutable](https://learn.microsoft.com/en-us
1515
| `HashMap` | `ImmutableDictionary<'Key, 'Value>` | – |
1616
| `SortedMap` | `ImmutableSortedDictionary<'Key, 'Value>` | – |
1717
| `HashSet` | `ImmutableHashSet<'T>` | `hashSet { }` |
18-
| `SortedSet` | `ImmutableSortedSet<'T>` | – |
18+
| `SortedSet` | `ImmutableSortedSet<'T>` | `sortedSet { }` |
1919
| `ISet` | `IImmutableSet<'T>` | – |
2020
| `IIndexedSeq` | `IReadOnlyList<'T>` | – |
2121

0 commit comments

Comments
 (0)