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

phf/
lib.rs
