Release 0.5.9

.github/workflows/ci.yml

@@ -27,6 +27,8 @@ jobs:
             features: rayon
           - rust: stable
             features: serde
+          - rust: stable
+            features: sval
           - rust: stable
             features: borsh
           - rust: stable
@@ -62,6 +64,10 @@ jobs:
         if: matrix.features == 'serde'
         run: |
           cargo test --verbose -p test-serde
+      - name: Tests (sval)
+        if: matrix.features == 'sval'
+        run: |
+          cargo test --verbose -p test-sval
       - name: Test run benchmarks
         if: matrix.bench != ''
         run: cargo test -v --benches
@@ -141,7 +147,7 @@ jobs:
       - name: Build (nightly)
         run: cargo +nightly build --verbose --all-features
       - name: Build (MSRV)
-        run: cargo build --verbose --features arbitrary,quickcheck,serde,rayon
+        run: cargo build --verbose --features arbitrary,quickcheck,serde,sval,rayon
 
   # One job that "summarizes" the success state of this pipeline. This can then be added to branch
   # protection, rather than having to add each job separately.

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "ordermap"
 edition = "2021"
-version = "0.5.8"
+version = "0.5.9"
 documentation = "https://docs.rs/ordermap/"
 repository = "https://github.com/indexmap-rs/ordermap"
 license = "Apache-2.0 OR MIT"
@@ -14,13 +14,14 @@ rust-version = "1.63"
 bench = false
 
 [dependencies]
-indexmap = { version = "2.10.0", default-features = false }
+indexmap = { version = "2.11.0", default-features = false }
 
 arbitrary = { version = "1.0", optional = true, default-features = false }
 quickcheck = { version = "1.0", optional = true, default-features = false }
 serde = { version = "1.0", optional = true, default-features = false }
 borsh = { version = "1.5.6", optional = true, default-features = false }
 rayon = { version = "1.9", optional = true }
+sval = { version = "2", optional = true, default-features = false }
 
 [dev-dependencies]
 itertools = "0.14"
@@ -37,6 +38,7 @@ arbitrary = ["dep:arbitrary", "indexmap/arbitrary"]
 quickcheck = ["dep:quickcheck", "indexmap/quickcheck"]
 rayon = ["dep:rayon", "indexmap/rayon"]
 serde = ["dep:serde", "indexmap/serde"]
+sval = ["dep:sval", "indexmap/sval"]
 borsh = ["dep:borsh", "borsh/indexmap"]
 
 [profile.bench]
@@ -48,11 +50,11 @@ sign-tag = true
 tag-name = "{{version}}"
 
 [package.metadata.docs.rs]
-features = ["arbitrary", "quickcheck", "serde", "borsh", "rayon"]
+features = ["arbitrary", "quickcheck", "serde", "borsh", "rayon", "sval"]
 rustdoc-args = ["--cfg", "docsrs"]
 
 [workspace]
-members = ["test-nostd", "test-serde"]
+members = ["test-nostd", "test-serde", "test-sval"]
 
 [lints.clippy]
 style = "allow"

RELEASES.md

@@ -1,5 +1,17 @@
 # Releases
 
+## 0.5.9 (2025-08-22)
+
+- Added `insert_sorted_by` and `insert_sorted_by_key` methods to `OrderMap`,
+  `OrderSet`, and `VacantEntry`, like customizable versions of `insert_sorted`.
+- Added `is_sorted`, `is_sorted_by`, and `is_sorted_by_key` methods to
+  `OrderMap` and `OrderSet`, as well as their `Slice` counterparts.
+- Added `sort_by_key` and `sort_unstable_by_key` methods to `OrderMap` and
+  `OrderSet`, as well as parallel counterparts.
+- Added `replace_index` methods to `OrderMap`, `OrderSet`, and `VacantEntry`
+  to replace the key (or set value) at a given index.
+- Added optional `sval` serialization support.
+
 ## 0.5.8 (2025-06-26)
 
 - Added `extract_if` methods to `OrderMap` and `OrderSet`, similar to the

src/lib.rs

@@ -110,6 +110,8 @@ mod macros;
 mod borsh;
 #[cfg(feature = "serde")]
 mod serde;
+#[cfg(feature = "sval")]
+mod sval;
 
 pub mod map;
 pub mod set;

src/map.rs

@@ -466,6 +466,51 @@ where
         self.inner.insert_sorted(key, value)
     }
 
