bt_string_utils/

lib.rs

//! Multiple String related functions

use rand::{distr::Alphanumeric, Rng};
use regex::Regex;

/// Splits the given string at the first occurrence of the specified separator.
///
/// # Arguments
///
/// * `s` - A string slice to be split.
/// * `separator` - The substring used as a separator.
///
/// # Returns
///
/// A tuple containing two strings:
/// - The first part of the string before the separator.
/// - The second part of the string after the separator.
///
/// If the separator is not found, returns the original string and an empty string.
///
/// # Examples
///
/// ```
/// use bt_string_utils::get_first_of_split;
/// let (part1, part2) = get_first_of_split("hello=world", "=");
/// assert_eq!(part1, "hello");
/// assert_eq!(part2, "world");
///
/// let (part1, part2) = get_first_of_split("key:value", ":");
/// assert_eq!(part1, "key");
/// assert_eq!(part2, "value");
///
/// let (part1, part2) = get_first_of_split("no=separator", " ");
/// assert_eq!(part1, "no=separator");
/// assert_eq!(part2, "");
/// ```
pub fn get_first_of_split(s: &str, separator: &str) -> (String, String){
    if let Some(position) = s.find(separator){
        let str1 = s[..position].to_owned();
        let str2 = s[position + 1..].to_owned();
        (str1, str2)
    }else{
        (s.to_owned(),"".to_owned())
    }
}

/// Finds and returns the substring before the first occurrence of a given separator.
///
/// # Arguments
///
/// * `s` - A string slice that holds the text to search within.
/// * `separator` - A string slice that specifies the character(s) to look for as a separator.
///
/// # Returns
///
/// Returns a new `String` containing the substring before the first occurrence of the separator.
/// If the separator is not found, an empty `String` is returned.
///
/// # Examples
///
/// ```
/// use bt_string_utils::get_first_occurrance;
/// let result = get_first_occurrance("Hello, world!", ", ");
/// assert_eq!(result, "Hello");
///
/// let result = get_first_occurrance("No separator here", ",");
/// assert_eq!(result, "");
/// ```

pub fn get_first_occurrance(s: &str, separator: &str) -> String{
    if let Some(position) = s.find(separator){
        s[..position].to_owned()
    }else{
        "".to_owned()
    }
}

/// Finds and returns the value corresponding to a given key in a vector of key-value pairs.
///
/// # Arguments
///
/// * `kv_pairs` - A reference to a vector of strings where each string represents a key-value pair separated by '='.
/// * `key_to_find` - The key for which the corresponding value is to be found.
///
/// # Returns
///
/// Returns an `Option`:
/// - `Some(value)` if a matching key is found, containing the value associated with that key.
/// - `None` if no matching key is found.
///
/// # Examples
///
/// ```
/// use bt_string_utils::find_value_by_key;
/// let pairs = vec!["name=John".to_owned(), "age=30".to_owned(), "city=New York".to_owned()];
/// assert_eq!(find_value_by_key(&pairs, "name"), Some("John".to_string()));
/// assert_eq!(find_value_by_key(&pairs, "gender"), None);
/// ```
pub fn find_value_by_key(kv_pairs: &Vec<String>, key_to_find: &str) -> Option<String> {
    for item in kv_pairs {
        // Split the string at the '=' character
        if let Some((key, value)) = item.split_once('=') {
            if key == key_to_find {
                return Some(value.to_owned());
            }
        }
    }
    None
}

/// Remove Location for remove_char function
pub enum RemoveLocationEnum {
    Begin,
    End,
}

/// Removes the first or last character of a string if it matches the given target character.
///
/// # Arguments
///
/// * `begin` - A boolean indicating whether to remove the first (`true`) or last (`false`) character.
/// * `input` - A `String` to process.
/// * `target` - The character to remove.
///
/// # Returns
///
/// Returns a new `String` with the character removed if it matched.
///
/// # Examples
///
/// ```
/// use bt_string_utils::{remove_char, RemoveLocationEnum};
/// let modified = remove_char(RemoveLocationEnum::Begin, &"hello".to_string(), 'h');
/// assert_eq!(modified, "ello");
///
/// let modified = remove_char(RemoveLocationEnum::End, &"world!".to_string(), '!');
/// assert_eq!(modified, "world");
/// ```
///
/// If the character doesn't match, the original string is returned:
///
/// ```
/// use bt_string_utils::{remove_char, RemoveLocationEnum};
/// let modified = remove_char(RemoveLocationEnum::Begin, &"rust".to_string(), 'x');
/// assert_eq!(modified, "rust");
/// ```
pub fn remove_char(remove_from: RemoveLocationEnum, input: &String, target: char) -> String {
    match remove_from{
        RemoveLocationEnum::Begin => if input.starts_with(target) {
                                        return input.chars().skip(1).collect();
                                     },
        RemoveLocationEnum::End => if input.ends_with(target) {
                                        return input.chars().take(input.len() - 1).collect();
                                    },
    }
    /*if begin {
        if input.starts_with(target) {
            return input.chars().skip(1).collect();
        }
    } else {
        if input.ends_with(target) {
            return input.chars().take(input.len() - 1).collect();
        }
    }*/
    input.to_string() // Return unchanged if no removal occurs
}

/// Generates a random URL-safe string of the specified length.
///
/// # Arguments
///
/// * `n` - The length of the generated string.
///
/// # Returns
///
/// A `String` containing `n` random alphanumeric characters (`A-Z`, `a-z`, `0-9`).
///
/// # Examples
///
/// ```
/// use bt_string_utils::generate_url_safe_string;
/// let random_string = generate_url_safe_string(16);
/// println!("Generated string: {}", random_string);
/// ```
///
/// # Notes
///
/// - Uses the `rand` crate to generate random alphanumeric characters.
/// - Ensures the output contains only **URL-safe** characters.
/// - May require the `rand` crate in your Cargo.toml:
///
/// ```toml
/// [dependencies]
/// rand = "0.8"
/// ```
pub fn generate_url_safe_string(n: usize) -> String {
    rand::rng()
        .sample_iter(&Alphanumeric)
        .take(n)
        .map(char::from)
        .collect()
}

/// Checks whether a given `haystack` string contains the specified `word`
/// as a whole word, using word boundaries.
///
/// A whole word match means the `word` must be surrounded by non-word characters
/// (e.g., spaces, punctuation) or string boundaries. Substrings within longer words
/// will not match.
///
/// # Arguments
///
/// * `text` - The string to search within.
/// * `word` - The target word to search for.
///
/// # Returns
///
/// * `true` if `word` appears as a whole word in `haystack`.
/// * `false` otherwise.
///
/// # Examples
///
/// ```
/// use bt_string_utils::contains_whole_word;
/// assert_eq!(contains_whole_word("this is a target match", "target"), true);
/// assert_eq!(contains_whole_word("this is a targeted match", "target"), false);
/// assert_eq!(contains_whole_word("no-target", "target"), false);
/// ```
pub fn contains_whole_word(text: &str, word: &str) -> bool {
    //let pattern = format!(r"\b{}\b", regex::escape(word));
    //let pattern = format!(r"(?i)(?<!\w){}(?!\w)", regex::escape(word));
    //let pattern =  format!(r"(?<![A-Za-z0-9-]){}(?![A-Za-z0-9-])",regex::escape(word) );
    let pattern = format!(r"(?:^|[^A-Za-z0-9-]){}(?:[^A-Za-z0-9-]|$)", regex::escape(word));    

    let re = Regex::new(&pattern).unwrap();
    re.is_match(text)
}