v1.0.0

HashMapPro v1.0.0

The first stable release of HashMapPro, a high-performance separate-chaining hash map implementation for modern C++.

Highlights

• O(1) average-case lookup, insertion, and removal via separate chaining.
• Power-of-two bucket sizing with bitmask indexing instead of modulo.
• Automatic rehashing once the load factor exceeds 0.75.
• Lazily-allocated storage, so a moved-from map can be safely reused.
• Support for insert() and update() operations.
• Support for find(), contains(), operator[], and at() lookups.
• Support for erase() and clear() operations.
• Bidirectional forward and reverse iteration, with const and non-const variants.
• Capacity management via reserve().
• Copy and move construction and assignment support.
• Custom key types via a user-supplied Hash functor.
• Exception-safe cloning on copy construction/assignment.

Performance

The implementation is designed with performance and cache-friendliness in mind.

• Bitmask indexing (hash & (capacity - 1)) replaces division/modulo on the hot path.
• Bucket-chain prepend insertion keeps single-key insertion O(1).
• findNode() reuses a single hash computation across insert, operator[], and find().
• Bucket count is always kept a power of two, so growth and indexing stay cheap.
• cloneFrom() copies elements directly during copy, skipping the per-element existence check insert() would otherwise perform.
• Rehashing relinks existing nodes in place rather than reallocating or copying elements.

Benchmarks

Measured against std::unordered_map at 10K / 100K / 1M iterations. Full results: benchmarks/results/v1_0_0.md.

Operation	HashMapPro (1M)	std::unordered_map (1M)	Δ
Insert() Existing	2.29 ms	14.63 ms	+538.3%
Contains() Hit	934.05 us	2.17 ms	+132.7%
Update() Existing	988.29 us	2.30 ms	+132.3%
At() Existing	939.44 us	2.17 ms	+131.4%
Insert() New	1.36 s	2.82 s	+107.0%
Erase() Missing	1.34 s	2.68 s	+99.6%
Clear() Populated	1.40 s	2.64 s	+88.5%
Move Construct	2.30 s	4.26 s	+85.6%
Find() Hit	1.25 ms	2.17 ms	+73.4%
Copy Construct	2.88 s	2.93 s	+1.8%
Reserved Construct	150.24 ms	37.85 ms	-74.8%
Copy Assignment	2.61 s	256.05 ms	-90.2%

HashMapPro's bitmask-indexed, separate-chaining design pays off most on
no-op paths that skip real work (Insert() Existing short-circuits on the
first matching node without allocating), and on the ordinary hit/miss
lookups (Contains(), At(), Update(), Find()) that dominate typical
usage.

The trade-off: bucket storage is allocated lazily but grows by full
reallocation, so operations that touch every element under a fresh
allocation — Reserved Construct, and especially Copy Assignment, which
releases the destination before cloning — pay that cost directly rather
than amortizing it the way std::unordered_map's node-based allocator
does.

Testing

The project includes a comprehensive test suite covering:

• Unit tests
• Integration tests
• Lifecycle tests
• Move semantics
• Regression tests
• Concurrency tests
• Exception safety
• Custom hash functor workflows
• Rehash and load-factor boundary behavior
• Power-of-two bucket rounding
• Hash collision chains
• Sparse bucket iteration
• External synchronization contracts

Code Coverage

The current test suite achieves:

• 93.0% line coverage
• 99.0% function coverage

Coverage reports exclude test infrastructure and third-party dependencies, focusing on the HashMapPro library implementation.

Continuous Integration

Automated builds and tests are configured for:

• GCC — Debug
• GCC — Release
• Clang — Debug
• Clang — Release
• MSVC — Debug
• MSVC — Release
• AppleClang — Debug
• AppleClang — Release

Release

This release represents the first stable version of HashMapPro and establishes the initial API, hash table design, testing infrastructure, and cross-platform CI pipeline.

Installation

Clone the repository and integrate HashMapPro into your C++ project using the provided CMake configuration. HashMapPro is header-only and also available via vcpkg and Conan.

See the project documentation for build instructions, API usage, and integration details.