{"id":18400550,"url":"https://github.com/bogwi/sortedmap","last_synced_at":"2025-04-12T16:57:48.813Z","repository":{"id":210507849,"uuid":"724924144","full_name":"bogwi/SortedMap","owner":"bogwi","description":"Map for fast storing key-value pairs sorted by key","archived":false,"fork":false,"pushed_at":"2024-03-13T16:46:18.000Z","size":128,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-16T03:24:08.463Z","etag":null,"topics":["map","skiplist","sorted-data","sorted-map","zig","zig-library","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bogwi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2023-11-29T04:12:49.000Z","updated_at":"2024-10-25T08:43:07.000Z","dependencies_parsed_at":"2023-12-03T09:45:56.857Z","dependency_job_id":"c82f4bb9-7b4c-4e6d-8027-be870c0f2201","html_url":"https://github.com/bogwi/SortedMap","commit_stats":null,"previous_names":["bogwi/sortedmap"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bogwi%2FSortedMap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bogwi%2FSortedMap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bogwi%2FSortedMap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bogwi%2FSortedMap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bogwi","download_url":"https://codeload.github.com/bogwi/SortedMap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248601763,"owners_count":21131612,"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":["map","skiplist","sorted-data","sorted-map","zig","zig-library","zig-package","ziglang"],"created_at":"2024-11-06T02:34:35.556Z","updated_at":"2025-04-12T16:57:48.794Z","avatar_url":"https://github.com/bogwi.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SortedMap in ZIG\n\n## Description\n\nSorted Map is a fast key-value table, an advance version of [skiplist ADT](https://en.wikipedia.org/wiki/Skip_list) as proposed by W.Pugh in 1989 for ordered mapping of keys to  values.\n\n## Features \n* Takes any numeric key except the maximum possible value for the given type. \n* Takes any literal key of type `[]const u8` and of any length, but lexicographically smaller than `\"ÿ\"` ASCII 255. \n* Values are arbitrary values.\n* Works in `.set` or `.list` mode. The latter allows duplicate keys.\n* Has forward and backward iteration.\n* Has `min`, `max`, `median` key query.\n* Supports queries by key or index, similar to Python's list class, including reverse indexing.\n* Basic operations like `get`, `remove` work on a range as well.\n* Updating the values by giving the `start_idx` - `stop_idx` range is O(1) each update. Yes, the whole map can be updated in O(n).\n* Updating the values by giving the `start_key` - `stop_key` range is O(1) each update.\n\n## Performance\nThe benchmark is a set of standard stress routines to measure the throughput for the given task. The machine is an Apple M1 with 32GB RAM, optimization flag `ReleaseFast`.\n\nThere are five tests in total, all of which are run on the random data with intermediate shuffling during the test stages:\n\n**READ HEAVY**\\\n[read 98, insert 1,  remove 1,  update 0 ]\\\nModels caching of data in places such as web servers and disk page caches.\n\n**EXCHANGE**\\\n[read 10, insert 40, remove 40, update 10]\\\nReplicates a scenario where the map is used to exchange data.\n\n**EXCHANGE HEAVY**\\\n[read 1, insert 98, remove 98, update 1]\\\nThis test is an inverse of *RH* test. Hard for any map.\n\n**RAPID GROW**\\\n[read 5,  insert 80, remove 5,  update 10]\\\nA scenario where the map is used to collect large amounts of data in a short burst.\n\n**CLONE**\\\nClone the Map. That is, rebuild the map anew yet from the sorted data.\n\n### `u64`, arbitrary feed\n```\n               SortedMap u64 BENCHMARK|\n              10_000_000 ops:each test|\n\n|name         |Tp Mops:sec|    Rt :sec|\n =====================================\n|RH           |      51.47|   0.194274|\narena size: 13804, cache len: 131\n\n|EX           |      23.25|   0.430069|\narena size: 13804, cache len: 121\n\n|EXH          |      20.20|   0.494928|\narena size: 13804, cache len: 135\n\n|RG           |       0.53|  18.996072|\narena size: 595966060, cache len: 5\n\n|CLONE        |       5.86|   1.279128|\n```\n\n### `[8]const u8`, arbitrary literal, arbitrary feed\n```\n               SortedMap STR BENCHMARK|\n              10_000_000 ops:each test|\n\n|name         |Tp Mops:sec|    Rt :sec|\n =====================================\n|RH           |      25.49|   0.392336|\narena size: 13564, cache len: 133\n\n|EX           |      17.02|   0.587408|\narena size: 13564, cache len: 123\n\n|EXH          |      14.49|   0.690115|\narena size: 13564, cache len: 137\n\n|RG           |       0.37|  26.855707|\narena size: 894236804, cache len: 5\n\n|CLONE        |       3.12|   2.400613|\n```\n\n## How to run the benchmark\n```\nzig build bench\n```\nBy default it runs 100_000 rounds each test on the `u64` type.\n\nGive it a larger number to stress the map more.\n```\nzig build bench -- 1_000_000\n```\nPrepend with `-str` to test on the arbitrary `[8]u8` word.\n```\nzig build bench -- 1_000_000 -str\n```\n\n## How to use it\nCopy `sorted_map.zig` and `cache.zig` into your project, or make a fork and work from there. Or you can import it as a dependency.\n\nDeclare in your file:\n```zig\nconst SortedMap = @import(\"sorted_map.zig\").SortedMap;\n```\n\nInitiate for numeric keys:\n```zig\nconst map = SortedMap(u64, your_value_type, .list).init(your_allocator);\ndefer map.deinit();\n\n```\n\nInitiate for string literal keys:\n```zig\nconst map = SortedMap([]const u8, your_value_type, .set).init(your_allocator);\ndefer map.deinit();\n```\n\n\n## zig version\n```\n0.12.0-dev.1830+779b8e259\n```\n\n\n\n\n\n\n\n\n\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbogwi%2Fsortedmap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbogwi%2Fsortedmap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbogwi%2Fsortedmap/lists"}