{"id":28571008,"url":"https://github.com/mohameds-dev/ordered_map_lib","last_synced_at":"2025-10-29T22:39:54.009Z","repository":{"id":293366694,"uuid":"983774526","full_name":"mohameds-dev/ordered_map_lib","owner":"mohameds-dev","description":"Building an implementation of Ordered Map in C++.","archived":false,"fork":false,"pushed_at":"2025-06-02T01:19:06.000Z","size":82,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-02T11:27:07.002Z","etag":null,"topics":["cmake","cpp17","data-structures","hash-tables","linked-list","pointers","smart-pointers","test-driven-development"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mohameds-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-14T22:38:09.000Z","updated_at":"2025-06-02T01:19:10.000Z","dependencies_parsed_at":"2025-06-02T02:34:09.400Z","dependency_job_id":"76e121d4-6e8c-4266-9f59-03cd4e83be1c","html_url":"https://github.com/mohameds-dev/ordered_map_lib","commit_stats":null,"previous_names":["mohameds-dev/ordered_map_lib"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohameds-dev%2Fordered_map_lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohameds-dev%2Fordered_map_lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohameds-dev%2Fordered_map_lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohameds-dev%2Fordered_map_lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mohameds-dev","download_url":"https://codeload.github.com/mohameds-dev/ordered_map_lib/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mohameds-dev%2Fordered_map_lib/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259123991,"owners_count":22808880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","cpp17","data-structures","hash-tables","linked-list","pointers","smart-pointers","test-driven-development"],"created_at":"2025-06-10T18:15:02.632Z","updated_at":"2025-10-29T22:39:54.001Z","avatar_url":"https://github.com/mohameds-dev.png","language":"C++","readme":"# Ordered Map Library\n\nA C++ implementation of an ordered map data structure that maintains insertion order while providing O(1) key-value lookups.\n\n## 🏆 Quality Metrics\n\n- **Code Coverage**: 97.3% implementation coverage (271/277 lines)\n- **Memory Safety**: Zero memory leaks verified by Valgrind\n- **Test Suite**: 2,246 assertions across 195 test cases\n- **Build Status**: [![CMake](https://github.com/mohameds-dev/ordered_map_lib/actions/workflows/cmake.yml/badge.svg)](https://github.com/mohameds-dev/ordered_map_lib/actions/workflows/cmake.yml)\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n- [Implementation Details](#implementation-details)\n- [Class Diagram](#class-diagram)\n- [Prerequisites](#prerequisites)\n- [Project Structure](#project-structure)\n- [Setting Up VS Code (or Cursor)](#setting-up-vs-code-or-cursor)\n- [Formatting Code](#formatting-code)\n- [Building and Running Tests](#building-and-running-tests)\n- [Memory Leak Checks](#memory-leak-checks)\n- [Code Coverage](#code-coverage)\n- [GitHub Actions CI](#github-actions-ci)\n- [Adding a New Test](#adding-a-new-test)\n- [Future Improvements](#future-improvements)\n\n## Features\n\n- Maintains insertion order of key-value pairs\n- O(1) key-value lookups using hash table\n- O(1) insertion and deletion operations\n- STL-like iterator interface\n- Memory safe with smart pointers\n- Exception handling for out-of-range access\n\n## Usage\n\n```cpp\n#include \"ordered_map.hpp\"\n#include \u003ciostream\u003e\n\nint main() {\n\n    // Create an ordered map\n    OrderedMap\u003cstd::string, int\u003e map;\n\n    // Insert key-value pairs\n    map.insert(\"apple\", 1);\n    map.insert(\"banana\", 2);\n    map.insert(\"cherry\", 3);\n\n    // Access values\n    int value = map[\"apple\"];  // Returns 1\n\n    // Iterate in insertion order\n    for (const auto\u0026 pair : map) {\n        std::cout \u003c\u003c pair.first \u003c\u003c \": \" \u003c\u003c pair.second \u003c\u003c std::endl;\n    }\n\n    return 0;\n}\n```\n\n## Implementation Details\n\nThe implementation of `OrderedMap` uses a combination of:\n\n- Doubly linked list for maintaining insertion order\n- Smart pointers for memory management\n- Hash table (std::unordered_map) for O(1) lookups\n- STL-compatible iterator interface\n\n## Class Diagram\n\n```mermaid\nclassDiagram\n\nclass Node~T~ {\n    +T value\n    +unique_ptr\u003cNode~T~\u003e next\n    +Node~T~* prev\n    +Node(Node* prev, unique_ptr\u003cNode\u003e next, U\u0026\u0026 value)\n    +Node(Node* prev, unique_ptr\u003cNode\u003e next, Args\u0026\u0026... args)\n}\n\nclass DoublyLinkedList~T~ {\n    -unique_ptr\u003cNode~T~\u003e head\n    -Node~T~* tail\n    -int _size\n    +push_back(const T\u0026)\n    +push_back(T\u0026\u0026)\n    +push_front(const T\u0026)\n    +push_front(T\u0026\u0026)\n    +emplace_back(Args\u0026\u0026...)\n    +pop_back()\n    +pop_front()\n    +move_to_begin(Iterator)\n    +move_to_end(Iterator)\n    +erase(Iterator)\n    +size() const\n    +begin()\n    +end()\n    +front() const\n    +back() const\n    +clear()\n    +back_iterator()\n    -extract_node_and_link_prev_with_next(Node~T~*)\n    -emplace_node_before(unique_ptr\u003cNode~T~\u003e, Node~T~*)\n    -emplace_node_after(unique_ptr\u003cNode~T~\u003e, Node~T~*)\n}\n\nclass DoublyLinkedListIterator~T~ {\n    -Node~T~* current_node_ptr\n    -DoublyLinkedList~T~* list_ptr\n    +operator++()\n    +operator--()\n    +operator*()\n    +operator-\u003e()\n    +operator==() const\n    +operator!=() const\n}\n\nclass OrderedMap~Key,Value~ {\n    -unordered_map\u003cKey, DoublyLinkedListIterator~pair\u003cKey,Value\u003e~\u003e _map\n    -DoublyLinkedList~pair\u003cKey,Value\u003e~ _list\n    +insert(const Key\u0026, const Value\u0026)\n    +insert(const Key\u0026, Value\u0026\u0026)\n    +move_to_front(const Key\u0026)\n    +move_to_back(const Key\u0026)\n    +operator[](const Key\u0026)\n    +at(const Key\u0026) const\n    +erase(const Key\u0026)\n    +find(const Key\u0026) const\n    +size() const\n    +begin()\n    +end()\n    +clear()\n    +back_iterator()\n}\n\nclass OrderedMapIterator~Key,Value~ {\n    -DoublyLinkedListIterator~pair\u003cKey,Value\u003e~ list_iterator\n    +operator++()\n    +operator*()\n    +operator-\u003e()\n    +operator!=() const\n    +operator==() const\n}\n\nDoublyLinkedList~T~ *-- Node~T~\nDoublyLinkedList~T~ *-- DoublyLinkedListIterator~T~\nOrderedMap~Key,Value~ *-- DoublyLinkedList~pair\u003cKey,Value\u003e~\nOrderedMap~Key,Value~ *-- OrderedMapIterator~Key,Value~\nOrderedMapIterator~Key,Value~ *-- DoublyLinkedListIterator~pair\u003cKey,Value\u003e~\n\n\n```\n\n## Prerequisites\n\n- **CMake** (3.10+): `sudo apt install cmake`\n- **Git**: `sudo apt install git`\n- **C++ Compiler**: GCC 9.4.0+ (`sudo apt install g++`)\n- **Clang-Format**: For code formatting (`sudo apt install clang-format`)\n- **VS Code** or **Cursor**: Code editor with C++ support\n\nVerify installations:\n\n```bash\ncmake --version\ngit --version\ng++ --version\nclang-format --version\n```\n\n## Project Structure\n\n```\nordered_map/\n├── .github/\n│   └── workflows/\n│       └── cmake.yml       # GitHub Actions workflow\n├── CMakeLists.txt         # CMake build configuration\n├── build.sh              # Script to build and test\n├── .clang-format         # Code formatting rules\n├── include/\n│   ├── doubly_linked_list.hpp    # Doubly-linked list implementation\n│   └── ordered_map.hpp          # Ordered map interface\n├── src/\n├── tests/\n│   └── doubly_linked_list/      # Test files for doubly linked list\n│       ├── front_and_back.cpp   # Tests for front/back operations\n│       ├── iterator_tests.cpp   # Tests for iterator functionality\n│       ├── pop_back_tests.cpp   # Tests for pop_back operations\n│       ├── pop_front_tests.cpp  # Tests for pop_front operations\n│       ├── push_back_tests.cpp  # Tests for push_back operations\n│       └── push_front_tests.cpp # Tests for push_front operations\n```\n\n## Setting Up VS Code (or Cursor)\n\n1. **Install Extensions**:\n\n   - In VS Code/Cursor, go to Extensions (Ctrl+Shift+X).\n   - Install:\n     - **C/C++** (Microsoft): For IntelliSense and debugging.\n     - **CMake Tools** (Microsoft): For CMake integration.\n\n2. **Configure IntelliSense**:\n\n   - Create `.vscode/settings.json` (or `.cursor/settings.json`):\n     ```json\n     {\n       \"C_Cpp.default.compileCommands\": \"${workspaceFolder}/build/compile_commands.json\",\n       \"C_Cpp.clang_format_path\": \"/usr/bin/clang-format\",\n       \"C_Cpp.formatting\": \"clangFormat\",\n       \"editor.formatOnSave\": true,\n       \"[cpp]\": {\n         \"editor.defaultFormatter\": \"ms-vscode.cpptools\"\n       }\n     }\n     ```\n\n3. **Open Project**:\n   - Open the project folder in VS Code/Cursor.\n\n## Formatting Code\n\n- **Clang-Format**: Uses `.clang-format` for consistent style (Google-based).\n- **Auto-Format**: Formats on save (see `editor.formatOnSave`).\n- **Manual Format**:\n  ```bash\n  clang-format -i src/*.cpp include/*.hpp tests/*.cpp\n  ```\n- **Via build.sh**: Formats all `.cpp`/`.hpp` files before building.\n\n## Building and Running Tests\n\n1. **Build and Test**:\n\n   ```bash\n   chmod +x build.sh\n   ./build.sh\n   ```\n\n   - Formats code, builds with CMake/make, and runs Catch2 tests.\n\n2. **Output**:\n\n   - Successful tests show:\n     ```\n     All tests passed (X assertions in Y test cases)\n     ```\n\n3. **Run Specific Tests**:\n   ```bash\n   cd build\n   ./tests --tags [tag]\n   ```\n\n## Memory Leak Checks\n\nThis project is tested for memory leaks using Valgrind.  \nBelow is a sample output from running the full test suite under Valgrind:\n\n```\n$ valgrind --leak-check=full ./build/tests --rng-seed 0\n\n==12798== Memcheck, a memory error detector\n==12798== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.\n==12798== Using Valgrind-3.15.0 and LibVEX; rerun with -h for copyright info\n==12798== Command: ./build/tests --rng-seed 0\n==12798==\nRandomness seeded to: 0\n===============================================================================\nAll tests passed (2246 assertions in 195 test cases)\n\n==12798==\n==12798== HEAP SUMMARY:\n==12798==     in use at exit: 0 bytes in 0 blocks\n==12798==   total heap usage: 1,528,976 allocs, 1,528,976 frees, 45,317,931 bytes allocated\n==12798==\n==12798== All heap blocks were freed -- no leaks are possible\n==12798==\n==12798== For lists of detected and suppressed errors, rerun with: -s\n==12798== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)\n```\n\n## Code Coverage\n\nThis project includes comprehensive test coverage analysis using **LCOV**, which provides accurate coverage metrics for header-only libraries by distinguishing between implementation code and test code.\n\n### Generate Coverage Report\n\nFrom the build directory, run this script:\n\n```bash\n./create_and_run_coverage.sh\n```\n\n### Implementation Coverage Results\n\n**Pure Implementation Coverage (excluding test code and system headers):**\n\n- **doubly_linked_list.hpp**: **97.8%** of 185 lines covered\n- **ordered_map.hpp**: **98.9%** of 91 lines covered\n\n### Coverage Summary\n\nThis shows that:\n\n- **97.8%** of the doubly linked list implementation is tested\n- **98.9%** of the ordered map implementation is tested\n- Only a few edge cases remain uncovered\n- The test suite comprehensively exercises the core functionality\n\nThe HTML report provides line-by-line coverage details, showing exactly which implementation lines are covered by the test suite.\n\n## GitHub Actions CI\n\n- **Workflow**: `.github/workflows/cmake.yml` automates building and testing on push to `main` or pull requests to `main`.\n- **Setup**:\n  1. Push your repository to GitHub.\n  2. Ensure `.github/workflows/cmake.yml` exists.\n  3. CI runs `build.sh` on `ubuntu-latest`, formatting, building, and testing.\n- **View Results**:\n  - Check the \"Actions\" tab on GitHub for CI logs.\n\n## Adding a New Test\n\n1. **Choose the appropriate test file** in `tests/doubly_linked_list/` based on the functionality being tested:\n\n   - `front_and_back.cpp` for front/back operations\n   - `iterator_tests.cpp` for iterator functionality\n   - `pop_back_tests.cpp` for pop_back operations\n   - `pop_front_tests.cpp` for pop_front operations\n   - `push_back_tests.cpp` for push_back operations\n   - `push_front_tests.cpp` for push_front operations\n\n2. **Add your test case**:\n\n   ```cpp\n   TEST_CASE(\"Your test description\", \"[tag]\") {\n       DoublyLinkedList\u003cint\u003e list;\n       // Your test code here\n       REQUIRE(/* your assertion */);\n   }\n   ```\n\n3. **Rebuild and Test**:\n   ```bash\n   ./build.sh\n   ```\n\n## Future Features\n\n- [x] Add std::move and copying semantics\n- [x] **DoublyLinkedList:** Add tests for copying \u0026 moving\n- [x] **DoublyLinkedList:** Add `erase` method to erase elements given their iterator\n- [x] **DoublyLinkedList:** Add pre and post decrement operators\n- [x] **DoublyLinkedList:** Test front(), back(), insertion and deletion functions for copying behavior\n- [x] Add `move_to_front` and `move_to_back` operations in ordered_map to re-order entries (without affecting or copying the entry value)\n- [x] **OrderedMap:** Add support for initializing map with intializer list\n- [x] **OrderedMap:** Add support for initializing map with two container iterators\n- [x] **OrderedMap:** Add `erase` method to erase elements given their iterator or key\n- [x] Test for memory leaks\n- [x] Add test coverage\n- [ ] Add const iterators\n- [ ] Add reverse iterators\n- [ ] Add performance benchmarks\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohameds-dev%2Fordered_map_lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmohameds-dev%2Fordered_map_lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmohameds-dev%2Fordered_map_lib/lists"}