{"id":15400489,"url":"https://github.com/haxelion/bva","last_synced_at":"2025-04-15T22:31:00.404Z","repository":{"id":62438650,"uuid":"317755094","full_name":"haxelion/bva","owner":"haxelion","description":"Bit Vector Arithmetic in Rust","archived":false,"fork":false,"pushed_at":"2025-03-09T11:44:53.000Z","size":248,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-29T03:41:33.917Z","etag":null,"topics":["arithmetic","bitvector","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/haxelion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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-12-02T05:01:59.000Z","updated_at":"2025-03-17T00:24:15.000Z","dependencies_parsed_at":"2024-02-25T08:26:02.635Z","dependency_job_id":"b21ee6bf-d34b-4276-abe8-1be841c29ddd","html_url":"https://github.com/haxelion/bva","commit_stats":{"total_commits":69,"total_committers":1,"mean_commits":69.0,"dds":0.0,"last_synced_commit":"645154cdbd3fcd8eb6627f75c161cbc0b18fde06"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haxelion%2Fbva","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haxelion%2Fbva/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haxelion%2Fbva/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haxelion%2Fbva/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haxelion","download_url":"https://codeload.github.com/haxelion/bva/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249165931,"owners_count":21223347,"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":["arithmetic","bitvector","rust"],"created_at":"2024-10-01T15:54:01.892Z","updated_at":"2025-04-15T22:30:59.379Z","avatar_url":"https://github.com/haxelion.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bva\n\n[![crates.io Version](https://img.shields.io/crates/v/bva.svg)](https://crates.io/crates/bva)\n[![Rayon documentation](https://img.shields.io/docsrs/bva/latest)](https://docs.rs/bva)\n![Build Status](https://github.com/haxelion/bva/actions/workflows/ci.yaml/badge.svg)\n[![codecov](https://codecov.io/github/haxelion/bva/graph/badge.svg?token=UMXJD47JCY)](https://codecov.io/github/haxelion/bva)\n![Minimum Rust 1.61](https://img.shields.io/badge/Rust-1.61+-red.svg)\n[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nThis crate is for manipulating and doing arithmetics on bit vectors of fixed but arbitrary size.\nThey are meant to behave like CPU hardware registers with wrap-around on overflow.\n\nThis crate provides multiple implementations relying on different memory management strategies.\n\n* The `Bvf` implementation uses statically sized arrays of unsigned integers as storage\n  and thus has a fixed capacity but does not require dynamic memory allocation.\n* The `Bvd` implementation uses a dynamically allocated array of\n  integers as storage and therefore has a dynamic capacity and support resizing operations.\n* The `Bv` implementation is capable of switching at runtime between the `Bvf` and `Bvd`\n  implementations to try to minimize dynamic memory allocations whenever possible.\n\nAll of those implementations implement the `BitVector` trait and can be freely mixed together\nand abstracted through generic traits.\n\nThe different bit vector types represent a vector of bits where the bit at index 0 is the least\nsignificant bit and the bit at index `.len() - 1` is the most significant bit. There is no\nnotion of endianness for the bit vector themselves, endianness is only involved when reading or\nwriting a bit vector from or to memory.\n\nArithmetic operation can be applied to bit vectors of different types and different lengths.\nThe result will always have the type and the length of the left hand side operand. The right\nhand side operand will be zero extended if needed. Operations will wrap-around in the case of\noverflows. This should match the behavior of unsigned integer arithmetics on CPU registers.\n\n## Examples\n\nBit vectors expose an API similar to Rust `std::collections::Vec`:\n```rust\nuse bva::{Bit, BitVector, Bvd};\n\nlet mut bv = Bvd::with_capacity(128);\nassert_eq!(bv.capacity(), 128);\nbv.push(Bit::One);\nbv.push(Bit::One);\nbv.resize(16, Bit::Zero);\nassert_eq!(bv.len(), 16);\nassert_eq!(bv.first(), Some(Bit::One));\nassert_eq!(bv.last(), Some(Bit::Zero));\nlet pop_count = bv.iter().fold(0u32, |acc, b| acc + u32::from(b));\nassert_eq!(pop_count, 2);\n```\n\nAdditionally, bit vector specific operations are available:\n```rust\nuse bva::{Bit, BitVector, Bv32};\n\n// While Bv32 has a capacity of 32 bits, it inherits the length of the u8.\nlet mut a = Bv32::try_from(0b111u8).unwrap();\na.rotr(2);\nassert_eq!(a, Bv32::try_from(0b11000001u8).unwrap());\nassert_eq!(a.get(7), Bit::One);\na.set(1, Bit::One);\nassert_eq!(a, Bv32::try_from(0b11000011u8).unwrap());\nassert_eq!(a.copy_range(1..7), Bv32::try_from(0b100001u8).unwrap());\n```\n\nBit vectors behave like unsigned integers with wrap-around on overflow:\n```rust\nuse bva::{Bit, BitVector, Bv32};\n\n// Bv32 is a type alias for a Bvf with 32 bits of capacity.\nlet a = Bv32::ones(32);\nlet b = Bv32::try_from(1u32).unwrap();\nassert_eq!(b.leading_zeros(), 31);\nlet c = a + b;\nassert_eq!(c, Bv32::zeros(32));\n```\n\nGeneric traits can be used to abstract over the different bit vector implementations:\n```rust\nuse core::ops::AddAssign;\nuse bva::{Bit, BitVector, Bv, Bvd, Bvf};\n\nfn fibonnaci\u003cB: BitVector + for\u003c'a\u003e AddAssign\u003c\u0026'a B\u003e\u003e(n: usize) -\u003e B {\n    let mut f0 = B::zeros(1);\n    let mut f1 = B::ones(1);\n    if n == 0 {\n        return f0;\n    }\n\n    for _ in 1..n {\n        // Avoid overflow\n        f0.resize(f1.significant_bits() + 1, Bit::Zero);\n        // Addition is done in place\n        f0 += \u0026f1;\n        // Swap f0 and f1\n        std::mem::swap(\u0026mut f0, \u0026mut f1);\n    }\n    return f1;\n}\n\nassert_eq!(fibonnaci::\u003cBvf\u003cu8, 2\u003e\u003e(15), Bvf::\u003cu8, 2\u003e::try_from(610u16).unwrap());\nassert_eq!(fibonnaci::\u003cBvd\u003e(18), Bvd::from(2584u32));\nassert_eq!(fibonnaci::\u003cBv\u003e(19), Bv::from(4181u32));\n```\n\n## Changelog\n\n* 2024/08/18 - 0.4.0\n  * 100% function test coverage, 98% line test coverage\n    * Some bug were fixed in the process\n  * Better API and proper documentation\n  * extend, append, prepend, repeat, first, last and sign_extend functions\n  * Constructing bit vectors from array of integers\n  * Operation with unsigned integers as right hand side\n* 2024/07/07 - 0.3.0\n  * Multiplication, division and modulo operations\n  * Various helper functions\n  * Much more rigorous testing reaching high code coverage.\n* 2023/07/04 - 0.2.0\n  * Major rewrite using const generics\n  * Iterator support\n* 2020/12/20 - 0.1.0\n  * BitVector trait with fixed, dynamic and auto implementations.\n  * Conversion between all the implementations\n  * Basic arithmetic operations between the different implementations.\n  * Reading and writing bit vector in various format.\n\n## Roadmap\n\n* no-std support\n* More convenience BitVector functions\n* Signed operation support.\n* Borrowing of bits and bit slice inside a bit vector.\n* Numerical algorithms such as gcd, modular exponentiation, ...\n\n## Why\n\nNone of the existing crate really satisfied me and I wanted an implementation capable of\nminimizing dynamic memory allocations by automatically switching to fixed storage.\nI also wanted a crate that was capable of doing arithmetics on arbitrarily sized bit vectors, not\njust powers of two.\nAlso it was great practice for my rust macro writing skills.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaxelion%2Fbva","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaxelion%2Fbva","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaxelion%2Fbva/lists"}