Trait core_extensions::strings::StringExt

pub trait StringExt: Borrow<str> {
    // Provided methods
    fn previous_char_boundary(&self, index: usize) -> usize { ... }
    fn next_char_boundary(&self, index: usize) -> usize { ... }
    fn left_char_boundary(&self, index: usize) -> usize { ... }
    fn right_char_boundary(&self, index: usize) -> usize { ... }
    fn split_while<'a, P, T: Eq + Clone>(
        &'a self,
        mapper: P,
    ) -> SplitWhile<'a, P, T> 
       where P: FnMut(char) -> T { ... }
    fn rsplit_while<'a, P, T: Eq + Clone>(
        &'a self,
        mapper: P,
    ) -> RSplitWhile<'a, P, T> 
       where P: FnMut(char) -> T { ... }
    fn get_nth_char_index(&self, nth: usize) -> Option<usize> { ... }
    fn nth_char_index(&self, nth: usize) -> usize { ... }
    fn nth_char(&self, nth: usize) -> Option<char> { ... }
    fn first_chars(&self, n: usize) -> &str { ... }
    fn last_chars(&self, n: usize) -> &str { ... }
    fn from_nth_char(&self, n: usize) -> &str { ... }
    fn calc_len_utf16(&self) -> usize { ... }
    fn get_char_at(&self, at_byte: usize) -> Option<char> { ... }
    fn char_indices_to(&self, to: usize) -> CharIndices<'_> { ... }
    fn char_indices_from(&self, from: usize) -> CharIndicesFrom<'_>  { ... }
    fn left_pad(&self, how_much: usize) -> String { ... }
    fn left_padder<'a>(&'a self, how_much: usize) -> LeftPadder<'a> { ... }
    fn line_indentation(&self) -> usize { ... }
    fn min_indentation(&self) -> usize { ... }
    fn max_indentation(&self) -> usize { ... }
}

Extension trait for strings (any type that borrows as str).

Provided Methods

fn previous_char_boundary(&self, index: usize) -> usize

Returns the previous character boundary, stopping at 0.

if index > self.len(), returns self.len().

Example

use core_extensions::StringExt;

let word = "foo速度惊人";

assert_eq!(word.previous_char_boundary(0), 0);
assert_eq!(word.previous_char_boundary(1), 0);
assert_eq!(word.previous_char_boundary(2), 1);
assert_eq!(word.previous_char_boundary(3), 2);

// This input index is inside of '速'
assert_eq!(word.previous_char_boundary(4), 3);
assert_eq!(word.previous_char_boundary(5), 3);
assert_eq!(word.previous_char_boundary(6), 3);

// This input index is inside of '度'
assert_eq!(word.previous_char_boundary(7), 6);

assert_eq!(word.previous_char_boundary(10000), word.len());

fn next_char_boundary(&self, index: usize) -> usize

Returns the next character boundary.

If index > self.len(), returns self.len()

Example

use core_extensions::StringExt;

let word = "foo誰もが";

assert_eq!(word.next_char_boundary(0), 1);
assert_eq!(word.next_char_boundary(1), 2);
assert_eq!(word.next_char_boundary(2), 3);

// This input index is inside of '誰'
assert_eq!(word.next_char_boundary(3), 6);
assert_eq!(word.next_char_boundary(4), 6);
assert_eq!(word.next_char_boundary(5), 6);

// This input index is inside of 'も'
assert_eq!(word.next_char_boundary(6), 9);

assert_eq!(word.next_char_boundary(10000), word.len());

fn left_char_boundary(&self, index: usize) -> usize

Returns the closest characted boundary left of index(including index).

if index > self.len(), returns self.len()

Example

use core_extensions::StringExt;

let word = "barЯзык";

assert_eq!(word.left_char_boundary(0), 0);
assert_eq!(word.left_char_boundary(1), 1);
assert_eq!(word.left_char_boundary(2), 2);

// The input index is inside of 'Я'
assert_eq!(word.left_char_boundary(3), 3);
assert_eq!(word.left_char_boundary(4), 3);

// The input index is inside of 'з'
assert_eq!(word.left_char_boundary(5), 5);
assert_eq!(word.left_char_boundary(6), 5);

assert_eq!(word.left_char_boundary(10000), word.len());

fn right_char_boundary(&self, index: usize) -> usize

