├── .github └── workflows │ └── ci.yml ├── .gitignore ├── CHANGELOG.md ├── Cargo.toml ├── LICENSE-APACHE ├── LICENSE-MIT ├── README.md ├── benches └── bench.rs ├── cliff.toml ├── clippy.toml ├── deny.toml ├── release.toml ├── rustfmt.toml ├── scripts └── changelog.sh └── src ├── lib.rs └── nibbles.rs /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: [main] 6 | pull_request: 7 | 8 | env: 9 | CARGO_TERM_COLOR: always 10 | 11 | concurrency: 12 | group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} 13 | cancel-in-progress: true 14 | 15 | jobs: 16 | test: 17 | name: Test 18 | runs-on: ubuntu-latest 19 | strategy: 20 | fail-fast: false 21 | matrix: 22 | target: [aarch64-unknown-linux-gnu, i686-unknown-linux-gnu, x86_64-unknown-linux-gnu] 23 | rust: [nightly, stable, "1.66"] # MSRV 24 | timeout-minutes: 30 25 | steps: 26 | - uses: actions/checkout@v4 27 | - uses: dtolnay/rust-toolchain@master 28 | with: 29 | toolchain: ${{ matrix.rust }} 30 | target: ${{ matrix.target }} 31 | - uses: taiki-e/setup-cross-toolchain-action@v1 32 | with: 33 | target: ${{ matrix.target }} 34 | 35 | - name: Enable type layout randomization 36 | run: echo RUSTFLAGS=${RUSTFLAGS}\ -Zrandomize-layout >> $GITHUB_ENV 37 | if: matrix.rust == 'nightly' 38 | 39 | - uses: Swatinem/rust-cache@v2 40 | 41 | - run: cargo build 42 | - run: cargo test 43 | if: matrix.rust != '1.66' # MSRV 44 | - run: cargo build --no-default-features 45 | - run: cargo test --no-default-features 46 | if: matrix.rust != '1.66' # MSRV 47 | - run: cargo test 48 | if: matrix.rust != '1.66' # MSRV 49 | - run: cargo test --all-features 50 | if: matrix.rust == 'nightly' 51 | 52 | miri: 53 | name: miri ${{ matrix.flags }} 54 | runs-on: ubuntu-latest 55 | timeout-minutes: 30 56 | strategy: 57 | fail-fast: false 58 | matrix: 59 | flags: ["--no-default-features", "", "--all-features"] 60 | env: 61 | MIRIFLAGS: -Zmiri-strict-provenance 62 | steps: 63 | - uses: actions/checkout@v4 64 | - uses: dtolnay/rust-toolchain@miri 65 | - uses: Swatinem/rust-cache@v2 66 | - run: cargo miri test ${{ matrix.flags }} 67 | 68 | feature-checks: 69 | name: feature checks 70 | runs-on: ubuntu-latest 71 | timeout-minutes: 30 72 | steps: 73 | - uses: actions/checkout@v4 74 | - uses: dtolnay/rust-toolchain@nightly 75 | - uses: taiki-e/install-action@cargo-hack 76 | - uses: Swatinem/rust-cache@v2 77 | - name: cargo hack 78 | run: cargo hack check --feature-powerset --depth 2 --all-targets 79 | 80 | clippy: 81 | runs-on: ubuntu-latest 82 | timeout-minutes: 30 83 | steps: 84 | - uses: actions/checkout@v4 85 | - uses: dtolnay/rust-toolchain@clippy 86 | - uses: Swatinem/rust-cache@v2 87 | with: 88 | cache-on-failure: true 89 | - run: cargo clippy --workspace --all-targets --all-features 90 | env: 91 | RUSTFLAGS: -Dwarnings 92 | 93 | docs: 94 | name: docs 95 | runs-on: ubuntu-latest 96 | timeout-minutes: 30 97 | steps: 98 | - uses: actions/checkout@v4 99 | - uses: dtolnay/rust-toolchain@nightly 100 | with: 101 | components: rust-docs 102 | - uses: Swatinem/rust-cache@v2 103 | - run: cargo doc --workspace --all-features --no-deps --document-private-items 104 | env: 105 | RUSTDOCFLAGS: "--cfg docsrs -D warnings" 106 | 107 | fmt: 108 | name: fmt 109 | runs-on: ubuntu-latest 110 | timeout-minutes: 30 111 | steps: 112 | - uses: actions/checkout@v4 113 | - uses: dtolnay/rust-toolchain@nightly 114 | with: 115 | components: rustfmt 116 | - run: cargo fmt --all --check 117 | 118 | deny: 119 | uses: ithacaxyz/ci/.github/workflows/deny.yml@main 120 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /target 2 | /Cargo.lock 3 | .vscode 4 | .idea 5 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | All notable changes to this project will be documented in this file. 4 | 5 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), 6 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). 7 | 8 | ## [0.3.4](https://github.com/alloy-rs/nybbles/releases/tag/v0.3.4) - 2025-01-06 9 | 10 | ### Miscellaneous Tasks 11 | 12 | - Better debug impl ([#16](https://github.com/alloy-rs/nybbles/issues/16)) 13 | 14 | ### Other 15 | 16 | - Fix 17 | - Update 18 | 19 | ## [0.3.3](https://github.com/alloy-rs/nybbles/releases/tag/v0.3.3) - 2024-12-30 20 | 21 | ### Features 22 | 23 | - Add from_repr 24 | 25 | ### Miscellaneous Tasks 26 | 27 | - Release 0.3.3 28 | 29 | ## [0.3.2](https://github.com/alloy-rs/nybbles/releases/tag/v0.3.2) - 2024-12-30 30 | 31 | ### Features 32 | 33 | - Expose smallvec_with 34 | 35 | ### Miscellaneous Tasks 36 | 37 | - Release 0.3.2 38 | 39 | ## [0.3.1](https://github.com/alloy-rs/nybbles/releases/tag/v0.3.1) - 2024-12-30 40 | 41 | ### Features 42 | 43 | - Add more raw APIs for working with slices directly ([#15](https://github.com/alloy-rs/nybbles/issues/15)) 44 | 45 | ### Miscellaneous Tasks 46 | 47 | - Release 0.3.1 48 | 49 | ### Other 50 | 51 | - Remove outdated ci 52 | 53 | ## [0.3.0](https://github.com/alloy-rs/nybbles/releases/tag/v0.3.0) - 2024-12-10 54 | 55 | ### Bug Fixes 56 | 57 | - Ci branch target ([#13](https://github.com/alloy-rs/nybbles/issues/13)) 58 | 59 | ### Dependencies 60 | 61 | - Remove path encoding ([#12](https://github.com/alloy-rs/nybbles/issues/12)) 62 | 63 | ### Features 64 | 65 | - Improve benchmarks, compare with naive implementation ([#11](https://github.com/alloy-rs/nybbles/issues/11)) 66 | 67 | ### Miscellaneous Tasks 68 | 69 | - Release 0.3.0 70 | - Sync cliff.toml 71 | 72 | ### Other 73 | 74 | - Move deny to ci ([#14](https://github.com/alloy-rs/nybbles/issues/14)) 75 | 76 | ## [0.2.1](https://github.com/alloy-rs/nybbles/releases/tag/v0.2.1) - 2024-02-26 77 | 78 | ### Documentation 79 | 80 | - Add CHANGELOG.md and cliff.toml ([#10](https://github.com/alloy-rs/nybbles/issues/10)) 81 | 82 | ### Features 83 | 84 | - Import nybbles bench from reth 85 | - Add SizeRange to proptest Arbitrary parameters 86 | 87 | ### Miscellaneous Tasks 88 | 89 | - Release 0.2.1 90 | - Add changelog script 91 | 92 | ## [0.2.0](https://github.com/alloy-rs/nybbles/releases/tag/v0.2.0) - 2024-02-26 93 | 94 | ### Bug Fixes 95 | 96 | - Add an overflow check in unpack_heap ([#6](https://github.com/alloy-rs/nybbles/issues/6)) 97 | - Out-of-bound memory read on `Nibbles::get_byte` ([#4](https://github.com/alloy-rs/nybbles/issues/4)) 98 | 99 | ### Features 100 | 101 | - Make it clear when an invalid instance is created ([#8](https://github.com/alloy-rs/nybbles/issues/8)) 102 | 103 | ### Miscellaneous Tasks 104 | 105 | - Release 0.2.0 106 | - Simplify slice implementation ([#7](https://github.com/alloy-rs/nybbles/issues/7)) 107 | - Update release.toml 108 | - Update configs 109 | 110 | ### Other 111 | 112 | - Add concurrency ([#9](https://github.com/alloy-rs/nybbles/issues/9)) 113 | 114 | ### Performance 115 | 116 | - Optimize usize::MAX check in get_byte ([#5](https://github.com/alloy-rs/nybbles/issues/5)) 117 | 118 | ### Testing 119 | 120 | - `arbitrary` feature separation ([#3](https://github.com/alloy-rs/nybbles/issues/3)) 121 | 122 | ## [0.1.2](https://github.com/alloy-rs/nybbles/releases/tag/v0.1.2) - 2023-12-20 123 | 124 | ### Bug Fixes 125 | 126 | - Assume macro 127 | 128 | ### Documentation 129 | 130 | - Add logo 131 | 132 | ### Features 133 | 134 | - More methods, examples 135 | 136 | ### Miscellaneous Tasks 137 | 138 | - Release 0.1.2 139 | - Rename macros 140 | 141 | ### Other 142 | 143 | - Merge pull request [#1](https://github.com/alloy-rs/nybbles/issues/1) from dvush/pop-idx-mut 144 | - Replace mut index with set_at 145 | - Add mutable indexing, pop 146 | 147 | ## [0.1.1](https://github.com/alloy-rs/nybbles/releases/tag/v0.1.1) - 2023-12-15 148 | 149 | ### Features 150 | 151 | - Implement Index 152 | 153 | ### Miscellaneous Tasks 154 | 155 | - Release 0.1.1 156 | - Add clippy.toml 157 | - Add release.toml 158 | 159 | ### Other 160 | 161 | - Master 162 | 163 | ## [0.1.0](https://github.com/alloy-rs/nybbles/releases/tag/v0.1.0) - 2023-12-15 164 | 165 | ### Documentation 166 | 167 | - Add more examples 168 | - Description 169 | 170 | ### Features 171 | 172 | - Initial implementation 173 | 174 | ### Other 175 | 176 | - Initial commit 177 | 178 | ### Performance 179 | 180 | - Remove useless branch on smallvec heap init 181 | 182 | 183 | -------------------------------------------------------------------------------- /Cargo.toml: -------------------------------------------------------------------------------- 1 | [package] 2 | name = "nybbles" 3 | version = "0.3.4" 4 | authors = ["DaniPopes <57450786+DaniPopes@users.noreply.github.com>"] 5 | description = "Efficient nibble-sized (4-bit) byte sequence data structure" 6 | edition = "2021" 7 | rust-version = "1.66" 8 | license = "MIT OR Apache-2.0" 9 | categories = ["data-structures", "no-std"] 10 | keywords = ["nibbles", "vector", "ethereum"] 11 | homepage = "https://github.com/alloy-rs/nybbles" 12 | repository = "https://github.com/alloy-rs/nybbles" 13 | exclude = [".github/", "deny.toml", "release.toml", "rustfmt.toml"] 14 | 15 | [dependencies] 16 | smallvec = { version = "1.0", default-features = false, features = [ 17 | "const_new", 18 | "union", 19 | ] } 20 | const-hex = { version = "1.10", default-features = false, features = ["alloc"] } 21 | 22 | # serde 23 | serde = { version = "1.0", default-features = false, optional = true, features = [ 24 | "derive", 25 | ] } 26 | 27 | # rlp 28 | alloy-rlp = { version = "0.3", default-features = false, optional = true } 29 | 30 | # arbitrary 31 | arbitrary = { version = "1.3", default-features = false, optional = true, features = [ 32 | "derive", 33 | ] } 34 | proptest = { version = "1.4", default-features = false, optional = true, features = [ 35 | "alloc", 36 | ] } 37 | 38 | [dev-dependencies] 39 | hex-literal = "0.4" 40 | criterion = "0.5" 41 | 42 | [features] 43 | default = ["std"] 44 | std = ["const-hex/std", "serde?/std", "alloy-rlp?/std", "proptest?/std"] 45 | nightly = ["smallvec/specialization", "smallvec/may_dangle"] 46 | serde = ["dep:serde", "smallvec/serde"] 47 | rlp = ["dep:alloy-rlp"] 48 | arbitrary = ["dep:arbitrary", "dep:proptest", "smallvec/arbitrary", "std"] 49 | 50 | [[bench]] 51 | name = "bench" 52 | harness = false 53 | required-features = ["arbitrary"] 54 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Permission is hereby granted, free of charge, to any 2 | person obtaining a copy of this software and associated 3 | documentation files (the "Software"), to deal in the 4 | Software without restriction, including without 5 | limitation the rights to use, copy, modify, merge, 6 | publish, distribute, sublicense, and/or sell copies of 7 | the Software, and to permit persons to whom the Software 8 | is furnished to do so, subject to the following 9 | conditions: 10 | 11 | The above copyright notice and this permission notice 12 | shall be included in all copies or substantial portions 13 | of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 16 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 17 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 18 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 19 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 20 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 21 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 22 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23 | DEALINGS IN THE SOFTWARE. 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # nybbles 2 | 3 | Efficient nibble-sized (4-bit) byte sequence data structure. 4 | -------------------------------------------------------------------------------- /benches/bench.rs: -------------------------------------------------------------------------------- 1 | use criterion::{ 2 | criterion_group, criterion_main, measurement::WallTime, BenchmarkGroup, Criterion, 3 | }; 4 | use nybbles::Nibbles; 5 | use proptest::{prelude::*, strategy::ValueTree}; 6 | use std::{hint::black_box, time::Duration}; 7 | 8 | /// Benchmarks the nibble unpacking. 9 | pub fn nibbles_benchmark(c: &mut Criterion) { 10 | let lengths = [16u64, 32, 256, 2048]; 11 | 12 | { 13 | let mut g = group(c, "unpack"); 14 | for len in lengths { 15 | g.throughput(criterion::Throughput::Bytes(len)); 16 | 17 | let id = criterion::BenchmarkId::new("naive", len); 18 | g.bench_function(id, |b| { 19 | let bytes = &get_bytes(len as usize)[..]; 20 | b.iter(|| unpack_naive(black_box(bytes))) 21 | }); 22 | 23 | let id = criterion::BenchmarkId::new("nybbles", len); 24 | g.bench_function(id, |b| { 25 | let bytes = &get_bytes(len as usize)[..]; 26 | b.iter(|| Nibbles::unpack(black_box(bytes))) 27 | }); 28 | } 29 | } 30 | 31 | { 32 | let mut g = group(c, "pack"); 33 | for len in lengths { 34 | g.throughput(criterion::Throughput::Bytes(len)); 35 | 36 | let id = criterion::BenchmarkId::new("naive", len); 37 | g.bench_function(id, |b| { 38 | let bytes = &get_nibbles(len as usize)[..]; 39 | b.iter(|| pack_naive(black_box(bytes))) 40 | }); 41 | 42 | let id = criterion::BenchmarkId::new("nybbles", len); 43 | g.bench_function(id, |b| { 44 | let bytes = &get_nibbles(len as usize); 45 | b.iter(|| black_box(bytes).pack()) 46 | }); 47 | } 48 | } 49 | } 50 | 51 | fn group<'c>(c: &'c mut Criterion, name: &str) -> BenchmarkGroup<'c, WallTime> { 52 | let mut g = c.benchmark_group(name); 53 | g.warm_up_time(Duration::from_secs(1)); 54 | g.noise_threshold(0.02); 55 | g 56 | } 57 | 58 | fn get_nibbles(len: usize) -> Nibbles { 59 | proptest::arbitrary::any_with::(len.into()) 60 | .new_tree(&mut Default::default()) 61 | .unwrap() 62 | .current() 63 | } 64 | 65 | fn get_bytes(len: usize) -> Vec { 66 | proptest::collection::vec(proptest::arbitrary::any::(), len) 67 | .new_tree(&mut Default::default()) 68 | .unwrap() 69 | .current() 70 | } 71 | 72 | fn unpack_naive(bytes: &[u8]) -> Vec { 73 | bytes.iter().flat_map(|byte| [byte >> 4, byte & 0x0f]).collect() 74 | } 75 | 76 | fn pack_naive(bytes: &[u8]) -> Vec { 77 | let chunks = bytes.chunks_exact(2); 78 | let rem = chunks.remainder(); 79 | chunks.map(|chunk| (chunk[0] << 4) | chunk[1]).chain(rem.iter().copied()).collect() 80 | } 81 | 82 | criterion_group!(benches, nibbles_benchmark); 83 | criterion_main!(benches); 84 | 85 | #[test] 86 | fn naive_equivalency() { 87 | for len in [0, 1, 2, 3, 4, 15, 16, 17, 31, 32, 33] { 88 | let bytes = get_bytes(len); 89 | let nibbles = Nibbles::unpack(&bytes); 90 | assert_eq!(unpack_naive(&bytes)[..], nibbles[..]); 91 | assert_eq!(pack_naive(&nibbles[..])[..], nibbles.pack()[..]); 92 | } 93 | } 94 | -------------------------------------------------------------------------------- /cliff.toml: -------------------------------------------------------------------------------- 1 | # Configuration file for [`git-cliff`](https://github.com/orhun/git-cliff) 2 | # See https://git-cliff.org/docs/configuration 3 | 4 | [changelog] 5 | header = """ 6 | # Changelog 7 | 8 | All notable changes to this project will be documented in this file. 9 | 10 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), 11 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n 12 | """ 13 | # https://tera.netlify.app/docs/#introduction 14 | body = """ 15 | {% if version %}\ 16 | ## [{{ version | trim_start_matches(pat="v") }}](https://github.com/alloy-rs/nybbles/releases/tag/v{{ version | trim_start_matches(pat="v") }}) - {{ timestamp | date(format="%Y-%m-%d") }} 17 | {% else %}\ 18 | ## [Unreleased](https://github.com/alloy-rs/nybbles/compare/{{ previous.version }}...HEAD) 19 | {% endif %}\ 20 | {% for group, commits in commits | group_by(attribute="group") %} 21 | ### {{ group | title }} 22 | {% for commit in commits %} 23 | - {% if commit.scope %}[{{ commit.scope }}] {% endif %}{{ commit.message | upper_first | split(pat="\\n") | first }}\ 24 | {% endfor %} 25 | {% endfor %}\n 26 | """ 27 | trim = true 28 | footer = "" 29 | 30 | [git] 31 | conventional_commits = true 32 | filter_unconventional = false 33 | commit_preprocessors = [ 34 | { pattern = '#(\d+)', replace = "[#$1](https://github.com/alloy-rs/nybbles/issues/$1)" }, 35 | ] 36 | commit_parsers = [ 37 | { message = "^[Ff]eat", group = "Features" }, 38 | { message = "^[Ff]ix", group = "Bug Fixes" }, 39 | { message = "^[Dd]oc", group = "Documentation" }, 40 | { message = ".*\\b([Dd]eps|[Dd]ependencies|[Bb]ump)\\b", group = "Dependencies" }, 41 | { message = "^[Pp]erf", group = "Performance" }, 42 | { message = "^[Rr]efactor", group = "Refactor" }, 43 | { message = ".*\\b([Ss]tyle|[Ff]mt|[Ff]ormat)\\b", group = "Styling" }, 44 | { message = "^[Tt]est", group = "Testing" }, 45 | { message = "^[Cc]hore", group = "Miscellaneous Tasks" }, 46 | 47 | { message = ".*", group = "Other" }, 48 | ] 49 | protect_breaking_commits = false 50 | filter_commits = false 51 | tag_pattern = "v[0-9]*" 52 | skip_tags = "beta|alpha" 53 | ignore_tags = "rc" 54 | sort_commits = "newest" 55 | -------------------------------------------------------------------------------- /clippy.toml: -------------------------------------------------------------------------------- 1 | msrv = "1.66" 2 | -------------------------------------------------------------------------------- /deny.toml: -------------------------------------------------------------------------------- 1 | [advisories] 2 | version = 2 3 | yanked = "warn" 4 | ignore = [] 5 | 6 | [bans] 7 | multiple-versions = "warn" 8 | wildcards = "deny" 9 | highlight = "all" 10 | 11 | [licenses] 12 | confidence-threshold = 0.9 13 | # copyleft = "deny" 14 | 15 | allow = [ 16 | "MIT", 17 | "MIT-0", 18 | "Apache-2.0", 19 | "Apache-2.0 WITH LLVM-exception", 20 | "BSD-2-Clause", 21 | "BSD-3-Clause", 22 | "ISC", 23 | "Unicode-DFS-2016", 24 | "Unicode-3.0", 25 | "Unlicense", 26 | "MPL-2.0", 27 | "Zlib", 28 | # https://github.com/briansmith/ring/issues/902 29 | "LicenseRef-ring", 30 | # https://github.com/briansmith/webpki/issues/148 31 | "LicenseRef-webpki", 32 | ] 33 | 34 | exceptions = [ 35 | # CC0 is a permissive license but somewhat unclear status for source code 36 | # so we prefer to not have dependencies using it 37 | # https://tldrlegal.com/license/creative-commons-cc0-1.0-universal 38 | { allow = ["CC0-1.0"], name = "tiny-keccak" }, 39 | ] 40 | 41 | [[licenses.clarify]] 42 | name = "ring" 43 | expression = "LicenseRef-ring" 44 | license-files = [{ path = "LICENSE", hash = 0xbd0eed23 }] 45 | 46 | [[licenses.clarify]] 47 | name = "webpki" 48 | expression = "LicenseRef-webpki" 49 | license-files = [{ path = "LICENSE", hash = 0x001c7e6c }] 50 | 51 | [sources] 52 | unknown-registry = "deny" 53 | unknown-git = "deny" 54 | -------------------------------------------------------------------------------- /release.toml: -------------------------------------------------------------------------------- 1 | # Configuration file for [`cargo-release`](https://github.com/crate-ci/cargo-release) 2 | # See: https://github.com/crate-ci/cargo-release/blob/master/docs/reference.md 3 | 4 | allow-branch = ["main"] 5 | sign-commit = true 6 | sign-tag = true 7 | shared-version = true 8 | pre-release-commit-message = "chore: release {{version}}" 9 | tag-prefix = "" # tag only once instead of per every crate 10 | pre-release-hook = ["sh", "-c", "$WORKSPACE_ROOT/scripts/changelog.sh --tag {{version}}"] 11 | -------------------------------------------------------------------------------- /rustfmt.toml: -------------------------------------------------------------------------------- 1 | reorder_imports = true 2 | use_field_init_shorthand = true 3 | use_small_heuristics = "Max" 4 | 5 | # Nightly 6 | max_width = 100 7 | comment_width = 100 8 | imports_granularity = "Crate" 9 | wrap_comments = true 10 | format_code_in_doc_comments = true 11 | doc_comment_code_block_width = 100 12 | format_macro_matchers = true 13 | -------------------------------------------------------------------------------- /scripts/changelog.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | set -e -o pipefail 3 | 4 | root=$(dirname "$(dirname "$0")") 5 | cmd=(git cliff --workdir "$root" --output "$root/CHANGELOG.md" "$@") 6 | 7 | if [ "$DRY_RUN" = "true" ]; then 8 | echo "skipping due to dry run: ${cmd[*]}" >&2 9 | exit 0 10 | else 11 | "${cmd[@]}" 12 | fi 13 | -------------------------------------------------------------------------------- /src/lib.rs: -------------------------------------------------------------------------------- 1 | #![doc = include_str!("../README.md")] 2 | #![doc( 3 | html_logo_url = "https://raw.githubusercontent.com/alloy-rs/core/main/assets/alloy.jpg", 4 | html_favicon_url = "https://raw.githubusercontent.com/alloy-rs/core/main/assets/favicon.ico" 5 | )] 6 | #![warn( 7 | missing_copy_implementations, 8 | missing_debug_implementations, 9 | missing_docs, 10 | unreachable_pub, 11 | clippy::missing_const_for_fn, 12 | rustdoc::all 13 | )] 14 | #![cfg_attr(not(test), warn(unused_crate_dependencies))] 15 | #![deny(unused_must_use, rust_2018_idioms)] 16 | #![cfg_attr(not(feature = "std"), no_std)] 17 | #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))] 18 | #![cfg_attr(feature = "nightly", feature(core_intrinsics), allow(internal_features))] 19 | 20 | #[macro_use] 21 | #[allow(unused_imports)] 22 | extern crate alloc; 23 | 24 | mod nibbles; 25 | pub use nibbles::{ 26 | common_prefix_length, get_byte, get_byte_unchecked, pack_to, pack_to_unchecked, smallvec_with, 27 | Nibbles, 28 | }; 29 | -------------------------------------------------------------------------------- /src/nibbles.rs: -------------------------------------------------------------------------------- 1 | use core::{borrow::Borrow, fmt, mem::MaybeUninit, ops::Index, slice}; 2 | use smallvec::SmallVec; 3 | 4 | #[cfg(not(feature = "nightly"))] 5 | #[allow(unused_imports)] 6 | use core::convert::{identity as likely, identity as unlikely}; 7 | #[cfg(feature = "nightly")] 8 | #[allow(unused_imports)] 9 | use core::intrinsics::{likely, unlikely}; 10 | 11 | #[cfg(not(feature = "std"))] 12 | use alloc::vec::Vec; 13 | 14 | type Repr = SmallVec<[u8; 64]>; 15 | 16 | /// Structure representing a sequence of nibbles. 17 | /// 18 | /// A nibble is a 4-bit value, and this structure is used to store the nibble sequence representing 19 | /// the keys in a Merkle Patricia Trie (MPT). 20 | /// Using nibbles simplifies trie operations and enables consistent key representation in the MPT. 21 | /// 22 | /// # Internal representation 23 | /// 24 | /// The internal representation is currently a [`SmallVec`] that stores one nibble per byte. Nibbles 25 | /// are stored inline (on the stack) up to a length of 64 nibbles, or 32 unpacked bytes. This means 26 | /// that each byte has its upper 4 bits set to zero and the lower 4 bits representing the nibble 27 | /// value. 28 | /// 29 | /// This is enforced in the public API, but it is possible to create invalid [`Nibbles`] instances 30 | /// using methods suffixed with `_unchecked`. These methods are not marked as `unsafe` as they 31 | /// are not memory-unsafe, but creating invalid values will cause unexpected behavior in other 32 | /// methods, and users should exercise caution when using them. 33 | /// 34 | /// # Examples 35 | /// 36 | /// ``` 37 | /// use nybbles::Nibbles; 38 | /// 39 | /// let bytes = [0xAB, 0xCD]; 40 | /// let nibbles = Nibbles::unpack(&bytes); 41 | /// assert_eq!(nibbles, Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D])); 42 | /// assert_eq!(nibbles[..], [0x0A, 0x0B, 0x0C, 0x0D]); 43 | /// 44 | /// let packed = nibbles.pack(); 45 | /// assert_eq!(&packed[..], &bytes[..]); 46 | /// ``` 47 | #[derive(Default, PartialEq, Eq, PartialOrd, Ord, Hash)] 48 | #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] 49 | #[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))] 50 | pub struct Nibbles(Repr); 51 | 52 | impl core::ops::Deref for Nibbles { 53 | type Target = [u8]; 54 | 55 | #[inline] 56 | fn deref(&self) -> &Self::Target { 57 | self.as_slice() 58 | } 59 | } 60 | 61 | // Override `SmallVec::from` in the default `Clone` implementation since it's not specialized for 62 | // `Copy` types. 63 | impl Clone for Nibbles { 64 | #[inline] 65 | fn clone(&self) -> Self { 66 | Self(SmallVec::from_slice(&self.0)) 67 | } 68 | 69 | #[inline] 70 | fn clone_from(&mut self, source: &Self) { 71 | self.0.clone_from(&source.0); 72 | } 73 | } 74 | 75 | impl fmt::Debug for Nibbles { 76 | #[inline] 77 | fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 78 | write!(f, "Nibbles(0x{})", const_hex::encode(self.as_slice())) 79 | } 80 | } 81 | 82 | impl From for Vec { 83 | #[inline] 84 | fn from(value: Nibbles) -> Self { 85 | value.0.into_vec() 86 | } 87 | } 88 | 89 | impl PartialEq<[u8]> for Nibbles { 90 | #[inline] 91 | fn eq(&self, other: &[u8]) -> bool { 92 | self.as_slice() == other 93 | } 94 | } 95 | 96 | impl PartialEq for [u8] { 97 | #[inline] 98 | fn eq(&self, other: &Nibbles) -> bool { 99 | self == other.as_slice() 100 | } 101 | } 102 | 103 | impl PartialOrd<[u8]> for Nibbles { 104 | #[inline] 105 | fn partial_cmp(&self, other: &[u8]) -> Option { 106 | self.as_slice().partial_cmp(other) 107 | } 108 | } 109 | 110 | impl PartialOrd for [u8] { 111 | #[inline] 112 | fn partial_cmp(&self, other: &Nibbles) -> Option { 113 | self.partial_cmp(other.as_slice()) 114 | } 115 | } 116 | 117 | impl Borrow<[u8]> for Nibbles { 118 | #[inline] 119 | fn borrow(&self) -> &[u8] { 120 | self.as_slice() 121 | } 122 | } 123 | 124 | impl core::ops::Index for Nibbles 125 | where 126 | Repr: core::ops::Index, 127 | { 128 | type Output = >::Output; 129 | 130 | #[inline] 131 | fn index(&self, index: Idx) -> &Self::Output { 132 | self.0.index(index) 133 | } 134 | } 135 | 136 | #[cfg(feature = "rlp")] 137 | impl alloy_rlp::Encodable for Nibbles { 138 | #[inline] 139 | fn length(&self) -> usize { 140 | alloy_rlp::Encodable::length(self.as_slice()) 141 | } 142 | 143 | #[inline] 144 | fn encode(&self, out: &mut dyn alloy_rlp::BufMut) { 145 | alloy_rlp::Encodable::encode(self.as_slice(), out) 146 | } 147 | } 148 | 149 | #[cfg(feature = "arbitrary")] 150 | impl proptest::arbitrary::Arbitrary for Nibbles { 151 | type Parameters = proptest::collection::SizeRange; 152 | type Strategy = proptest::strategy::Map< 153 | proptest::collection::VecStrategy>, 154 | fn(Vec) -> Self, 155 | >; 156 | 157 | #[inline] 158 | fn arbitrary_with(size: proptest::collection::SizeRange) -> Self::Strategy { 159 | use proptest::prelude::*; 160 | proptest::collection::vec(0x0..=0xf, size).prop_map(Self::from_nibbles_unchecked) 161 | } 162 | } 163 | 164 | impl Nibbles { 165 | /// Creates a new empty [`Nibbles`] instance. 166 | /// 167 | /// # Examples 168 | /// 169 | /// ``` 170 | /// # use nybbles::Nibbles; 171 | /// let nibbles = Nibbles::new(); 172 | /// assert_eq!(nibbles.len(), 0); 173 | /// ``` 174 | #[inline] 175 | pub const fn new() -> Self { 176 | Self(SmallVec::new_const()) 177 | } 178 | 179 | /// Creates a new [`Nibbles`] instance with the given capacity. 180 | /// 181 | /// # Examples 182 | /// 183 | /// ``` 184 | /// # use nybbles::Nibbles; 185 | /// let nibbles = Nibbles::with_capacity(10); 186 | /// assert_eq!(nibbles.len(), 0); 187 | /// ``` 188 | #[inline] 189 | pub fn with_capacity(capacity: usize) -> Self { 190 | Self(SmallVec::with_capacity(capacity)) 191 | } 192 | 193 | /// Creates a new [`Nibbles`] instance with the given nibbles. 194 | #[inline] 195 | pub fn from_repr(nibbles: Repr) -> Self { 196 | check_nibbles(&nibbles); 197 | Self::from_repr_unchecked(nibbles) 198 | } 199 | 200 | /// Creates a new [`Nibbles`] instance with the given nibbles. 201 | /// 202 | /// This will not unpack the bytes into nibbles, and will instead store the bytes as-is. 203 | /// 204 | /// Note that it is possible to create a [`Nibbles`] instance with invalid nibble values (i.e. 205 | /// values greater than 0xf) using this method. See [the type docs](Self) for more details. 206 | /// 207 | /// # Panics 208 | /// 209 | /// Panics if the any of the bytes is not a valid nibble (`0..=0x0f`). 210 | #[inline] 211 | pub const fn from_repr_unchecked(small_vec: Repr) -> Self { 212 | Self(small_vec) 213 | } 214 | 215 | /// Creates a new [`Nibbles`] instance by copying the given bytes. 216 | /// 217 | /// # Panics 218 | /// 219 | /// Panics if the any of the bytes is not a valid nibble (`0..=0x0f`). 220 | /// 221 | /// # Examples 222 | /// 223 | /// ``` 224 | /// # use nybbles::Nibbles; 225 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 226 | /// assert_eq!(nibbles[..], [0x0A, 0x0B, 0x0C, 0x0D]); 227 | /// ``` 228 | /// 229 | /// Invalid values will cause panics: 230 | /// 231 | /// ```should_panic 232 | /// # use nybbles::Nibbles; 233 | /// let nibbles = Nibbles::from_nibbles(&[0xFF]); 234 | /// ``` 235 | #[inline] 236 | #[track_caller] 237 | pub fn from_nibbles>(nibbles: T) -> Self { 238 | let nibbles = nibbles.as_ref(); 239 | check_nibbles(nibbles); 240 | Self::from_nibbles_unchecked(nibbles) 241 | } 242 | 243 | /// Creates a new [`Nibbles`] instance by copying the given bytes, without checking their 244 | /// validity. 245 | /// 246 | /// This will not unpack the bytes into nibbles, and will instead store the bytes as-is. 247 | /// 248 | /// Note that it is possible to create a [`Nibbles`] instance with invalid nibble values (i.e. 249 | /// values greater than 0xf) using this method. See [the type docs](Self) for more details. 250 | /// 251 | /// # Examples 252 | /// 253 | /// ``` 254 | /// # use nybbles::Nibbles; 255 | /// let nibbles = Nibbles::from_nibbles_unchecked(&[0x0A, 0x0B, 0x0C, 0x0D]); 256 | /// assert_eq!(nibbles[..], [0x0A, 0x0B, 0x0C, 0x0D]); 257 | /// 258 | /// // Invalid value! 259 | /// let nibbles = Nibbles::from_nibbles_unchecked(&[0xFF]); 260 | /// assert_eq!(nibbles[..], [0xFF]); 261 | /// ``` 262 | #[inline] 263 | pub fn from_nibbles_unchecked>(nibbles: T) -> Self { 264 | Self(SmallVec::from_slice(nibbles.as_ref())) 265 | } 266 | 267 | /// Creates a new [`Nibbles`] instance from a byte vector, without checking its validity. 268 | /// 269 | /// This will not unpack the bytes into nibbles, and will instead store the bytes as-is. 270 | /// 271 | /// Note that it is possible to create a [`Nibbles`] instance with invalid nibble values (i.e. 272 | /// values greater than 0xf) using this method. See [the type docs](Self) for more details. 273 | /// 274 | /// # Examples 275 | /// 276 | /// ``` 277 | /// # use nybbles::Nibbles; 278 | /// let nibbles = Nibbles::from_vec_unchecked(vec![0x0A, 0x0B, 0x0C, 0x0D]); 279 | /// assert_eq!(nibbles[..], [0x0A, 0x0B, 0x0C, 0x0D]); 280 | /// ``` 281 | /// 282 | /// Invalid values will cause panics: 283 | /// 284 | /// ```should_panic 285 | /// # use nybbles::Nibbles; 286 | /// let nibbles = Nibbles::from_vec(vec![0xFF]); 287 | /// ``` 288 | #[inline] 289 | #[track_caller] 290 | pub fn from_vec(vec: Vec) -> Self { 291 | check_nibbles(&vec); 292 | Self::from_vec_unchecked(vec) 293 | } 294 | 295 | /// Creates a new [`Nibbles`] instance from a byte vector, without checking its validity. 296 | /// 297 | /// Note that it is possible to create a [`Nibbles`] instance with invalid nibble values (i.e. 298 | /// values greater than 0xf) using this method. See [the type docs](Self) for more details. 299 | /// 300 | /// # Examples 301 | /// 302 | /// ``` 303 | /// # use nybbles::Nibbles; 304 | /// let nibbles = Nibbles::from_vec_unchecked(vec![0x0A, 0x0B, 0x0C, 0x0D]); 305 | /// assert_eq!(nibbles[..], [0x0A, 0x0B, 0x0C, 0x0D]); 306 | /// 307 | /// // Invalid value! 308 | /// let nibbles = Nibbles::from_vec_unchecked(vec![0xFF]); 309 | /// assert_eq!(nibbles[..], [0xFF]); 310 | /// ``` 311 | #[inline] 312 | pub fn from_vec_unchecked(vec: Vec) -> Self { 313 | Self(SmallVec::from_vec(vec)) 314 | } 315 | 316 | /// Converts a byte slice into a [`Nibbles`] instance containing the nibbles (half-bytes or 4 317 | /// bits) that make up the input byte data. 318 | /// 319 | /// # Panics 320 | /// 321 | /// Panics if the length of the input is greater than `usize::MAX / 2`. 322 | /// 323 | /// # Examples 324 | /// 325 | /// ``` 326 | /// # use nybbles::Nibbles; 327 | /// let nibbles = Nibbles::unpack(&[0xAB, 0xCD]); 328 | /// assert_eq!(nibbles[..], [0x0A, 0x0B, 0x0C, 0x0D]); 329 | /// ``` 330 | #[inline] 331 | pub fn unpack>(data: T) -> Self { 332 | Self::unpack_(data.as_ref()) 333 | } 334 | 335 | #[inline] 336 | fn unpack_(data: &[u8]) -> Self { 337 | let unpacked_len = 338 | data.len().checked_mul(2).expect("trying to unpack usize::MAX / 2 bytes"); 339 | Self(unsafe { smallvec_with(unpacked_len, |out| Self::unpack_to_unchecked(data, out)) }) 340 | } 341 | 342 | /// Unpacks into the given slice rather than allocating a new [`Nibbles`] instance. 343 | #[inline] 344 | pub fn unpack_to(data: &[u8], out: &mut [u8]) { 345 | assert!(out.len() >= data.len() * 2); 346 | // SAFETY: asserted length. 347 | unsafe { 348 | let out = slice::from_raw_parts_mut(out.as_mut_ptr().cast(), out.len()); 349 | Self::unpack_to_unchecked(data, out) 350 | } 351 | } 352 | 353 | /// Unpacks into the given slice rather than allocating a new [`Nibbles`] instance. 354 | /// 355 | /// # Safety 356 | /// 357 | /// `out` must be valid for at least `data.len() * 2` bytes. 358 | #[inline] 359 | pub unsafe fn unpack_to_unchecked(data: &[u8], out: &mut [MaybeUninit]) { 360 | debug_assert!(out.len() >= data.len() * 2); 361 | let ptr = out.as_mut_ptr().cast::(); 362 | for (i, &byte) in data.iter().enumerate() { 363 | ptr.add(i * 2).write(byte >> 4); 364 | ptr.add(i * 2 + 1).write(byte & 0x0f); 365 | } 366 | } 367 | 368 | /// Packs the nibbles into the given slice. 369 | /// 370 | /// This method combines each pair of consecutive nibbles into a single byte, 371 | /// effectively reducing the size of the data by a factor of two. 372 | /// If the number of nibbles is odd, the last nibble is shifted left by 4 bits and 373 | /// added to the packed byte vector. 374 | /// 375 | /// # Examples 376 | /// 377 | /// ``` 378 | /// # use nybbles::Nibbles; 379 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 380 | /// assert_eq!(nibbles.pack()[..], [0xAB, 0xCD]); 381 | /// ``` 382 | #[inline] 383 | pub fn pack(&self) -> SmallVec<[u8; 32]> { 384 | let packed_len = (self.len() + 1) / 2; 385 | unsafe { smallvec_with(packed_len, |out| self.pack_to_unchecked2(out)) } 386 | } 387 | 388 | /// Packs the nibbles into the given slice. 389 | /// 390 | /// See [`pack`](Self::pack) for more information. 391 | /// 392 | /// # Panics 393 | /// 394 | /// Panics if the slice is not at least `(self.len() + 1) / 2` bytes long. 395 | /// 396 | /// # Examples 397 | /// 398 | /// ``` 399 | /// # use nybbles::Nibbles; 400 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 401 | /// let mut packed = [0; 2]; 402 | /// nibbles.pack_to(&mut packed); 403 | /// assert_eq!(packed[..], [0xAB, 0xCD]); 404 | /// ``` 405 | #[inline] 406 | #[track_caller] 407 | pub fn pack_to(&self, out: &mut [u8]) { 408 | pack_to(self, out); 409 | } 410 | 411 | /// Packs the nibbles into the given pointer. 412 | /// 413 | /// See [`pack`](Self::pack) for more information. 414 | /// 415 | /// # Safety 416 | /// 417 | /// `ptr` must be valid for at least `(self.len() + 1) / 2` bytes. 418 | /// 419 | /// # Examples 420 | /// 421 | /// ``` 422 | /// # use nybbles::Nibbles; 423 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 424 | /// let mut packed = [0; 2]; 425 | /// // SAFETY: enough capacity. 426 | /// unsafe { nibbles.pack_to_unchecked(packed.as_mut_ptr()) }; 427 | /// assert_eq!(packed[..], [0xAB, 0xCD]); 428 | /// ``` 429 | #[inline] 430 | #[deprecated = "prefer using `pack_to` or `pack_to_unchecked2` instead"] 431 | pub unsafe fn pack_to_unchecked(&self, ptr: *mut u8) { 432 | self.pack_to_unchecked2(slice::from_raw_parts_mut(ptr.cast(), (self.len() + 1) / 2)); 433 | } 434 | 435 | /// Packs the nibbles into the given slice without checking its length. 436 | /// 437 | /// # Safety 438 | /// 439 | /// `out` must be valid for at least `(self.len() + 1) / 2` bytes. 440 | #[inline] 441 | pub unsafe fn pack_to_unchecked2(&self, out: &mut [MaybeUninit]) { 442 | pack_to_unchecked(self, out); 443 | } 444 | 445 | /// Gets the byte at the given index by combining two consecutive nibbles. 446 | /// 447 | /// # Examples 448 | /// 449 | /// ``` 450 | /// # use nybbles::Nibbles; 451 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 452 | /// assert_eq!(nibbles.get_byte(0), Some(0xAB)); 453 | /// assert_eq!(nibbles.get_byte(1), Some(0xBC)); 454 | /// assert_eq!(nibbles.get_byte(2), Some(0xCD)); 455 | /// assert_eq!(nibbles.get_byte(3), None); 456 | /// ``` 457 | #[inline] 458 | pub fn get_byte(&self, i: usize) -> Option { 459 | get_byte(self, i) 460 | } 461 | 462 | /// Gets the byte at the given index by combining two consecutive nibbles. 463 | /// 464 | /// # Safety 465 | /// 466 | /// `i..i + 1` must be in range. 467 | /// 468 | /// # Examples 469 | /// 470 | /// ``` 471 | /// # use nybbles::Nibbles; 472 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 473 | /// // SAFETY: in range. 474 | /// unsafe { 475 | /// assert_eq!(nibbles.get_byte_unchecked(0), 0xAB); 476 | /// assert_eq!(nibbles.get_byte_unchecked(1), 0xBC); 477 | /// assert_eq!(nibbles.get_byte_unchecked(2), 0xCD); 478 | /// } 479 | /// ``` 480 | #[inline] 481 | pub unsafe fn get_byte_unchecked(&self, i: usize) -> u8 { 482 | get_byte_unchecked(self, i) 483 | } 484 | 485 | /// Increments the nibble sequence by one. 486 | #[inline] 487 | pub fn increment(&self) -> Option { 488 | let mut incremented = self.clone(); 489 | 490 | for nibble in incremented.0.iter_mut().rev() { 491 | debug_assert!(*nibble <= 0xf); 492 | if *nibble < 0xf { 493 | *nibble += 1; 494 | return Some(incremented); 495 | } else { 496 | *nibble = 0; 497 | } 498 | } 499 | 500 | None 501 | } 502 | 503 | /// The last element of the hex vector is used to determine whether the nibble sequence 504 | /// represents a leaf or an extension node. If the last element is 0x10 (16), then it's a leaf. 505 | #[inline] 506 | pub fn is_leaf(&self) -> bool { 507 | self.last() == Some(16) 508 | } 509 | 510 | /// Returns `true` if this nibble sequence starts with the given prefix. 511 | #[inline] 512 | pub fn has_prefix(&self, other: &[u8]) -> bool { 513 | self.starts_with(other) 514 | } 515 | 516 | /// Returns the nibble at the given index. 517 | /// 518 | /// # Panics 519 | /// 520 | /// Panics if the index is out of bounds. 521 | #[inline] 522 | #[track_caller] 523 | pub fn at(&self, i: usize) -> usize { 524 | self[i] as usize 525 | } 526 | 527 | /// Sets the nibble at the given index. 528 | /// 529 | /// # Panics 530 | /// 531 | /// Panics if the index is out of bounds, or if `value` is not a valid nibble (`0..=0x0f`). 532 | #[inline] 533 | #[track_caller] 534 | pub fn set_at(&mut self, i: usize, value: u8) { 535 | assert!(value <= 0xf); 536 | self.set_at_unchecked(i, value); 537 | } 538 | 539 | /// Sets the nibble at the given index, without checking its validity. 540 | /// 541 | /// # Panics 542 | /// 543 | /// Panics if the index is out of bounds. 544 | #[inline] 545 | #[track_caller] 546 | pub fn set_at_unchecked(&mut self, i: usize, value: u8) { 547 | self.0[i] = value; 548 | } 549 | 550 | /// Returns the first nibble of this nibble sequence. 551 | #[inline] 552 | pub fn first(&self) -> Option { 553 | self.0.first().copied() 554 | } 555 | 556 | /// Returns the last nibble of this nibble sequence. 557 | #[inline] 558 | pub fn last(&self) -> Option { 559 | self.0.last().copied() 560 | } 561 | 562 | /// Returns the length of the common prefix between this nibble sequence and the given. 563 | /// 564 | /// # Examples 565 | /// 566 | /// ``` 567 | /// # use nybbles::Nibbles; 568 | /// let a = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F]); 569 | /// let b = &[0x0A, 0x0B, 0x0C, 0x0E]; 570 | /// assert_eq!(a.common_prefix_length(b), 3); 571 | /// ``` 572 | #[inline] 573 | pub fn common_prefix_length(&self, other: &[u8]) -> usize { 574 | common_prefix_length(self, other) 575 | } 576 | 577 | /// Returns a reference to the underlying byte slice. 578 | #[inline] 579 | pub fn as_slice(&self) -> &[u8] { 580 | &self.0 581 | } 582 | 583 | /// Returns a mutable reference to the underlying byte slice. 584 | /// 585 | /// Note that it is possible to create invalid [`Nibbles`] instances using this method. See 586 | /// [the type docs](Self) for more details. 587 | #[inline] 588 | pub fn as_mut_slice_unchecked(&mut self) -> &mut [u8] { 589 | &mut self.0 590 | } 591 | 592 | /// Returns a mutable reference to the underlying byte vector. 593 | /// 594 | /// Note that it is possible to create invalid [`Nibbles`] instances using this method. See 595 | /// [the type docs](Self) for more details. 596 | #[inline] 597 | pub fn as_mut_vec_unchecked(&mut self) -> &mut Repr { 598 | &mut self.0 599 | } 600 | 601 | /// Slice the current nibbles within the provided index range. 602 | /// 603 | /// # Panics 604 | /// 605 | /// Panics if the range is out of bounds. 606 | #[inline] 607 | #[track_caller] 608 | pub fn slice(&self, range: I) -> Self 609 | where 610 | Self: Index, 611 | { 612 | Self::from_nibbles_unchecked(&self[range]) 613 | } 614 | 615 | /// Join two nibbles together. 616 | #[inline] 617 | pub fn join(&self, b: &Self) -> Self { 618 | let mut nibbles = SmallVec::with_capacity(self.len() + b.len()); 619 | nibbles.extend_from_slice(self); 620 | nibbles.extend_from_slice(b); 621 | Self(nibbles) 622 | } 623 | 624 | /// Pushes a nibble to the end of the current nibbles. 625 | /// 626 | /// # Panics 627 | /// 628 | /// Panics if the nibble is not a valid nibble (`0..=0x0f`). 629 | #[inline] 630 | #[track_caller] 631 | pub fn push(&mut self, nibble: u8) { 632 | assert!(nibble <= 0xf); 633 | self.push_unchecked(nibble); 634 | } 635 | 636 | /// Pushes a nibble to the end of the current nibbles without checking its validity. 637 | /// 638 | /// Note that it is possible to create invalid [`Nibbles`] instances using this method. See 639 | /// [the type docs](Self) for more details. 640 | #[inline] 641 | pub fn push_unchecked(&mut self, nibble: u8) { 642 | self.0.push(nibble); 643 | } 644 | 645 | /// Pops a nibble from the end of the current nibbles. 646 | #[inline] 647 | pub fn pop(&mut self) -> Option { 648 | self.0.pop() 649 | } 650 | 651 | /// Extend the current nibbles with another nibbles. 652 | #[inline] 653 | pub fn extend_from_slice(&mut self, b: &Nibbles) { 654 | self.0.extend_from_slice(b.as_slice()); 655 | } 656 | 657 | /// Extend the current nibbles with another byte slice. 658 | /// 659 | /// Note that it is possible to create invalid [`Nibbles`] instances using this method. See 660 | /// [the type docs](Self) for more details. 661 | #[inline] 662 | pub fn extend_from_slice_unchecked(&mut self, b: &[u8]) { 663 | self.0.extend_from_slice(b); 664 | } 665 | 666 | /// Truncates the current nibbles to the given length. 667 | #[inline] 668 | pub fn truncate(&mut self, new_len: usize) { 669 | self.0.truncate(new_len); 670 | } 671 | 672 | /// Clears the current nibbles. 673 | #[inline] 674 | pub fn clear(&mut self) { 675 | self.0.clear(); 676 | } 677 | } 678 | 679 | /// Gets the byte at the given index by combining two consecutive nibbles. 680 | /// 681 | /// # Examples 682 | /// 683 | /// ``` 684 | /// # use nybbles::get_byte; 685 | /// let nibbles: &[u8] = &[0x0A, 0x0B, 0x0C, 0x0D]; 686 | /// assert_eq!(get_byte(nibbles, 0), Some(0xAB)); 687 | /// assert_eq!(get_byte(nibbles, 1), Some(0xBC)); 688 | /// assert_eq!(get_byte(nibbles, 2), Some(0xCD)); 689 | /// assert_eq!(get_byte(nibbles, 3), None); 690 | /// ``` 691 | #[inline] 692 | pub fn get_byte(nibbles: &[u8], i: usize) -> Option { 693 | if likely((i < usize::MAX) & (i.wrapping_add(1) < nibbles.len())) { 694 | Some(unsafe { get_byte_unchecked(nibbles, i) }) 695 | } else { 696 | None 697 | } 698 | } 699 | 700 | /// Gets the byte at the given index by combining two consecutive nibbles. 701 | /// 702 | /// # Safety 703 | /// 704 | /// `i..i + 1` must be in range. 705 | /// 706 | /// # Examples 707 | /// 708 | /// ``` 709 | /// # use nybbles::get_byte_unchecked; 710 | /// let nibbles: &[u8] = &[0x0A, 0x0B, 0x0C, 0x0D]; 711 | /// // SAFETY: in range. 712 | /// unsafe { 713 | /// assert_eq!(get_byte_unchecked(nibbles, 0), 0xAB); 714 | /// assert_eq!(get_byte_unchecked(nibbles, 1), 0xBC); 715 | /// assert_eq!(get_byte_unchecked(nibbles, 2), 0xCD); 716 | /// } 717 | /// ``` 718 | #[inline] 719 | pub unsafe fn get_byte_unchecked(nibbles: &[u8], i: usize) -> u8 { 720 | debug_assert!( 721 | i < usize::MAX && i + 1 < nibbles.len(), 722 | "index {i}..{} out of bounds of {}", 723 | i + 1, 724 | nibbles.len() 725 | ); 726 | let hi = *nibbles.get_unchecked(i); 727 | let lo = *nibbles.get_unchecked(i + 1); 728 | (hi << 4) | lo 729 | } 730 | 731 | /// Packs the nibbles into the given slice. 732 | /// 733 | /// See [`Nibbles::pack`] for more information. 734 | /// 735 | /// # Panics 736 | /// 737 | /// Panics if the slice is not at least `(self.len() + 1) / 2` bytes long. 738 | /// 739 | /// # Examples 740 | /// 741 | /// ``` 742 | /// # use nybbles::Nibbles; 743 | /// let nibbles = Nibbles::from_nibbles(&[0x0A, 0x0B, 0x0C, 0x0D]); 744 | /// let mut packed = [0; 2]; 745 | /// nibbles.pack_to(&mut packed); 746 | /// assert_eq!(packed[..], [0xAB, 0xCD]); 747 | /// ``` 748 | #[inline] 749 | pub fn pack_to(nibbles: &[u8], out: &mut [u8]) { 750 | assert!(out.len() >= (nibbles.len() + 1) / 2); 751 | // SAFETY: asserted length. 752 | unsafe { 753 | let out = slice::from_raw_parts_mut(out.as_mut_ptr().cast(), out.len()); 754 | pack_to_unchecked(nibbles, out) 755 | } 756 | } 757 | 758 | /// Packs the nibbles into the given slice without checking its length. 759 | /// 760 | /// # Safety 761 | /// 762 | /// `out` must be valid for at least `(self.len() + 1) / 2` bytes. 763 | #[inline] 764 | pub unsafe fn pack_to_unchecked(nibbles: &[u8], out: &mut [MaybeUninit]) { 765 | let len = nibbles.len(); 766 | debug_assert!(out.len() >= (len + 1) / 2); 767 | let ptr = out.as_mut_ptr().cast::(); 768 | for i in 0..len / 2 { 769 | ptr.add(i).write(get_byte_unchecked(nibbles, i * 2)); 770 | } 771 | if len % 2 != 0 { 772 | let i = len / 2; 773 | ptr.add(i).write(nibbles.last().unwrap_unchecked() << 4); 774 | } 775 | } 776 | 777 | /// Returns the length of the common prefix between the two slices. 778 | /// 779 | /// # Examples 780 | /// 781 | /// ``` 782 | /// # use nybbles::common_prefix_length; 783 | /// let a = &[0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F]; 784 | /// let b = &[0x0A, 0x0B, 0x0C, 0x0E]; 785 | /// assert_eq!(common_prefix_length(a, b), 3); 786 | /// ``` 787 | #[inline] 788 | pub fn common_prefix_length(a: &[u8], b: &[u8]) -> usize { 789 | let len = core::cmp::min(a.len(), b.len()); 790 | let a = &a[..len]; 791 | let b = &b[..len]; 792 | for i in 0..len { 793 | if a[i] != b[i] { 794 | return i; 795 | } 796 | } 797 | len 798 | } 799 | 800 | /// Initializes a smallvec with the given length and a closure that initializes the buffer. 801 | /// 802 | /// Optimized version of `SmallVec::with_capacity` + `f()` + `.set_len`. 803 | /// 804 | /// # Safety 805 | /// 806 | /// The closure must fully initialize the buffer with the given length. 807 | #[inline] 808 | pub unsafe fn smallvec_with( 809 | len: usize, 810 | f: impl FnOnce(&mut [MaybeUninit]), 811 | ) -> SmallVec<[u8; N]> { 812 | let mut buf = smallvec_with_len::(len); 813 | f(unsafe { slice::from_raw_parts_mut(buf.as_mut_ptr().cast(), len) }); 814 | buf 815 | } 816 | 817 | #[inline] 818 | #[allow(clippy::uninit_vec)] 819 | unsafe fn smallvec_with_len(len: usize) -> SmallVec<[u8; N]> { 820 | if likely(len <= N) { 821 | SmallVec::from_buf_and_len_unchecked(MaybeUninit::<[u8; N]>::uninit(), len) 822 | } else { 823 | let mut vec = Vec::with_capacity(len); 824 | unsafe { vec.set_len(len) }; 825 | SmallVec::from_vec(vec) 826 | } 827 | } 828 | 829 | #[inline] 830 | #[track_caller] 831 | fn check_nibbles(nibbles: &[u8]) { 832 | if !valid_nibbles(nibbles) { 833 | panic_invalid_nibbles(); 834 | } 835 | } 836 | 837 | fn valid_nibbles(nibbles: &[u8]) -> bool { 838 | nibbles.iter().all(|&nibble| nibble <= 0xf) 839 | } 840 | 841 | #[cold] 842 | #[track_caller] 843 | const fn panic_invalid_nibbles() -> ! { 844 | panic!("attempted to create invalid nibbles"); 845 | } 846 | 847 | #[cfg(test)] 848 | mod tests { 849 | use super::*; 850 | use hex_literal::hex; 851 | 852 | #[test] 853 | fn pack_nibbles() { 854 | let tests = [ 855 | (&[][..], &[][..]), 856 | (&[0xa], &[0xa0]), 857 | (&[0xa, 0x0], &[0xa0]), 858 | (&[0xa, 0xb], &[0xab]), 859 | (&[0xa, 0xb, 0x2], &[0xab, 0x20]), 860 | (&[0xa, 0xb, 0x2, 0x0], &[0xab, 0x20]), 861 | (&[0xa, 0xb, 0x2, 0x7], &[0xab, 0x27]), 862 | ]; 863 | for (input, expected) in tests { 864 | assert!(valid_nibbles(input)); 865 | let nibbles = Nibbles::from_nibbles(input); 866 | let encoded = nibbles.pack(); 867 | assert_eq!(&encoded[..], expected); 868 | } 869 | } 870 | 871 | #[test] 872 | fn slice() { 873 | const RAW: &[u8] = &hex!("05010406040a040203030f010805020b050c04070003070e0909070f010b0a0805020301070c0a0902040b0f000f0006040a04050f020b090701000a0a040b"); 874 | 875 | #[track_caller] 876 | fn test_slice(range: I, expected: &[u8]) 877 | where 878 | Nibbles: Index, 879 | { 880 | let nibbles = Nibbles::from_nibbles_unchecked(RAW); 881 | let sliced = nibbles.slice(range); 882 | assert_eq!(sliced, Nibbles::from_nibbles(expected)); 883 | assert_eq!(sliced.as_slice(), expected); 884 | } 885 | 886 | test_slice(0..0, &[]); 887 | test_slice(0..1, &[0x05]); 888 | test_slice(1..1, &[]); 889 | test_slice(1..=1, &[0x01]); 890 | test_slice(0..=1, &[0x05, 0x01]); 891 | test_slice(0..2, &[0x05, 0x01]); 892 | 893 | test_slice(..0, &[]); 894 | test_slice(..1, &[0x05]); 895 | test_slice(..=1, &[0x05, 0x01]); 896 | test_slice(..2, &[0x05, 0x01]); 897 | 898 | test_slice(.., RAW); 899 | test_slice(..RAW.len(), RAW); 900 | test_slice(0.., RAW); 901 | test_slice(0..RAW.len(), RAW); 902 | } 903 | 904 | #[test] 905 | fn indexing() { 906 | let mut nibbles = Nibbles::from_nibbles([0x0A]); 907 | assert_eq!(nibbles.at(0), 0x0A); 908 | nibbles.set_at(0, 0x0B); 909 | assert_eq!(nibbles.at(0), 0x0B); 910 | } 911 | 912 | #[test] 913 | fn push_pop() { 914 | let mut nibbles = Nibbles::new(); 915 | nibbles.push(0x0A); 916 | assert_eq!(nibbles[0], 0x0A); 917 | assert_eq!(nibbles.len(), 1); 918 | 919 | assert_eq!(nibbles.pop(), Some(0x0A)); 920 | assert_eq!(nibbles.len(), 0); 921 | } 922 | 923 | #[test] 924 | fn get_byte_max() { 925 | let nibbles = Nibbles::from_nibbles([0x0A, 0x0B, 0x0C, 0x0D]); 926 | assert_eq!(nibbles.get_byte(usize::MAX), None); 927 | } 928 | 929 | #[cfg(feature = "arbitrary")] 930 | mod arbitrary { 931 | use super::*; 932 | use proptest::{collection::vec, prelude::*}; 933 | 934 | proptest::proptest! { 935 | #[test] 936 | #[cfg_attr(miri, ignore = "no proptest")] 937 | fn pack_unpack_roundtrip(input in vec(any::(), 0..64)) { 938 | let nibbles = Nibbles::unpack(&input); 939 | prop_assert!(valid_nibbles(&nibbles)); 940 | let packed = nibbles.pack(); 941 | prop_assert_eq!(&packed[..], input); 942 | } 943 | } 944 | } 945 | } 946 | --------------------------------------------------------------------------------