vendor/tinystr/src/lib.rs

   1 // This file is part of ICU4X. For terms of use, please see the file
   2 // called LICENSE at the top level of the ICU4X source tree
   3 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
   4
   5 //! `tinystr` is a utility crate of the [`ICU4X`] project.
   6 //!
   7 //! It includes [`TinyAsciiStr`], a core API for representing small ASCII-only bounded length strings.
   8 //!
   9 //! It is optimized for operations on strings of size 8 or smaller. When use cases involve comparison
  10 //! and conversion of strings for lowercase/uppercase/titlecase, or checking
  11 //! numeric/alphabetic/alphanumeric, `TinyAsciiStr` is the edge performance library.
  12 //!
  13 //! # Examples
  14 //!
  15 //! ```rust
  16 //! use tinystr::TinyAsciiStr;
  17 //!
  18 //! let s1: TinyAsciiStr<4> = "tEsT".parse().expect("Failed to parse.");
  19 //!
  20 //! assert_eq!(s1, "tEsT");
  21 //! assert_eq!(s1.to_ascii_uppercase(), "TEST");
  22 //! assert_eq!(s1.to_ascii_lowercase(), "test");
  23 //! assert_eq!(s1.to_ascii_titlecase(), "Test");
  24 //! assert_eq!(s1.is_ascii_alphanumeric(), true);
  25 //! assert_eq!(s1.is_ascii_numeric(), false);
  26 //!
  27 //! let s2 = TinyAsciiStr::<8>::try_from_raw(*b"New York")
  28 //!     .expect("Failed to parse.");
  29 //!
  30 //! assert_eq!(s2, "New York");
  31 //! assert_eq!(s2.to_ascii_uppercase(), "NEW YORK");
  32 //! assert_eq!(s2.to_ascii_lowercase(), "new york");
  33 //! assert_eq!(s2.to_ascii_titlecase(), "New york");
  34 //! assert_eq!(s2.is_ascii_alphanumeric(), false);
  35 //! ```
  36 //!
  37 //! # Details
  38 //!
  39 //! When strings are of size 8 or smaller, the struct transforms the strings as `u32`/`u64` and uses
  40 //! bitmasking to provide basic string manipulation operations:
  41 //! * `is_ascii_numeric`
  42 //! * `is_ascii_alphabetic`
  43 //! * `is_ascii_alphanumeric`
  44 //! * `to_ascii_lowercase`
  45 //! * `to_ascii_uppercase`
  46 //! * `to_ascii_titlecase`
  47 //! * `PartialEq`
  48 //!
  49 //! `TinyAsciiStr` will fall back to `u8` character manipulation for strings of length greater than 8.
  50
  51 //!
  52 //! [`ICU4X`]: ../icu/index.html
  53
  54 // https://github.com/unicode-org/icu4x/blob/main/docs/process/boilerplate.md#library-annotations
  55 #![cfg_attr(not(test), no_std)]
  56 #![cfg_attr(
  57     not(test),
  58     deny(
  59         clippy::indexing_slicing,
  60         clippy::unwrap_used,
  61         clippy::expect_used,
  62         clippy::panic,
  63         clippy::exhaustive_structs,
  64         clippy::exhaustive_enums,
  65         missing_debug_implementations,
  66     )
  67 )]
  68
  69 mod macros;
  70
  71 mod ascii;
  72 mod asciibyte;
  73 mod error;
  74 mod int_ops;
  75
  76 #[cfg(feature = "serde")]
  77 mod serde;
  78
  79 #[cfg(feature = "databake")]
  80 mod databake;
  81
  82 #[cfg(feature = "zerovec")]
  83 mod ule;
  84
  85 #[cfg(any(feature = "serde", feature = "alloc"))]
  86 extern crate alloc;
  87
  88 pub use ascii::TinyAsciiStr;
  89 pub use error::TinyStrError;
  90
  91 /// These are temporary compatability reexports that will be removed
  92 /// in a future version.
  93 pub type TinyStr4 = TinyAsciiStr<4>;
  94 /// These are temporary compatability reexports that will be removed
  95 /// in a future version.
  96 pub type TinyStr8 = TinyAsciiStr<8>;
  97 /// These are temporary compatability reexports that will be removed
  98 /// in a future version.
  99 pub type TinyStr16 = TinyAsciiStr<16>;
 100
 101 #[test]
 102 fn test_size() {
 103     assert_eq!(
 104         core::mem::size_of::<TinyStr4>(),
 105         core::mem::size_of::<Option<TinyStr4>>()
 106     );
 107     assert_eq!(
 108         core::mem::size_of::<TinyStr8>(),
 109         core::mem::size_of::<Option<TinyStr8>>()
 110     );
 111 }
 112 // /// Allows unit tests to use the macro
 113 // #[cfg(test)]
 114 // mod tinystr {
 115 //     pub use super::{TinyAsciiStr, TinyStrError};
 116 // }