third_party/rust/phf/src/lib.rs

   1 //! Rust-PHF is a library to generate efficient lookup tables at compile time using
   2 //! [perfect hash functions](http://en.wikipedia.org/wiki/Perfect_hash_function).
   3 //!
   4 //! It currently uses the
   5 //! [CHD algorithm](http://cmph.sourceforge.net/papers/esa09.pdf) and can generate
   6 //! a 100,000 entry map in roughly .4 seconds.
   7 //!
   8 //! MSRV (minimum supported rust version) is Rust 1.60.
   9 //!
  10 //! ## Usage
  11 //!
  12 //! PHF data structures can be constructed via either the procedural
  13 //! macros in the `phf_macros` crate or code generation supported by the
  14 //! `phf_codegen` crate. If you prefer macros, you can easily use them by
  15 //! enabling the `macros` feature of the `phf` crate, like:
  16 //!
  17 //!```toml
  18 //! [dependencies]
  19 //! phf = { version = "0.11", features = ["macros"] }
  20 //! ```
  21 //!
  22 //! To compile the `phf` crate with a dependency on
  23 //! libcore instead of libstd, enabling use in environments where libstd
  24 //! will not work, set `default-features = false` for the dependency:
  25 //!
  26 //! ```toml
  27 //! [dependencies]
  28 //! # to use `phf` in `no_std` environments
  29 //! phf = { version = "0.11", default-features = false }
  30 //! ```
  31 //!
  32 //! ## Example (with the `macros` feature enabled)
  33 //!
  34 //! ```rust
  35 //! use phf::phf_map;
  36 //!
  37 //! #[derive(Clone)]
  38 //! pub enum Keyword {
  39 //!     Loop,
  40 //!     Continue,
  41 //!     Break,
  42 //!     Fn,
  43 //!     Extern,
  44 //! }
  45 //!
  46 //! static KEYWORDS: phf::Map<&'static str, Keyword> = phf_map! {
  47 //!     "loop" => Keyword::Loop,
  48 //!     "continue" => Keyword::Continue,
  49 //!     "break" => Keyword::Break,
  50 //!     "fn" => Keyword::Fn,
  51 //!     "extern" => Keyword::Extern,
  52 //! };
  53 //!
  54 //! pub fn parse_keyword(keyword: &str) -> Option<Keyword> {
  55 //!     KEYWORDS.get(keyword).cloned()
  56 //! }
  57 //! ```
  58 //!
  59 //! Alternatively, you can use the [`phf_codegen`] crate to generate PHF datatypes
  60 //! in a build script.
  61 //!
  62 //! [`phf_codegen`]: https://docs.rs/phf_codegen
  63 //!
  64 //! ## Note
  65 //!
  66 //! Currently, the macro syntax has some limitations and may not
  67 //! work as you want. See [#183] or [#196] for example.
  68 //!
  69 //! [#183]: https://github.com/rust-phf/rust-phf/issues/183
  70 //! [#196]: https://github.com/rust-phf/rust-phf/issues/196
  71
  72 #![doc(html_root_url = "https://docs.rs/phf/0.11")]
  73 #![warn(missing_docs)]
  74 #![cfg_attr(not(feature = "std"), no_std)]
  75
  76 #[cfg(feature = "std")]
  77 extern crate std as core;
  78
  79 #[cfg(feature = "macros")]
  80 /// Macro to create a `static` (compile-time) [`Map`].
  81 ///
  82 /// Requires the `macros` feature.
  83 ///
  84 /// Supported key expressions are:
  85 /// - literals: bools, (byte) strings, bytes, chars, and integers (these must have a type suffix)
  86 /// - arrays of `u8` integers
  87 /// - dereferenced byte string literals
  88 /// - `UniCase::unicode(string)` or `UniCase::ascii(string)` if the `unicase` feature is enabled
  89 ///
  90 /// # Example
  91 ///
  92 /// ```
  93 /// use phf::{phf_map, Map};
  94 ///
  95 /// static MY_MAP: Map<&'static str, u32> = phf_map! {
  96 ///     "hello" => 1,
  97 ///     "world" => 2,
  98 /// };
  99 ///
 100 /// fn main () {
 101 ///     assert_eq!(MY_MAP["hello"], 1);
 102 /// }
 103 /// ```
 104 pub use phf_macros::phf_map;
 105
 106 #[cfg(feature = "macros")]
 107 /// Macro to create a `static` (compile-time) [`OrderedMap`].
 108 ///
 109 /// Requires the `macros` feature. Same usage as [`phf_map`].
 110 pub use phf_macros::phf_ordered_map;
 111
 112 #[cfg(feature = "macros")]
 113 /// Macro to create a `static` (compile-time) [`Set`].
 114 ///
 115 /// Requires the `macros` feature.
 116 ///
 117 /// # Example
 118 ///
 119 /// ```
 120 /// use phf::{phf_set, Set};
 121 ///
 122 /// static MY_SET: Set<&'static str> = phf_set! {
 123 ///     "hello world",
 124 ///     "hola mundo",
 125 /// };
 126 ///
 127 /// fn main () {
 128 ///     assert!(MY_SET.contains("hello world"));
 129 /// }
 130 /// ```
 131 pub use phf_macros::phf_set;
 132
 133 #[cfg(feature = "macros")]
 134 /// Macro to create a `static` (compile-time) [`OrderedSet`].
 135 ///
 136 /// Requires the `macros` feature. Same usage as [`phf_set`].
 137 pub use phf_macros::phf_ordered_set;
 138
 139 #[doc(inline)]
 140 pub use self::map::Map;
 141 #[doc(inline)]
 142 pub use self::ordered_map::OrderedMap;
 143 #[doc(inline)]
 144 pub use self::ordered_set::OrderedSet;
 145 #[doc(inline)]
 146 pub use self::set::Set;
 147 pub use phf_shared::PhfHash;
 148
 149 pub mod map;
 150 pub mod ordered_map;
 151 pub mod ordered_set;
 152 pub mod set;