Skip to main content

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}