From beaab636ee4657147e9aa0e2013256ec0bcace46 Mon Sep 17 00:00:00 2001
From: Joel Natividad <1980690+jqnatividad@users.noreply.github.com>
Date: Wed, 25 Dec 2024 09:12:26 -0500
Subject: [PATCH] docs: document `util::transform()` helper function used in
 `join`

---
 src/util.rs | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/util.rs b/src/util.rs
index eeca99ca9..4809f7a6b 100644
--- a/src/util.rs
+++ b/src/util.rs
@@ -1341,6 +1341,23 @@ pub fn round_num(dec_f64: f64, places: u32) -> String {
 }
 
 #[inline]
+/// Transforms a byte slice into a ByteString with optional case-insensitive conversion.
+///
+/// This function takes a byte slice and attempts to convert it to a UTF-8 string. If successful,
+/// it trims whitespace and optionally converts to lowercase. If the input is not valid UTF-8,
+/// it returns the original bytes unchanged.
+///
+/// It's fine-tuned for speed and memory usage, using simdutf8 for UTF-8 validation and
+/// to_lowercase_into for non-allocating, in-place lowercase conversion.
+///
+/// # Arguments
+///
+/// * `bs` - The input byte slice to transform
+/// * `casei` - If true, converts the string to lowercase. If false, leaves case unchanged.
+///
+/// # Returns
+///
+/// * A `ByteString` (Vec<u8>) containing the transformed bytes
 pub fn transform(bs: &[u8], casei: bool) -> ByteString {
     if let Ok(s) = simdutf8::basic::from_utf8(bs) {
         if casei {