diff options
Diffstat (limited to 'vendor/tinystr/README.md')
| -rw-r--r-- | vendor/tinystr/README.md | 116 |
1 files changed, 37 insertions, 79 deletions
diff --git a/vendor/tinystr/README.md b/vendor/tinystr/README.md index 15a8338be..96b3f955f 100644 --- a/vendor/tinystr/README.md +++ b/vendor/tinystr/README.md @@ -1,95 +1,53 @@ -# tinystr [](https://crates.io/crates/tinystr) [](https://travis-ci.org/zbraniecki/tinystr) [](https://coveralls.io/github/zbraniecki/tinystr?branch=master) +# tinystr [](https://crates.io/crates/tinystr) -`tinystr` is a small ASCII-only bounded length string representation. +`tinystr` is a utility crate of the [`ICU4X`] project. -Usage ------ +It includes [`TinyAsciiStr`], a core API for representing small ASCII-only bounded length strings. -```rust -use tinystr::{TinyStr4, TinyStr8, TinyStr16, TinyStrAuto}; - -fn main() { - let s1: TinyStr4 = "tEsT".parse() - .expect("Failed to parse."); - - assert_eq!(s1, "tEsT"); - assert_eq!(s1.to_ascii_uppercase(), "TEST"); - assert_eq!(s1.to_ascii_lowercase(), "test"); - assert_eq!(s1.to_ascii_titlecase(), "Test"); - assert_eq!(s1.is_ascii_alphanumeric(), true); +It is optimized for operations on strings of size 8 or smaller. When use cases involve comparison +and conversion of strings for lowercase/uppercase/titlecase, or checking +numeric/alphabetic/alphanumeric, `TinyAsciiStr` is the edge performance library. - let s2: TinyStr8 = "New York".parse() - .expect("Failed to parse."); +## Examples - assert_eq!(s2, "New York"); - assert_eq!(s2.to_ascii_uppercase(), "NEW YORK"); - assert_eq!(s2.to_ascii_lowercase(), "new york"); - assert_eq!(s2.to_ascii_titlecase(), "New york"); - assert_eq!(s2.is_ascii_alphanumeric(), false); +```rust +use tinystr::TinyAsciiStr; - let s3: TinyStr16 = "metaMoRphosis123".parse() - .expect("Failed to parse."); +let s1: TinyAsciiStr<4> = "tEsT".parse().expect("Failed to parse."); - assert_eq!(s3, "metaMoRphosis123"); - assert_eq!(s3.to_ascii_uppercase(), "METAMORPHOSIS123"); - assert_eq!(s3.to_ascii_lowercase(), "metamorphosis123"); - assert_eq!(s3.to_ascii_titlecase(), "Metamorphosis123"); - assert_eq!(s3.is_ascii_alphanumeric(), true); +assert_eq!(s1, "tEsT"); +assert_eq!(s1.to_ascii_uppercase(), "TEST"); +assert_eq!(s1.to_ascii_lowercase(), "test"); +assert_eq!(s1.to_ascii_titlecase(), "Test"); +assert_eq!(s1.is_ascii_alphanumeric(), true); +assert_eq!(s1.is_ascii_numeric(), false); - let s4: TinyStrAuto = "shortNoAlloc".parse().unwrap(); - assert!(matches!(s4, TinyStrAuto::Tiny { .. })); - assert_eq!(s4, "shortNoAlloc"); +let s2 = TinyAsciiStr::<8>::try_from_raw(*b"New York") + .expect("Failed to parse."); - let s5: TinyStrAuto = "longFallbackToHeap".parse().unwrap(); - assert!(matches!(s4, TinyStrAuto::Heap { .. })); - assert_eq!(s4, "shortNoAlloc"); -} +assert_eq!(s2, "New York"); +assert_eq!(s2.to_ascii_uppercase(), "NEW YORK"); +assert_eq!(s2.to_ascii_lowercase(), "new york"); +assert_eq!(s2.to_ascii_titlecase(), "New york"); +assert_eq!(s2.is_ascii_alphanumeric(), false); ``` -Details -------- - -The crate provides three structs and an enum: - * `TinyStr4` an ASCII-only string limited to 4 characters. - * `TinyStr8` an ASCII-only string limited to 8 characters. - * `TinyStr16` an ASCII-only string limited to 16 characters. - * `TinyStrAuto` (enum): - * `Tiny` when the string is 16 characters or less. - * `Heap` when the string is 17 or more characters. - -The structs stores the characters as `u32`/`u64`/`u128` and uses bitmasking to provide basic string manipulation operations: - * is_ascii_numeric - * is_ascii_alphabetic - * is_ascii_alphanumeric - * to_ascii_lowercase - * to_ascii_uppercase - * to_ascii_titlecase - * PartialEq - -`TinyStrAuto` stores the string as a TinyStr16 when it is short enough, or else falls back to a standard `String`. You should use TinyStrAuto when you expect most strings to be 16 characters or smaller, but occasionally you receive one that exceeds that length. Unlike the structs, `TinyStrAuto` does not implement `Copy`. - -This set is sufficient for certain classes of uses such as `unic-langid` libraries. - -no_std ------- - -Disable the `std` feature of this crate to make it `#[no_std]`. Doing so disables `TinyStrAuto`. You -can re-enable `TinyStrAuto` in `#[no_std]` mode by enabling the `alloc` feature. - -Performance ------------ +## Details -For those uses, TinyStr provides [performance characteristics](https://github.com/zbraniecki/tinystr/wiki/Performance) much better than the regular `String`. +When strings are of size 8 or smaller, the struct transforms the strings as `u32`/`u64` and uses +bitmasking to provide basic string manipulation operations: +* `is_ascii_numeric` +* `is_ascii_alphabetic` +* `is_ascii_alphanumeric` +* `to_ascii_lowercase` +* `to_ascii_uppercase` +* `to_ascii_titlecase` +* `PartialEq` -Status ------- +`TinyAsciiStr` will fall back to `u8` character manipulation for strings of length greater than 8. -The crate is fully functional and ready to be used in production. -The capabilities can be extended. +[`ICU4X`]: ../icu/index.html -#### License +## More Information -<sup> -Licensed under either of <a href="LICENSE-APACHE">Apache License, Version -2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. -</sup +For more information on development, authorship, contributing etc. please visit [`ICU4X home page`](https://github.com/unicode-org/icu4x). |