Trait collections::str::StrExtExperimental [-]  [+] [src]

pub trait StrExt: Slice<uint, str> + ?Sized {
    fn escape_default(&self) -> String { ... }
    fn escape_unicode(&self) -> String { ... }
    fn replace(&self, from: &str, to: &str) -> String { ... }
    fn repeat(&self, nn: uint) -> String { ... }
    fn lev_distance(&self, t: &str) -> uint { ... }
    fn nfd_chars<'a>(&'a self) -> Decompositions<'a> { ... }
    fn nfkd_chars<'a>(&'a self) -> Decompositions<'a> { ... }
    fn nfc_chars<'a>(&'a self) -> Recompositions<'a> { ... }
    fn nfkc_chars<'a>(&'a self) -> Recompositions<'a> { ... }
    fn contains(&self, pat: &str) -> bool { ... }
    fn contains_char<P: CharEq>(&self, pat: P) -> bool { ... }
    fn chars(&self) -> Chars { ... }
    fn bytes(&self) -> Bytes { ... }
    fn char_indices(&self) -> CharIndices { ... }
    fn split<P: CharEq>(&self, pat: P) -> Split<P> { ... }
    fn splitn<P: CharEq>(&self, count: uint, pat: P) -> SplitN<P> { ... }
    fn split_terminator<P: CharEq>(&self, pat: P) -> SplitTerminator<P> { ... }
    fn rsplitn<P: CharEq>(&self, count: uint, pat: P) -> RSplitN<P> { ... }
    fn match_indices<'a>(&'a self, pat: &'a str) -> MatchIndices<'a> { ... }
    fn split_str<'a>(&'a self, pat: &'a str) -> StrSplits<'a> { ... }
    fn lines(&self) -> Lines { ... }
    fn lines_any(&self) -> LinesAny { ... }
    fn char_len(&self) -> uint { ... }
    fn slice(&self, begin: uint, end: uint) -> &str { ... }
    fn slice_from(&self, begin: uint) -> &str { ... }
    fn slice_to(&self, end: uint) -> &str { ... }
    fn slice_chars(&self, begin: uint, end: uint) -> &str { ... }
    unsafe fn slice_unchecked(&self, begin: uint, end: uint) -> &str { ... }
    fn starts_with(&self, pat: &str) -> bool { ... }
    fn ends_with(&self, pat: &str) -> bool { ... }
    fn trim_matches<P: CharEq>(&self, pat: P) -> &str { ... }
    fn trim_chars<'a, C: CharEq>(&'a self, to_trim: C) -> &'a str { ... }
    fn trim_left_matches<P: CharEq>(&self, pat: P) -> &str { ... }
    fn trim_left_chars<'a, C: CharEq>(&'a self, to_trim: C) -> &'a str { ... }
    fn trim_right_matches<P: CharEq>(&self, pat: P) -> &str { ... }
    fn trim_right_chars<'a, C: CharEq>(&'a self, to_trim: C) -> &'a str { ... }
    fn is_char_boundary(&self, index: uint) -> bool { ... }
    fn char_range_at(&self, start: uint) -> CharRange { ... }
    fn char_range_at_reverse(&self, start: uint) -> CharRange { ... }
    fn char_at(&self, i: uint) -> char { ... }
    fn char_at_reverse(&self, i: uint) -> char { ... }
    fn as_bytes(&self) -> &[u8] { ... }
    fn find<P: CharEq>(&self, pat: P) -> Option<uint> { ... }
    fn rfind<P: CharEq>(&self, pat: P) -> Option<uint> { ... }
    fn find_str(&self, needle: &str) -> Option<uint> { ... }
    fn slice_shift_char(&self) -> Option<(char, &str)> { ... }
    fn subslice_offset(&self, inner: &str) -> uint { ... }
    fn as_ptr(&self) -> *const u8 { ... }
    fn utf16_units(&self) -> Utf16Units { ... }
    fn len(&self) -> uint { ... }
    fn is_empty(&self) -> bool { ... }
    fn parse<F: FromStr>(&self) -> Option<F> { ... }
    fn graphemes(&self, is_extended: bool) -> Graphemes { ... }
    fn grapheme_indices(&self, is_extended: bool) -> GraphemeIndices { ... }
    fn words(&self) -> Words { ... }
    fn is_whitespace(&self) -> bool { ... }
    fn is_alphanumeric(&self) -> bool { ... }
    fn width(&self, is_cjk: bool) -> uint { ... }
    fn trim(&self) -> &str { ... }
    fn trim_left(&self) -> &str { ... }
    fn trim_right(&self) -> &str { ... }
    fn into_string(&self) -> String { ... }
}

