From 8c59d920a12fe40398a0033438ff426bb3387fd0 Mon Sep 17 00:00:00 2001 From: Huon Wilson Date: Mon, 10 Jun 2013 23:57:41 +1000 Subject: [PATCH] std: basic documentation for the new str methods --- src/libstd/str.rs | 88 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 20 deletions(-) diff --git a/src/libstd/str.rs b/src/libstd/str.rs index c820f645490..a7fe102738d 100644 --- a/src/libstd/str.rs +++ b/src/libstd/str.rs @@ -155,9 +155,7 @@ pub fn from_chars(chs: &[char]) -> ~str { buf } -/// A function version of the `.push_str`, required for `fmt!` during -/// the bootstrap. Use `lhs.push_str(rhs)` instead of this. -#[doc="hidden"] +#[doc(hidden)] pub fn push_str(lhs: &mut ~str, rhs: &str) { lhs.push_str(rhs) } @@ -1604,25 +1602,9 @@ pub trait StrSlice<'self> { fn splitn_iter(&self, sep: Sep, count: uint) -> StrCharSplitIterator<'self, Sep>; fn split_options_iter(&self, sep: Sep, count: uint, allow_trailing_empty: bool) -> StrCharSplitIterator<'self, Sep>; - /// An iterator over the start and end indices of each match of - /// `sep` within `self`. fn matches_index_iter(&self, sep: &'self str) -> StrMatchesIndexIterator<'self>; - /** - * An iterator over the substrings of `self` separated by `sep`. - * - * # Example - * - * ~~~ {.rust} - * let v: ~[&str] = ".XXX.YYY.".split_str_iter(".").collect() - * assert_eq!(v, ["", "XXX", "YYY", ""]); - * ~~~ - */ fn split_str_iter(&self, &'self str) -> StrStrSplitIterator<'self>; - /// An iterator over the lines of a string (subsequences separated - /// by `\n`). fn line_iter(&self) -> StrCharSplitIterator<'self, char>; - /// An iterator over the words of a string (subsequences separated - /// by any sequence of whitespace). fn word_iter(&self) -> WordIterator<'self>; fn ends_with(&self, needle: &str) -> bool; fn is_empty(&self) -> bool; @@ -1681,7 +1663,15 @@ fn contains<'a>(&self, needle: &'a str) -> bool { fn contains_char(&self, needle: char) -> bool { self.find(needle).is_some() } - + /// An iterator over the characters of `self`. Note, this iterates + /// over unicode code-points, not unicode graphemes. + /// + /// # Example + /// + /// ~~~ {.rust} + /// let v: ~[char] = "abc åäö".iter().collect(); + /// assert_eq!(v, ~['a', 'b', 'c', ' ', 'å', 'ä', 'ö']); + /// ~~~ #[inline] fn iter(&self) -> StrCharIterator<'self> { StrCharIterator { @@ -1689,6 +1679,7 @@ fn iter(&self) -> StrCharIterator<'self> { string: *self } } + /// An iterator over the characters of `self`, in reverse order. #[inline] fn rev_iter(&self) -> StrCharRevIterator<'self> { StrCharRevIterator { @@ -1697,20 +1688,47 @@ fn rev_iter(&self) -> StrCharRevIterator<'self> { } } + /// An iterator over the bytes of `self` + #[inline] fn bytes_iter(&self) -> StrBytesIterator<'self> { StrBytesIterator { it: as_bytes_slice(*self).iter() } } + /// An iterator over the bytes of `self`, in reverse order + #[inline] fn bytes_rev_iter(&self) -> StrBytesRevIterator<'self> { StrBytesRevIterator { it: as_bytes_slice(*self).rev_iter() } } + /// An iterator over substrings of `self`, separated by characters + /// matched by `sep`. + /// + /// # Example + /// + /// ~~~ {.rust} + /// let v: ~[&str] = "Mary had a little lamb".split_iter(' ').collect(); + /// assert_eq!(v, ~["Mary", "had", "a", "little", "lamb"]); + /// + /// let v: ~[&str] = "abc1def2ghi".split_iter(|c: char| c.is_digit()).collect(); + /// assert_eq!(v, ~["abc", "def", "ghi"]); + /// ~~~ + #[inline] fn split_iter(&self, sep: Sep) -> StrCharSplitIterator<'self, Sep> { self.split_options_iter(sep, self.len(), true) } + /// An iterator over substrings of `self`, separated by characters + /// matched by `sep`, restricted to splitting at most `count` + /// times. + #[inline] fn splitn_iter(&self, sep: Sep, count: uint) -> StrCharSplitIterator<'self, Sep> { self.split_options_iter(sep, count, true) } + + /// An iterator over substrings of `self`, separated by characters + /// matched by `sep`, splitting at most `count` times, and + /// possibly not including the trailing empty substring, if it + /// exists. + #[inline] fn split_options_iter(&self, sep: Sep, count: uint, allow_trailing_empty: bool) -> StrCharSplitIterator<'self, Sep> { let only_ascii = sep.only_ascii(); @@ -1724,6 +1742,9 @@ fn split_options_iter(&self, sep: Sep, count: uint, allow_trailing_ only_ascii: only_ascii } } + /// An iterator over the start and end indices of each match of + /// `sep` within `self`. + #[inline] fn matches_index_iter(&self, sep: &'self str) -> StrMatchesIndexIterator<'self> { assert!(!sep.is_empty()) StrMatchesIndexIterator { @@ -1732,6 +1753,17 @@ fn matches_index_iter(&self, sep: &'self str) -> StrMatchesIndexIterator<'self> position: 0 } } + /** + * An iterator over the substrings of `self` separated by `sep`. + * + * # Example + * + * ~~~ {.rust} + * let v: ~[&str] = "abcXXXabcYYYabc".split_str_iter("abc").collect() + * assert_eq!(v, ["", "XXX", "YYY", ""]); + * ~~~ + */ + #[inline] fn split_str_iter(&self, sep: &'self str) -> StrStrSplitIterator<'self> { StrStrSplitIterator { it: self.matches_index_iter(sep), @@ -1740,9 +1772,15 @@ fn split_str_iter(&self, sep: &'self str) -> StrStrSplitIterator<'self> { } } + /// An iterator over the lines of a string (subsequences separated + /// by `\n`). + #[inline] fn line_iter(&self) -> StrCharSplitIterator<'self, char> { self.split_options_iter('\n', self.len(), false) } + /// An iterator over the words of a string (subsequences separated + /// by any sequence of whitespace). + #[inline] fn word_iter(&self) -> WordIterator<'self> { self.split_iter(char::is_whitespace).filter(|s| !s.is_empty()) } @@ -1791,14 +1829,24 @@ fn slice(&self, begin: uint, end: uint) -> &'self str { assert!(self.is_char_boundary(end)); unsafe { raw::slice_bytes(*self, begin, end) } } + /// Returns a slice of the string from `begin` to its end. + /// + /// Fails when `begin` does not point to a valid character, or is + /// out of bounds. #[inline] fn slice_from(&self, begin: uint) -> &'self str { self.slice(begin, self.len()) } + /// Returns a slice of the string from the beginning to byte + /// `end`. + /// + /// Fails when `end` does not point to a valid character, or is + /// out of bounds. #[inline] fn slice_to(&self, end: uint) -> &'self str { self.slice(0, end) } + /// Checks if `needle` is a prefix of the string. #[inline] fn starts_with<'a>(&self, needle: &'a str) -> bool { starts_with(*self, needle)