+    /// Insert a key-value pair in the map at its ordered position among keys
+    /// sorted by `cmp`.
+    ///
+    /// This is equivalent to finding the position with
+    /// [`binary_search_by`][Self::binary_search_by], then calling
+    /// [`insert_before`][Self::insert_before] with the given key and value.
+    ///
+    /// If the existing keys are **not** already sorted, then the insertion
+    /// index is unspecified (like [`slice::binary_search`]), but the key-value
+    /// pair is moved to or inserted at that position regardless.
+    ///
+    /// Computes in **O(n)** time (average).
+    pub fn insert_sorted_by<F>(&mut self, key: K, value: V, cmp: F) -> (usize, Option<V>)
+    where
+        K: Ord,
+        F: FnMut(&K, &V, &K, &V) -> Ordering,
+    {
+        self.inner.insert_sorted_by(key, value, cmp)
+    }
+
+    /// Insert a key-value pair in the map at its ordered position
+    /// using a sort-key extraction function.
+    ///
+    /// This is equivalent to finding the position with
+    /// [`binary_search_by_key`][Self::binary_search_by_key] with `sort_key(key)`, then
+    /// calling [`insert_before`][Self::insert_before] with the given key and value.
+    ///
+    /// If the existing keys are **not** already sorted, then the insertion
+    /// index is unspecified (like [`slice::binary_search`]), but the key-value
+    /// pair is moved to or inserted at that position regardless.
+    ///
+    /// Computes in **O(n)** time (average).
+    pub fn insert_sorted_by_key<B, F>(
+        &mut self,
+        key: K,
+        value: V,
+        sort_key: F,
+    ) -> (usize, Option<V>)
+    where
+        B: Ord,
+        F: FnMut(&K, &V) -> B,
+    {
+        self.inner.insert_sorted_by_key(key, value, sort_key)
+    }
+
     /// Insert a key-value pair in the map before the entry at the given index, or at the end.
     ///
     /// If an equivalent key already exists in the map: the key remains and
@@ -581,7 +626,27 @@ where
         self.inner.shift_insert(index, key, value)
     }
 
-    /// Get the given key’s corresponding entry in the map for insertion and/or
+    /// Replaces the key at the given index. The new key does not need to be
+    /// equivalent to the one it is replacing, but it must be unique to the rest
+    /// of the map.
+    ///
+    /// Returns `Ok(old_key)` if successful, or `Err((other_index, key))` if an
+    /// equivalent key already exists at a different index. The map will be
+    /// unchanged in the error case.
+    ///
+    /// Direct indexing can be used to change the corresponding value: simply
+    /// `map[index] = value`, or `mem::replace(&mut map[index], value)` to
+    /// retrieve the old value as well.
+    ///
+    /// ***Panics*** if `index` is out of bounds.
+    ///
+    /// Computes in **O(1)** time (average).
+    #[track_caller]
+    pub fn replace_index(&mut self, index: usize, key: K) -> Result<K, (usize, K)> {
+        self.inner.replace_index(index, key)
+    }
+
+    /// Get the given key's corresponding entry in the map for insertion and/or
     /// in-place manipulation.
     ///
     /// Computes in **O(1)** time (amortized average).
@@ -869,7 +934,7 @@ impl<K, V, S> OrderMap<K, V, S> {
         self.inner.retain(keep);
     }
 
-    /// Sort the map’s key-value pairs by the default ordering of the keys.
+    /// Sort the map's key-value pairs by the default ordering of the keys.
     ///
     /// This is a stable sort -- but equivalent keys should not normally coexist in
     /// a map at all, so [`sort_unstable_keys`][Self::sort_unstable_keys] is preferred
@@ -883,7 +948,7 @@ impl<K, V, S> OrderMap<K, V, S> {
         self.inner.sort_keys();
     }
 
-    /// Sort the map’s key-value pairs in place using the comparison
+    /// Sort the map's key-value pairs in place using the comparison
     /// function `cmp`.
     ///
     /// The comparison function receives two key and value pairs to compare (you
@@ -909,6 +974,18 @@ impl<K, V, S> OrderMap<K, V, S> {
         self.inner.sorted_by(cmp)
     }
 
+    /// Sort the map's key-value pairs in place using a sort-key extraction function.
+    ///
+    /// Computes in **O(n log n + c)** time and **O(n)** space where *n* is
+    /// the length of the map and *c* the capacity. The sort is stable.
+    pub fn sort_by_key<T, F>(&mut self, sort_key: F)
+    where
+        T: Ord,
+        F: FnMut(&K, &V) -> T,
+    {
+        self.inner.sort_by_key(sort_key)
+    }
+
     /// Sort the map's key-value pairs by the default ordering of the keys, but
     /// may not preserve the order of equal elements.
     ///
@@ -947,7 +1024,19 @@ impl<K, V, S> OrderMap<K, V, S> {
         self.inner.sorted_unstable_by(cmp)
     }
 
-    /// Sort the map’s key-value pairs in place using a sort-key extraction function.
+    /// Sort the map's key-value pairs in place using a sort-key extraction function.
+    ///
+    /// Computes in **O(n log n + c)** time where *n* is
+    /// the length of the map and *c* is the capacity. The sort is unstable.
+    pub fn sort_unstable_by_key<T, F>(&mut self, sort_key: F)
+    where
+        T: Ord,
+        F: FnMut(&K, &V) -> T,
+    {
+        self.inner.sort_unstable_by_key(sort_key)
+    }
+
+    /// Sort the map's key-value pairs in place using a sort-key extraction function.
     ///
     /// During sorting, the function is called at most once per entry, by using temporary storage
     /// to remember the results of its evaluation. The order of calls to the function is
@@ -1006,6 +1095,34 @@ impl<K, V, S> OrderMap<K, V, S> {
         self.inner.binary_search_by_key(b, f)
     }
 
