{"id":15660297,"url":"https://github.com/thelartians/bitlens","last_synced_at":"2026-03-14T07:38:46.941Z","repository":{"id":88218073,"uuid":"251096412","full_name":"TheLartians/BitLens","owner":"TheLartians","description":"🔎 Have your bits and eat them too! A C++17 bit lens container for vector types.","archived":false,"fork":false,"pushed_at":"2020-04-20T23:43:18.000Z","size":58,"stargazers_count":21,"open_issues_count":0,"forks_count":1,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-05T20:11:46.639Z","etag":null,"topics":["array","bit","bitset","container","cxx","cxx17","lens","vector","wrapper","zero-overhead","zero-overhead-abstraction"],"latest_commit_sha":null,"homepage":"","language":"C++","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/TheLartians.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":"2020-03-29T17:52:17.000Z","updated_at":"2024-06-26T19:43:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"989047da-9f85-4fa6-a763-ae613d9563a0","html_url":"https://github.com/TheLartians/BitLens","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/TheLartians/BitLens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FBitLens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FBitLens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FBitLens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FBitLens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TheLartians","download_url":"https://codeload.github.com/TheLartians/BitLens/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TheLartians%2FBitLens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002103,"owners_count":26083307,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["array","bit","bitset","container","cxx","cxx17","lens","vector","wrapper","zero-overhead","zero-overhead-abstraction"],"created_at":"2024-10-03T13:20:56.993Z","updated_at":"2025-10-09T22:36:53.510Z","avatar_url":"https://github.com/TheLartians.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Actions Status](https://github.com/TheLartians/BitLens/workflows/MacOS/badge.svg)](https://github.com/TheLartians/BitLens/actions)\n[![Actions Status](https://github.com/TheLartians/BitLens/workflows/Windows/badge.svg)](https://github.com/TheLartians/BitLens/actions)\n[![Actions Status](https://github.com/TheLartians/BitLens/workflows/Ubuntu/badge.svg)](https://github.com/TheLartians/BitLens/actions)\n[![Actions Status](https://github.com/TheLartians/BitLens/workflows/Style/badge.svg)](https://github.com/TheLartians/BitLens/actions)\n[![Actions Status](https://github.com/TheLartians/BitLens/workflows/Install/badge.svg)](https://github.com/TheLartians/BitLens/actions)\n\n# BitLens\n\nA zero-overhead container wrapper for seamless switching between integer and bit representations.\nEver wished you could have the convenience and compact storage of `std::vector\u003cbool\u003e` without all the [issues](http://www.gotw.ca/publications/N1211.pdf) and performance sacrifices?\nThen this is a library for you!\n\n## Usage\n\nThe actual data is stored in an unsigned integral container, such as `std::vector\u003cunsigned int\u003e`.\nBitwise operations are performed as usual on the original container.\nThese operate on many bits in parallel and are optimized by the compiler.\n`bit_lens::BitLens` provides a simple API for bit-specific operations and can be created with zero overhead whenever needed.\n\n## API\n\n```cpp\n#include \u003cbit_lens.h\u003e\n#include \u003cvector\u003e\n#include \u003calgorithm\u003e\n\nint main() {\n  // create a bit container based on any another random-access container\n  bit_lens::BitContainer\u003cstd::vector\u003cunsigned\u003e\u003e bits;\n\n  // or create a lens into an existing container\n  // bit_lens::BitLens bits(container);\n\n  // resize the container to store at least 10 bits\n  bits.resize(10);\n\n  // the actual number of bits that the container can store\n  bits.size();\n\n  // access individual bits using standard operators\n  bits[8] = 1;\n  \n  // iterate over all bits using bit references\n  for (auto bit: bits) { bit = 1; }\n\n  // \u003calgorithm\u003e compatible iterators\n  std::count(bits.begin(), bits.end(), true);\n\n  // access the underlying data container\n  bits.data();\n\n  // if possible, use bitwise operators on values as it's much more performant (see benchmark)\n  for (auto \u0026v: bits.data()) { v \u0026= 0b1101; }\n}\n```\n\n## Integration\n\nBitLens is a single header library that can be easily added via [CPM.cmake](https://github.com/TheLartians/CPM.cmake).\n\n```cmake\nCPMAddPackage(\n  NAME BitLens\n  GITHUB_REPOSITORY TheLartians/BitLens\n  VERSION 2.1\n)\n```\n\nAlternatively, use git submodules, install globally, or simply download and copy the [header](include/bit_lens.h) into your project.\n\n## Benchmark\n\nTo illustrate the performance difference between `vector\u003cbool\u003e` and other container types, this repository contains a benchmark suite than  can be run through the following commands.\n\n```bash\ncmake -Hbenchmark -Bbuild/bench -DCMAKE_BUILD_TYPE=Release\ncmake --build build/bench -j8\n./build/bench/BitLensBenchmark\n```\n\nAs an example, on a 2018 mac notebook, the benchmark produced the following output.\n\n```\n-------------------------------------------------------------------------\nBenchmark                               Time             CPU   Iterations\n-------------------------------------------------------------------------\nbitwiseRandomAccessVectorBool     1080454 ns      1079235 ns          629\nbitwiseRandomAccessVectorChar      852203 ns       851398 ns          797\nbitwiseRandomAccessVectorInt       820476 ns       819897 ns          806\nbitwiseDifferenceVectorBool        426308 ns       425972 ns         1331\nbitwiseDifferenceVectorChar        159575 ns       159465 ns         4143\nbitwiseDifferenceVectorInt         171368 ns       171338 ns         3874\nvaluewiseDifferenceVectorChar        8185 ns         8180 ns        80039\nvaluewiseDifferenceVectorInt          433 ns          433 ns      1560264\nvaluewiseDifferenceVectorSizeT        422 ns          422 ns      1636872\n```\n\nWe can see that for integer containers, even bitwise random access operations are noticeably faster than `vector\u003cbool\u003e`.\nBitwise iteration using a `BitLens` has more than twice the speed, while doing bitwise operations on values (e.g. working on `BitLens::data()`) outperforms `vector\u003cbool\u003e` by many orders of magnitude.\nThis is because bitwise operators allow manipulating up to 64 bits at once (depending on the value type) and get an extra performance boost through vectorization.\nUsing BitLens we can choose the appropriate representation (value / bits) anytime, allowing us to achieve optimal storage and performance requirements.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthelartians%2Fbitlens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthelartians%2Fbitlens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthelartians%2Fbitlens/lists"}