base64_pad

base64 with padding library.
git clone https://git.philomathiclife.com/repos/base64_pad
Log | Files | Refs | README

README.md (4308B)

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