diff options
Diffstat (limited to 'src/libcollections')
| -rw-r--r-- | src/libcollections/str.rs | 488 | ||||
| -rw-r--r-- | src/libcollections/string.rs | 2 |
2 files changed, 393 insertions, 97 deletions
diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs index c22b6fb9286..28ba7369d52 100644 --- a/src/libcollections/str.rs +++ b/src/libcollections/str.rs @@ -58,6 +58,8 @@ use core::iter::{Iterator, Extend}; use core::option::Option::{self, Some, None}; use core::result::Result; use core::str as core_str; +use core::str::pattern::Pattern; +use core::str::pattern::{Searcher, ReverseSearcher, DoubleEndedSearcher}; use unicode::str::{UnicodeStr, Utf16Encoder}; use core::convert::AsRef; @@ -69,14 +71,16 @@ use vec::Vec; use slice::SliceConcatExt; pub use core::str::{FromStr, Utf8Error, Str}; -pub use core::str::{Lines, LinesAny, MatchIndices, CharRange}; -pub use core::str::{Split, SplitTerminator, SplitN}; -pub use core::str::{RSplit, RSplitN}; +pub use core::str::{Lines, LinesAny, CharRange}; +pub use core::str::{Split, RSplit}; +pub use core::str::{SplitN, RSplitN}; +pub use core::str::{SplitTerminator, RSplitTerminator}; +pub use core::str::{Matches, RMatches}; +pub use core::str::{MatchIndices, RMatchIndices}; pub use core::str::{from_utf8, Chars, CharIndices, Bytes}; pub use core::str::{from_utf8_unchecked, ParseBoolError}; pub use unicode::str::{Words, Graphemes, GraphemeIndices}; -pub use core::str::Pattern; -pub use core::str::{Searcher, ReverseSearcher, DoubleEndedSearcher, SearchStep}; +pub use core::str::pattern; /* Section: Creating a string @@ -429,7 +433,8 @@ impl str { /// Replaces all occurrences of one string with another. /// - /// `replace` takes two arguments, a sub-`&str` to find in `self`, and a second `&str` to + /// `replace` takes two arguments, a sub-`&str` to find in `self`, and a + /// second `&str` to /// replace it with. If the original `&str` isn't found, no change occurs. /// /// # Examples @@ -581,12 +586,24 @@ impl str { /// An iterator over substrings of `self`, separated by characters /// matched by a pattern. /// - /// The pattern can be a simple `&str`, or a closure that determines - /// the split. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator will be double ended if the pattern allows a + /// reverse search and forward/reverse search yields the same elements. + /// This is true for, eg, `char` but not + /// for `&str`. + /// + /// If the pattern allows a reverse search but its results might differ + /// from a forward search, `rsplit()` can be used. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect(); @@ -594,81 +611,116 @@ impl str { /// /// let v: Vec<&str> = "".split('X').collect(); /// assert_eq!(v, [""]); + /// + /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect(); + /// assert_eq!(v, ["lion", "", "tiger", "leopard"]); + /// + /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect(); + /// assert_eq!(v, ["lion", "tiger", "leopard"]); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// let v: Vec<&str> = "abc1def2ghi".split(|c: char| c.is_numeric()).collect(); /// assert_eq!(v, ["abc", "def", "ghi"]); /// - /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect(); - /// assert_eq!(v, ["lion", "", "tiger", "leopard"]); + /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect(); + /// assert_eq!(v, ["lion", "tiger", "leopard"]); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> { core_str::StrExt::split(&self[..], pat) } - /// An iterator over substrings of `self`, separated by characters matched - /// by a pattern, returning most `count` items. + /// An iterator over substrings of `self`, separated by characters + /// matched by a pattern and yielded in reverse order. /// - /// The pattern can be a simple `&str`, or a closure that determines - /// the split. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. /// - /// The last element returned, if any, will contain the remainder of the - /// string. + /// # Iterator behavior /// - /// # Examples + /// The returned iterator requires that the pattern supports a + /// reverse search, + /// and it will be double ended if a forward/reverse search yields + /// the same elements. /// - /// Simple `&str` patterns: + /// For iterating from the front, `split()` can be used. /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lambda".splitn(2, ' ').collect(); - /// assert_eq!(v, ["Mary", "had a little lambda"]); + /// # Examples /// - /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(2, 'X').collect(); - /// assert_eq!(v, ["lion", "XtigerXleopard"]); + /// Simple patterns: /// - /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect(); - /// assert_eq!(v, ["abcXdef"]); + /// ```rust + /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect(); + /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]); /// - /// let v: Vec<&str> = "".splitn(1, 'X').collect(); + /// let v: Vec<&str> = "".rsplit('X').collect(); /// assert_eq!(v, [""]); - /// ``` /// - /// More complex patterns with a lambda: + /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect(); + /// assert_eq!(v, ["leopard", "tiger", "", "lion"]); /// + /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect(); + /// assert_eq!(v, ["leopard", "tiger", "lion"]); /// ``` - /// let v: Vec<&str> = "abc1def2ghi".splitn(2, |c: char| c.is_numeric()).collect(); - /// assert_eq!(v, ["abc", "def2ghi"]); + /// + /// More complex patterns with closures: + /// + /// ```rust + /// let v: Vec<&str> = "abc1def2ghi".rsplit(|c: char| c.is_numeric()).collect(); + /// assert_eq!(v, ["ghi", "def", "abc"]); + /// + /// let v: Vec<&str> = "lionXtigerXleopard".rsplit(char::is_uppercase).collect(); + /// assert_eq!(v, ["leopard", "tiger", "lion"]); /// ``` #[stable(feature = "rust1", since = "1.0.0")] - pub fn splitn<'a, P: Pattern<'a>>(&'a self, count: usize, pat: P) -> SplitN<'a, P> { - core_str::StrExt::splitn(&self[..], count, pat) + pub fn rsplit<'a, P: Pattern<'a>>(&'a self, pat: P) -> RSplit<'a, P> + where P::Searcher: ReverseSearcher<'a> + { + core_str::StrExt::rsplit(&self[..], pat) } /// An iterator over substrings of `self`, separated by characters /// matched by a pattern. /// - /// Equivalent to `split`, except that the trailing substring is skipped if empty. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns + /// like regular expressions. /// - /// The pattern can be a simple `&str`, or a closure that determines - /// the split. + /// Equivalent to `split`, except that the trailing substring + /// is skipped if empty. + /// + /// This method can be used for string data that is _terminated_, + /// rather than _seperated_ by a pattern. + /// + /// # Iterator behavior + /// + /// The returned iterator will be double ended if the pattern allows a + /// reverse search + /// and forward/reverse search yields the same elements. This is true + /// for, eg, `char` but not for `&str`. + /// + /// If the pattern allows a reverse search but its results might differ + /// from a forward search, `rsplit_terminator()` can be used. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// let v: Vec<&str> = "A.B.".split_terminator('.').collect(); /// assert_eq!(v, ["A", "B"]); /// - /// let v: Vec<&str> = "A..B..".split_terminator('.').collect(); + /// let v: Vec<&str> = "A..B..".split_terminator(".").collect(); /// assert_eq!(v, ["A", "", "B", ""]); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// let v: Vec<&str> = "abc1def2ghi3".split_terminator(|c: char| c.is_numeric()).collect(); @@ -679,32 +731,98 @@ impl str { core_str::StrExt::split_terminator(&self[..], pat) } - /// An iterator over substrings of `self`, separated by a pattern, - /// starting from the end of the string. + /// An iterator over substrings of `self`, separated by characters + /// matched by a pattern and yielded in reverse order. + /// + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// Equivalent to `split`, except that the trailing substring is + /// skipped if empty. + /// + /// This method can be used for string data that is _terminated_, + /// rather than _seperated_ by a pattern. + /// + /// # Iterator behavior + /// + /// The returned iterator requires that the pattern supports a + /// reverse search, and it will be double ended if a forward/reverse + /// search yields the same elements. + /// + /// For iterating from the front, `split_terminator()` can be used. /// /// # Examples /// /// Simple patterns: /// /// ``` - /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect(); - /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]); + /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect(); + /// assert_eq!(v, ["B", "A"]); /// - /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect(); - /// assert_eq!(v, ["leopard", "tiger", "lion"]); + /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect(); + /// assert_eq!(v, ["", "B", "", "A"]); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` - /// let v: Vec<&str> = "abc1def2ghi".rsplit(|c: char| c.is_numeric()).collect(); + /// let v: Vec<&str> = "abc1def2ghi3".rsplit_terminator(|c: char| c.is_numeric()).collect(); /// assert_eq!(v, ["ghi", "def", "abc"]); /// ``` #[stable(feature = "rust1", since = "1.0.0")] - pub fn rsplit<'a, P: Pattern<'a>>(&'a self, pat: P) -> RSplit<'a, P> + pub fn rsplit_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> RSplitTerminator<'a, P> where P::Searcher: ReverseSearcher<'a> { - core_str::StrExt::rsplit(&self[..], pat) + core_str::StrExt::rsplit_terminator(&self[..], pat) + } + + /// An iterator over substrings of `self`, separated by a pattern, + /// restricted to returning + /// at most `count` items. + /// + /// The last element returned, if any, will contain the remainder of the + /// string. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator will not be double ended, because it is + /// not efficient to support. + /// + /// If the pattern allows a reverse search, `rsplitn()` can be used. + /// + /// # Examples + /// + /// Simple patterns: + /// + /// ``` + /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect(); + /// assert_eq!(v, ["Mary", "had", "a little lambda"]); + /// + /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect(); + /// assert_eq!(v, ["lion", "", "tigerXleopard"]); + /// + /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect(); + /// assert_eq!(v, ["abcXdef"]); + /// + /// let v: Vec<&str> = "".splitn(1, 'X').collect(); + /// assert_eq!(v, [""]); + /// ``` + /// + /// More complex patterns with closures: + /// + /// ``` + /// let v: Vec<&str> = "abc1def2ghi".splitn(2, |c: char| c.is_numeric()).collect(); + /// assert_eq!(v, ["abc", "def2ghi"]); + /// ``` + #[stable(feature = "rust1", since = "1.0.0")] + pub fn splitn<'a, P: Pattern<'a>>(&'a self, count: usize, pat: P) -> SplitN<'a, P> { + core_str::StrExt::splitn(&self[..], count, pat) } /// An iterator over substrings of `self`, separated by a pattern, @@ -714,6 +832,18 @@ impl str { /// The last element returned, if any, will contain the remainder of the /// string. /// + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator will not be double ended, because it is not + /// efficient to support. + /// + /// `splitn()` can be used for splitting from the front. + /// /// # Examples /// /// Simple patterns: @@ -722,11 +852,14 @@ impl str { /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect(); /// assert_eq!(v, ["lamb", "little", "Mary had a"]); /// + /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect(); + /// assert_eq!(v, ["leopard", "tiger", "lionX"]); + /// /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect(); /// assert_eq!(v, ["leopard", "lion::tiger"]); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// let v: Vec<&str> = "abc1def2ghi".rsplitn(2, |c: char| c.is_numeric()).collect(); @@ -739,34 +872,166 @@ impl str { core_str::StrExt::rsplitn(&self[..], count, pat) } - /// An iterator over the start and end indices of the disjoint matches of a `&str` within - /// `self`. + /// An iterator over the matches of a pattern within `self`. + /// + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator will be double ended if the pattern allows + /// a reverse search + /// and forward/reverse search yields the same elements. This is true + /// for, eg, `char` but not + /// for `&str`. + /// + /// If the pattern allows a reverse search but its results might differ + /// from a forward search, `rmatches()` can be used. + /// + /// # Examples + /// + /// ``` + /// # #![feature(collections)] + /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect(); + /// assert_eq!(v, ["abc", "abc", "abc"]); + /// + /// let v: Vec<&str> = "1abc2abc3".matches(|c: char| c.is_numeric()).collect(); + /// assert_eq!(v, ["1", "2", "3"]); + /// ``` + #[unstable(feature = "collections", + reason = "method got recently added")] + pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> { + core_str::StrExt::matches(&self[..], pat) + } + + /// An iterator over the matches of a pattern within `self`, yielded in + /// reverse order. + /// + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator requires that the pattern supports a + /// reverse search, + /// and it will be double ended if a forward/reverse search yields + /// the same elements. + /// + /// For iterating from the front, `matches()` can be used. + /// + /// # Examples + /// + /// ``` + /// # #![feature(collections)] + /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect(); + /// assert_eq!(v, ["abc", "abc", "abc"]); + /// + /// let v: Vec<&str> = "1abc2abc3".rmatches(|c: char| c.is_numeric()).collect(); + /// assert_eq!(v, ["3", "2", "1"]); + /// ``` + #[unstable(feature = "collections", + reason = "method got recently added")] + pub fn rmatches<'a, P: Pattern<'a>>(&'a self, pat: P) -> RMatches<'a, P> + where P::Searcher: ReverseSearcher<'a> + { + core_str::StrExt::rmatches(&self[..], pat) + } + + /// An iterator over the start and end indices of the disjoint matches + /// of a pattern 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 + /// For matches of `pat` within `self` that overlap, only the indices + /// corresponding to the first /// match are returned. /// + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines + /// the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator will be double ended if the pattern allows a + /// reverse search + /// and forward/reverse search yields the same elements. This is true for, + /// eg, `char` but not + /// for `&str`. + /// + /// If the pattern allows a reverse search but its results might differ + /// from a forward search, `rmatch_indices()` can be used. + /// /// # Examples /// /// ``` /// # #![feature(collections)] /// let v: Vec<(usize, usize)> = "abcXXXabcYYYabc".match_indices("abc").collect(); - /// assert_eq!(v, [(0,3), (6,9), (12,15)]); + /// assert_eq!(v, [(0, 3), (6, 9), (12, 15)]); /// /// let v: Vec<(usize, usize)> = "1abcabc2".match_indices("abc").collect(); - /// assert_eq!(v, [(1,4), (4,7)]); + /// assert_eq!(v, [(1, 4), (4, 7)]); /// /// let v: Vec<(usize, usize)> = "ababa".match_indices("aba").collect(); /// assert_eq!(v, [(0, 3)]); // only the first `aba` /// ``` #[unstable(feature = "collections", reason = "might have its iterator type changed")] - // NB: Right now MatchIndices yields `(usize, usize)`, - // but it would be more consistent and useful to return `(usize, &str)` + // NB: Right now MatchIndices yields `(usize, usize)`, but it would + // be more consistent with `matches` and `char_indices` to return `(usize, &str)` pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> { core_str::StrExt::match_indices(&self[..], pat) } + /// An iterator over the start and end indices of the disjoint matches of + /// a pattern within + /// `self`, yielded in reverse order. + /// + /// For matches of `pat` within `self` that overlap, only the indices + /// corresponding to the last + /// match are returned. + /// + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines + /// the split. + /// Additional libraries might provide more complex patterns like + /// regular expressions. + /// + /// # Iterator behavior + /// + /// The returned iterator requires that the pattern supports a + /// reverse search, + /// and it will be double ended if a forward/reverse search yields + /// the same elements. + /// + /// For iterating from the front, `match_indices()` can be used. + /// + /// # Examples + /// + /// ``` + /// # #![feature(collections)] + /// let v: Vec<(usize, usize)> = "abcXXXabcYYYabc".rmatch_indices("abc").collect(); + /// assert_eq!(v, [(12, 15), (6, 9), (0, 3)]); + /// + /// let v: Vec<(usize, usize)> = "1abcabc2".rmatch_indices("abc").collect(); + /// assert_eq!(v, [(4, 7), (1, 4)]); + /// + /// let v: Vec<(usize, usize)> = "ababa".rmatch_indices("aba").collect(); + /// assert_eq!(v, [(2, 5)]); // only the last `aba` + /// ``` + #[unstable(feature = "collections", + reason = "might have its iterator type changed")] + // NB: Right now RMatchIndices yields `(usize, usize)`, but it would + // be more consistent with `rmatches` and `char_indices` to return `(usize, &str)` + pub fn rmatch_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> RMatchIndices<'a, P> + where P::Searcher: ReverseSearcher<'a> + { + core_str::StrExt::rmatch_indices(&self[..], pat) + } + /// An iterator over the lines of a string, separated by `\n`. /// /// This does not include the empty string after a trailing `\n`. @@ -793,7 +1058,8 @@ impl str { core_str::StrExt::lines(&self[..]) } - /// An iterator over the lines of a string, separated by either `\n` or `\r\n`. + /// 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. /// @@ -855,7 +1121,8 @@ impl str { /// /// # Unsafety /// - /// Caller must check both UTF-8 character boundaries and the boundaries of the entire slice as + /// Caller must check both UTF-8 character boundaries and the boundaries + /// of the entire slice as /// well. /// /// # Examples @@ -898,13 +1165,15 @@ impl str { core_str::StrExt::ends_with(&self[..], pat) } - /// Returns a string with all pre- and suffixes that match a pattern repeatedly removed. + /// Returns a string with all pre- and suffixes that match a pattern + /// repeatedly removed. /// - /// The pattern can be a simple `&str`, or a closure that determines the split. + /// The pattern can be a simple `char`, or a closure that determines + /// the split. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar"); @@ -913,7 +1182,7 @@ impl str { /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar"); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// assert_eq!("123foo1bar123".trim_matches(|c: char| c.is_numeric()), "foo1bar"); @@ -925,13 +1194,15 @@ impl str { core_str::StrExt::trim_matches(&self[..], pat) } - /// Returns a string with all prefixes that match a pattern repeatedly removed. + /// Returns a string with all prefixes that match a pattern + /// repeatedly removed. /// - /// The pattern can be a simple `&str`, or a closure that determines the split. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11"); @@ -940,7 +1211,7 @@ impl str { /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12"); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// assert_eq!("123foo1bar123".trim_left_matches(|c: char| c.is_numeric()), "foo1bar123"); @@ -950,13 +1221,15 @@ impl str { core_str::StrExt::trim_left_matches(&self[..], pat) } - /// Returns a string with all suffixes that match a pattern repeatedly removed. + /// Returns a string with all suffixes that match a pattern + /// repeatedly removed. /// - /// The pattern can be a simple `&str`, or a closure that determines the split. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the split. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar"); @@ -964,7 +1237,7 @@ impl str { /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar"); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// assert_eq!("123foo1bar123".trim_right_matches(|c: char| c.is_numeric()), "123foo1bar"); @@ -976,9 +1249,11 @@ impl str { core_str::StrExt::trim_right_matches(&self[..], pat) } - /// Check that `index`-th byte lies at the start and/or end of a UTF-8 code point sequence. + /// 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 + /// The start and end of the string (when `index == self.len()`) are + /// considered to be /// boundaries. /// /// # Panics @@ -1021,7 +1296,8 @@ impl str { /// /// # Examples /// - /// This example manually iterates through the characters of a string; this should normally be + /// This example manually iterates through the characters of a string; + /// this should normally be /// done by `.chars()` or `.char_indices()`. /// /// ``` @@ -1072,7 +1348,8 @@ impl str { /// /// # Examples /// - /// This example manually iterates through the characters of a string; this should normally be + /// This example manually iterates through the characters of a string; + /// this should normally be /// done by `.chars().rev()` or `.char_indices()`. /// /// ``` @@ -1135,7 +1412,8 @@ impl str { core_str::StrExt::char_at(&self[..], i) } - /// Given a byte position, return the `char` at that position, counting from the end. + /// Given a byte position, return the `char` at that position, counting + /// from the end. /// /// # Panics /// @@ -1170,31 +1448,36 @@ impl str { core_str::StrExt::as_bytes(&self[..]) } - /// Returns the byte index of the first character of `self` that matches the pattern, if it + /// Returns the byte index of the first character of `self` that matches + /// the pattern, if it /// exists. /// /// Returns `None` if it doesn't exist. /// - /// The pattern can be a simple `&str`, or a closure that determines the split. + /// The pattern can be a simple `&str`, `char`, or a closure that + /// determines the + /// split. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// let s = "Löwe 老虎 Léopard"; /// /// assert_eq!(s.find('L'), Some(0)); /// assert_eq!(s.find('é'), Some(14)); + /// assert_eq!(s.find("Léopard"), Some(13)); /// /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// let s = "Löwe 老虎 Léopard"; /// /// assert_eq!(s.find(|c: char| c.is_whitespace()), Some(5)); + /// assert_eq!(s.find(char::is_lowercase), Some(1)); /// ``` /// /// Not finding the pattern: @@ -1210,16 +1493,18 @@ impl str { core_str::StrExt::find(&self[..], pat) } - /// Returns the byte index of the last character of `self` that matches the pattern, if it + /// Returns the byte index of the last character of `self` that + /// matches the pattern, if it /// exists. /// /// Returns `None` if it doesn't exist. /// - /// The pattern can be a simple `&str`, or a closure that determines the split. + /// The pattern can be a simple `&str`, `char`, + /// or a closure that determines the split. /// /// # Examples /// - /// Simple `&str` patterns: + /// Simple patterns: /// /// ``` /// let s = "Löwe 老虎 Léopard"; @@ -1228,12 +1513,13 @@ impl str { /// assert_eq!(s.rfind('é'), Some(14)); /// ``` /// - /// More complex patterns with a lambda: + /// More complex patterns with closures: /// /// ``` /// let s = "Löwe 老虎 Léopard"; /// /// assert_eq!(s.rfind(|c: char| c.is_whitespace()), Some(12)); + /// assert_eq!(s.rfind(char::is_lowercase), Some(20)); /// ``` /// /// Not finding the pattern: @@ -1253,7 +1539,8 @@ impl str { /// Retrieves the first character from a `&str` and returns it. /// - /// This does not allocate a new string; instead, it returns a slice that points one character + /// This does not allocate a new string; instead, it returns a slice that + /// points one character /// beyond the character that was shifted. /// /// If the slice does not contain any characters, None is returned instead. @@ -1281,7 +1568,8 @@ impl str { core_str::StrExt::slice_shift_char(&self[..]) } - /// Returns the byte offset of an inner slice relative to an enclosing outer slice. + /// Returns the byte offset of an inner slice relative to an enclosing + /// outer slice. /// /// # Panics /// @@ -1306,7 +1594,8 @@ impl str { /// Return an unsafe pointer to the `&str`'s buffer. /// - /// The caller must ensure that the string outlives this pointer, and that it is not + /// The caller must ensure that the string outlives this pointer, and + /// that it is not /// reallocated (e.g. by pushing to the string). /// /// # Examples @@ -1382,7 +1671,8 @@ impl str { /// /// [graphemes]: http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries /// - /// If `is_extended` is true, the iterator is over the *extended grapheme clusters*; + /// If `is_extended` is true, the iterator is over the + /// *extended grapheme clusters*; /// otherwise, the iterator is over the *legacy grapheme clusters*. /// [UAX#29](http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries) /// recommends extended grapheme cluster boundaries for general processing. @@ -1407,7 +1697,8 @@ impl str { UnicodeStr::graphemes(&self[..], is_extended) } - /// Returns an iterator over the grapheme clusters of `self` and their byte offsets. See + /// Returns an iterator over the grapheme clusters of `self` and their + /// byte offsets. See /// `graphemes()` for more information. /// /// # Examples @@ -1427,7 +1718,8 @@ impl str { /// An iterator over the non-empty words of `self`. /// - /// A 'word' is a subsequence separated by any sequence of whitespace. Sequences of whitespace + /// A 'word' is a subsequence separated by any sequence of whitespace. + /// Sequences of whitespace /// are collapsed, so empty "words" are not included. /// /// # Examples @@ -1449,11 +1741,15 @@ impl str { /// /// Control characters have 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 + /// `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](http://www.unicode.org/reports/tr11/) recommends that these - /// characters be treated as 1 column (i.e., `is_cjk = false`) if the locale is unknown. + /// [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/) + /// recommends that these + /// characters be treated as 1 column (i.e., `is_cjk = false`) if the + /// locale is unknown. #[unstable(feature = "unicode", reason = "this functionality may only be provided by libunicode")] pub fn width(&self, is_cjk: bool) -> usize { diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 8da8cad98a7..441d0f2c5df 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -24,7 +24,7 @@ use core::mem; use core::ops::{self, Deref, Add, Index}; use core::ptr; use core::slice; -use core::str::Pattern; +use core::str::pattern::Pattern; use unicode::str as unicode_str; use unicode::str::Utf16Item; |