Add find_or_insert_with

README.md

@@ -29,9 +29,22 @@ In C++ for example, This lookup complexity is easily outperformed by `find()` on
 
 ## Usage
 
-This library is written in C++20, and can be used as a single-header library by directly including the file `include/memo_cache.hpp`.
+This library requires a C++20 compiler, and can be used as a single-header library by directly including the file `include/memo_cache.hpp`.
 
-It can be used like this:
+It can be used like this (using `find_or_insert_with`):
+
+```c++
+// A function performing expensive, deterministic calculations.
+float calculate(int input) {
+  static mc::memo_cache<int, float> cache;
+
+  return cache.find_or_insert_with(input, [](auto& key) {
+    return /* ..some expensive calculation.. */;
+  });
+}
+```
+
+Or like this (using separate `find` and `insert` calls):
 
 ```c++
 // A function performing expensive, deterministic calculations.
@@ -67,7 +80,7 @@ clang++-18 -std=c++20 -Wall -Wextra -Werror -Wconversion -O3 -I../include ../tes
 
 ### Benchmark
 
-See here: https://quick-bench.com/q/7sBFm5NaPWqhhDFrynIwmAx9Kx4
+See here: https://quick-bench.com/q/NG9pFDcSWBmG3xWWoL_O45IgDUk
 
 ## TODO
 

benches/memo_cache.cpp

@@ -17,12 +17,9 @@ constexpr auto INPUT_VARIANCE = 100;
     std::normal_distribution<> distribution{0, INPUT_VARIANCE}; \
     \
     for (auto _ : state) { \
-      const auto x = static_cast<int>(distribution(generator)); \
-      if (const auto v = c.find(x); v) { \
-        benchmark::DoNotOptimize(v); \
-      } else { \
-        c.insert(x, x); \
-      } \
+      auto v = c.find_or_insert_with(static_cast<int>(distribution(generator)), \
+                                     [](auto& k) { return k; }); \
+      benchmark::DoNotOptimize(v); \
     } \
   } \
   BENCHMARK(MemoCache##s);
@@ -34,9 +31,16 @@ MemoCacheBench_impl(32)
 MemoCacheBench_impl(64)
 MemoCacheBench_impl(128)
 MemoCacheBench_impl(256)
-MemoCacheBench_impl(512)
 // NOTE: Behavior gets worse beyond this size.
 
+// NOTE1: Yes. The test is slightly flawed as it also tests the random key generation
+//        itself. However, I think relatively and statistically speaking it's fine.
+//        The best solution would be to pre-generate a large set of random numbers
+//        and use that set for all of the tests.
+// NOTE2: The test is run using the 'int' input space, and a normal distribution to
+//        produce values with a mean of 0 and a variance as defined here:
+constexpr auto INPUT_VARIANCE = 100;
+
 static void OrderedMap(benchmark::State& state) {
   std::map<int, int> c;
 

include/memo_cache.hpp

@@ -5,6 +5,7 @@
 #include <concepts>
 #include <cstddef>
 #include <functional>
+#include <iterator>
 #include <optional>
 #include <utility>
 
@@ -31,6 +32,19 @@ class memo_cache {
   buffer_t buffer;
   std::size_t cursor{};
 
+  /// Replace slot under cursor and shift cursor position. Returns a reference to the replaced slot value.
+  template<typename Key_, typename Val_>
+  Val& replace_and_shift(Key_&& key, Val_&& val) {
+    buffer[cursor] = {.key = std::forward<Key_>(key), .val = std::forward<Val_>(val), .empty = false};
+
+    auto& value = buffer[cursor].val;
+
+    // Move the cursor over the buffer elements sequentially, creating FIFO behavior.
+    cursor = (cursor + 1) % Size; // Wrap; overwrite the oldest element next time around.
+
+    return value;
+  }
+
 public:
   /// Get the (fixed) size of the cache.
   ///
@@ -73,10 +87,7 @@ class memo_cache {
     if (auto found = find(key); found) {
       found.value().get() = std::forward<Val_>(val);
     } else {
-      buffer[cursor] = {.key = std::forward<Key_>(key), .val = std::forward<Val_>(val), .empty = false};
-
-      // Move the cursor over the buffer elements sequentially, creating FIFO behavior.
-      cursor = (cursor + 1) % Size; // Wrap; overwrite the oldest element next time around.
+      replace_and_shift(std::forward<Key_>(key), std::forward<Val_>(val));
     }
   }
 
@@ -106,6 +117,34 @@ class memo_cache {
     }
   }
 
+  /// Get a value, or, if it does not exist in the cache, insert it using the value computed by `f`.
+  /// Returns a reference to the found, or newly inserted value associated with the given key.
+  ///
+  /// # Examples
+  ///
+  /// ```
+  /// #include <cassert>
+  /// #include <memo_cache.hpp>
+  ///
+  /// memo_cache<int, std::string, 4> c;
+  ///
+  /// assert(!c.contains(42));
+  ///
+  /// auto v = c.find_or_insert_with(42, [] { return "The Answer"; });
+  ///
+  /// assert(v == "The Answer");
+  /// assert(c.find(42).has_value());
+  /// assert(c.find(42).value() == "The Answer");
+  /// ```
+  template<typename F>
+  [[nodiscard]] std::reference_wrapper<Val> find_or_insert_with(const Key& key, F f) {
+    if (auto slot = find(key); slot) {
+      return *slot;
+    } else {
+      return replace_and_shift(key, f(key));
+    }
+  }
+
   /// Returns `true` if the cache contains a value for the specified key.
   ///
   /// # Examples