Any string that can be represented as a slice.

Provided Methods

fn escape_default(&self) -> String

Escapes each char in s with char::escape_default.

fn escape_unicode(&self) -> String

Escapes each char in s with char::escape_unicode.

fn replace(&self, from: &str, to: &str) -> String

Replaces all occurrences of one string with another.

Arguments

  • from - The string to replace
  • to - The replacement string

Return value

The original string with all occurrences of from replaced with to.

Examples

fn main() { let s = "Do you know the muffin man, The muffin man, the muffin man, ...".to_string(); assert_eq!(s.replace("muffin man", "little lamb"), "Do you know the little lamb, The little lamb, the little lamb, ...".to_string()); // not found, so no change. assert_eq!(s.replace("cookie monster", "little lamb"), s); }
let s = "Do you know the muffin man,
The muffin man, the muffin man, ...".to_string();

assert_eq!(s.replace("muffin man", "little lamb"),
           "Do you know the little lamb,
The little lamb, the little lamb, ...".to_string());

// not found, so no change.
assert_eq!(s.replace("cookie monster", "little lamb"), s);

fn repeat(&self, nn: uint) -> String

Given a string, makes a new string with repeated copies of it.

fn lev_distance(&self, t: &str) -> uint

Returns the Levenshtein Distance between two strings.

fn nfd_chars<'a>(&'a self) -> Decompositions<'a>

Returns an iterator over the string in Unicode Normalization Form D (canonical decomposition).

fn nfkd_chars<'a>(&'a self) -> Decompositions<'a>

Returns an iterator over the string in Unicode Normalization Form KD (compatibility decomposition).

fn nfc_chars<'a>(&'a self) -> Recompositions<'a>

An Iterator over the string in Unicode Normalization Form C (canonical decomposition followed by canonical composition).

fn nfkc_chars<'a>(&'a self) -> Recompositions<'a>

An Iterator over the string in Unicode Normalization Form KC (compatibility decomposition followed by canonical composition).

fn contains(&self, pat: &str) -> bool

Returns true if a string contains a string pattern.

Arguments

  • pat - The string pattern to look for

Example

fn main() { assert!("bananas".contains("nana")); }
assert!("bananas".contains("nana"));

fn contains_char<P: CharEq>(&self, pat: P) -> bool

Returns true if a string contains a char pattern.

Arguments

  • pat - The char pattern to look for

Example

fn main() { assert!("hello".contains_char('e')); }
assert!("hello".contains_char('e'));

fn chars(&self) -> Chars

An iterator over the characters of self. Note, this iterates over Unicode code-points, not Unicode graphemes.

Example

fn main() { let v: Vec<char> = "abc åäö".chars().collect(); assert_eq!(v, vec!['a', 'b', 'c', ' ', 'å', 'ä', 'ö']); }
let v: Vec<char> = "abc åäö".chars().collect();
assert_eq!(v, vec!['a', 'b', 'c', ' ', 'å', 'ä', 'ö']);

fn bytes(&self) -> Bytes

An iterator over the bytes of self

Example

fn main() { let v: Vec<u8> = "bors".bytes().collect(); assert_eq!(v, b"bors".to_vec()); }
let v: Vec<u8> = "bors".bytes().collect();
assert_eq!(v, b"bors".to_vec());

fn char_indices(&self) -> CharIndices

An iterator over the characters of self and their byte offsets.

fn split<P: CharEq>(&self, pat: P) -> Split<P>

An iterator over substrings of self, separated by characters matched by the pattern pat.

Example

fn main() { let v: Vec<&str> = "Mary had a little lamb".split(' ').collect(); assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]); let v: Vec<&str> = "abc1def2ghi".split(|&: c: char| c.is_numeric()).collect(); assert_eq!(v, vec!["abc", "def", "ghi"]); let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect(); assert_eq!(v, vec!["lion", "", "tiger", "leopard"]); let v: Vec<&str> = "".split('X').collect(); assert_eq!(v, vec![""]); }
let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]);

let v: Vec<&str> = "abc1def2ghi".split(|&: c: char| c.is_numeric()).collect();
assert_eq!(v, vec!["abc", "def", "ghi"]);

let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
assert_eq!(v, vec!["lion", "", "tiger", "leopard"]);

let v: Vec<&str> = "".split('X').collect();
assert_eq!(v, vec![""]);

fn splitn<P: CharEq>(&self, count: uint, pat: P) -> SplitN<P>