Returns the closest characted boundary right of index(including index).

if index > self.len(), returns self.len()

Example

use core_extensions::StringExt;

let word = "rápido";

assert_eq!(word.right_char_boundary(0),0);

// The input index is inside of 'á'
assert_eq!(word.right_char_boundary(1), 1);
assert_eq!(word.right_char_boundary(2), 3);

assert_eq!(word.right_char_boundary(3), 3);
assert_eq!(word.right_char_boundary(4), 4);

assert_eq!(word.right_char_boundary(10000), word.len());

fn split_while<'a, P, T: Eq + Clone>( &'a self, mapper: P, ) -> SplitWhile<'a, P, T>

where P: FnMut(char) -> T,

Returns an iterator over substrings whose characters were mapped to the same key by mapper.

The returned type implements DoubleEndedIterator<Item =KeyStr<T>>.

Example

use core_extensions::strings::{StringExt, KeyStr};

assert_eq!(
    "Hello, world!".split_while(|c| c.is_alphanumeric()).collect::<Vec<_>>(),
    vec![
        KeyStr{key: true, str: "Hello"},
        KeyStr{key: false, str: ", "},
        KeyStr{key: true, str: "world"},
        KeyStr{key: false, str: "!"},
    ]
);
assert_eq!(
    "aaabbbccc".split_while(|c| c).collect::<Vec<_>>(),
    vec![
        KeyStr{key: 'a', str: "aaa"},
        KeyStr{key: 'b', str: "bbb"},
        KeyStr{key: 'c', str: "ccc"},
    ]
);

fn rsplit_while<'a, P, T: Eq + Clone>( &'a self, mapper: P, ) -> RSplitWhile<'a, P, T>

where P: FnMut(char) -> T,

A variation of split_while that iterates from the right(the order of substrings is reversed).

The returned type implements DoubleEndedIterator<Item =KeyStr<T>>.

Example

use core_extensions::strings::{StringExt, KeyStr};

assert_eq!(
    "Hello, world!".rsplit_while(|c| c.is_alphanumeric()).collect::<Vec<_>>(),
    vec![
        KeyStr{key: false, str: "!"},
        KeyStr{key: true, str: "world"},
        KeyStr{key: false, str: ", "},
        KeyStr{key: true, str: "Hello"},
    ]
);
assert_eq!(
    "aaabbbccc".rsplit_while(|c| c).collect::<Vec<_>>(),
    vec![
        KeyStr{key: 'c', str: "ccc"},
        KeyStr{key: 'b', str: "bbb"},
        KeyStr{key: 'a', str: "aaa"},
    ]
);

fn get_nth_char_index(&self, nth: usize) -> Option<usize>

The byte index of the nth character

If there is no nth character, this returns None.

This operation takes O(n) time, where n is self.len().

Example

use core_extensions::StringExt;

let word = "fooпозволяющий";

assert_eq!(word.get_nth_char_index(0), Some(0));
assert_eq!(word.get_nth_char_index(1), Some(1));
assert_eq!(word.get_nth_char_index(2), Some(2));
assert_eq!(word.get_nth_char_index(3), Some(3));
assert_eq!(word.get_nth_char_index(4), Some(5));
assert_eq!(word.get_nth_char_index(5), Some(7));

assert_eq!(word.get_nth_char_index(13), Some(23));
assert_eq!(word.get_nth_char_index(14), None);

fn nth_char_index(&self, nth: usize) -> usize

The byte index of the nth character

If there is no nth character, this returns self.len().

This operation takes O(n) time, where n is self.len().

Example

use core_extensions::StringExt;

let word = "fooпозволяющий";

assert_eq!(word.nth_char_index(0), 0);
assert_eq!(word.nth_char_index(1), 1);
assert_eq!(word.nth_char_index(2), 2);
assert_eq!(word.nth_char_index(3), 3);
assert_eq!(word.nth_char_index(4), 5);
assert_eq!(word.nth_char_index(5), 7);

assert_eq!(word.nth_char_index(13), 23);
assert_eq!(word.nth_char_index(14), word.len());

fn nth_char(&self, nth: usize) -> Option<char>

Returns the nth character in the str.

This operation takes O(n) time, where n is self.len().

Example

use core_extensions::StringExt;

