documented [c]visit_(until|while)

doc/unordered/changes.adoc

@@ -6,6 +6,11 @@
 :github-pr-url: https://github.com/boostorg/unordered/pull
 :cpp: C++
 
+== Release 1.84.0
+
+* Added `[c]visit_until` and `[c]visit_while` operations to `boost::concurrent_map`,
+with serial and parallel variants.
+
 == Release 1.83.0 - Major update
 
 * Added `boost::concurrent_flat_map`, a fast, thread-safe hashmap based on open addressing.

doc/unordered/concurrent.adoc

@@ -154,7 +154,34 @@ m.visit_all(std::execution::par, [](auto& x) { // run in parallel
 });
 ----
 
-There is another whole-table visitation operation, `erase_if`:
+Traversal can be interrupted midway:
+
+[source,c++]
+----
+// finds the key to a given (unique value)
+
+int  key = 0;
+int  value = ...;
+bool found = m.visit_until([&](const auto& x) {
+  if(x.second == value) {
+    key = x.first;
+    return true;  // finish
+  }
+  else {
+    return false; // keep on visiting
+  }
+});
+
+if(found) { ... }
+
+// check if all values are != 0
+
+bool all_ok = m.visit_while([&](const auto& x) {
+  return x.second != 0;
+});
+----
+
+There is one last whole-table visitation operation, `erase_if`:
 
 [source,c++]
 ----
@@ -163,8 +190,8 @@ m.erase_if([](auto& x) {
 });
 ----
 
-`erase_if` can also be parallelized. Note that, in order to increase efficiency,
-these operations do not block the table during execution: this implies that elements
+`visit_until`, `visit_while` and `erase_if` can also be parallelized. Note that, in order to increase efficiency,
+whole-table visitation operations do not block the table during execution: this implies that elements
 may be inserted, modified or erased by other threads during visitation. It is
 advisable not to assume too much about the exact global state of a `boost::concurrent_flat_map`
 at any point in your program.

doc/unordered/concurrent_flat_map.adoc

@@ -114,6 +114,26 @@ namespace boost {
     template<class ExecutionPolicy, class F>
       void xref:#concurrent_flat_map_parallel_cvisit_all[cvisit_all](ExecutionPolicy&& policy, F f) const;
 
+    template<class F> bool xref:#concurrent_flat_map_cvisit_until[visit_until](F f);
+    template<class F> bool xref:#concurrent_flat_map_cvisit_until[visit_until](F f) const;
+    template<class F> bool xref:#concurrent_flat_map_cvisit_until[cvisit_until](F f) const;
+    template<class ExecutionPolicy, class F>
+      bool xref:#concurrent_flat_map_parallel_cvisit_until[visit_until](ExecutionPolicy&& policy, F f);
+    template<class ExecutionPolicy, class F>
+      bool xref:#concurrent_flat_map_parallel_cvisit_until[visit_until](ExecutionPolicy&& policy, F f) const;
+    template<class ExecutionPolicy, class F>
+      bool xref:#concurrent_flat_map_parallel_cvisit_until[cvisit_until](ExecutionPolicy&& policy, F f) const;
+
+    template<class F> bool xref:#concurrent_flat_map_cvisit_while[visit_while](F f);
+    template<class F> bool xref:#concurrent_flat_map_cvisit_while[visit_while](F f) const;
+    template<class F> bool xref:#concurrent_flat_map_cvisit_while[cvisit_while](F f) const;
+    template<class ExecutionPolicy, class F>
+      bool xref:#concurrent_flat_map_parallel_cvisit_while[visit_while](ExecutionPolicy&& policy, F f);
+    template<class ExecutionPolicy, class F>
+      bool xref:#concurrent_flat_map_parallel_cvisit_while[visit_while](ExecutionPolicy&& policy, F f) const;
+    template<class ExecutionPolicy, class F>
+      bool xref:#concurrent_flat_map_parallel_cvisit_while[cvisit_while](ExecutionPolicy&& policy, F f) const;
+
     // capacity
     ++[[nodiscard]]++ bool xref:#concurrent_flat_map_empty[empty]() const noexcept;
     size_type xref:#concurrent_flat_map_size[size]() const noexcept;
@@ -720,6 +740,94 @@ Unsequenced execution policies are not allowed.
 
 ---
 
+==== [c]visit_until
+
+```c++
+template<class F> bool visit_until(F f);
+template<class F> bool visit_until(F f) const;
+template<class F> bool cvisit_until(F f) const;
+```
+
+Successively invokes `f` with references to each of the elements in the table until `f` returns `true`
+or all the elements are visited.
+Such references to the elements are const iff `*this` is const.
+
+[horizontal]
+Returns:;; `true` iff `f` ever returns `true`.
+
+---
+
+==== Parallel [c]visit_until
+
+```c++
+template<class ExecutionPolicy, class F> bool visit_until(ExecutionPolicy&& policy, F f);
+template<class ExecutionPolicy, class F> bool visit_until(ExecutionPolicy&& policy, F f) const;
+template<class ExecutionPolicy, class F> bool cvisit_until(ExecutionPolicy&& policy, F f) const;
+```
+
+Invokes `f` with references to each of the elements in the table until `f` returns `true`
+or all the elements are visited.
+Such references to the elements are const iff `*this` is const.
+Execution is parallelized according to the semantics of the execution policy specified.
+
+[horizontal]
+Returns:;; `true` iff `f` ever returns `true`.
+Throws:;; Depending on the exception handling mechanism of the execution policy used, may call `std::terminate` if an exception is thrown within `f`.
+Notes:;; Only available in compilers supporting C++17 parallel algorithms. +
++
+These overloads only participate in overload resolution if `std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>` is `true`. +
++
+Unsequenced execution policies are not allowed. +
++
+Parallelization implies that execution does not necessary finish as soon as `f` returns `true`, and as a result
+`f` may be invoked with further elements for which the return value is also `true`.
+
+---
+
+==== [c]visit_while
+
+```c++
+template<class F> bool visit_while(F f);
+template<class F> bool visit_while(F f) const;
+template<class F> bool cvisit_while(F f) const;
+```
+
+Successively invokes `f` with references to each of the elements in the table until `f` returns `false`
+or all the elements are visited.
+Such references to the elements are const iff `*this` is const.
+
+[horizontal]
+Returns:;; `false` iff `f` ever returns `false`.
+
+---
+
+==== Parallel [c]visit_while
+
+```c++
+template<class ExecutionPolicy, class F> bool visit_while(ExecutionPolicy&& policy, F f);
+template<class ExecutionPolicy, class F> bool visit_while(ExecutionPolicy&& policy, F f) const;
+template<class ExecutionPolicy, class F> bool cvisit_while(ExecutionPolicy&& policy, F f) const;
+```
+
+Invokes `f` with references to each of the elements in the table until `f` returns `false`
+or all the elements are visited.
+Such references to the elements are const iff `*this` is const.
+Execution is parallelized according to the semantics of the execution policy specified.
+
+[horizontal]
+Returns:;; `false` iff `f` ever returns `false`.
+Throws:;; Depending on the exception handling mechanism of the execution policy used, may call `std::terminate` if an exception is thrown within `f`.
+Notes:;; Only available in compilers supporting C++17 parallel algorithms. +
++
+These overloads only participate in overload resolution if `std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>` is `true`. +
++
+Unsequenced execution policies are not allowed. +
++
+Parallelization implies that execution does not necessary finish as soon as `f` returns `false`, and as a result
+`f` may be invoked with further elements for which the return value is also `false`.
+
+---
+
 === Size and Capacity
 
 ==== empty