rstring 0.1.0

//! String wrapping and unwrapping utilities.
//!
//! This module provides functions for wrapping strings with characters or other strings,
//! and for unwrapping (removing) such wrappers.
//!
//! # Usage
//!
//! Import the [`StringWrap`] trait to use methods directly on strings:
//!
//! ```
//! use rstring::StringWrap;
//!
//! assert_eq!("ab".wrap_with_char('x'), "xabx");
//! assert_eq!("ab".wrap_with_str("\""), "\"ab\"");
//! assert_eq!("xabx".unwrap_with_char('x'), "ab");
//! ```

use std::borrow::Cow;

/// Extension trait for string wrapping and unwrapping methods.
///
/// This trait is implemented for `str`, allowing you to call wrapping
/// methods directly on `&str`, `String`, and other string types.
///
/// # Examples
///
/// ```
/// use rstring::StringWrap;
///
/// // Wrap with character
/// assert_eq!("hello".wrap_with_char('"'), "\"hello\"");
///
/// // Wrap with string
/// assert_eq!("hello".wrap_with_str("**"), "**hello**");
///
/// // Unwrap
/// assert_eq!("\"hello\"".unwrap_with_char('"'), "hello");
/// ```
pub trait StringWrap {
    /// Wraps a string with a character.
    ///
    /// If the string is empty or the wrap character is `'\0'`, returns the original string.
    ///
    /// # Examples
    ///
    /// ```
    /// use rstring::StringWrap;
    ///
    /// assert_eq!("".wrap_with_char('x'), "");
    /// assert_eq!("ab".wrap_with_char('\0'), "ab");
    /// assert_eq!("ab".wrap_with_char('x'), "xabx");
    /// assert_eq!("ab".wrap_with_char('\''), "'ab'");
    /// assert_eq!("\"ab\"".wrap_with_char('"'), "\"\"ab\"\"");
    /// ```
    #[must_use]
    fn wrap_with_char(&self, wrap_with: char) -> String;

    /// Wraps a string with another string.
    ///
    /// If the string is empty or the wrap string is empty, returns the original string.
    ///
    /// # Examples
    ///
    /// ```
    /// use rstring::StringWrap;
    ///
    /// assert_eq!("".wrap_with_str("x"), "");
    /// assert_eq!("ab".wrap_with_str(""), "ab");
    /// assert_eq!("ab".wrap_with_str("x"), "xabx");
    /// assert_eq!("ab".wrap_with_str("\""), "\"ab\"");
    /// assert_eq!("\"ab\"".wrap_with_str("\""), "\"\"ab\"\"");
    /// assert_eq!("ab".wrap_with_str("'"), "'ab'");
    /// assert_eq!("'abcd'".wrap_with_str("'"), "''abcd''");
    /// assert_eq!("\"abcd\"".wrap_with_str("'"), "'\"abcd\"'");
    /// assert_eq!("'abcd'".wrap_with_str("\""), "\"'abcd'\"");
    /// ```
    #[must_use]
    fn wrap_with_str(&self, wrap_with: &str) -> String;

    /// Wraps a string with a character if that character is missing from the start or end.
    ///
    /// If the string already starts and ends with the character, returns the original string
    /// as a borrowed reference (`Cow::Borrowed`). Otherwise, returns a new string (`Cow::Owned`).
    ///
    /// If it only starts with the character, adds it to the end.
    /// If it only ends with the character, adds it to the start.
    /// If it has neither, adds to both.
    ///
    /// # Examples
    ///
    /// ```
    /// use rstring::StringWrap;
    ///
    /// assert_eq!("".wrap_if_missing_char('x'), "");
    /// assert_eq!("ab".wrap_if_missing_char('\0'), "ab");
    /// assert_eq!("ab".wrap_if_missing_char('x'), "xabx");
    /// assert_eq!("xabx".wrap_if_missing_char('x'), "xabx");
    /// assert_eq!("xab".wrap_if_missing_char('x'), "xabx");
    /// assert_eq!("abx".wrap_if_missing_char('x'), "xabx");
    /// assert_eq!("'ab'".wrap_if_missing_char('\''), "'ab'");
    /// ```
    #[must_use]
    fn wrap_if_missing_char(&self, wrap_with: char) -> Cow<'_, str>;