let word = "débuter";

assert_eq!(word.nth_char(0), Some('d'));
assert_eq!(word.nth_char(1), Some('é'));
assert_eq!(word.nth_char(2), Some('b'));
assert_eq!(word.nth_char(3), Some('u'));
assert_eq!(word.nth_char(4), Some('t'));
assert_eq!(word.nth_char(5), Some('e'));
assert_eq!(word.nth_char(6), Some('r'));
assert_eq!(word.nth_char(7), None);

fn first_chars(&self, n: usize) -> &str

Returns a string containing the first n chars.

if n is greater than the amount of chars, this returns the entire string.

Example

use core_extensions::StringExt;

let word = "сине";

assert_eq!(word.first_chars(0),"");
assert_eq!(word.first_chars(1),"с");
assert_eq!(word.first_chars(2),"си");
assert_eq!(word.first_chars(3),"син");
assert_eq!(word.first_chars(4),"сине");
assert_eq!(word.first_chars(5),"сине");

fn last_chars(&self, n: usize) -> &str

Returns a string containing the last n chars

if n is greater than the amount of chars, this returns the entire string.

Example

use core_extensions::StringExt;

let word = "сине";

assert_eq!(word.last_chars(0),"");
assert_eq!(word.last_chars(1),"е");
assert_eq!(word.last_chars(2),"не");
assert_eq!(word.last_chars(3),"ине");
assert_eq!(word.last_chars(4),"сине");
assert_eq!(word.last_chars(5),"сине");

fn from_nth_char(&self, n: usize) -> &str

Returns the string from the nth character

if n is greater than the amount of chars, this returns an empty string.

Example

use core_extensions::StringExt;

let word = "υιός";

assert_eq!(word.from_nth_char(0), "υιός");
assert_eq!(word.from_nth_char(1), "ιός");
assert_eq!(word.from_nth_char(2), "ός");
assert_eq!(word.from_nth_char(3), "ς");
assert_eq!(word.from_nth_char(4), "");
assert_eq!(word.from_nth_char(5), "");
assert_eq!(word.from_nth_char(6), "");

fn calc_len_utf16(&self) -> usize

Returns the length of the string in utf16

Warning

This is calculated every time the function is called.

Example

use core_extensions::StringExt;

assert_eq!("foo".calc_len_utf16(), 3);
assert_eq!("υιός".calc_len_utf16(), 4);
assert_eq!("👪".calc_len_utf16(), 2);

fn get_char_at(&self, at_byte: usize) -> Option<char>

Returns the character at the at_byte index inside of the string, returning None if the index is outside the string.

If the index is between char boundaries, this returns the char at the previous char boundary.

If self.len() <= index, this returns none.

Example

use core_extensions::StringExt;

let word = "foo 効 门";

assert_eq!(word.get_char_at(0), Some('f'));
assert_eq!(word.get_char_at(1), Some('o'));
assert_eq!(word.get_char_at(2), Some('o'));
assert_eq!(word.get_char_at(3), Some(' '));
assert_eq!(word.get_char_at(4), Some('効'));
assert_eq!(word.get_char_at(5), Some('効'));
assert_eq!(word.get_char_at(6), Some('効'));
assert_eq!(word.get_char_at(7), Some(' '));
assert_eq!(word.get_char_at(8), Some('门'));
assert_eq!(word.get_char_at(9), Some('门'));
assert_eq!(word.get_char_at(10), Some('门'));
assert_eq!(word.get_char_at(11), None);

fn char_indices_to(&self, to: usize) -> CharIndices<'_>

Returns an iterator over (index,char) pairs up to (but not including) the char at the to byte.

IF the index is between char boundaries, it doesn’t include the char that index is inside of.

if index > self.len(), returns an iterator over the entire string.

Example

use core_extensions::StringExt;

let word = "foo 効 ";

assert_eq!(word.char_indices_to(0).collect::<Vec<_>>(), vec![]);
assert_eq!(word.char_indices_to(1).collect::<Vec<_>>(), vec![(0, 'f')]);
 
let expected_a = vec![(0, 'f'), (1, 'o'), (2, 'o'), (3, ' ')];
assert_eq!(word.char_indices_to(4).collect::<Vec<_>>(), expected_a);
assert_eq!(word.char_indices_to(5).collect::<Vec<_>>(), expected_a);
assert_eq!(word.char_indices_to(6).collect::<Vec<_>>(), expected_a);
 