An iterator over substrings of self, separated by characters matched by the pattern pat, restricted to splitting at most count times.

Example

fn main() { let v: Vec<&str> = "Mary had a little lambda".splitn(2, ' ').collect(); assert_eq!(v, vec!["Mary", "had", "a little lambda"]); let v: Vec<&str> = "abc1def2ghi".splitn(1, |&: c: char| c.is_numeric()).collect(); assert_eq!(v, vec!["abc", "def2ghi"]); let v: Vec<&str> = "lionXXtigerXleopard".splitn(2, 'X').collect(); assert_eq!(v, vec!["lion", "", "tigerXleopard"]); let v: Vec<&str> = "abcXdef".splitn(0, 'X').collect(); assert_eq!(v, vec!["abcXdef"]); let v: Vec<&str> = "".splitn(1, 'X').collect(); assert_eq!(v, vec![""]); }
let v: Vec<&str> = "Mary had a little lambda".splitn(2, ' ').collect();
assert_eq!(v, vec!["Mary", "had", "a little lambda"]);

let v: Vec<&str> = "abc1def2ghi".splitn(1, |&: c: char| c.is_numeric()).collect();
assert_eq!(v, vec!["abc", "def2ghi"]);

let v: Vec<&str> = "lionXXtigerXleopard".splitn(2, 'X').collect();
assert_eq!(v, vec!["lion", "", "tigerXleopard"]);

let v: Vec<&str> = "abcXdef".splitn(0, 'X').collect();
assert_eq!(v, vec!["abcXdef"]);

let v: Vec<&str> = "".splitn(1, 'X').collect();
assert_eq!(v, vec![""]);

fn split_terminator<P: CharEq>(&self, pat: P) -> SplitTerminator<P>

An iterator over substrings of self, separated by characters matched by the pattern pat.

Equivalent to split, except that the trailing substring is skipped if empty (terminator semantics).

Example

fn main() { let v: Vec<&str> = "A.B.".split_terminator('.').collect(); assert_eq!(v, vec!["A", "B"]); let v: Vec<&str> = "A..B..".split_terminator('.').collect(); assert_eq!(v, vec!["A", "", "B", ""]); let v: Vec<&str> = "Mary had a little lamb".split(' ').rev().collect(); assert_eq!(v, vec!["lamb", "little", "a", "had", "Mary"]); let v: Vec<&str> = "abc1def2ghi".split(|&: c: char| c.is_numeric()).rev().collect(); assert_eq!(v, vec!["ghi", "def", "abc"]); let v: Vec<&str> = "lionXXtigerXleopard".split('X').rev().collect(); assert_eq!(v, vec!["leopard", "tiger", "", "lion"]); }
let v: Vec<&str> = "A.B.".split_terminator('.').collect();
assert_eq!(v, vec!["A", "B"]);

let v: Vec<&str> = "A..B..".split_terminator('.').collect();
assert_eq!(v, vec!["A", "", "B", ""]);

let v: Vec<&str> = "Mary had a little lamb".split(' ').rev().collect();
assert_eq!(v, vec!["lamb", "little", "a", "had", "Mary"]);

let v: Vec<&str> = "abc1def2ghi".split(|&: c: char| c.is_numeric()).rev().collect();
assert_eq!(v, vec!["ghi", "def", "abc"]);

let v: Vec<&str> = "lionXXtigerXleopard".split('X').rev().collect();
assert_eq!(v, vec!["leopard", "tiger", "", "lion"]);

fn rsplitn<P: CharEq>(&self, count: uint, pat: P) -> RSplitN<P>

An iterator over substrings of self, separated by characters matched by the pattern pat, starting from the end of the string. Restricted to splitting at most count times.

Example

fn main() { let v: Vec<&str> = "Mary had a little lamb".rsplitn(2, ' ').collect(); assert_eq!(v, vec!["lamb", "little", "Mary had a"]); let v: Vec<&str> = "abc1def2ghi".rsplitn(1, |&: c: char| c.is_numeric()).collect(); assert_eq!(v, vec!["ghi", "abc1def"]); let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(2, 'X').collect(); assert_eq!(v, vec!["leopard", "tiger", "lionX"]); }
let v: Vec<&str> = "Mary had a little lamb".rsplitn(2, ' ').collect();
assert_eq!(v, vec!["lamb", "little", "Mary had a"]);

let v: Vec<&str> = "abc1def2ghi".rsplitn(1, |&: c: char| c.is_numeric()).collect();
assert_eq!(v, vec!["ghi", "abc1def"]);

