phf/
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.66.
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.13.1", 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.13.1", 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.13.1")]
73#![warn(missing_docs)]
74#![cfg_attr(not(feature = "std"), no_std)]
75
76#[cfg(feature = "std")]
77extern 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/// - tuples of any supported key expressions
88/// - dereferenced byte string literals
89/// - OR patterns using `|` to map multiple keys to the same value
90/// - `UniCase::unicode(string)`, `UniCase::ascii(string)`, or `Ascii::new(string)` if the `unicase` feature is enabled
91/// - `UncasedStr::new(string)` if the `uncased` feature is enabled
92///
93/// # Example
94///
95/// ```
96/// use phf::{phf_map, Map};
97///
98/// static MY_MAP: Map<&'static str, u32> = phf_map! {
99///     "hello" => 1,
100///     "world" => 2,
101/// };
102///
103/// fn main () {
104///     assert_eq!(MY_MAP["hello"], 1);
105/// }
106/// ```
107///
108/// # OR Patterns
109///
110/// You can use OR patterns to map multiple keys to the same value:
111///
112/// ```
113/// use phf::{phf_map, Map};
114///
115/// static OPERATORS: Map<&'static str, &'static str> = phf_map! {
116///     "+" | "add" | "plus" => "addition",
117///     "-" | "sub" | "minus" => "subtraction",
118///     "*" | "mul" | "times" => "multiplication",
119/// };
120///
121/// fn main() {
122///     assert_eq!(OPERATORS["+"], "addition");
123///     assert_eq!(OPERATORS["add"], "addition");
124///     assert_eq!(OPERATORS["plus"], "addition");
125/// }
126/// ```
127pub use phf_macros::phf_map;
128
129#[cfg(feature = "macros")]
130/// Macro to create a `static` (compile-time) [`OrderedMap`].
131///
132/// Requires the `macros` feature. Same usage as [`phf_map`].
133pub use phf_macros::phf_ordered_map;
134
135#[cfg(feature = "macros")]
136/// Macro to create a `static` (compile-time) [`Set`].
137///
138/// Requires the `macros` feature.
139///
140/// # Example
141///
142/// ```
143/// use phf::{phf_set, Set};
144///
145/// static MY_SET: Set<&'static str> = phf_set! {
146///     "hello world",
147///     "hola mundo",
148/// };
149///
150/// fn main () {
151///     assert!(MY_SET.contains("hello world"));
152/// }
153/// ```
154///
155/// # OR Patterns
156///
157/// You can use OR patterns to include multiple keys in a single entry:
158///
159/// ```
160/// use phf::{phf_set, Set};
161///
162/// static KEYWORDS: Set<&'static str> = phf_set! {
163///     "if" | "elif" | "else",
164///     "for" | "while" | "loop",
165///     "fn" | "function" | "def",
166/// };
167///
168/// fn main() {
169///     assert!(KEYWORDS.contains("if"));
170///     assert!(KEYWORDS.contains("elif"));
171///     assert!(KEYWORDS.contains("else"));
172///     assert!(KEYWORDS.contains("for"));
173/// }
174/// ```
175pub use phf_macros::phf_set;
176
177#[cfg(feature = "macros")]
178/// Macro to create a `static` (compile-time) [`OrderedSet`].
179///
180/// Requires the `macros` feature. Same usage as [`phf_set`].
181pub use phf_macros::phf_ordered_set;
182
183#[doc(inline)]
184pub use self::map::Map;
185#[doc(inline)]
186pub use self::ordered_map::OrderedMap;
187#[doc(inline)]
188pub use self::ordered_set::OrderedSet;
189#[doc(inline)]
190pub use self::set::Set;
191pub use phf_shared::PhfHash;
192
193pub mod map;
194pub mod ordered_map;
195pub mod ordered_set;
196pub mod set;
phf/lib.rs

phf/
lib.rs
