tuwunel_core/utils/string.rs
1//! String conversion, formatting, parsing, serialization, and slicing
2//! utilities.
3//!
4//! The module includes borrowed unquoted views, Serde adapters, chunking, case
5//! conversion, deterministic prefix selection, and UTF-8 conversion.
6//! Specialized display wrappers avoid allocation. String traits and helpers
7//! are re-exported from child modules.
8
9mod between;
10mod chunk;
11
12pub mod de;
13
14mod split;
15mod tests;
16mod unquote;
17mod unquoted;
18
19use std::{
20 borrow::Cow,
21 fmt::{self, write},
22 io,
23 mem::replace,
24 ops::{Range, RangeInclusive},
25 str::from_utf8,
26};
27
28pub use self::{
29 between::Between, chunk::chunk, split::SplitInfallible, unquote::Unquote, unquoted::Unquoted,
30};
31use crate::{Result, arrayvec::ArrayString, smallstr::SmallString};
32
33/// Provides a shared empty string slice.
34///
35/// The value has static lifetime and is suitable for default or fallback
36/// references. It is identical to the empty string literal.
37pub const EMPTY: &str = "";
38
39const OPAQUE_ID_LENGTHS: RangeInclusive<usize> = 1..=255;
40
41/// Formats arguments into a small string with an inline byte capacity.
42///
43/// Arguments are forwarded to [`format_small_string`] without an intermediate
44/// `String` allocation. Inline capacity is inferred from the expected type at
45/// the call site, and output beyond it spills to the heap.
46#[macro_export]
47#[collapse_debuginfo(yes)]
48macro_rules! format_small_string {
49 ($($args:tt)+) => {
50 $crate::utils::string::format_small_string(std::format_args!($($args)+))
51 };
52}
53
54/// Formats arguments into an array string with constant byte capacity.
55///
56/// Arguments are forwarded to [`format_array_string`] without any allocation.
57/// Capacity is inferred from the expected type at the call site, and output
58/// beyond it panics.
59#[macro_export]
60#[collapse_debuginfo(yes)]
61macro_rules! format_array_string {
62 ($($args:tt)+) => {
63 $crate::utils::string::format_array_string(std::format_args!($($args)+))
64 };
65}
66
67/// Formats a literal only when placeholders appear to be present.
68///
69/// With one argument, a literal containing both `{` and `}` is formatted; any
70/// other literal is converted directly through `Into`. With additional
71/// arguments, the first literal is always treated as a format string.
72#[macro_export]
73#[collapse_debuginfo(yes)]
74macro_rules! format_maybe {
75 ($s:literal $(,)?) => {
76 if $crate::is_format!($s) { std::format!($s).into() } else { $s.into() }
77 };
78
79 ($s:literal, $($args:tt)+) => {
80 std::format!($s, $($args)+).into()
81 };
82}
83
84/// Tests whether a string literal appears to contain a formatting placeholder.
85///
86/// A literal returns `true` only when it contains at least one `{` and at least
87/// one `}`. Every other token pattern returns `false`, so the result is a
88/// heuristic rather than syntax validation.
89#[macro_export]
90#[collapse_debuginfo(yes)]
91macro_rules! is_format {
92 ($s:literal) => {
93 ::const_str::contains!($s, "{") && ::const_str::contains!($s, "}")
94 };
95
96 ($($s:tt)+) => {
97 false
98 };
99}
100
101/// Collects text emitted by a callback into an owned string.
102///
103/// The callback receives a formatting writer backed by a new `String`. Its
104/// error is propagated, and the buffer is returned only after the callback
105/// succeeds.
106#[inline]
107pub fn collect_stream<F>(func: F) -> Result<String>
108where
109 F: FnOnce(&mut dyn fmt::Write) -> Result,
110{
111 let mut out = String::new();
112 func(&mut out)?;
113
114 Ok(out)
115}
116
117/// Converts ASCII camel-case text into an owned lowercase snake-case string.
118///
119/// An underscore is inserted before an uppercase byte only when the preceding
120/// byte is not uppercase; leading and consecutive capitals remain joined. Input
121/// is processed bytewise, so non-ASCII UTF-8 text is not preserved.
122#[inline]
123#[must_use]
124pub fn camel_to_snake_string(s: &str) -> String {
125 let est_len = s
126 .chars()
127 .fold(s.len(), |est, c| est.saturating_add(usize::from(c.is_ascii_uppercase())));
128
129 let mut ret = String::with_capacity(est_len);
130 camel_to_snake_case(&mut ret, s.as_bytes()).expect("string-to-string stream error");
131 ret
132}
133
134/// Streams ASCII camel-case bytes into a writer as lowercase snake case.
135///
136/// The underscore rule matches [`camel_to_snake_string`]. The first input read
137/// error stops processing and is not returned, while output formatting errors
138/// are propagated. Bytes outside ASCII are written as individual Unicode code
139/// points rather than decoded as UTF-8.
140#[inline]
141#[expect(clippy::unbuffered_bytes)] // these are allocated string utilities, not file I/O utils
142pub fn camel_to_snake_case<I, O>(output: &mut O, input: I) -> Result
143where
144 I: io::Read,
145 O: fmt::Write,
146{
147 let mut state = false;
148 input
149 .bytes()
150 .take_while(Result::is_ok)
151 .map(Result::unwrap)
152 .map(char::from)
153 .try_for_each(|ch| {
154 let m = ch.is_ascii_uppercase();
155 let s = replace(&mut state, !m);
156 if m && s {
157 output.write_char('_')?;
158 }
159
160 output.write_char(ch.to_ascii_lowercase())?;
161
162 Result::<()>::Ok(())
163 })
164}
165
166/// Returns the longest common ASCII prefix of a collection of strings.
167///
168/// The result borrows from the first entry and is empty when the collection is
169/// empty or shares no prefix. Inputs are expected to be ASCII because some
170/// non-ASCII prefixes can produce an invalid byte boundary and panic.
171#[must_use]
172#[expect(clippy::string_slice)]
173pub fn common_prefix<T: AsRef<str>>(choice: &[T]) -> &str {
174 choice.first().map_or(EMPTY, move |best| {
175 choice
176 .iter()
177 .skip(1)
178 .fold(best.as_ref(), |best, choice| {
179 &best[0..choice
180 .as_ref()
181 .char_indices()
182 .zip(best.char_indices())
183 .take_while(|&(a, b)| a == b)
184 .count()]
185 })
186 })
187}
188
189/// Reports whether `haystack` contains any of the non-empty `needles`.
190///
191/// An empty needle is skipped rather than matching every haystack, so an
192/// empty list or a list of empty strings matches nothing.
193#[must_use]
194pub fn contains_any<Needles>(haystack: &str, needles: Needles) -> bool
195where
196 Needles: IntoIterator,
197 Needles::Item: AsRef<str>,
198{
199 needles
200 .into_iter()
201 .filter(|needle| !needle.as_ref().is_empty())
202 .any(|needle| haystack.contains(needle.as_ref()))
203}
204
205/// Reports whether any of `candidates` equals `item`.
206///
207/// Unlike a slice's `contains`, the candidates need not share the type of
208/// `item`, so a list of `String` is searched for a `&str` without allocating.
209#[must_use]
210pub fn equals_any<Candidates>(item: &str, candidates: Candidates) -> bool
211where
212 Candidates: IntoIterator,
213 Candidates::Item: AsRef<str>,
214{
215 candidates
216 .into_iter()
217 .any(|candidate| candidate.as_ref() == item)
218}
219
220/// Returns a deterministic prefix selected from the string contents.
221///
222/// The candidate index is the wrapping sum of input bytes modulo the byte
223/// length, with empty input using a modulus of one. When a range is supplied,
224/// the index is clamped inclusively between `range.start` and `range.end`;
225/// reversed endpoints panic. The index is then interpreted as a
226/// character position, or the full string is returned when that position does
227/// not exist. Because selection uses byte length but truncation uses character
228/// count, non-ASCII input more often falls back to the full string.
229#[inline]
230#[must_use]
231#[expect(clippy::arithmetic_side_effects)]
232pub fn truncate_deterministic(str: &str, range: Option<Range<usize>>) -> &str {
233 let range = range.unwrap_or(0..str.len());
234 let len = str
235 .as_bytes()
236 .iter()
237 .copied()
238 .map(Into::into)
239 .fold(0_usize, usize::wrapping_add)
240 .wrapping_rem(str.len().max(1))
241 .clamp(range.start, range.end);
242
243 str.char_indices()
244 .nth(len)
245 .map(|(i, _)| str.split_at(i).0)
246 .unwrap_or(str)
247}
248
249/// Shortens a string to at most `max` characters.
250///
251/// Characters are Unicode scalar values, so the cut never splits one. A string
252/// already within the limit is returned whole.
253#[inline]
254#[must_use]
255pub fn truncate_chars(str: &str, max: usize) -> &str {
256 str.char_indices()
257 .nth(max)
258 .map_or(str, |(i, _)| str.split_at(i).0)
259}
260
261/// Displays a value into a small string with an inline byte capacity.
262///
263/// Output beyond `CAP` bytes spills to the heap. Panics if the value's
264/// `Display` implementation returns a formatting error.
265#[inline]
266#[must_use]
267pub fn to_small_string<const CAP: usize, T>(t: T) -> SmallString<[u8; CAP]>
268where
269 T: fmt::Display,
270{
271 format_small_string(format_args!("{t}"))
272}
273
274/// Formats arguments into a small string with an inline byte capacity.
275///
276/// Output beyond `CAP` bytes spills to the heap. Panics if formatting the
277/// arguments fails; [`try_format_small_string`] returns that error instead.
278#[inline]
279#[must_use]
280pub fn format_small_string<const CAP: usize>(args: fmt::Arguments<'_>) -> SmallString<[u8; CAP]> {
281 try_format_small_string(args).expect("Failed to format into SmallString")
282}
283
284/// Formats arguments into a small string, propagating any formatting error.
285///
286/// Output beyond `CAP` bytes spills to the heap, so the buffer itself never
287/// overflows. Only a `Display` implementation among the arguments can fail.
288#[inline]
289pub fn try_format_small_string<const CAP: usize>(
290 args: fmt::Arguments<'_>,
291) -> Result<SmallString<[u8; CAP]>> {
292 let mut ret = SmallString::<[u8; CAP]>::new();
293 write(&mut ret, args)?;
294
295 Ok(ret)
296}
297
298/// Displays a value into an array string with constant byte capacity.
299///
300/// Output is confined to the stack, so `CAP` must bound the formatted length.
301/// Panics when the output exceeds it, or when the value's `Display`
302/// implementation returns a formatting error.
303#[inline]
304#[must_use]
305pub fn to_array_string<const CAP: usize, T>(t: T) -> ArrayString<CAP>
306where
307 T: fmt::Display,
308{
309 format_array_string(format_args!("{t}"))
310}
311
312/// Formats arguments into an array string with constant byte capacity.
313///
314/// Output is confined to the stack, so `CAP` must bound the formatted length.
315/// Panics when the output exceeds it or the arguments fail to format;
316/// [`try_format_array_string`] returns both as an error.
317#[inline]
318#[must_use]
319pub fn format_array_string<const CAP: usize>(args: fmt::Arguments<'_>) -> ArrayString<CAP> {
320 try_format_array_string(args).expect("Failed to format into ArrayString")
321}
322
323/// Formats arguments into an array string, propagating any formatting error.
324///
325/// Output is confined to the stack. Exceeding `CAP` bytes yields a formatting
326/// error, indistinguishable from a failure in an argument's `Display`
327/// implementation.
328#[inline]
329pub fn try_format_array_string<const CAP: usize>(
330 args: fmt::Arguments<'_>,
331) -> Result<ArrayString<CAP>> {
332 let mut ret = ArrayString::<CAP>::new();
333 write(&mut ret, args)?;
334
335 Ok(ret)
336}
337
338/// Converts UTF-8 bytes into an owned string.
339///
340/// Valid input is copied into a new `String`. Invalid UTF-8 is returned as an
341/// error.
342pub fn string_from_bytes(bytes: &[u8]) -> Result<String> {
343 let str: &str = str_from_bytes(bytes)?;
344
345 Ok(str.to_owned())
346}
347
348/// Borrows a byte slice as UTF-8 text.
349///
350/// Valid input is returned without allocation. Invalid UTF-8 is returned as an
351/// error.
352#[inline]
353pub fn str_from_bytes(bytes: &[u8]) -> Result<&str> { Ok(from_utf8(bytes)?) }
354
355/// Escapes a value for one markdown table cell.
356///
357/// Backslashes and pipes are escaped, and control characters and Unicode line
358/// or paragraph separators become spaces, so the value cannot end its cell or
359/// row. A value needing no change is borrowed.
360#[must_use]
361pub fn markdown_cell(value: &str) -> Cow<'_, str> {
362 let breaks_cell = |character: char| {
363 character.is_control() || matches!(character, '\\' | '|' | '\u{2028}' | '\u{2029}')
364 };
365
366 let escape = |mut escaped: String, character: char| {
367 match character {
368 | '\\' => escaped.push_str("\\\\"),
369 | '|' => escaped.push_str("\\|"),
370 | _ if breaks_cell(character) => escaped.push(' '),
371 | _ => escaped.push(character),
372 }
373
374 escaped
375 };
376
377 value
378 .contains(breaks_cell)
379 .then(|| {
380 value
381 .chars()
382 .fold(String::with_capacity(value.len()), escape)
383 })
384 .map_or(Cow::Borrowed(value), Cow::Owned)
385}
386
387/// Replaces control characters and Unicode line separators with spaces.
388///
389/// Each replaced character becomes one space, keeping the value on one line.
390/// Values that need no replacements are borrowed without allocation.
391#[must_use]
392pub fn single_line(value: &str) -> Cow<'_, str> {
393 let breaks_line =
394 |character: char| character.is_control() || matches!(character, '\u{2028}' | '\u{2029}');
395
396 value
397 .contains(breaks_line)
398 .then(|| value.replace(breaks_line, " "))
399 .map_or(Cow::Borrowed(value), Cow::Owned)
400}
401
402/// Picks the singular or plural form of a noun for a count.
403///
404/// Only a count of exactly one takes the singular, so zero reads as plural.
405#[inline]
406#[must_use]
407pub fn plural<'a>(count: usize, one: &'a str, many: &'a str) -> &'a str {
408 match count {
409 | 1 => one,
410 | _ => many,
411 }
412}
413
414/// Reports whether a string is a Matrix opaque identifier.
415///
416/// The grammar allows 1 to 255 characters, all of them unreserved.
417#[must_use]
418pub fn is_opaque_id(value: &str) -> bool {
419 OPAQUE_ID_LENGTHS.contains(&value.len()) && is_unreserved(value)
420}
421
422/// Reports whether every byte of a string is unreserved.
423///
424/// An empty string passes, so a grammar with a minimum length checks it apart.
425#[must_use]
426pub fn is_unreserved(value: &str) -> bool { value.bytes().all(is_unreserved_byte) }
427
428/// Reports whether a byte is an RFC 3986 unreserved character.
429///
430/// The set is `[0-9A-Za-z._~-]`, which a URL component carries unescaped.
431#[inline]
432#[must_use]
433pub const fn is_unreserved_byte(byte: u8) -> bool {
434 byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'.' | b'_' | b'~')
435}