let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(2, 'X').collect();
assert_eq!(v, vec!["leopard", "tiger", "lionX"]);

fn match_indices<'a>(&'a self, pat: &'a str) -> MatchIndices<'a>

An iterator over the start and end indices of the disjoint matches of the pattern pat within self.

That is, each returned value (start, end) satisfies self.slice(start, end) == sep. For matches of sep within self that overlap, only the indices corresponding to the first match are returned.

Example

fn main() { let v: Vec<(uint, uint)> = "abcXXXabcYYYabc".match_indices("abc").collect(); assert_eq!(v, vec![(0,3), (6,9), (12,15)]); let v: Vec<(uint, uint)> = "1abcabc2".match_indices("abc").collect(); assert_eq!(v, vec![(1,4), (4,7)]); let v: Vec<(uint, uint)> = "ababa".match_indices("aba").collect(); assert_eq!(v, vec![(0, 3)]); // only the first `aba` }
let v: Vec<(uint, uint)> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, vec![(0,3), (6,9), (12,15)]);

let v: Vec<(uint, uint)> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, vec![(1,4), (4,7)]);

let v: Vec<(uint, uint)> = "ababa".match_indices("aba").collect();
assert_eq!(v, vec![(0, 3)]); // only the first `aba`

fn split_str<'a>(&'a self, pat: &'a str) -> StrSplits<'a>

An iterator over the substrings of self separated by the pattern sep.

Example

fn main() { let v: Vec<&str> = "abcXXXabcYYYabc".split_str("abc").collect(); assert_eq!(v, vec!["", "XXX", "YYY", ""]); let v: Vec<&str> = "1abcabc2".split_str("abc").collect(); assert_eq!(v, vec!["1", "", "2"]); }
let v: Vec<&str> = "abcXXXabcYYYabc".split_str("abc").collect();
assert_eq!(v, vec!["", "XXX", "YYY", ""]);

let v: Vec<&str> = "1abcabc2".split_str("abc").collect();
assert_eq!(v, vec!["1", "", "2"]);

fn lines(&self) -> Lines

An iterator over the lines of a string (subsequences separated by \n). This does not include the empty string after a trailing \n.

Example

fn main() { let four_lines = "foo\nbar\n\nbaz\n"; let v: Vec<&str> = four_lines.lines().collect(); assert_eq!(v, vec!["foo", "bar", "", "baz"]); }
let four_lines = "foo\nbar\n\nbaz\n";
let v: Vec<&str> = four_lines.lines().collect();
assert_eq!(v, vec!["foo", "bar", "", "baz"]);

fn lines_any(&self) -> LinesAny

An iterator over the lines of a string, separated by either \n or \r\n. As with .lines(), this does not include an empty trailing line.

Example

fn main() { let four_lines = "foo\r\nbar\n\r\nbaz\n"; let v: Vec<&str> = four_lines.lines_any().collect(); assert_eq!(v, vec!["foo", "bar", "", "baz"]); }
let four_lines = "foo\r\nbar\n\r\nbaz\n";
let v: Vec<&str> = four_lines.lines_any().collect();
assert_eq!(v, vec!["foo", "bar", "", "baz"]);

fn char_len(&self) -> uint

Returns the number of Unicode code points (char) that a string holds.

This does not perform any normalization, and is O(n), since UTF-8 is a variable width encoding of code points.

Warning: The number of code points in a string does not directly correspond to the number of visible characters or width of the visible text due to composing characters, and double- and zero-width ones.

See also .len() for the byte length.

Example

