base64url_nopad

base64url without padding library.
git clone https://git.philomathiclife.com/repos/base64url_nopad
Log | Files | Refs | README

README.md (4362B)

      1 # `base64url_nopad`
      2 
      3 [<img alt="git" src="https://git.philomathiclife.com/badges/base64url_nopad.svg" height="20">](https://git.philomathiclife.com/base64url_nopad/log.html)
      4 [<img alt="crates.io" src="https://img.shields.io/crates/v/base64url_nopad.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/base64url_nopad)
      5 [<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-base64url_nopad-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/base64url_nopad/latest/base64url_nopad/)
      6 
      7 `base64url_nopad` is a library for efficient and correct encoding and decoding of base64url without padding
      8 data. All functions that can be `const` are `const`. Great care is made to ensure _all_ arithmetic is free
      9 from "side effects" (e.g., overflow). `panic`s are avoided at all costs unless explicitly documented
     10 _including_ `panic`s related to memory allocations.
     11 
     12 ## `base64url_nopad` in action
     13 
     14 ```rust
     15 use base64url_nopad::DecodeErr;
     16 /// Length of our input to encode.
     17 const INPUT_LEN: usize = 259;
     18 /// The base64url encoded value without padding of our input.
     19 const ENCODED_VAL: &str = "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vMDEyMzQ1Njc4OTo7PD0-P0BBQkNERUZHSElKS0xNTk9QUVJTVFVWV1hZWltcXV5fYGFiY2RlZmdoaWprbG1ub3BxcnN0dXZ3eHl6e3x9fn-AgYKDhIWGh4iJiouMjY6PkJGSk5SVlpeYmZqbnJ2en6ChoqOkpaanqKmqq6ytrq-wsbKztLW2t7i5uru8vb6_wMHCw8TFxsfIycrLzM3Oz9DR0tPU1dbX2Nna29zd3t_g4eLj5OXm5-jp6uvs7e7v8PHy8_T19vf4-fr7_P3-_1MH0Q";
     20 fn main() -> Result<(), DecodeErr> {
     21     let mut input = [0; INPUT_LEN];
     22     for i in 0..=255 {
     23         input[usize::from(i)] = i;
     24     }
     25     input[256] = 83;
     26     input[257] = 7;
     27     input[258] = 209;
     28     let mut output = [0; base64url_nopad::encode_len(INPUT_LEN)];
     29     assert_eq!(base64url_nopad::encode_buffer(&input, &mut output), ENCODED_VAL);
     30     assert!(base64url_nopad::decode_len(output.len()).is_some_and(|len| len == INPUT_LEN));
     31     base64url_nopad::decode_buffer(ENCODED_VAL.as_bytes(), &mut output[..INPUT_LEN])?;
     32     assert_eq!(input, output[..INPUT_LEN]);
     33 }
     34 ```
     35 
     36 ## Cargo "features"
     37 
     38 ### `alloc`
     39 
     40 Enables support for memory allocations via [`alloc`](https://doc.rust-lang.org/alloc/).
     41 
     42 ## Correctness of code
     43 
     44 This library is written in a way that is free from any overflow, underflow, or other kinds of
     45 "arithmetic side effects". All functions that can `panic` are explicitly documented as such; and all
     46 possible `panic`s are isolated to convenience functions that `panic` instead of error. Strict encoding and
     47 decoding is performed; thus if an input contains _any_ invalid data, it is guaranteed to fail when decoding
     48 it (e.g., trailing non-zero bits).
     49 
     50 ## Minimum Supported Rust Version (MSRV)
     51 
     52 This will frequently be updated to be the same as stable. Specifically, any time stable is updated and that
     53 update has "useful" features or compilation no longer succeeds (e.g., due to new compiler lints), then MSRV
     54 will be updated.
     55 
     56 MSRV changes will correspond to a SemVer patch version bump pre-`1.0.0`; otherwise a minor version bump.
     57 
     58 ## SemVer Policy
     59 
     60 * All on-by-default features of this library are covered by SemVer
     61 * MSRV is considered exempt from SemVer as noted above
     62 
     63 ## License
     64 
     65 Licensed under either of
     66 
     67 * Apache License, Version 2.0 ([LICENSE-APACHE](https://www.apache.org/licenses/LICENSE-2.0))
     68 * MIT license ([LICENSE-MIT](https://opensource.org/licenses/MIT))
     69 
     70 at your option.
     71 
     72 ## Contribution
     73 
     74 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
     75 as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
     76 
     77 Before any PR is sent, `cargo clippy` and `cargo t` should be run _for each possible combination of "features"_
     78 using stable Rust. One easy way to achieve this is by building `ci` and invoking it with no commands in the
     79 `base64url_nopad` directory or sub-directories. You can fetch `ci` via
     80 `git clone https://git.philomathiclife.com/repos/ci`, and it can be built with `cargo build --release`.
     81 Additionally, `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features` should be run to ensure
     82 documentation can be built.
     83 
     84 ### Status
     85 
     86 The crate is only tested on the `x86_64-unknown-linux-gnu`, `x86_64-unknown-openbsd`, and `aarch64-apple-darwin`
     87 targets; but it should work on most platforms.