    /// Wraps a string with another string if that string is missing from the start or end.
    ///
    /// If the string already starts and ends with the wrap string, returns the original string
    /// as a borrowed reference (`Cow::Borrowed`). Otherwise, returns a new string (`Cow::Owned`).
    ///
    /// If it only starts with the wrap string, adds it to the end.
    /// If it only ends with the wrap string, adds it to the start.
    /// If it has neither, adds to both.
    ///
    /// # Examples
    ///
    /// ```
    /// use rstring::StringWrap;
    ///
    /// assert_eq!("".wrap_if_missing_str("x"), "");
    /// assert_eq!("ab".wrap_if_missing_str(""), "ab");
    /// assert_eq!("ab".wrap_if_missing_str("x"), "xabx");
    /// assert_eq!("xabx".wrap_if_missing_str("x"), "xabx");
    /// assert_eq!("xab".wrap_if_missing_str("x"), "xabx");
    /// assert_eq!("abx".wrap_if_missing_str("x"), "xabx");
    /// assert_eq!("\"ab\"".wrap_if_missing_str("\""), "\"ab\"");
    /// assert_eq!("**hello**".wrap_if_missing_str("**"), "**hello**");
    /// assert_eq!("**hello".wrap_if_missing_str("**"), "**hello**");
    /// ```
    #[must_use]
    fn wrap_if_missing_str(&self, wrap_with: &str) -> Cow<'_, str>;

    /// Unwraps a string by removing the wrapping character from both ends.
    ///
    /// The character is only removed if it appears at both the start and end of the string.
    /// If the string is too short to unwrap (less than 2 characters), returns the original string.
    ///
    /// # Examples
    ///
    /// ```
    /// use rstring::StringWrap;
    ///
    /// assert_eq!("".unwrap_with_char('x'), "");
    /// assert_eq!("x".unwrap_with_char('x'), "x");
    /// assert_eq!("xabx".unwrap_with_char('x'), "ab");
    /// assert_eq!("xab".unwrap_with_char('x'), "xab");
    /// assert_eq!("abx".unwrap_with_char('x'), "abx");
    /// assert_eq!("'ab'".unwrap_with_char('\''), "ab");
    /// assert_eq!("\"ab\"".unwrap_with_char('"'), "ab");
    /// assert_eq!("xx".unwrap_with_char('x'), "");
    /// ```
    #[must_use]
    fn unwrap_with_char(&self, wrap_char: char) -> &str;

    /// Unwraps a string by removing the wrapping string from both ends.
    ///
    /// The string is only removed if it appears at both the start and end of the string.
    /// If the string is too short to unwrap, returns the original string.
    ///
    /// # Examples
    ///
    /// ```
    /// use rstring::StringWrap;
    ///
    /// assert_eq!("".unwrap_with_str("x"), "");
    /// assert_eq!("x".unwrap_with_str("x"), "x");
    /// assert_eq!("xabx".unwrap_with_str("x"), "ab");
    /// assert_eq!("xab".unwrap_with_str("x"), "xab");
    /// assert_eq!("abx".unwrap_with_str("x"), "abx");
    /// assert_eq!("**hello**".unwrap_with_str("**"), "hello");
    /// assert_eq!("**hello".unwrap_with_str("**"), "**hello");
    /// assert_eq!("****".unwrap_with_str("**"), "");
    /// ```
    #[must_use]
    fn unwrap_with_str(&self, wrap_str: &str) -> &str;
}

macro_rules! impl_wrap {
    ($fn_name:ident, $wrap_ty:ty, $skip_check:expr) => {
        fn $fn_name(&self, wrap_with: $wrap_ty) -> String {
            if $skip_check(self, wrap_with) {
                return self.to_string();
            }
            format!("{}{}{}", wrap_with, self, wrap_with)
        }
    };
}

