@@ -27,14 +27,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   value, as `ImmutableArray<'T>.Builder.Replace` does, where `FlatList.replace` throws `ArgumentException`.
 * `flatList { }` builds a flat list.
 * `HashSet` has every function of the FSharp.Core `Set` module that applies to a hash set, with its semantics, argument
-  order and exceptions, plus `builder`, `choose`, `clear`, `comparer`, `forComparer`, `ofBuilder`, `overlaps`, `setEquals`,
-  `symmetricDifference`, `toBuilder` and `tryGetValue`.
-* `HashSet.forComparer comparer` creates the `CustomComparerHashSet` struct, whose members `empty`, `ofArray`, `ofList`,
-  `ofSeq`, `singleton` and `builder` create hash sets and builders that compare with the comparer, as in
-  `(HashSet.forComparer StringComparer.OrdinalIgnoreCase).ofSeq names`. `ofSeq` also gives an existing hash set the
-  comparer. A `null` comparer throws `ArgumentNullException`.
+  order and exceptions, plus `addRange`, `build`, `builder`, `choose`, `clear`, `comparer`, `forComparer`, `ofBuilder`,
+  `ofReadOnlySpan`, `ofSpan`, `overlaps`, `removeRange`, `setEquals`, `symmetricDifference`, `toBuilder`, `tryGetValue`
+  and `update`.
+* `HashSet.addRange elements set` and `removeRange elements set` wrap the `Union` and `Except` members that take a
+  sequence. The result keeps the comparer of the hash set, an element of the sequence that the comparer finds equal to
+  an element of the hash set does not replace it, and the input itself comes back when nothing changes.
+* `HashSet.ofReadOnlySpan` and `ofSpan` create a hash set from a span, `build` fills a builder with an action, and
+  `update` applies an action to a builder of a hash set and returns its contents, so that the in-place operations of the
+  builder, such as `IntersectWith`, are one expression.
+* `HashSet.forComparer comparer` creates the `CustomComparerHashSet` struct, whose members `build`, `builder`, `empty`,
+  `ofArray`, `ofList`, `ofReadOnlySpan`, `ofSeq`, `ofSpan` and `singleton` create hash sets and builders that compare
+  with the comparer, as in `(HashSet.forComparer StringComparer.OrdinalIgnoreCase).ofSeq names`. They replace the BCL
+  members `Create(comparer, ...)`, `CreateRange(comparer, items)` and `CreateBuilder(comparer)`. `ofSeq` also gives an
+  existing hash set the comparer, as `WithComparer` does: the hash set itself comes back for the same comparer
+  instance, and an equal but distinct instance rebuilds it. `WithComparer(null)` is `HashSet.ofSeq set`. A `null`
+  comparer throws `ArgumentNullException`.
+* `HashSet.add` and `remove` return the input itself when nothing changes, so a reference comparison of the input and
+  the result tells whether `Add` changed anything, as the `bool` result of `Builder.Add` does. Hash sets have no builder
+  module: `builder`, `toBuilder` and `ofBuilder` are `CreateBuilder`, `ToBuilder` and `ToImmutable`, and the builder is
+  used directly.
 * The `ISet` module works on any `IImmutableSet<'T>` with the functions of `HashSet` that need neither a creation nor a
-  comparer; the transformations that keep the element type return the implementation of their input.
+  comparer, `addRange` and `removeRange` included; the transformations that keep the element type return the
+  implementation of their input.
 * The `FSharp.Collections.Immutable.Option.HashSet`, `FSharp.Collections.Immutable.Tuple.HashSet`,
   `FSharp.Collections.Immutable.Option.ISet` and `FSharp.Collections.Immutable.Tuple.ISet` modules repeat `choose` and
   `tryGetValue` with options, and `partition` and `partitionWith` with reference tuples.
@@ -54,8 +69,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * `FlatList.sub` has the meaning of `Array.sub`: `sub array startIndex count` returns `count` elements from `startIndex`.
   It was `sub start stop list`.
 * The nested `FlatList.Builder` module is now the `FlatListBuilder` module.
-* `HashSet`: `difference set1 set2` returns the elements of `set1` that are not in `set2`, as `Set.difference` does; it
-  took its arguments in the reverse order before.
+* `HashSet`: `difference set1 set2` returns the elements of `set1` that are not in `set2`, as `Set.difference` does. In
+  1.0.0 `difference values set` removed a sequence from a hash set: that is `removeRange values set` now, with the same
+  order of the arguments. `union set values` of 1.0.0 is `addRange values set`.
+* `HashSet`: `union`, `intersect`, `isSubset`, `isProperSubset`, `isSuperset` and `isProperSuperset` took a sequence as
+  the second argument in 1.0.0 and take a hash set now, as the `Set` functions do: pass `HashSet.ofSeq elements`, or
+  `(HashSet.forComparer (HashSet.comparer set)).ofSeq elements` to give the elements the comparer of the first hash
+  set. The BCL members that take a sequence map the same way: `Union` and `Except` are `addRange` and `removeRange`,
+  `Overlaps` and `IsSupersetOf` are `Seq.exists` and `Seq.forall` with `contains`, and the others take `ofSeq` of the
+  sequence.
+* `HashSet`: the element that stays when the comparer finds two elements equal follows the BCL: `union` and `addRange`
+  keep the element of the first hash set, `intersect` keeps the elements of the second one, and the creation functions
+  keep the first element of their input. `isProperSuperset` counts the elements of the second hash set that the
+  comparer of the first one finds equal once, where `ImmutableHashSet.IsProperSupersetOf` counts each of them, against
+  its documentation.
+* `HashSet`: the compiled name of the module is `HashSet`, which C# callers see; it was `ImmutableHashSetModule`.
 * `HashSet`: `length` is renamed to `count` and `keyComparer` to `comparer`.
 * `HashSet`: `filter`, `partition` and the set algebra keep the comparer of their input, the set algebra that of the first
   set; `map`, `choose` and `partitionWith` compare with the default comparer of the result type. `filter` dropped the
@@ -84,10 +112,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * The `ISet<'T>` abbreviation of `IImmutableSet<'T>`, because it shadowed `System.Collections.Generic.ISet<'T>`: use
   `IImmutableSet<'T>` and the `ISet` module.
 * The `HashSetBuilder<'T>` abbreviation: use `HashSet<'T>.Builder`.
-* `HashSet.where`: use `filter`. `HashSet.pick`, `tryPick` and `vTryPick`: use `Seq.pick` and `Seq.tryPick`. The public
+* `HashSet.where`: use `filter`. `HashSet.pick`, `tryPick` and `vTryPick`, which the FSharp.Core `Set` module does not
+  have: use `HashSet.toSeq set |> Seq.pick chooser`, or `Seq.tryPick` and `ValueOption.ofOption`. The public
   `HashSet.check`.
-* `HashSet.ofComparer`, `ofSeqWithComparer`, `builderWithComparer` and `builderWith`, which took a comparer despite its
-  name: use the members `empty`, `ofSeq` and `builder` of `HashSet.forComparer comparer`.
+* `HashSet.ofComparer comparer`, `ofSeqWithComparer comparer elements` and `builderWithComparer comparer`: use
+  `(HashSet.forComparer comparer).empty`, `(HashSet.forComparer comparer).ofSeq elements` and
+  `(HashSet.forComparer comparer).builder ()`. `HashSet.builderWith`, whose argument bound to the comparer overload of
+  the BCL member, has no replacement: hash sets have no capacity.
 
 ## [1.0.0] - 2020-02-23