Returns true if one string contains another

Arguments

• needle - The string to look for

Returns true if a string contains a char.

Arguments

• needle - The char to look for

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

Example

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

An iterator over the bytes of self

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

An iterator over substrings of self, separated by characters matched by sep.

Example

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_digit()).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![""]);

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

Example

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(|c: char| c.is_digit(), 1).collect();
assert_eq!(v, vec!["abc", "def2ghi"]);

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

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

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

An iterator over substrings of self, separated by characters matched by sep.

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

Example

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_digit()).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"]);

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

Example

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(|c: char| c.is_digit(), 1).collect();
assert_eq!(v, vec!["ghi", "abc1def"]);

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

An iterator over the start and end indices of the disjoint matches of sep 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

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`

An iterator over the substrings of self separated by sep.

Example

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"]);

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

Example

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

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

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"]);

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

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"]);

Returns true if the string contains only whitespace.

Whitespace characters are determined by char::is_whitespace.

Example

assert!(" \t\n".is_whitespace());
assert!("".is_whitespace());

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

Returns true if the string contains only alphanumeric code points.

Alphanumeric characters are determined by char::is_alphanumeric.

Example

assert!("Löwe老虎Léopard123".is_alphanumeric());
assert!("".is_alphanumeric());

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

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

// composed forms of `ö` and `é`
let c = "Löwe 老虎 Léopard"; // German, Simplified Chinese, French
// decomposed forms of `ö` and `é`
let d = "Lo\u0308we 老虎 Le\u0301opard";

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);

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

This operation is O(1).

Fails 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

let s = "Löwe 老虎 Léopard";
assert_eq!(s.slice(0, 1), "L");

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

// these will fail:
// 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);

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

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

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

See also slice, slice_to and slice_chars.

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

Equivalent to self.slice(0, end).

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

See also slice, slice_from and slice_chars.

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.

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

Example

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

Returns true if needle is a prefix of the string.

Returns true if needle is a suffix of the string.

Returns a string with leading and trailing whitespace removed.

Returns a string with leading whitespace removed.

Returns a string with trailing whitespace removed.

Returns a string with characters that match to_trim removed.

Arguments

• to_trim - a character matcher

Example

assert_eq!("11foo1bar11".trim_chars('1'), "foo1bar")
assert_eq!("12foo1bar12".trim_chars(&['1', '2']), "foo1bar")
assert_eq!("123foo1bar123".trim_chars(|c: char| c.is_digit()), "foo1bar")

Returns a string with leading chars_to_trim removed.

Arguments

• to_trim - a character matcher

Example

assert_eq!("11foo1bar11".trim_left_chars('1'), "foo1bar11")
assert_eq!("12foo1bar12".trim_left_chars(&['1', '2']), "foo1bar12")
assert_eq!("123foo1bar123".trim_left_chars(|c: char| c.is_digit()), "foo1bar123")

Returns a string with trailing chars_to_trim removed.

Arguments

• to_trim - a character matcher

Example

assert_eq!("11foo1bar11".trim_right_chars('1'), "11foo1bar")
assert_eq!("12foo1bar12".trim_right_chars(&['1', '2']), "12foo1bar")
assert_eq!("123foo1bar123".trim_right_chars(|c: char| c.is_digit()), "123foo1bar")

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.

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

Example

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));

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 iterate through the characters of a string; this should normally by done by .chars() or .char_indices.

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;
}

Output

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.

Failure

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.

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.

Failure

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

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

Failure

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.

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

Failure

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

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

Returns the byte index of the first character of self that matches search.

Return value

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

Example

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
assert_eq!(s.find(&['1', '2']), None);

Returns the byte index of the last character of self that matches search.

Return value

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

Example

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
assert_eq!(s.rfind(&['1', '2']), None);

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

let s = "Löwe 老虎 Léopard";

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

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, a tuple of None and an empty string is returned instead.

Example

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

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

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

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

Example

let string = "a\nb\nc";
let lines: Vec<&str> = string.lines().collect();
let lines = lines.as_slice();

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

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).