[2026-06 LWG Motion 16] P3091R6 Better Lookups for map, unordered_map, and flat_map

source/containers.tex

@@ -11731,6 +11731,10 @@
     constexpr const mapped_type& at(const key_type& x) const;
     template<class K> constexpr mapped_type&       at(const K& x);
     template<class K> constexpr const mapped_type& at(const K& x) const;
+    constexpr optional<mapped_type&>       lookup(const key_type& x);
+    constexpr optional<const mapped_type&> lookup(const key_type& x) const;
+    template<class K> constexpr optional<mapped_type&>       lookup(const K& x);
+    template<class K> constexpr optional<const mapped_type&> lookup(const K& x) const;
 
     // \ref{map.modifiers}, modifiers
     template<class... Args> constexpr pair<iterator, bool> emplace(Args&&... args);
@@ -12020,6 +12024,35 @@
 Logarithmic.
 \end{itemdescr}
 
+\indexlibrarymember{lookup}{map}%
+\begin{itemdecl}
+constexpr optional<mapped_type&>       lookup(const key_type& x);
+constexpr optional<const mapped_type&> lookup(const key_type& x) const;
+template<class K> constexpr optional<mapped_type&>       lookup(const K& x);
+template<class K> constexpr optional<const mapped_type&> lookup(const K& x) const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+For the third and fourth overloads,
+the \grammarterm{qualified-id} \tcode{Compare::is_transparent}
+is valid and denotes a type.
+
+\pnum
+\expects
+The expression \tcode{find(x)} is well-formed and has well-defined behavior.
+
+\pnum
+\returns
+\tcode{find(x)->second} if \tcode{contains(x)} is \tcode{true},
+otherwise \tcode{nullopt}.
+
+\pnum
+\complexity
+Logarithmic.
+\end{itemdescr}
+
 \rSec3[map.modifiers]{Modifiers}
 
 \indexlibrarymember{insert}{map}%
@@ -13761,6 +13794,10 @@
     constexpr const mapped_type& at(const key_type& k) const;
     template<class K> constexpr mapped_type& at(const K& k);
     template<class K> constexpr const mapped_type& at(const K& k) const;
+    constexpr optional<mapped_type&>       lookup(const key_type& k);
+    constexpr optional<const mapped_type&> lookup(const key_type& k) const;
+    template<class K> constexpr optional<mapped_type&>       lookup(const K& k);
+    template<class K> constexpr optional<const mapped_type&> lookup(const K& k) const;
 
     // bucket interface
     constexpr size_type bucket_count() const noexcept;
@@ -14005,6 +14042,37 @@
 if \tcode{find(k) == end()} is \tcode{true}.
 \end{itemdescr}
 
+\indexlibrarymember{lookup}{unordered_map}%
+\begin{itemdecl}
+constexpr optional<mapped_type&>       lookup(const key_type& k);
+constexpr optional<const mapped_type&> lookup(const key_type& k) const;
+template<class K> constexpr optional<mapped_type&>       lookup(const K& k);
+template<class K> constexpr optional<const mapped_type&> lookup(const K& k) const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+For the third and fourth overloads,
+the \grammarterm{qualified-id}s
+\tcode{Hash::is_transparent} and \linebreak
+\tcode{Pred::is_transparent}
+are valid and denote types.
+
+\pnum
+\expects
+The expression \tcode{find(k)} is well-formed and has well-defined behavior.
+
+\pnum
+\returns
+\tcode{find(k)->second} if \tcode{contains(k)} is \tcode{true},
+otherwise \tcode{nullopt}.
+
+\pnum
+\complexity
+Average case constant, worst case linear in \tcode{size()}.
+\end{itemdescr}
+
 \rSec3[unord.map.modifiers]{Modifiers}
 
 \indexlibrarymember{unordered_map}{insert}%
@@ -17364,6 +17432,10 @@
     constexpr const mapped_type& at(const key_type& x) const;
     template<class K> constexpr mapped_type& at(const K& x);
     template<class K> constexpr const mapped_type& at(const K& x) const;
+    constexpr optional<mapped_type&>       lookup(const key_type& x);
+    constexpr optional<const mapped_type&> lookup(const key_type& x) const;
+    template<class K> constexpr optional<mapped_type&>       lookup(const K& x);
+    template<class K> constexpr optional<const mapped_type&> lookup(const K& x) const;
 
     // \ref{flat.map.modifiers}, modifiers
     template<class... Args> constexpr pair<iterator, bool> emplace(Args&&... args);
@@ -17827,6 +17899,35 @@
 Logarithmic.
 \end{itemdescr}
 
+\indexlibrarymember{lookup}{flat_map}%
+\begin{itemdecl}
+constexpr optional<mapped_type&>       lookup(const key_type& x);
+constexpr optional<const mapped_type&> lookup(const key_type& x) const;
+template<class K> constexpr optional<mapped_type&>       lookup(const K& x);
+template<class K> constexpr optional<const mapped_type&> lookup(const K& x) const;
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\constraints
+For the third and fourth overloads,
+the \grammarterm{qualified-id} \tcode{Compare::is_transparent}
+is valid and denotes a type.
+
+\pnum
+\expects
+The expression \tcode{find(x)} is well-formed and has well-defined behavior.
+
+\pnum
+\returns
+\tcode{find(x)->second} if \tcode{contains(x)} is \tcode{true},
+otherwise \tcode{nullopt}.
+
+\pnum
+\complexity
+Logarithmic.
+\end{itemdescr}
+
 \rSec3[flat.map.modifiers]{Modifiers}
 
 \indexlibrarymember{emplace}{flat_map}%

source/support.tex

@@ -763,6 +763,8 @@
 #define @\defnlibxname{cpp_lib_make_from_tuple}@                   201606L // freestanding, also in \libheader{tuple}
 #define @\defnlibxname{cpp_lib_make_reverse_iterator}@             201402L // freestanding, also in \libheader{iterator}
 #define @\defnlibxname{cpp_lib_make_unique}@                       201304L // also in \libheader{memory}
+#define @\defnlibxname{cpp_lib_map_lookup}@                        202606L
+  // also in \libheader{map}, \libheader{unordered_map}, \libheader{flat_map}
 #define @\defnlibxname{cpp_lib_map_try_emplace}@                   201411L // also in \libheader{map}
 #define @\defnlibxname{cpp_lib_math_constants}@                    201907L // also in \libheader{numbers}
 #define @\defnlibxname{cpp_lib_math_special_functions}@            201603L // also in \libheader{cmath}