fn main() { #![allow(deprecated)] // composed forms of `ö` and `é` let c = "Löwe 老虎 Léopard"; // German, Simplified Chinese, French // decomposed forms of `ö` and `é` let d = "Lo\u{0308}we 老虎 Le\u{0301}opard"; assert_eq!(c.char_len(), 15); assert_eq!(d.char_len(), 17); assert_eq!(c.len(), 21); assert_eq!(d.len(), 23); // the two strings *look* the same println!("{}", c); println!("{}", d); }
// composed forms of `ö` and `é`
let c = "Löwe 老虎 Léopard"; // German, Simplified Chinese, French
// decomposed forms of `ö` and `é`
let d = "Lo\u{0308}we 老虎 Le\u{0301}opard";

assert_eq!(c.char_len(), 15);
assert_eq!(d.char_len(), 17);

assert_eq!(c.len(), 21);
assert_eq!(d.len(), 23);

// the two strings *look* the same
println!("{}", c);
println!("{}", d);

fn slice(&self, begin: uint, end: uint) -> &str

Returns a slice of the given string from the byte range [begin..end).

This operation is O(1).

Panics when begin and end do not point to valid characters or point beyond the last character of the string.

See also slice_to and slice_from for slicing prefixes and suffixes of strings, and slice_chars for slicing based on code point counts.

Example

fn main() { let s = "Löwe 老虎 Léopard"; assert_eq!(s.slice(0, 1), "L"); assert_eq!(s.slice(1, 9), "öwe 老"); // these will panic: // byte 2 lies within `ö`: // s.slice(2, 3); // byte 8 lies within `老` // s.slice(1, 8); // byte 100 is outside the string // s.slice(3, 100); }
let s = "Löwe 老虎 Léopard";
assert_eq!(s.slice(0, 1), "L");

assert_eq!(s.slice(1, 9), "öwe 老");

// these will panic:
// byte 2 lies within `ö`:
// s.slice(2, 3);

// byte 8 lies within `老`
// s.slice(1, 8);

// byte 100 is outside the string
// s.slice(3, 100);

fn slice_from(&self, begin: uint) -> &str

Returns a slice of the string from begin to its end.

Equivalent to self.slice(begin, self.len()).

Panics when begin does not point to a valid character, or is out of bounds.

See also slice, slice_to and slice_chars.

fn slice_to(&self, end: uint) -> &str

Returns a slice of the string from the beginning to byte end.

Equivalent to self.slice(0, end).

Panics when end does not point to a valid character, or is out of bounds.

See also slice, slice_from and slice_chars.

fn slice_chars(&self, begin: uint, end: uint) -> &str

Returns a slice of the string from the character range [begin..end).

That is, start at the begin-th code point of the string and continue to the end-th code point. This does not detect or handle edge cases such as leaving a combining character as the first code point of the string.

Due to the design of UTF-8, this operation is O(end). See slice, slice_to and slice_from for O(1) variants that use byte indices rather than code point indices.

Panics if begin > end or the either begin or end are beyond the last character of the string.

Example

fn main() { let s = "Löwe 老虎 Léopard"; assert_eq!(s.slice_chars(0, 4), "Löwe"); assert_eq!(s.slice_chars(5, 7), "老虎"); }
let s = "Löwe 老虎 Léopard";
assert_eq!(s.slice_chars(0, 4), "Löwe");
assert_eq!(s.slice_chars(5, 7), "老虎");

unsafe fn slice_unchecked(&self, begin: uint, end: uint) -> &str

Takes a bytewise (not UTF-8) slice from a string.

Returns the substring from [begin..end).

Caller must check both UTF-8 character boundaries and the boundaries of the entire slice as well.

fn starts_with(&self, pat: &str) -> bool

Returns true if the pattern pat is a prefix of the string.

Example

fn main() { assert!("banana".starts_with("ba")); }
assert!("banana".starts_with("ba"));

fn ends_with(&self, pat: &str) -> bool

Returns true if the pattern pat is a suffix of the string.

Example

fn main() { assert!("banana".ends_with("nana")); }
assert!("banana".ends_with("nana"));

fn trim_matches<P: CharEq>(&self, pat: P) -> &str

Returns a string with all pre- and suffixes that match the pattern pat repeatedly removed.

Arguments

  • pat - a string pattern

Example

fn main() { assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar"); let x: &[_] = &['1', '2']; assert_eq!("12foo1bar12".trim_matches(x), "foo1bar"); assert_eq!("123foo1bar123".trim_matches(|&: c: char| c.is_numeric()), "foo1bar"); }
assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
assert_eq!("123foo1bar123".trim_matches(|&: c: char| c.is_numeric()), "foo1bar");

fn trim_chars<'a, C: CharEq>(&'a self, to_trim: C) -> &'a str

Deprecated

fn trim_left_matches<P: CharEq>(&self, pat: P) -> &str

Returns a string with all prefixes that match the pattern pat repeatedly removed.

Arguments

  • pat - a string pattern

Example

fn main() { assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11"); let x: &[_] = &['1', '2']; assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12"); assert_eq!("123foo1bar123".trim_left_matches(|&: c: char| c.is_numeric()), "foo1bar123"); }
assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
assert_eq!("123foo1bar123".trim_left_matches(|&: c: char| c.is_numeric()), "foo1bar123");

fn trim_left_chars<'a, C: CharEq>(&'a self, to_trim: C) -> &'a str

Deprecated

fn trim_right_matches<P: CharEq>(&self, pat: P) -> &str

Returns a string with all suffixes that match the pattern pat repeatedly removed.

Arguments

  • pat - a string pattern