macro_rules! impl_wrap_if_missing {
    ($fn_name:ident, $wrap_ty:ty, $skip_check:expr) => {
        fn $fn_name(&self, wrap_with: $wrap_ty) -> Cow<'_, str> {
            if $skip_check(self, wrap_with) {
                return Cow::Borrowed(self);
            }
            let starts = self.starts_with(wrap_with);
            let ends = self.ends_with(wrap_with);
            match (starts, ends) {
                (true, true) => Cow::Borrowed(self),
                (true, false) => Cow::Owned(format!("{}{}", self, wrap_with)),
                (false, true) => Cow::Owned(format!("{}{}", wrap_with, self)),
                (false, false) => Cow::Owned(format!("{}{}{}", wrap_with, self, wrap_with)),
            }
        }
    };
}

macro_rules! impl_unwrap {
    ($fn_name:ident, $wrap_ty:ty, $len_fn:expr) => {
        fn $fn_name(&self, wrap_with: $wrap_ty) -> &str {
            let wrap_len = $len_fn(wrap_with);
            if wrap_len == 0 || self.len() < wrap_len * 2 {
                return self;
            }
            if self.starts_with(wrap_with) && self.ends_with(wrap_with) {
                &self[wrap_len..self.len() - wrap_len]
            } else {
                self
            }
        }
    };
}

impl StringWrap for str {
    impl_wrap!(wrap_with_char, char, |s: &str, c: char| s.is_empty()
        || c == '\0');
    impl_wrap!(wrap_with_str, &str, |s: &str, w: &str| s.is_empty()
        || w.is_empty());

    impl_wrap_if_missing!(wrap_if_missing_char, char, |s: &str, c: char| s.is_empty()
        || c == '\0');
    impl_wrap_if_missing!(wrap_if_missing_str, &str, |s: &str, w: &str| s.is_empty()
        || w.is_empty());

    impl_unwrap!(unwrap_with_char, char, |c: char| c.len_utf8());
    impl_unwrap!(unwrap_with_str, &str, |s: &str| s.len());
}

#[cfg(test)]
mod tests {
    use super::*;

    mod wrap_with_char {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!("".wrap_with_char('x'), "");
        }

        #[test]
        fn null_char() {
            assert_eq!("ab".wrap_with_char('\0'), "ab");
        }

        #[test]
        fn simple_wrap() {
            assert_eq!("ab".wrap_with_char('x'), "xabx");
        }

        #[test]
        fn single_quote() {
            assert_eq!("ab".wrap_with_char('\''), "'ab'");
        }

        #[test]
        fn double_quote_already_present() {
            assert_eq!("\"ab\"".wrap_with_char('"'), "\"\"ab\"\"");
        }

        #[test]
        fn unicode_char() {
            assert_eq!("hello".wrap_with_char('§'), "§hello§");
        }

        #[test]
        fn emoji_wrapper() {
            assert_eq!("hello".wrap_with_char('🦀'), "🦀hello🦀");
        }

