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.46.
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.10", 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.10", 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.10")]
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/// ```
105#[proc_macro_hack::proc_macro_hack]
106pub use phf_macros::phf_map;
107
108#[cfg(feature = "macros")]
109/// Macro to create a `static` (compile-time) [`OrderedMap`].
110///
111/// Requires the `macros` feature. Same usage as [`phf_map`].
112#[proc_macro_hack::proc_macro_hack]
113pub use phf_macros::phf_ordered_map;
114
115#[cfg(feature = "macros")]
116/// Macro to create a `static` (compile-time) [`Set`].
117///
118/// Requires the `macros` feature.
119///
120/// # Example
121///
122/// ```
123/// use phf::{phf_set, Set};
124///
125/// static MY_SET: Set<&'static str> = phf_set! {
126/// "hello world",
127/// "hola mundo",
128/// };
129///
130/// fn main () {
131/// assert!(MY_SET.contains("hello world"));
132/// }
133/// ```
134#[proc_macro_hack::proc_macro_hack]
135pub use phf_macros::phf_set;
136
137#[cfg(feature = "macros")]
138/// Macro to create a `static` (compile-time) [`OrderedSet`].
139///
140/// Requires the `macros` feature. Same usage as [`phf_set`].
141#[proc_macro_hack::proc_macro_hack]
142pub use phf_macros::phf_ordered_set;
143
144#[doc(inline)]
145pub use self::map::Map;
146#[doc(inline)]
147pub use self::ordered_map::OrderedMap;
148#[doc(inline)]
149pub use self::ordered_set::OrderedSet;
150#[doc(inline)]
151pub use self::set::Set;
152pub use phf_shared::PhfHash;
153
154pub mod map;
155pub mod ordered_map;
156pub mod ordered_set;
157pub mod set;
158