Example

fn main() { assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar"); let x: &[_] = &['1', '2']; assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar"); assert_eq!("123foo1bar123".trim_right_matches(|&: c: char| c.is_numeric()), "123foo1bar"); }
assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
assert_eq!("123foo1bar123".trim_right_matches(|&: c: char| c.is_numeric()), "123foo1bar");

fn trim_right_chars<'a, C: CharEq>(&'a self, to_trim: C) -> &'a str

Deprecated

fn is_char_boundary(&self, index: uint) -> bool

Check that index-th byte lies at the start and/or end of a UTF-8 code point sequence.

The start and end of the string (when index == self.len()) are considered to be boundaries.

Panics if index is greater than self.len().

Example

fn main() { let s = "Löwe 老虎 Léopard"; assert!(s.is_char_boundary(0)); // start of `老` assert!(s.is_char_boundary(6)); assert!(s.is_char_boundary(s.len())); // second byte of `ö` assert!(!s.is_char_boundary(2)); // third byte of `老` assert!(!s.is_char_boundary(8)); }
let s = "Löwe 老虎 Léopard";
assert!(s.is_char_boundary(0));
// start of `老`
assert!(s.is_char_boundary(6));
assert!(s.is_char_boundary(s.len()));

// second byte of `ö`
assert!(!s.is_char_boundary(2));

// third byte of `老`
assert!(!s.is_char_boundary(8));

fn char_range_at(&self, start: uint) -> CharRange

Pluck a character out of a string and return the index of the next character.

This function can be used to iterate over the Unicode characters of a string.

Example

This example manually iterates through the characters of a string; this should normally be done by .chars() or .char_indices.

fn main() { use std::str::CharRange; let s = "中华Việt Nam"; let mut i = 0u; while i < s.len() { let CharRange {ch, next} = s.char_range_at(i); println!("{}: {}", i, ch); i = next; } }
use std::str::CharRange;

let s = "中华Việt Nam";
let mut i = 0u;
while i < s.len() {
    let CharRange {ch, next} = s.char_range_at(i);
    println!("{}: {}", i, ch);
    i = next;
}

This outputs:

0: 中
3: 华
6: V
7: i
8: ệ
11: t
12:
13: N
14: a
15: m

Arguments

  • s - The string
  • i - The byte offset of the char to extract

Return value

A record {ch: char, next: uint} containing the char value and the byte index of the next Unicode character.

Panics

If i is greater than or equal to the length of the string. If i is not the index of the beginning of a valid UTF-8 character.

fn char_range_at_reverse(&self, start: uint) -> CharRange

Given a byte position and a str, return the previous char and its position.

This function can be used to iterate over a Unicode string in reverse.

Returns 0 for next index if called on start index 0.

Panics

If i is greater than the length of the string. If i is not an index following a valid UTF-8 character.

fn char_at(&self, i: uint) -> char

Plucks the character starting at the ith byte of a string.

Example

fn main() { let s = "abπc"; assert_eq!(s.char_at(1), 'b'); assert_eq!(s.char_at(2), 'π'); assert_eq!(s.char_at(4), 'c'); }
let s = "abπc";
assert_eq!(s.char_at(1), 'b');
assert_eq!(s.char_at(2), 'π');
assert_eq!(s.char_at(4), 'c');

Panics

If i is greater than or equal to the length of the string. If i is not the index of the beginning of a valid UTF-8 character.

fn char_at_reverse(&self, i: uint) -> char

Plucks the character ending at the ith byte of a string.

Panics

If i is greater than the length of the string. If i is not an index following a valid UTF-8 character.

fn as_bytes(&self) -> &[u8]

Work with the byte buffer of a string as a byte slice.

Example

fn main() { assert_eq!("bors".as_bytes(), b"bors"); }
assert_eq!("bors".as_bytes(), b"bors");

fn find<P: CharEq>(&self, pat: P) -> Option<uint>

Returns the byte index of the first character of self that matches the pattern pat.

Return value

Some containing the byte index of the last matching character or None if there is no match

Example

fn main() { let s = "Löwe 老虎 Léopard"; assert_eq!(s.find('L'), Some(0)); assert_eq!(s.find('é'), Some(14)); // the first space assert_eq!(s.find(|&: c: char| c.is_whitespace()), Some(5)); // neither are found let x: &[_] = &['1', '2']; assert_eq!(s.find(x), None); }
let s = "Löwe 老虎 Léopard";

assert_eq!(s.find('L'), Some(0));
assert_eq!(s.find('é'), Some(14));

// the first space
assert_eq!(s.find(|&: c: char| c.is_whitespace()), Some(5));

// neither are found
let x: &[_] = &['1', '2'];
assert_eq!(s.find(x), None);

fn rfind<P: CharEq>(&self, pat: P) -> Option<uint>

Returns the byte index of the last character of self that matches the pattern pat.

Return value

Some containing the byte index of the last matching character or None if there is no match.

Example

fn main() { let s = "Löwe 老虎 Léopard"; assert_eq!(s.rfind('L'), Some(13)); assert_eq!(s.rfind('é'), Some(14)); // the second space assert_eq!(s.rfind(|&: c: char| c.is_whitespace()), Some(12)); // searches for an occurrence of either `1` or `2`, but neither are found let x: &[_] = &['1', '2']; assert_eq!(s.rfind(x), None); }
let s = "Löwe 老虎 Léopard";

assert_eq!(s.rfind('L'), Some(13));
assert_eq!(s.rfind('é'), Some(14));

// the second space
assert_eq!(s.rfind(|&: c: char| c.is_whitespace()), Some(12));

// searches for an occurrence of either `1` or `2`, but neither are found
let x: &[_] = &['1', '2'];
assert_eq!(s.rfind(x), None);

fn find_str(&self, needle: &str) -> Option<uint>

Returns the byte index of the first matching substring

Arguments

  • needle - The string to search for

Return value

Some containing the byte index of the first matching substring or None if there is no match.

Example

fn main() { let s = "Löwe 老虎 Léopard"; assert_eq!(s.find_str("老虎 L"), Some(6)); assert_eq!(s.find_str("muffin man"), None); }
let s = "Löwe 老虎 Léopard";

assert_eq!(s.find_str("老虎 L"), Some(6));
assert_eq!(s.find_str("muffin man"), None);

fn slice_shift_char(&self) -> Option<(char, &str)>

Retrieves the first character from a string slice and returns it. This does not allocate a new string; instead, it returns a slice that point one character beyond the character that was shifted. If the string does not contain any characters, None is returned instead.

Example

fn main() { let s = "Löwe 老虎 Léopard"; let (c, s1) = s.slice_shift_char().unwrap(); assert_eq!(c, 'L'); assert_eq!(s1, "öwe 老虎 Léopard"); let (c, s2) = s1.slice_shift_char().unwrap(); assert_eq!(c, 'ö'); assert_eq!(s2, "we 老虎 Léopard"); }
let s = "Löwe 老虎 Léopard";
let (c, s1) = s.slice_shift_char().unwrap();
assert_eq!(c, 'L');
assert_eq!(s1, "öwe 老虎 Léopard");

let (c, s2) = s1.slice_shift_char().unwrap();
assert_eq!(c, 'ö');
assert_eq!(s2, "we 老虎 Léopard");

fn subslice_offset(&self, inner: &str) -> uint

Returns the byte offset of an inner slice relative to an enclosing outer slice.

Panics if inner is not a direct slice contained within self.

Example

fn main() { let string = "a\nb\nc"; let lines: Vec<&str> = string.lines().collect(); assert!(string.subslice_offset(lines[0]) == 0); // &"a" assert!(string.subslice_offset(lines[1]) == 2); // &"b" assert!(string.subslice_offset(lines[2]) == 4); // &"c" }
let string = "a\nb\nc";
let lines: Vec<&str> = string.lines().collect();

assert!(string.subslice_offset(lines[0]) == 0); // &"a"
assert!(string.subslice_offset(lines[1]) == 2); // &"b"
assert!(string.subslice_offset(lines[2]) == 4); // &"c"

fn as_ptr(&self) -> *const u8

Return an unsafe pointer to the strings buffer.

The caller must ensure that the string outlives this pointer, and that it is not reallocated (e.g. by pushing to the string).

fn utf16_units(&self) -> Utf16Units

Return an iterator of u16 over the string encoded as UTF-16.

fn len(&self) -> uint

Return the number of bytes in this string

Example

fn main() { assert_eq!("foo".len(), 3); assert_eq!("ƒoo".len(), 4); }
assert_eq!("foo".len(), 3);
assert_eq!("ƒoo".len(), 4);

fn is_empty(&self) -> bool

Returns true if this slice contains no bytes

Example

fn main() { assert!("".is_empty()); }
assert!("".is_empty());

fn parse<F: FromStr>(&self) -> Option<F>

Parse this string into the specified type.

Example

fn main() { assert_eq!("4".parse::<u32>(), Some(4)); assert_eq!("j".parse::<u32>(), None); }
assert_eq!("4".parse::<u32>(), Some(4));
assert_eq!("j".parse::<u32>(), None);

fn graphemes(&self, is_extended: bool) -> Graphemes

Returns an iterator over the grapheme clusters of the string.

If is_extended is true, the iterator is over the extended grapheme clusters; otherwise, the iterator is over the legacy grapheme clusters. UAX#29 recommends extended grapheme cluster boundaries for general processing.

Example

fn main() { let gr1 = "a\u{310}e\u{301}o\u{308}\u{332}".graphemes(true).collect::<Vec<&str>>(); let b: &[_] = &["a\u{310}", "e\u{301}", "o\u{308}\u{332}"]; assert_eq!(gr1.as_slice(), b); let gr2 = "a\r\nb🇷🇺🇸🇹".graphemes(true).collect::<Vec<&str>>(); let b: &[_] = &["a", "\r\n", "b", "🇷🇺🇸🇹"]; assert_eq!(gr2.as_slice(), b); }
let gr1 = "a\u{310}e\u{301}o\u{308}\u{332}".graphemes(true).collect::<Vec<&str>>();
let b: &[_] = &["a\u{310}", "e\u{301}", "o\u{308}\u{332}"];
assert_eq!(gr1.as_slice(), b);
let gr2 = "a\r\nb🇷🇺🇸🇹".graphemes(true).collect::<Vec<&str>>();
let b: &[_] = &["a", "\r\n", "b", "🇷🇺🇸🇹"];
assert_eq!(gr2.as_slice(), b);

fn grapheme_indices(&self, is_extended: bool) -> GraphemeIndices

Returns an iterator over the grapheme clusters of self and their byte offsets. See graphemes() method for more information.

Example

fn main() { let gr_inds = "a̐éö̲\r\n".grapheme_indices(true).collect::<Vec<(uint, &str)>>(); let b: &[_] = &[(0u, "a̐"), (3, "é"), (6, "ö̲"), (11, "\r\n")]; assert_eq!(gr_inds.as_slice(), b); }
let gr_inds = "a̐éö̲\r\n".grapheme_indices(true).collect::<Vec<(uint, &str)>>();
let b: &[_] = &[(0u, "a̐"), (3, "é"), (6, "ö̲"), (11, "\r\n")];
assert_eq!(gr_inds.as_slice(), b);

fn words(&self) -> Words

An iterator over the words of a string (subsequences separated by any sequence of whitespace). Sequences of whitespace are collapsed, so empty "words" are not included.

Example

fn main() { let some_words = " Mary had\ta little \n\t lamb"; let v: Vec<&str> = some_words.words().collect(); assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]); }
let some_words = " Mary   had\ta little  \n\t lamb";
let v: Vec<&str> = some_words.words().collect();
assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]);