tests/memo_cache.cpp

@@ -18,7 +18,54 @@ TEST_SUITE("memo_cache")
     CHECK_EQ(c.size(), SIZE);
   }
 
-  TEST_CASE("Contains")
+  TEST_CASE("find")
+  {
+    mc::memo_cache<std::string, int, 3> c;
+
+    CHECK_FALSE(c.find("hello").has_value());
+
+    c.insert("hello", 42);
+
+    REQUIRE(c.find("hello").has_value());
+    CHECK_EQ(c.find("hello").value(), 42);
+  }
+
+  TEST_CASE("find_or_insert_with")
+  {
+    mc::memo_cache<std::string, int, 3> c;
+
+    CHECK_FALSE(c.contains("hello"));
+    CHECK_FALSE(c.contains("hi"));
+
+    CHECK_EQ(c.find_or_insert_with("hello", [](auto& k) {
+                 CHECK_EQ(k, "hello");
+                 return 42;
+               }),
+             42);
+
+    REQUIRE(c.contains("hello"));
+    CHECK_EQ(c.find("hello").value(), 42);
+    CHECK_FALSE(c.contains("hi"));
+
+    CHECK_EQ(c.find_or_insert_with("hi", [](auto& k) {
+                 CHECK_EQ(k, "hi");
+                 return 17;
+               }),
+             17);
+
+    REQUIRE(c.contains("hello"));
+    CHECK_EQ(c.find("hello").value(), 42);
+    REQUIRE(c.contains("hi"));
+    CHECK_EQ(c.find("hi").value(), 17);
+
+    CHECK_EQ(c.find_or_insert_with("hello", []([[maybe_unused]] auto& _) {
+                 CHECK(false);
+                 return 13; // NOTE: Key already exists, this value is not used.
+               }),
+             42);
+  }
+
+  TEST_CASE("contains")
   {
     mc::memo_cache<std::string, int, 3> c;
 
@@ -29,7 +76,7 @@ TEST_SUITE("memo_cache")
     CHECK(c.contains("hello"));
   }
 
-  TEST_CASE("Clear")
+  TEST_CASE("clear")
   {
     mc::memo_cache<std::string, int, 3> c;