[llvm] [ADT][docs] Document SortedVectorMap in ProgrammersManual (NFC) (PR #215930)

[Kazu Hirata via llvm-commits]

https://github.com/kazutakahirata updated https://github.com/llvm/llvm-project/pull/215930

>From 8a842f5714c04c5752e1318563d0a201ee8de3cf Mon Sep 17 00:00:00 2001
From: Kazu Hirata <kazu at google.com>
Date: Wed, 12 Aug 2026 17:29:10 -0700
Subject: [PATCH 1/2] [ADT][docs] Document SortedVectorMap in ProgrammersManual
 (NFC)

This patch adds a section for SortedVectorMap in the Programmer's
Manual, detailing its intended use cases (small maps, minimal memory
overhead vs DenseMap, iteration in sorted key order) and trade-offs
(O(log N) binary search lookup and O(N) insertion/deletion vs O(1) in
DenseMap).

We also add a cross-reference from the existing "A sorted 'vector'"
section.
---
 llvm/docs/ProgrammersManual.md | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/llvm/docs/ProgrammersManual.md b/llvm/docs/ProgrammersManual.md
index 04d5bb273f686..628b8a337a599 100644
--- a/llvm/docs/ProgrammersManual.md
+++ b/llvm/docs/ProgrammersManual.md
@@ -2189,7 +2189,31 @@ If your usage pattern follows a strict insert-then-query approach, you can
 trivially use the same approach as {ref}`sorted vectors for set-like containers <dss_sortedvectorset>`.  The only difference is that your query function (which
 uses `std::lower_bound` to get efficient log(n) lookup) should only compare the
 key, not both the key and value.  This yields the same advantages as sorted
-vectors for sets.
+vectors for sets.  If you need a map-like container with incremental insertions
+backed by a sorted vector, see {ref}`SortedVectorMap <dss_sortedvectormap_class>`.
+
+(dss_sortedvectormap_class)=
+
+#### llvm/ADT/SortedVectorMap.h
+
+`SortedVectorMap<KeyT, ValueT, N, KeyCompare>` is a map backed by a sorted
+`SmallVector`. It provides a `std::map`-like interface with $O(\log N)$ binary
+search lookup while maintaining contiguous memory layout and cache locality.
+
+`SortedVectorMap` is intended for:
+- Small maps where memory footprint is a primary concern. In particular, it
+  avoids the initial bucket overhead of `DenseMap` (e.g. 64 buckets by default)
+  when only a few elements are stored.
+- Use cases that require iteration in sorted key order.
+
+Trade-offs:
+- Lookups take $O(\log N)$ time via binary search rather than $O(1)$ in `DenseMap`.
+- Insertions and deletions take $O(N)$ time due to shifting elements in the
+  underlying vector, making it best suited for small $N$ or mostly-read data.
+- Compared to `std::map`, elements are stored contiguously, eliminating per-node
+  heap allocations and pointer chasing.
+- Compared to `MapVector`, elements are ordered by key rather than insertion
+  order, with zero auxiliary hash table overhead.
 
 (dss_stringmap)=
 

>From 341eb56ded2ce390f30228141ed571745db0baaf Mon Sep 17 00:00:00 2001
From: Kazu Hirata <kazu at google.com>
Date: Wed, 12 Aug 2026 19:25:33 -0700
Subject: [PATCH 2/2] Address comments.

---
 llvm/docs/ProgrammersManual.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/llvm/docs/ProgrammersManual.md b/llvm/docs/ProgrammersManual.md
index 628b8a337a599..16f24d6565fad 100644
--- a/llvm/docs/ProgrammersManual.md
+++ b/llvm/docs/ProgrammersManual.md
@@ -2210,6 +2210,9 @@ Trade-offs:
 - Lookups take $O(\log N)$ time via binary search rather than $O(1)$ in `DenseMap`.
 - Insertions and deletions take $O(N)$ time due to shifting elements in the
   underlying vector, making it best suited for small $N$ or mostly-read data.
+- Like other vector-based containers (and unlike `std::map`), iterators and
+  references are invalidated by insertions (due to element shifting or
+  reallocations) and erasures (due to element shifting).
 - Compared to `std::map`, elements are stored contiguously, eliminating per-node
   heap allocations and pointer chasing.
 - Compared to `MapVector`, elements are ordered by key rather than insertion