        #[test]
        fn mixed_ascii_and_emoji_content() {
            assert_eq!("hello🌍world".wrap_with_char('*'), "*hello🌍world*");
        }
    }

    mod wrap_with_str {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!("".wrap_with_str("x"), "");
        }

        #[test]
        fn empty_wrapper() {
            assert_eq!("ab".wrap_with_str(""), "ab");
        }

        #[test]
        fn simple_wrap() {
            assert_eq!("ab".wrap_with_str("x"), "xabx");
        }

        #[test]
        fn double_quote() {
            assert_eq!("ab".wrap_with_str("\""), "\"ab\"");
        }

        #[test]
        fn double_quote_already_present() {
            assert_eq!("\"ab\"".wrap_with_str("\""), "\"\"ab\"\"");
        }

        #[test]
        fn single_quote() {
            assert_eq!("ab".wrap_with_str("'"), "'ab'");
        }

        #[test]
        fn single_quote_already_present() {
            assert_eq!("'abcd'".wrap_with_str("'"), "''abcd''");
        }

        #[test]
        fn mixed_quotes_double_in_single() {
            assert_eq!("\"abcd\"".wrap_with_str("'"), "'\"abcd\"'");
        }

        #[test]
        fn mixed_quotes_single_in_double() {
            assert_eq!("'abcd'".wrap_with_str("\""), "\"'abcd'\"");
        }

        #[test]
        fn multi_char_wrapper() {
            assert_eq!("hello".wrap_with_str("**"), "**hello**");
        }

        #[test]
        fn emoji_wrapper() {
            assert_eq!("hello".wrap_with_str("🦀"), "🦀hello🦀");
        }

        #[test]
        fn multi_char_emoji_wrapper() {
            assert_eq!("hello".wrap_with_str("🦀🦀"), "🦀🦀hello🦀🦀");
        }

        #[test]
        fn cjk_content() {
            assert_eq!("你好".wrap_with_str("【"), "【你好【");
        }
    }

    mod wrap_if_missing_char {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!("".wrap_if_missing_char('x'), "");
        }

        #[test]
        fn null_char() {
            assert_eq!("ab".wrap_if_missing_char('\0'), "ab");
        }

        #[test]
        fn not_wrapped() {
            assert_eq!("ab".wrap_if_missing_char('x'), "xabx");
        }

        #[test]
        fn already_wrapped() {
            assert_eq!("xabx".wrap_if_missing_char('x'), "xabx");
        }

        #[test]
        fn only_starts_with() {
            assert_eq!("xab".wrap_if_missing_char('x'), "xabx");
        }

        #[test]
        fn only_ends_with() {
            assert_eq!("abx".wrap_if_missing_char('x'), "xabx");
        }

        #[test]
        fn single_quote_already_wrapped() {
            assert_eq!("'ab'".wrap_if_missing_char('\''), "'ab'");
        }

        #[test]
        fn single_char_string() {
            assert_eq!("x".wrap_if_missing_char('x'), "x");
        }

        #[test]
        fn single_emoji_equals_wrapper() {
            assert_eq!("🦀".wrap_if_missing_char('🦀'), "🦀");
        }
    }

    mod wrap_if_missing_str {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!("".wrap_if_missing_str("x"), "");
        }

        #[test]
        fn empty_wrapper() {
            assert_eq!("ab".wrap_if_missing_str(""), "ab");
        }

        #[test]
        fn not_wrapped() {
            assert_eq!("ab".wrap_if_missing_str("x"), "xabx");
        }

        #[test]
        fn already_wrapped() {
            assert_eq!("xabx".wrap_if_missing_str("x"), "xabx");
        }

        #[test]
        fn only_starts_with() {
            assert_eq!("xab".wrap_if_missing_str("x"), "xabx");
        }

        #[test]
        fn only_ends_with() {
            assert_eq!("abx".wrap_if_missing_str("x"), "xabx");
        }

        #[test]
        fn double_quote_already_wrapped() {
            assert_eq!("\"ab\"".wrap_if_missing_str("\""), "\"ab\"");
        }

        #[test]
        fn multi_char_wrapper_already_wrapped() {
            assert_eq!("**hello**".wrap_if_missing_str("**"), "**hello**");
        }

        #[test]
        fn multi_char_wrapper_only_starts() {
            assert_eq!("**hello".wrap_if_missing_str("**"), "**hello**");
        }

        #[test]
        fn multi_char_wrapper_only_ends() {
            assert_eq!("hello**".wrap_if_missing_str("**"), "**hello**");
        }

        #[test]
        fn emoji_not_wrapped() {
            assert_eq!("hello".wrap_if_missing_str("🦀"), "🦀hello🦀");
        }

        #[test]
        fn already_wrapped_with_emoji() {
            assert_eq!("🦀hello🦀".wrap_if_missing_str("🦀"), "🦀hello🦀");
        }
    }

    mod unwrap_with_char {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!("".unwrap_with_char('x'), "");
        }

        #[test]
        fn single_char_string() {
            assert_eq!("x".unwrap_with_char('x'), "x");
        }

        #[test]
        fn wrapped_string() {
            assert_eq!("xabx".unwrap_with_char('x'), "ab");
        }

        #[test]
        fn only_starts_with() {
            assert_eq!("xab".unwrap_with_char('x'), "xab");
        }

        #[test]
        fn only_ends_with() {
            assert_eq!("abx".unwrap_with_char('x'), "abx");
        }

        #[test]
        fn single_quote() {
            assert_eq!("'ab'".unwrap_with_char('\''), "ab");
        }

        #[test]
        fn double_quote() {
            assert_eq!("\"ab\"".unwrap_with_char('"'), "ab");
        }

        #[test]
        fn just_wrapper_chars() {
            assert_eq!("xx".unwrap_with_char('x'), "");
        }

        #[test]
        fn unicode_wrapper() {
            assert_eq!("§hello§".unwrap_with_char('§'), "hello");
        }

        #[test]
        fn not_wrapped() {
            assert_eq!("ab".unwrap_with_char('x'), "ab");
        }

        #[test]
        fn emoji_wrapper() {
            assert_eq!("🦀hello🦀".unwrap_with_char('🦀'), "hello");
        }

        #[test]
        fn string_too_short_for_emoji_wrapper() {
            // Emoji is 4 bytes, "ab" is 2 bytes, so string is too short to unwrap
            assert_eq!("ab".unwrap_with_char('🦀'), "ab");
        }

        #[test]
        fn mixed_ascii_and_emoji_content() {
            assert_eq!("*hello🌍world*".unwrap_with_char('*'), "hello🌍world");
        }
    }

    mod unwrap_with_str {
        use super::*;

        #[test]
        fn empty_string() {
            assert_eq!("".unwrap_with_str("x"), "");
        }

        #[test]
        fn empty_wrapper() {
            assert_eq!("ab".unwrap_with_str(""), "ab");
        }

        #[test]
        fn single_char_wrapper() {
            assert_eq!("x".unwrap_with_str("x"), "x");
        }

        #[test]
        fn wrapped_string() {
            assert_eq!("xabx".unwrap_with_str("x"), "ab");
        }

        #[test]
        fn only_starts_with() {
            assert_eq!("xab".unwrap_with_str("x"), "xab");
        }

        #[test]
        fn only_ends_with() {
            assert_eq!("abx".unwrap_with_str("x"), "abx");
        }

        #[test]
        fn multi_char_wrapper() {
            assert_eq!("**hello**".unwrap_with_str("**"), "hello");
        }

        #[test]
        fn multi_char_wrapper_only_starts() {
            assert_eq!("**hello".unwrap_with_str("**"), "**hello");
        }

        #[test]
        fn just_wrapper_strings() {
            assert_eq!("****".unwrap_with_str("**"), "");
        }

        #[test]
        fn not_wrapped() {
            assert_eq!("ab".unwrap_with_str("x"), "ab");
        }

        #[test]
        fn wrapper_longer_than_half_string() {
            assert_eq!("abc".unwrap_with_str("ab"), "abc");
        }

        #[test]
        fn multi_char_emoji_wrapper() {
            assert_eq!("🦀🦀hello🦀🦀".unwrap_with_str("🦀🦀"), "hello");
        }

        #[test]
        fn just_emoji_wrappers() {
            assert_eq!("🦀🦀".unwrap_with_str("🦀"), "");
        }

        #[test]
        fn cjk_wrapper() {
            assert_eq!("「hello」".unwrap_with_str("「"), "「hello」");
            assert_eq!("「hello「".unwrap_with_str("「"), "hello");
        }
    }

    mod string_types {
        use super::*;

        #[test]
        fn string_type_wrap() {
            assert_eq!(String::from("hello").wrap_with_char('"'), "\"hello\"");
        }

        #[test]
        fn string_ref_unwrap() {
            let s = String::from("\"hello\"");
            assert_eq!(s.unwrap_with_char('"'), "hello");
        }

        #[test]
        fn boxed_str() {
            let s: Box<str> = "hello".into();
            assert_eq!(s.wrap_with_str("**"), "**hello**");
        }
    }
}