beman.map: Better Map Lookups for C++

beman.map implements safer, non-throwing map lookups returning optional<T&> instead of throwing (.at()) or silently inserting (operator[]).

Implements: Better lookups for map, unordered_map, and flat_map (P3091R5).

Status: Under development and not yet ready for production use.

License

beman.map is licensed under the Apache License v2.0 with LLVM Exceptions.

Usage

P3091 adds a .get(key) member function to map, unordered_map, and flat_map. It returns optional<mapped_type&> a non-throwing, never inserting, and composable with all optional monadic operations.

#include <beman/map/map.hpp>

beman::map::map<std::string, int> scores{{"alice", 42}, {"bob", 7}};

// Safe lookup: returns optional<int&>
if (auto v = scores.get("alice")) {
    std::cout << *v << "\n";  // 42
}

// Missing key: returns nullopt, no exception, no insertion
auto v = scores.get("carol");
assert(!v.has_value());

// Monadic composition
int result = scores.get("alice").value_or(0);  // 42

Heterogeneous lookup

When the comparator has is_transparent (e.g. std::less<void>), heterogeneous key types work without constructing a key_type:

beman::map::map<std::string, int, std::less<>> m{{"hello", 1}};
auto v = m.get(std::string_view{"hello"});  // optional<int&>

Full runnable examples can be found in examples/.

Dependencies

Build Environment

• A C++ compiler supporting C++23 or later
• CMake 3.30 or later
• beman.optional (auto-fetched via lockfile)
• (Test only) GoogleTest (auto-fetched via lockfile)

You can disable building tests by setting BEMAN_MAP_BUILD_TESTS=OFF.

Supported Platforms

Compiler	Version	C++ Standards	Standard Library
GCC	15-14	C++23	libstdc++
Clang	22-19	C++23	libstdc++, libc++
AppleClang	latest	C++23	libc++
MSVC	latest	C++23	MSVC STL

Development

See the Contributing Guidelines.

Configure, Build, Test and Run locally

# 1. Configure
cmake -S . -B build/debug \
  -G Ninja \
  -DCMAKE_CXX_STANDARD=23 \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake

# 2. Build
cmake --build build/debug

# 3. Test
ctest --test-dir build/debug --output-on-failure

# 4. Run examples
./build/debug/examples/beman.map.examples.basic_get
./build/debug/examples/beman.map.examples.heterogeneous_lookup

Alternatively, use a CMake workflow preset (requires CMake 3.30+):

cmake --workflow --preset gcc-debug    # debug build
cmake --workflow --preset gcc-release  # release build

Integrate beman.map into your project

Build and Install

cmake --workflow --preset gcc-release
sudo cmake --install build/gcc-release

CMake Configuration

find_package(beman.map REQUIRED)
target_link_libraries(yourlib PUBLIC beman::map)

Using beman.map

#include <beman/map/map.hpp>            // beman::map::map
#include <beman/map/unordered_map.hpp>  // beman::map::unordered_map
#include <beman/map/flat_map.hpp>       // beman::map::flat_map