1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

//! # Which `escape` function to use
//!
//! Generally, if the text goes in an attribute, use [`escape_attribute()`],
//! otherwise, use [`escape_text()`]. If you need bytes (`[u8]`) instead of a
//! `String`, use the `_bytes` version of the functions:
//! [`escape_attribute_bytes()`] and [`escape_text_bytes()`].
//!
//! |                         | `&` | `<` | `>` | `"` | `'` |
//! |-------------------------|:---:|:---:|:---:|:---:|:---:|
//! | [`escape_text()`]       |  ✓  |  ✓  |  ✓  |     |     |
//! | [`escape_attribute()`]  |  ✓  |  ✓  |  ✓  |  ✓  |     |
//! | [`escape_all_quotes()`] |  ✓  |  ✓  |  ✓  |  ✓  |  ✓  |
//!
//! You should almost never need [`escape_all_quotes()`], but it’s included
//! because sometimes it’s convenient to wrap attribute values in single quotes.
//!
//! # Which `unescape` function to use
//!
//! [`unescape()`] is probably fine for most uses. To be strictly correct, you
//! should use [`unescape_attribute()`] for attribute values.
//!
//! [`unescape_in()`] handles either depending on the value of the `context`
//! parameter. See its documentation for a discussion of the differences between
//! expanding attribute values and general text.
//!
//! [`unescape_bytes_in()`] is just like [`unescape_in()`] except that it works
//! on `[u8]` rather than strings.
//!
//! # Features
//!
//! The `escape` functions are all available with no features enabled.
//!
//!   * `unescape_fast`: provide fast version of [`unescape()`]. This does _not_
//!     enable the `entities` feature automatically.
//!
//!     This takes perhaps 30 seconds longer to build than `unescape`, but the
//!     performance is significantly better in the worst cases. That said, the
//!     performance of of the `unescape` version is already pretty good, so I
//!     don’t recommend enabling this unless you really need it.
//!
//!   * `unescape`: provide normal version of [`unescape()`]. This will
//!     automatically enable the `entities` feature.
//!
//!   * `entities`: build [`ENTITIES`] map. Enabling this will add a dependency
//!     on [phf] and may slow builds by a few seconds.
//!
//! ### Internal features
//!
//!   * `iai`: enable [iai] benchmarks. This should only be used when running
//!     benchmarks. See the [Benchmarks section in the README][benchmarks].
//!
//!   * `bench`: enable unescape benchmarks by making internal functions like
//!     `unescape_fast()` public. This must only be used when running
//!     benchmarks. It is required to run unescape benchmarks. See the
//!     [Benchmarks section in the README][benchmarks].
//!
//!   * `_unescape_either`: used internally to configure benchmarks. You should
//!     not specify this directly. It is automatically enabled when
//!     `unescape_fast` or `unescape` are enabled.
//!
//! # Minimum supported Rust version
//!
//! Currently the minimum supported Rust version (MSRV) is **1.60**. Future
//! increases in the MSRV will require a major version bump.
//!
//! [phf]: https://crates.io/crates/phf
//! [iai]: https://crates.io/crates/iai
//! [benchmarks]: https://github.com/danielparks/htmlize#benchmarks

#![forbid(unsafe_code)]

mod escape;
pub use escape::*;

#[cfg(any(feature = "unescape", feature = "unescape_fast"))]
mod unescape;
#[cfg(any(feature = "unescape", feature = "unescape_fast"))]
pub use unescape::*;

// Include the ENTITIES map generated by build.rs
#[cfg(feature = "entities")]
include!(concat!(env!("OUT_DIR"), "/entities.rs"));