+    /// Checks if the keys of this map are sorted.
+    #[inline]
+    pub fn is_sorted(&self) -> bool
+    where
+        K: PartialOrd,
+    {
+        self.inner.is_sorted()
+    }
+
+    /// Checks if this map is sorted using the given comparator function.
+    #[inline]
+    pub fn is_sorted_by<'a, F>(&'a self, cmp: F) -> bool
+    where
+        F: FnMut(&'a K, &'a V, &'a K, &'a V) -> bool,
+    {
+        self.inner.is_sorted_by(cmp)
+    }
+
+    /// Checks if this map is sorted using the given sort-key function.
+    #[inline]
+    pub fn is_sorted_by_key<'a, F, T>(&'a self, sort_key: F) -> bool
+    where
+        F: FnMut(&'a K, &'a V) -> T,
+        T: PartialOrd,
+    {
+        self.inner.is_sorted_by_key(sort_key)
+    }
+
     /// Returns the index of the partition point of a sorted map according to the given predicate
     /// (the index of the first element of the second partition).
     ///
@@ -1020,7 +1137,7 @@ impl<K, V, S> OrderMap<K, V, S> {
         self.inner.partition_point(pred)
     }
 
-    /// Reverses the order of the map’s key-value pairs in place.
+    /// Reverses the order of the map's key-value pairs in place.
     ///
     /// Computes in **O(n)** time and **O(1)** space.
     pub fn reverse(&mut self) {

src/map/entry.rs

@@ -1,3 +1,4 @@
+use core::cmp::Ordering;
 use core::fmt;
 use indexmap::map as ix;
 
@@ -326,6 +327,40 @@ impl<'a, K, V> VacantEntry<'a, K, V> {
         self.inner.insert_sorted(value)
     }
 
+    /// Inserts the entry's key and the given value into the map at its ordered
+    /// position among keys sorted by `cmp`, and returns the new index and a
+    /// mutable reference to the value.
+    ///
+    /// If the existing keys are **not** already sorted, then the insertion
+    /// index is unspecified (like [`slice::binary_search`]), but the key-value
+    /// pair is inserted at that position regardless.
+    ///
+    /// Computes in **O(n)** time (average).
+    pub fn insert_sorted_by<F>(self, value: V, cmp: F) -> (usize, &'a mut V)
+    where
+        K: Ord,
+        F: FnMut(&K, &V, &K, &V) -> Ordering,
+    {
+        self.inner.insert_sorted_by(value, cmp)
+    }
+
+    /// Inserts the entry's key and the given value into the map at its ordered
+    /// position using a sort-key extraction function, and returns the new index
+    /// and a mutable reference to the value.
+    ///
+    /// If the existing keys are **not** already sorted, then the insertion
+    /// index is unspecified (like [`slice::binary_search`]), but the key-value
+    /// pair is inserted at that position regardless.
+    ///
+    /// Computes in **O(n)** time (average).
+    pub fn insert_sorted_by_key<B, F>(self, value: V, sort_key: F) -> (usize, &'a mut V)
+    where
+        B: Ord,
+        F: FnMut(&K, &V) -> B,
+    {
+        self.inner.insert_sorted_by_key(value, sort_key)
+    }
+
     /// Inserts the entry's key and the given value into the map at the given index,
     /// shifting others to the right, and returns a mutable reference to the value.
     ///
@@ -336,6 +371,18 @@ impl<'a, K, V> VacantEntry<'a, K, V> {
     pub fn shift_insert(self, index: usize, value: V) -> &'a mut V {
         self.inner.shift_insert(index, value)
     }
+
+    /// Replaces the key at the given index with this entry's key, returning the
+    /// old key and an `OccupiedEntry` for that index.
+    ///
+    /// ***Panics*** if `index` is out of bounds.
+    ///
+    /// Computes in **O(1)** time (average).
+    #[track_caller]
+    pub fn replace_index(self, index: usize) -> (K, OccupiedEntry<'a, K, V>) {
+        let (old_key, inner) = self.inner.replace_index(index);
+        (old_key, OccupiedEntry { inner })
+    }
 }
 
 impl<K: fmt::Debug, V> fmt::Debug for VacantEntry<'_, K, V> {

src/map/mutable.rs

@@ -8,7 +8,7 @@ use indexmap::map::MutableKeys as _;
 /// These methods expose `&mut K`, mutable references to the key as it is stored
 /// in the map.
 /// You are allowed to modify the keys in the map **if the modification
-/// does not change the key’s hash and equality**.
+/// does not change the key's hash and equality**.
 ///
 /// If keys are modified erroneously, you can no longer look them up.
 /// This is sound (memory safe) but a logical error hazard (just like
@@ -88,7 +88,7 @@ where
 /// These methods expose `&mut K`, mutable references to the key as it is stored
 /// in the map.
 /// You are allowed to modify the keys in the map **if the modification
-/// does not change the key’s hash and equality**.
+/// does not change the key's hash and equality**.
 ///
 /// If keys are modified erroneously, you can no longer look them up.
 /// This is sound (memory safe) but a logical error hazard (just like