Prepare release 0.2.21 (#575)

Author: sjakobi

CHANGES.md

@@ -1,3 +1,36 @@
+## [0.2.21] - December 2025
+
+* API enhancements:
+  * [Add `HashMap.lookupKey` and `HashSet.lookupElement`](https://github.com/haskell-unordered-containers/unordered-containers/pull/554)
+  * [Add `differenceWithKey`](https://github.com/haskell-unordered-containers/unordered-containers/pull/542)
+  * [Add `disjoint`](https://github.com/haskell-unordered-containers/unordered-containers/pull/559)
+
+* Performance improvements:
+  * [`HashSet.fromList`: Use `unsafeInsert`](https://github.com/haskell-unordered-containers/unordered-containers/pull/515)
+  * [Use tree-diffing for `difference`](https://github.com/haskell-unordered-containers/unordered-containers/pull/535)
+  * [Remove some unnecessary forcing of HashMaps](https://github.com/haskell-unordered-containers/unordered-containers/pull/545)
+  * [Remove the `Array.index` function](https://github.com/haskell-unordered-containers/unordered-containers/pull/539)
+  * [`hashWithSalt`: Ensure that the salt `Int` is unboxed](https://github.com/haskell-unordered-containers/unordered-containers/pull/569)
+
+* Documentation changes:
+  * [Turn some comments into docstrings](https://github.com/haskell-unordered-containers/unordered-containers/pull/516)
+  * [Reword disclaimer regarding hash collision attacks](https://github.com/haskell-unordered-containers/unordered-containers/pull/557)
+  * [Update time complexity of some HashSet functions](https://github.com/haskell-unordered-containers/unordered-containers/pull/568)
+  * [Update instructions for code inspection](https://github.com/haskell-unordered-containers/unordered-containers/pull/567)
+
+* Other changes:
+  * [Drop support for GHC < 8.10](https://github.com/haskell-unordered-containers/unordered-containers/pull/510)
+  * [Address deprecation warnings and other warnings](https://github.com/haskell-unordered-containers/unordered-containers/pull/512)
+  * [Optimize indexing in arrays of length 2](https://github.com/haskell-unordered-containers/unordered-containers/pull/528)
+  * [Introduce `ShiftedHash`](https://github.com/haskell-unordered-containers/unordered-containers/pull/529)
+  * [New "fine-grained" benchmarks](https://github.com/haskell-unordered-containers/unordered-containers/pull/526)
+  * [Make it compile with MicroHs](https://github.com/haskell-unordered-containers/unordered-containers/pull/553). Thanks, @augustss!
+  * [Remove redundant `Eq` constraints](https://github.com/haskell-unordered-containers/unordered-containers/pull/558)
+  * [Refactor `delete`](https://github.com/haskell-unordered-containers/unordered-containers/pull/571)
+  * [`difference[With]`: Undo constraint relaxation](https://github.com/haskell-unordered-containers/unordered-containers/pull/573)
+
+[0.2.21]: https://github.com/haskell-unordered-containers/unordered-containers/compare/v0.2.20.1...v0.2.21
+
 ## [0.2.20.1] - October 2025
 
 * [Fix infinite loop in `isSubmapOf[By]` / `isSubsetOf` on 32-bit platforms](https://github.com/haskell-unordered-containers/unordered-containers/pull/501).

Data/HashMap/Internal.hs

@@ -790,6 +790,8 @@ infixl 9 !
 -- if present, otherwise return 'Nothing'.
 --
 -- This function can be used for /interning/, i.e. to reduce memory usage.
+--
+-- @since 0.2.21
 lookupKey :: Hashable k => k -> HashMap k v -> Maybe k
 lookupKey k = \m -> fromMaybe# (lookupKeyInSubtree# 0 (hash k) k m)
   where
@@ -1972,6 +1974,8 @@ differenceWith f = differenceWithKey (const f)
 -- encountered, the combining function is applied to the values of these keys.
 -- If it returns 'Nothing', the element is discarded (proper set difference). If
 -- it returns (@'Just' y@), the element is updated with a new value @y@.
+--
+-- @since 0.2.21
 differenceWithKey :: Eq k => (k -> v -> w -> Maybe v) -> HashMap k v -> HashMap k w -> HashMap k v
 differenceWithKey f = go_differenceWithKey 0
   where
@@ -2323,7 +2327,7 @@ searchSwap mary n toFind start = go start toFind start
 -- xs ``disjoint`` ys = null (xs ``intersection`` ys)
 -- @
 --
--- @since FIXME
+-- @since 0.2.21
 disjoint :: Eq k => HashMap k a -> HashMap k b -> Bool
 disjoint = disjointSubtrees 0
 {-# INLINE disjoint #-}

Data/HashMap/Internal/Strict.hs

@@ -632,6 +632,8 @@ differenceWith f = HM.differenceWithKey $
 -- encountered, the combining function is applied to the values of these keys.
 -- If it returns 'Nothing', the element is discarded (proper set difference). If
 -- it returns (@'Just' y@), the element is updated with a new value @y@.
+--
+-- @since 0.2.21
 differenceWithKey :: Eq k => (k -> v -> w -> Maybe v) -> HashMap k v -> HashMap k w -> HashMap k v
 differenceWithKey f = HM.differenceWithKey $
   \k vA vB -> case f k vA vB of

Data/HashSet/Internal.hs

@@ -356,6 +356,8 @@ member a s = case H.lookup a (asMap s) of
 -- present, otherwise return 'Nothing'.
 --
 -- This is useful for /interning/, i.e. to reduce memory usage.
+--
+-- @since 0.2.21
 lookupElement :: Hashable a => a -> HashSet a -> Maybe a
 lookupElement a = H.lookupKey a . asMap
 {-# INLINE lookupElement #-}
@@ -412,7 +414,7 @@ intersection (HashSet a) (HashSet b) = HashSet (H.intersection a b)
 -- xs ``disjoint`` ys = null (xs ``intersection`` ys)
 -- @
 --
--- @since FIXME
+-- @since 0.2.21
 disjoint :: Eq k => HashSet k -> HashSet k -> Bool
 disjoint (HashSet a) (HashSet b) = H.disjoint a b
 {-# INLINE disjoint #-}

unordered-containers.cabal

@@ -1,5 +1,5 @@
 name:           unordered-containers
-version:        0.2.20.1
+version:        0.2.21
 synopsis:       Efficient hashing-based container types
 description:
   Efficient hashing-based container types.  The containers have been