summaryrefslogtreecommitdiffstats
path: root/third_party/rust/base16/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/rust/base16/README.md')
-rw-r--r--third_party/rust/base16/README.md62
1 files changed, 62 insertions, 0 deletions
diff --git a/third_party/rust/base16/README.md b/third_party/rust/base16/README.md
new file mode 100644
index 0000000000..a19cc9d747
--- /dev/null
+++ b/third_party/rust/base16/README.md
@@ -0,0 +1,62 @@
+# [base16](https://crates.io/crates/base16) (hex) encoding for Rust.
+
+[![Docs](https://docs.rs/base16/badge.svg)](https://docs.rs/base16) [![CircleCI](https://circleci.com/gh/thomcc/rust-base16.svg?style=svg)](https://circleci.com/gh/thomcc/rust-base16) [![codecov](https://codecov.io/gh/thomcc/rust-base16/branch/master/graph/badge.svg)](https://codecov.io/gh/thomcc/rust-base16)
+
+This is a base16 (e.g. hexadecimal) encoding and decoding library which was initially written with an emphasis on performance.
+
+This was before Rust added SIMD, and I haven't gotten around to adding that. It's still probably the fastest non-SIMD impl.
+
+## Usage
+
+Add `base16 = "0.2"` to Cargo.toml, then:
+
+```rust
+fn main() {
+ let original_msg = "Foobar";
+ let hex_string = base16::encode_lower(original_msg);
+ assert_eq!(hex_string, "466f6f626172");
+ let decoded = base16::decode(&hex_string).unwrap();
+ assert_eq!(String::from_utf8(decoded).unwrap(), original_msg);
+}
+```
+
+More usage examples in the [docs](https://docs.rs/base16).
+
+## `no_std` Usage
+
+This crate supports use in `no_std` configurations using the following knobs.
+
+- The `"alloc"` feature, which is on by default, adds a number of helpful functions
+ that require use of the [`alloc`](https://doc.rust-lang.org/alloc/index.html) crate,
+ but not the rest of `std`. This is `no_std` compatible.
+ - Each function documents if it requires use of the `alloc` feature.
+- The `"std"` feature, which is on by default, enables the `"alloc"` feature, and
+ additionally makes `base16::DecodeError` implement the `std::error::Error` trait.
+ (Frustratingly, this trait is in `std` and not in `core` or `alloc`...)
+
+For clarity, this means that by default, we assume you are okay with use of `std`.
+
+If you'd like to disable the use of `std`, but are in an environment where you have
+an allocator (e.g. use of the [`alloc`](https://doc.rust-lang.org/alloc/index.html)
+crate is acceptable), then you require this as `alloc`-only as follows:
+
+```toml
+[dependencies]
+# Turn of use of `std` (but leave use of `alloc`).
+base16 = { version = "0.2", default-features = false, features = ["alloc"] }
+```
+
+If you just want the core `base16` functionality and none of the helpers, then
+you should turn off all features.
+
+```toml
+[dependencies]
+# Turn of use of `std` and `alloc`.
+base16 = { version = "0.2", default-features = false }
+```
+
+Both of these configurations are `no_std` compatible.
+
+# License
+
+Public domain, as explained [here](https://creativecommons.org/publicdomain/zero/1.0/legalcode)