Trait std::str::StrSlice
pub trait StrSlice<'a> { fn contains<'a>(&self, needle: &'a str) -> bool; fn contains_char(&self, needle: char) -> bool; fn chars(&self) -> Chars<'a>; fn chars_rev(&self) -> RevChars<'a>; fn bytes(&self) -> Bytes<'a>; fn bytes_rev(&self) -> RevBytes<'a>; fn char_indices(&self) -> CharOffsets<'a>; fn char_indices_rev(&self) -> RevCharOffsets<'a>; fn split<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep>; fn splitn<Sep: CharEq>(&self, sep: Sep, count: uint) -> CharSplitsN<'a, Sep>; fn split_terminator<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep>; fn rsplit<Sep: CharEq>(&self, sep: Sep) -> RevCharSplits<'a, Sep>; fn rsplitn<Sep: CharEq>(&self, sep: Sep, count: uint) -> CharSplitsN<'a, Sep>; fn match_indices(&self, sep: &'a str) -> MatchIndices<'a>; fn split_str(&self, &'a str) -> StrSplits<'a>; fn lines(&self) -> CharSplits<'a, char>; fn lines_any(&self) -> AnyLines<'a>; fn words(&self) -> Words<'a>; fn nfd_chars(&self) -> Normalizations<'a>; fn nfkd_chars(&self) -> Normalizations<'a>; fn is_whitespace(&self) -> bool; fn is_alphanumeric(&self) -> bool; fn char_len(&self) -> uint; fn slice(&self, begin: uint, end: uint) -> &'a str; fn slice_from(&self, begin: uint) -> &'a str; fn slice_to(&self, end: uint) -> &'a str; fn slice_chars(&self, begin: uint, end: uint) -> &'a str; fn starts_with(&self, needle: &str) -> bool; fn ends_with(&self, needle: &str) -> bool; fn escape_default(&self) -> ~str; fn escape_unicode(&self) -> ~str; fn trim(&self) -> &'a str; fn trim_left(&self) -> &'a str; fn trim_right(&self) -> &'a str; fn trim_chars<C: CharEq>(&self, to_trim: &C) -> &'a str; fn trim_left_chars<C: CharEq>(&self, to_trim: &C) -> &'a str; fn trim_right_chars<C: CharEq>(&self, to_trim: &C) -> &'a str; fn replace(&self, from: &str, to: &str) -> ~str; fn to_owned(&self) -> ~str; fn to_utf16(&self) -> ~[u16]; 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) -> &'a [u8]; fn find<C: CharEq>(&self, search: C) -> Option<uint>; fn rfind<C: CharEq>(&self, search: C) -> Option<uint>; fn find_str(&self, &str) -> Option<uint>; fn repeat(&self, nn: uint) -> ~str; fn slice_shift_char(&self) -> (Option<char>, &'a str); fn lev_distance(&self, t: &str) -> uint; fn subslice_offset(&self, inner: &str) -> uint; fn as_ptr(&self) -> *u8; }
Methods for string slices
Required Methods
fn contains<'a>(&self, needle: &'a str) -> bool
fn contains_char(&self, needle: char) -> bool
fn chars(&self) -> Chars<'a>
An iterator over the characters of self
. Note, this iterates
over unicode code-points, not unicode graphemes.
Example
let v: ~[char] = "abc åäö".chars().collect(); assert_eq!(v, ~['a', 'b', 'c', ' ', 'å', 'ä', 'ö']);
fn chars_rev(&self) -> RevChars<'a>
An iterator over the characters of self
, in reverse order.
fn bytes(&self) -> Bytes<'a>
An iterator over the bytes of self
fn bytes_rev(&self) -> RevBytes<'a>
An iterator over the bytes of self
, in reverse order
fn char_indices(&self) -> CharOffsets<'a>
An iterator over the characters of self
and their byte offsets.
fn char_indices_rev(&self) -> RevCharOffsets<'a>
An iterator over the characters of self
and their byte offsets,
in reverse order.
fn split<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep>
An iterator over substrings of self
, separated by characters
matched by sep
.
Example
let v: ~[&str] = "Mary had a little lamb".split(' ').collect(); assert_eq!(v, ~["Mary", "had", "a", "little", "lamb"]); let v: ~[&str] = "abc1def2ghi".split(|c: char| c.is_digit()).collect(); assert_eq!(v, ~["abc", "def", "ghi"]); let v: ~[&str] = "lionXXtigerXleopard".split('X').collect(); assert_eq!(v, ~["lion", "", "tiger", "leopard"]);
fn splitn<Sep: CharEq>(&self, sep: Sep, count: uint) -> CharSplitsN<'a, Sep>
An iterator over substrings of self
, separated by characters
matched by sep
, restricted to splitting at most count
times.
Example
let v: ~[&str] = "Mary had a little lambda".splitn(' ', 2).collect(); assert_eq!(v, ~["Mary", "had", "a little lambda"]); let v: ~[&str] = "abc1def2ghi".splitn(|c: char| c.is_digit(), 1).collect(); assert_eq!(v, ~["abc", "def2ghi"]); let v: ~[&str] = "lionXXtigerXleopard".splitn('X', 2).collect(); assert_eq!(v, ~["lion", "", "tigerXleopard"]);
fn split_terminator<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep>
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: ~[&str] = "A.B.".split_terminator('.').collect(); assert_eq!(v, ~["A", "B"]); let v: ~[&str] = "A..B..".split_terminator('.').collect(); assert_eq!(v, ~["A", "", "B", ""]);
fn rsplit<Sep: CharEq>(&self, sep: Sep) -> RevCharSplits<'a, Sep>
An iterator over substrings of self
, separated by characters
matched by sep
, in reverse order.
Example
let v: ~[&str] = "Mary had a little lamb".rsplit(' ').collect(); assert_eq!(v, ~["lamb", "little", "a", "had", "Mary"]); let v: ~[&str] = "abc1def2ghi".rsplit(|c: char| c.is_digit()).collect(); assert_eq!(v, ~["ghi", "def", "abc"]); let v: ~[&str] = "lionXXtigerXleopard".rsplit('X').collect(); assert_eq!(v, ~["leopard", "tiger", "", "lion"]);
fn rsplitn<Sep: CharEq>(&self, sep: Sep, count: uint) -> CharSplitsN<'a, Sep>
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: ~[&str] = "Mary had a little lamb".rsplitn(' ', 2).collect(); assert_eq!(v, ~["lamb", "little", "Mary had a"]); let v: ~[&str] = "abc1def2ghi".rsplitn(|c: char| c.is_digit(), 1).collect(); assert_eq!(v, ~["ghi", "abc1def"]); let v: ~[&str] = "lionXXtigerXleopard".rsplitn('X', 2).collect(); assert_eq!(v, ~["leopard", "tiger", "lionX"]);
fn match_indices(&self, sep: &'a str) -> MatchIndices<'a>
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 indicies corresponding to the
first match are returned.
Example
let v: ~[(uint, uint)] = "abcXXXabcYYYabc".match_indices("abc").collect(); assert_eq!(v, ~[(0,3), (6,9), (12,15)]); let v: ~[(uint, uint)] = "1abcabc2".match_indices("abc").collect(); assert_eq!(v, ~[(1,4), (4,7)]); let v: ~[(uint, uint)] = "ababa".match_indices("aba").collect(); assert_eq!(v, ~[(0, 3)]); // only the first `aba`
fn split_str(&self, &'a str) -> StrSplits<'a>
An iterator over the substrings of self
separated by sep
.
Example
let v: ~[&str] = "abcXXXabcYYYabc".split_str("abc").collect(); assert_eq!(v, ~["", "XXX", "YYY", ""]); let v: ~[&str] = "1abcabc2".split_str("abc").collect(); assert_eq!(v, ~["1", "", "2"]);
fn lines(&self) -> CharSplits<'a, char>
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: ~[&str] = four_lines.lines().collect(); assert_eq!(v, ~["foo", "bar", "", "baz"]);
fn lines_any(&self) -> AnyLines<'a>
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: ~[&str] = four_lines.lines_any().collect(); assert_eq!(v, ~["foo", "bar", "", "baz"]);
fn words(&self) -> Words<'a>
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: ~[&str] = some_words.words().collect(); assert_eq!(v, ~["Mary", "had", "a", "little", "lamb"]);
fn nfd_chars(&self) -> Normalizations<'a>
An Iterator over the string in Unicode Normalization Form D (canonical decomposition).
fn nfkd_chars(&self) -> Normalizations<'a>
An Iterator over the string in Unicode Normalization Form KD (compatibility decomposition).
fn is_whitespace(&self) -> bool
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());
fn is_alphanumeric(&self) -> bool
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());
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
// 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);
fn slice(&self, begin: uint, end: uint) -> &'a str
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);
fn slice_from(&self, begin: uint) -> &'a str
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
.
fn slice_to(&self, end: uint) -> &'a str
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
.
fn slice_chars(&self, begin: uint, end: uint) -> &'a 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.
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), "老虎");
fn starts_with(&self, needle: &str) -> bool
Returns true if needle
is a prefix of the string.
fn ends_with(&self, needle: &str) -> bool
Returns true if needle
is a suffix of the string.
fn escape_default(&self) -> ~str
Escape each char in s
with char::escape_default
.
fn escape_unicode(&self) -> ~str
Escape each char in s
with char::escape_unicode
.
fn trim(&self) -> &'a str
Returns a string with leading and trailing whitespace removed.
fn trim_left(&self) -> &'a str
Returns a string with leading whitespace removed.
fn trim_right(&self) -> &'a str
Returns a string with trailing whitespace removed.
fn trim_chars<C: CharEq>(&self, to_trim: &C) -> &'a str
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")
fn trim_left_chars<C: CharEq>(&self, to_trim: &C) -> &'a str
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")
fn trim_right_chars<C: CharEq>(&self, to_trim: &C) -> &'a str
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")
fn replace(&self, from: &str, to: &str) -> ~str
Replace all occurrences of one string with another.
Arguments
from
- The string to replaceto
- The replacement string
Return value
The original string with all occurances of from
replaced with to
.
Example
let s = ~"Do you know the muffin man, The muffin man, the muffin man, ..."; assert_eq!(s.replace("muffin man", "little lamb"), ~"Do you know the little lamb, The little lamb, the little lamb, ..."); // not found, so no change. assert_eq!(s.replace("cookie monster", "little lamb"), s);
fn to_owned(&self) -> ~str
Copy a slice into a new owned str.
fn to_utf16(&self) -> ~[u16]
Converts to a vector of u16
encoded as UTF-16.
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.
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));
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 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.
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.
fn char_at(&self, i: uint) -> char
Plucks the character starting at the i
th byte of a string
fn char_at_reverse(&self, i: uint) -> char
Plucks the character ending at the i
th byte of a string
fn as_bytes(&self) -> &'a [u8]
Work with the byte buffer of a string as a byte slice.
fn find<C: CharEq>(&self, search: C) -> Option<uint>
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);
fn rfind<C: CharEq>(&self, search: C) -> Option<uint>
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);
fn find_str(&self, &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
let s = "Löwe 老虎 Léopard"; assert_eq!(s.find_str("老虎 L"), Some(6)); assert_eq!(s.find_str("muffin man"), None);
fn repeat(&self, nn: uint) -> ~str
Given a string, make a new string with repeated copies of it.
fn slice_shift_char(&self) -> (Option<char>, &'a 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, 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");
fn lev_distance(&self, t: &str) -> uint
Levenshtein Distance between two strings.
fn subslice_offset(&self, inner: &str) -> uint
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: ~[&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) -> *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).
Implementors
impl<'a> StrSlice<'a> for &'a str