let expected_b = vec![(0, 'f'), (1, 'o'), (2, 'o'), (3, ' '), (4, '効')];
assert_eq!(word.char_indices_to(7).collect::<Vec<_>>(), expected_b);
     
let expected_c = vec![(0, 'f'), (1, 'o'), (2, 'o'), (3, ' '), (4, '効'), (7, ' ')];
assert_eq!(word.char_indices_to(8).collect::<Vec<_>>(), expected_c);
assert_eq!(word.char_indices_to(100).collect::<Vec<_>>(), expected_c);

fn char_indices_from(&self, from: usize) -> CharIndicesFrom<'_>

Returns an iterator over (index, char) pairs, starting from the from byte.

If the index is between char boundaries, this starts from the char at the previous char boundary.

if index > self.len(), returns an empty iterator.

Example

use core_extensions::StringExt;

let word = "foo 効 ";

let expected_a = vec![(0, 'f'), (1, 'o'), (2, 'o'), (3, ' '), (4, '効'), (7, ' ')];
assert_eq!(word.char_indices_from(0).collect::<Vec<_>>(), expected_a);

let expected_b = vec![(1, 'o'), (2, 'o'), (3, ' '), (4, '効'), (7, ' ')];
assert_eq!(word.char_indices_from(1).collect::<Vec<_>>(), expected_b);

let expected_c = vec![(3, ' '), (4, '効'), (7, ' ')];
assert_eq!(word.char_indices_from(3).collect::<Vec<_>>(), expected_c);

let expected_c = vec![(4, '効'), (7, ' ')];
assert_eq!(word.char_indices_from(4).collect::<Vec<_>>(), expected_c);
assert_eq!(word.char_indices_from(5).collect::<Vec<_>>(), expected_c);
assert_eq!(word.char_indices_from(6).collect::<Vec<_>>(), expected_c);
 
assert_eq!(word.char_indices_from(7).collect::<Vec<_>>(), vec![(7, ' ')]);

assert_eq!(word.char_indices_from(8).collect::<Vec<_>>(), vec![]);

assert_eq!(word.char_indices_from(9).collect::<Vec<_>>(), vec![]);

fn left_pad(&self, how_much: usize) -> String

Pads the string on the left with how_much additional spaces.

Example

use core_extensions::StringExt;

assert_eq!(
    "what\n  the\n    hall".left_pad(4),
    "    what\n      the\n        hall"
);

fn left_padder<'a>(&'a self, how_much: usize) -> LeftPadder<'a>

Returns a value that pads the string on the left with how_much additional spaces in its Display impl.

Use this to avoid allocating an extra string.

Example

use core_extensions::StringExt;

assert_eq!(
   "what\n  the\n    hall".left_pad(4).to_string(),
   "    what\n      the\n        hall"
);

fn line_indentation(&self) -> usize

The indentation of the first line.

This considers lines that only contains whitespace to have as much indentation as they’re long.

Example

use core_extensions::StringExt;

assert_eq!("".line_indentation(), 0);
assert_eq!("    ".line_indentation(), 4);
assert_eq!("    \n      word".line_indentation(), 4);
assert_eq!("    \nword".line_indentation(), 4);

fn min_indentation(&self) -> usize

The minimum indentation of the string, ignoring lines that only contain whitespace.

Example

use core_extensions::StringExt;

assert_eq!("".min_indentation(), 0);
assert_eq!("    ".min_indentation(), 0);
assert_eq!("    \nf".min_indentation(), 0);
assert_eq!("    \n      word".min_indentation(), 6);
assert_eq!("    \n word".min_indentation(), 1);
assert_eq!("    \n\nword".min_indentation(), 0);

fn max_indentation(&self) -> usize

The maximum indentation of the string, ignoring lines that only contain whitespace.

Example

use core_extensions::StringExt;

assert_eq!("".max_indentation(), 0);
assert_eq!("    ".max_indentation(), 0);
assert_eq!("    \n      word".max_indentation(), 6);
assert_eq!("    \n  word".max_indentation(), 2);

Object Safety

This trait is not object safe.

Implementors

impl<T> StringExt for T

where T: Borrow<str> + ?Sized,