fn is_whitespace(&self) -> bool

Returns true if the string contains only whitespace.

Whitespace characters are determined by char::is_whitespace.

Example

fn main() { #![allow(deprecated)] assert!(" \t\n".is_whitespace()); assert!("".is_whitespace()); assert!( !"abc".is_whitespace()); }
assert!(" \t\n".is_whitespace());
assert!("".is_whitespace());

assert!( !"abc".is_whitespace());

fn is_alphanumeric(&self) -> bool

Returns true if the string contains only alphanumeric code points.

Alphanumeric characters are determined by char::is_alphanumeric.

Example

fn main() { #![allow(deprecated)] assert!("Löwe老虎Léopard123".is_alphanumeric()); assert!("".is_alphanumeric()); assert!( !" &*~".is_alphanumeric()); }
assert!("Löwe老虎Léopard123".is_alphanumeric());
assert!("".is_alphanumeric());

assert!( !" &*~".is_alphanumeric());

fn width(&self, is_cjk: bool) -> uint

Returns a string's displayed width in columns, treating control characters as zero-width.

is_cjk determines behavior for characters in the Ambiguous category: if is_cjk is true, these are 2 columns wide; otherwise, they are 1. In CJK locales, is_cjk should be true, else it should be false. Unicode Standard Annex #11 recommends that these characters be treated as 1 column (i.e., is_cjk = false) if the locale is unknown.

fn trim(&self) -> &str

Returns a string with leading and trailing whitespace removed.

fn trim_left(&self) -> &str

Returns a string with leading whitespace removed.

fn trim_right(&self) -> &str

Returns a string with trailing whitespace removed.

fn into_string(&self) -> String

Deprecated, call .to_owned() instead from the std::borrow::ToOwned trait.

Implementors