charmap/
lib.rs

1//! # charmap
2//!
3//! A Rust library for one-to-(none/one/many) character mapping.
4//! It's main use-case is preprocessing, transliterating, and cleaning natural
5//! language text.
6//!
7//! ## Usage
8//!
9//! To use `charmap` with libstd's mapping types
10//! ([`HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html) and
11//! [`BTreeMap`](https://doc.rust-lang.org/std/collections/struct.BTreeMap.html)),
12//! add the following to your `Cargo.toml`:
13//!
14//! ```toml
15//! [dependencies]
16//! charmap = "0.2"
17//! ```
18//!
19//! This should also allow you to use
20//! [`rustc-hash`](https://crates.io/crates/rustc-hash)'s
21//! [`FxHashMap`](https://docs.rs/rustc-hash/latest/rustc_hash/type.FxHashMap.html)
22//! since it is an instance of libstd's
23//! [`HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html).
24//!
25//! `charmap` also supports [`hashbrown`](https://crates.io/crates/hashbrown)'s
26//! [`HashMap`](https://docs.rs/hashbrown/latest/hashbrown/struct.HashMap.html) and
27//! [`phf`](https://crates.io/crates/phf)'s
28//! [`Map`](https://docs.rs/phf/latest/phf/struct.Map.html) and
29//! [`OrderedMap`](https://docs.rs/phf/latest/phf/struct.OrderedMap.html) types.
30//! You can enable these by setting the `"hashbrown"` and `"phf"` features
31//! respectively.
32//! For example, to use `charmap` with [`phf`](https://crates.io/crates/phf),
33//! add the following to your `Cargo.toml`:
34//!
35//! ```toml
36//! [dependencies]
37//! charmap = {version = "0.2", features = ["phf"]}
38//! ```
39//!
40//! You can also disable libstd support for `no_std` builds by setting
41//! `default-features = false`. For example:
42//!
43//! ```toml
44//! [dependencies]
45//! charmap = {version = "0.2", default-features = false, features = ["phf"]}
46//! ```
47//!
48//! ## Example
49//!
50//! Below is an example of how to use `charmap` with libstd's
51//! [`HashMap`](https://doc.rust-lang.org/std/collections/struct.HashMap.html):
52//!
53//! ```rust
54//! use std::collections::HashMap;
55//! use charmap::*;
56//!
57//! // We first define our action map that will tell our CharMapper what to do
58//! // when it sees a particular character.
59//! let actions = HashMap::from([
60//!     ('!', CharMapAction::Delete),  // Delete instances of '!'
61//!     ('l', CharMapAction::SubStr("LLL")),  // Substitute instances of 'l' with 'LLL'
62//! ]);
63//!
64//! // This is the string we want to charmap.
65//! let start_str = "Hello, world!";
66//!
67//! // Create a character mapper using the previously defined actions while
68//! // allowing all other character to be output as they are.
69//! let mapper = CharMapper::new(&actions, CharMapAction::Pass);
70//!
71//! // Use mapper to charmap start_str
72//! let mapped_str: String = start_str.map_chars(&mapper).collect();
73//!
74//! // Output should be: HeLLLLLLo, worLLLd
75//! println!("{}", mapped_str);
76//! ```
77//!
78//! We can also use a different default action to apply to characters not
79//! defined in our actions map:
80//!
81//! ```rust
82//! use std::collections::HashMap;
83//! use charmap::*;
84//!
85//! // We first define our action map that will tell our CharMapper what to do
86//! // when it sees a particular character.
87//! let actions = HashMap::from([
88//!     ('!', CharMapAction::Delete),  // Delete instances of '!'
89//!     ('l', CharMapAction::SubStr("LLL")),  // Substitute instances of 'l' with 'LLL'
90//!     ('o', CharMapAction::Pass),  // Output instances of 'o' as is
91//! ]);
92//!
93//! // This is the string we want to charmap.
94//! let start_str = "Hello, world!";
95//!
96//! // Create a character mapper using the previously defined actions while
97//! // replacing all other characters with "-".
98//! let mapper = CharMapper::new(&actions, CharMapAction::SubChar('-'));
99//!
100//! // Use mapper to charmap start_str
101//! let mapped_str: String = start_str.map_chars(&mapper).collect();
102//!
103//! // Output should be: --LLLLLLo---o-LLL-
104//! println!("{}", mapped_str);
105//! ```
106
107mod actionmap;
108mod charmapper;
109
110pub use crate::actionmap::{ActionMap, CharMapAction};
111pub use crate::charmapper::{CharMapper, MapCharsIter, MappedChars};
charmap/lib.rs

charmap/
lib.rs
