Skip to main content

mla_titlecase/
lib.rs

1#![doc = include_str!("../README.md")]
2
3pub mod analysis;
4pub mod config;
5pub mod error;
6pub mod fst_store;
7pub mod json_store;
8pub mod lexicon;
9pub mod plugin;
10
11/// Internal normalization plumbing shared with the `mla-titlecase-cli` crate,
12/// which ships in lockstep with this one. Hidden from the documented public API
13/// and not covered by semver: external code should not depend on it.
14#[doc(hidden)]
15pub mod util;
16
17mod casing;
18mod classify;
19mod context;
20mod locale;
21mod rules;
22mod titlecase;
23mod token;
24mod tokenizer;
25
26pub use analysis::{CasingRule, CasingSpan, Confidence, TitleCaseAnalysis};
27pub use config::{
28    AllCapsPolicy, HyphenStyle, LocaleProfile, NameParticlePolicy, SmallWordPolicy,
29    TitleCaseOptions, UnknownWordCasing,
30};
31pub use error::{Error, Result};
32pub use lexicon::ExternalLexicons;
33pub use plugin::{
34    LexiconPlugin, MapEntry, PluginMetadata, PluginPayload, PluginPayloadKind, RankedEntry,
35    PLUGIN_SCHEMA_VERSION,
36};
37
38/// Converts `input` to MLA-style title case using the default options.
39#[must_use]
40pub fn titlecase_mla(input: &str) -> String {
41    titlecase::titlecase_mla(input)
42}
43
44/// Converts `input` to MLA-style title case using explicit options.
45#[must_use]
46pub fn titlecase_with_options(input: &str, options: &TitleCaseOptions<'_>) -> String {
47    titlecase::titlecase_with_options(input, options)
48}
49
50/// Converts `input` to MLA-style title case, writing the result into `out`.
51///
52/// `out` is cleared first, so its previous contents are replaced. Reusing one
53/// buffer across many calls avoids allocating a fresh `String` per title, which
54/// matters when processing large batches. Only the output buffer is reused:
55/// each call still allocates a `Vec` of tokens internally, so this reclaims the
56/// result allocation, not every allocation (see the
57/// `titlecase_batch_reused_buffer` benchmark).
58///
59/// # Examples
60///
61/// ```
62/// use mla_titlecase::{titlecase_into, TitleCaseOptions};
63///
64/// let options = TitleCaseOptions::default();
65/// let mut buffer = String::new();
66/// for title in ["the wind in the willows", "love in the time of cholera"] {
67///     titlecase_into(&mut buffer, title, &options);
68///     // use `buffer` here
69/// }
70/// ```
71pub fn titlecase_into(out: &mut String, input: &str, options: &TitleCaseOptions<'_>) {
72    titlecase::titlecase_into(out, input, options);
73}
74
75/// Converts `input` to MLA-style title case with the default options and returns
76/// a [`TitleCaseAnalysis`]: the cased string plus one span per casing decision,
77/// in order. That is usually one span per word, but a multiword lexicon match
78/// records a single span for the whole phrase, and all-caps input under
79/// [`AllCapsPolicy::Preserve`] records none. Each span carries the rule and
80/// confidence behind its casing; filter on [`CasingSpan::changed`] for only the
81/// words the engine modified.
82///
83/// # Examples
84///
85/// ```
86/// use mla_titlecase::{titlecase_analyze, CasingRule, Confidence};
87///
88/// let analysis = titlecase_analyze("turn off the lights");
89/// assert_eq!(analysis.output, "Turn Off the Lights");
90/// // The phrasal-verb particle is a heuristic, so the title is flagged.
91/// assert_eq!(analysis.confidence, Confidence::Heuristic);
92/// assert!(analysis.spans.iter().any(|span| span.rule == CasingRule::AdverbialParticle));
93/// ```
94#[must_use]
95pub fn titlecase_analyze(input: &str) -> TitleCaseAnalysis {
96    titlecase::titlecase_analyze(input, &TitleCaseOptions::default())
97}
98
99/// Converts `input` to MLA-style title case using explicit options and returns a
100/// [`TitleCaseAnalysis`]. See [`titlecase_analyze`].
101#[must_use]
102pub fn titlecase_analyze_with_options(
103    input: &str,
104    options: &TitleCaseOptions<'_>,
105) -> TitleCaseAnalysis {
106    titlecase::titlecase_analyze(input, options)
107}