1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
11 //! Unicode string manipulation (the `str` type).
13 //! Rust's `str` type is one of the core primitive types of the language. `&str`
14 //! is the borrowed string type. This type of string can only be created from
15 //! other strings, unless it is a `&'static str` (see below). It is not possible
16 //! to move out of borrowed strings because they are owned elsewhere.
20 //! Here's some code that uses a `&str`:
23 //! let s = "Hello, world.";
26 //! This `&str` is a `&'static str`, which is the type of string literals.
27 //! They're `'static` because literals are available for the entire lifetime of
30 //! You can get a non-`'static` `&str` by taking a slice of a `String`:
33 //! # let some_string = "Hello, world.".to_string();
34 //! let s = &some_string;
39 //! Rust's string type, `str`, is a sequence of Unicode scalar values encoded as
40 //! a stream of UTF-8 bytes. All [strings](../../reference.html#literals) are
41 //! guaranteed to be validly encoded UTF-8 sequences. Additionally, strings are
42 //! not null-terminated and can thus contain null bytes.
44 //! The actual representation of `str`s have direct mappings to slices: `&str`
45 //! is the same as `&[u8]`.
47 #![doc(primitive = "str")]
48 #![stable(feature = "rust1", since = "1.0.0")]
50 use self::RecompositionState
::*;
51 use self::DecompositionType
::*;
53 use core
::clone
::Clone
;
54 use core
::iter
::{Iterator, Extend}
;
55 use core
::option
::Option
::{self, Some, None}
;
56 use core
::result
::Result
;
57 use core
::str as core_str
;
58 use core
::str::pattern
::Pattern
;
59 use core
::str::pattern
::{Searcher, ReverseSearcher, DoubleEndedSearcher}
;
60 use rustc_unicode
::str::{UnicodeStr, Utf16Encoder}
;
62 use vec_deque
::VecDeque
;
63 use borrow
::{Borrow, ToOwned}
;
67 use slice
::SliceConcatExt
;
69 pub use core
::str::{FromStr, Utf8Error}
;
70 pub use core
::str::{Lines, LinesAny, CharRange}
;
71 pub use core
::str::{Split, RSplit}
;
72 pub use core
::str::{SplitN, RSplitN}
;
73 pub use core
::str::{SplitTerminator, RSplitTerminator}
;
74 pub use core
::str::{Matches, RMatches}
;
75 pub use core
::str::{MatchIndices, RMatchIndices}
;
76 pub use core
::str::{from_utf8, Chars, CharIndices, Bytes}
;
77 pub use core
::str::{from_utf8_unchecked, ParseBoolError}
;
78 pub use rustc_unicode
::str::{SplitWhitespace, Words, Graphemes, GraphemeIndices}
;
79 pub use core
::str::pattern
;
82 Section: Creating a string
85 impl<S
: Borrow
<str>> SliceConcatExt
<str> for [S
] {
88 fn concat(&self) -> String
{
93 // `len` calculation may overflow but push_str will check boundaries
94 let len
= self.iter().map(|s
| s
.borrow().len()).sum();
95 let mut result
= String
::with_capacity(len
);
98 result
.push_str(s
.borrow())
104 fn connect(&self, sep
: &str) -> String
{
106 return String
::new();
111 return self.concat();
114 // this is wrong without the guarantee that `self` is non-empty
115 // `len` calculation may overflow but push_str but will check boundaries
116 let len
= sep
.len() * (self.len() - 1)
117 + self.iter().map(|s
| s
.borrow().len()).sum
::<usize>();
118 let mut result
= String
::with_capacity(len
);
119 let mut first
= true;
125 result
.push_str(sep
);
127 result
.push_str(s
.borrow());
137 // Helper functions used for Unicode normalization
138 fn canonical_sort(comb
: &mut [(char, u8)]) {
139 let len
= comb
.len();
141 let mut swapped
= false;
143 let class_a
= comb
[j
-1].1;
144 let class_b
= comb
[j
].1;
145 if class_a
!= 0 && class_b
!= 0 && class_a
> class_b
{
150 if !swapped { break; }
155 enum DecompositionType
{
160 /// External iterator for a string decomposition's characters.
162 /// For use with the `std::iter` module.
164 #[deprecated(reason = "use the crates.io `unicode-normalization` library instead",
167 #[unstable(feature = "unicode",
168 reason
= "this functionality may be replaced with a more generic \
169 unicode crate on crates.io")]
170 pub struct Decompositions
<'a
> {
171 kind
: DecompositionType
,
173 buffer
: Vec
<(char, u8)>,
178 #[stable(feature = "rust1", since = "1.0.0")]
179 impl<'a
> Iterator
for Decompositions
<'a
> {
183 fn next(&mut self) -> Option
<char> {
184 match self.buffer
.first() {
187 self.buffer
.remove(0);
190 Some(&(c
, _
)) if self.sorted
=> {
191 self.buffer
.remove(0);
194 _
=> self.sorted
= false
198 for ch
in self.iter
.by_ref() {
199 let buffer
= &mut self.buffer
;
200 let sorted
= &mut self.sorted
;
204 rustc_unicode
::char::canonical_combining_class(d
);
205 if class
== 0 && !*sorted
{
206 canonical_sort(buffer
);
209 buffer
.push((d
, class
));
213 rustc_unicode
::char::decompose_canonical(ch
, callback
)
216 rustc_unicode
::char::decompose_compatible(ch
, callback
)
227 canonical_sort(&mut self.buffer
);
231 if self.buffer
.is_empty() {
234 match self.buffer
.remove(0) {
244 fn size_hint(&self) -> (usize, Option
<usize>) {
245 let (lower
, _
) = self.iter
.size_hint();
251 enum RecompositionState
{
257 /// External iterator for a string recomposition's characters.
259 /// For use with the `std::iter` module.
261 #[deprecated(reason = "use the crates.io `unicode-normalization` library instead",
264 #[unstable(feature = "unicode",
265 reason
= "this functionality may be replaced with a more generic \
266 unicode crate on crates.io")]
267 pub struct Recompositions
<'a
> {
268 iter
: Decompositions
<'a
>,
269 state
: RecompositionState
,
270 buffer
: VecDeque
<char>,
271 composee
: Option
<char>,
276 #[stable(feature = "rust1", since = "1.0.0")]
277 impl<'a
> Iterator
for Recompositions
<'a
> {
281 fn next(&mut self) -> Option
<char> {
285 for ch
in self.iter
.by_ref() {
286 let ch_class
= rustc_unicode
::char::canonical_combining_class(ch
);
287 if self.composee
.is_none() {
291 self.composee
= Some(ch
);
294 let k
= self.composee
.clone().unwrap();
296 match self.last_ccc
{
298 match rustc_unicode
::char::compose(k
, ch
) {
300 self.composee
= Some(r
);
305 self.composee
= Some(ch
);
308 self.buffer
.push_back(ch
);
309 self.last_ccc
= Some(ch_class
);
314 if l_class
>= ch_class
{
315 // `ch` is blocked from `composee`
317 self.composee
= Some(ch
);
318 self.last_ccc
= None
;
319 self.state
= Purging
;
322 self.buffer
.push_back(ch
);
323 self.last_ccc
= Some(ch_class
);
326 match rustc_unicode
::char::compose(k
, ch
) {
328 self.composee
= Some(r
);
332 self.buffer
.push_back(ch
);
333 self.last_ccc
= Some(ch_class
);
339 self.state
= Finished
;
340 if self.composee
.is_some() {
341 return self.composee
.take();
345 match self.buffer
.pop_front() {
346 None
=> self.state
= Composing
,
351 match self.buffer
.pop_front() {
352 None
=> return self.composee
.take(),
361 /// External iterator for a string's UTF16 codeunits.
363 /// For use with the `std::iter` module.
365 #[unstable(feature = "collections")]
366 pub struct Utf16Units
<'a
> {
367 encoder
: Utf16Encoder
<Chars
<'a
>>
370 #[stable(feature = "rust1", since = "1.0.0")]
371 impl<'a
> Iterator
for Utf16Units
<'a
> {
375 fn next(&mut self) -> Option
<u16> { self.encoder.next() }
378 fn size_hint(&self) -> (usize, Option
<usize>) { self.encoder.size_hint() }
385 // Return the initial codepoint accumulator for the first byte.
386 // The first byte is special, only want bottom 5 bits for width 2, 4 bits
387 // for width 3, and 3 bits for width 4
388 macro_rules
! utf8_first_byte
{
389 ($byte
:expr
, $width
:expr
) => (($byte
& (0x7F >> $width
)) as u32)
392 // return the value of $ch updated with continuation byte $byte
393 macro_rules
! utf8_acc_cont_byte
{
394 ($ch
:expr
, $byte
:expr
) => (($ch
<< 6) | ($byte
& 63) as u32)
397 #[stable(feature = "rust1", since = "1.0.0")]
398 impl Borrow
<str> for String
{
400 fn borrow(&self) -> &str { &self[..] }
403 #[stable(feature = "rust1", since = "1.0.0")]
404 impl ToOwned
for str {
406 fn to_owned(&self) -> String
{
408 String
::from_utf8_unchecked(self.as_bytes().to_owned())
418 Section: Trait implementations
422 /// Any string that can be represented as a slice.
425 #[stable(feature = "rust1", since = "1.0.0")]
427 /// Escapes each char in `s` with `char::escape_default`.
428 #[unstable(feature = "collections",
429 reason
= "return type may change to be an iterator")]
430 pub fn escape_default(&self) -> String
{
431 self.chars().flat_map(|c
| c
.escape_default()).collect()
434 /// Escapes each char in `s` with `char::escape_unicode`.
435 #[unstable(feature = "collections",
436 reason
= "return type may change to be an iterator")]
437 pub fn escape_unicode(&self) -> String
{
438 self.chars().flat_map(|c
| c
.escape_unicode()).collect()
441 /// Replaces all occurrences of one string with another.
443 /// `replace` takes two arguments, a sub-`&str` to find in `self`, and a
445 /// replace it with. If the original `&str` isn't found, no change occurs.
450 /// let s = "this is old";
452 /// assert_eq!(s.replace("old", "new"), "this is new");
455 /// When a `&str` isn't found:
458 /// let s = "this is old";
459 /// assert_eq!(s.replace("cookie monster", "little lamb"), s);
461 #[stable(feature = "rust1", since = "1.0.0")]
462 pub fn replace(&self, from
: &str, to
: &str) -> String
{
463 let mut result
= String
::new();
464 let mut last_end
= 0;
465 for (start
, end
) in self.match_indices(from
) {
466 result
.push_str(unsafe { self.slice_unchecked(last_end, start) }
);
470 result
.push_str(unsafe { self.slice_unchecked(last_end, self.len()) }
);
474 /// Returns an iterator over the string in Unicode Normalization Form D
475 /// (canonical decomposition).
477 #[deprecated(reason = "use the crates.io `unicode-normalization` library instead",
480 #[unstable(feature = "unicode",
481 reason
= "this functionality may be replaced with a more generic \
482 unicode crate on crates.io")]
483 pub fn nfd_chars(&self) -> Decompositions
{
485 iter
: self[..].chars(),
492 /// Returns an iterator over the string in Unicode Normalization Form KD
493 /// (compatibility decomposition).
495 #[deprecated(reason = "use the crates.io `unicode-normalization` library instead",
498 #[unstable(feature = "unicode",
499 reason
= "this functionality may be replaced with a more generic \
500 unicode crate on crates.io")]
501 pub fn nfkd_chars(&self) -> Decompositions
{
503 iter
: self[..].chars(),
510 /// An Iterator over the string in Unicode Normalization Form C
511 /// (canonical decomposition followed by canonical composition).
513 #[deprecated(reason = "use the crates.io `unicode-normalization` library instead",
516 #[unstable(feature = "unicode",
517 reason
= "this functionality may be replaced with a more generic \
518 unicode crate on crates.io")]
519 pub fn nfc_chars(&self) -> Recompositions
{
521 iter
: self.nfd_chars(),
523 buffer
: VecDeque
::new(),
529 /// An Iterator over the string in Unicode Normalization Form KC
530 /// (compatibility decomposition followed by canonical composition).
532 #[deprecated(reason = "use the crates.io `unicode-normalization` library instead",
535 #[unstable(feature = "unicode",
536 reason
= "this functionality may be replaced with a more generic \
537 unicode crate on crates.io")]
538 pub fn nfkc_chars(&self) -> Recompositions
{
540 iter
: self.nfkd_chars(),
542 buffer
: VecDeque
::new(),
548 /// Returns `true` if `self` contains another `&str`.
553 /// assert!("bananas".contains("nana"));
555 /// assert!(!"bananas".contains("foobar"));
557 #[stable(feature = "rust1", since = "1.0.0")]
558 pub fn contains
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> bool
{
559 core_str
::StrExt
::contains(&self[..], pat
)
562 /// An iterator over the codepoints of `self`.
567 /// let v: Vec<char> = "abc åäö".chars().collect();
569 /// assert_eq!(v, ['a', 'b', 'c', ' ', 'å', 'ä', 'ö']);
571 #[stable(feature = "rust1", since = "1.0.0")]
572 pub fn chars(&self) -> Chars
{
573 core_str
::StrExt
::chars(&self[..])
576 /// An iterator over the bytes of `self`.
581 /// let v: Vec<u8> = "bors".bytes().collect();
583 /// assert_eq!(v, b"bors".to_vec());
585 #[stable(feature = "rust1", since = "1.0.0")]
586 pub fn bytes(&self) -> Bytes
{
587 core_str
::StrExt
::bytes(&self[..])
590 /// An iterator over the characters of `self` and their byte offsets.
595 /// let v: Vec<(usize, char)> = "abc".char_indices().collect();
596 /// let b = vec![(0, 'a'), (1, 'b'), (2, 'c')];
598 /// assert_eq!(v, b);
600 #[stable(feature = "rust1", since = "1.0.0")]
601 pub fn char_indices(&self) -> CharIndices
{
602 core_str
::StrExt
::char_indices(&self[..])
605 /// An iterator over substrings of `self`, separated by characters
606 /// matched by a pattern.
608 /// The pattern can be a simple `&str`, `char`, or a closure that
609 /// determines the split.
610 /// Additional libraries might provide more complex patterns like
611 /// regular expressions.
613 /// # Iterator behavior
615 /// The returned iterator will be double ended if the pattern allows a
616 /// reverse search and forward/reverse search yields the same elements.
617 /// This is true for, eg, `char` but not
620 /// If the pattern allows a reverse search but its results might differ
621 /// from a forward search, `rsplit()` can be used.
628 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
629 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
631 /// let v: Vec<&str> = "".split('X').collect();
632 /// assert_eq!(v, [""]);
634 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
635 /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
637 /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
638 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
641 /// More complex patterns with closures:
644 /// let v: Vec<&str> = "abc1def2ghi".split(|c: char| c.is_numeric()).collect();
645 /// assert_eq!(v, ["abc", "def", "ghi"]);
647 /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
648 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
650 #[stable(feature = "rust1", since = "1.0.0")]
651 pub fn split
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Split
<'a
, P
> {
652 core_str
::StrExt
::split(&self[..], pat
)
655 /// An iterator over substrings of `self`, separated by characters
656 /// matched by a pattern and yielded in reverse order.
658 /// The pattern can be a simple `&str`, `char`, or a closure that
659 /// determines the split.
660 /// Additional libraries might provide more complex patterns like
661 /// regular expressions.
663 /// # Iterator behavior
665 /// The returned iterator requires that the pattern supports a
667 /// and it will be double ended if a forward/reverse search yields
668 /// the same elements.
670 /// For iterating from the front, `split()` can be used.
677 /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
678 /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
680 /// let v: Vec<&str> = "".rsplit('X').collect();
681 /// assert_eq!(v, [""]);
683 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
684 /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
686 /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
687 /// assert_eq!(v, ["leopard", "tiger", "lion"]);
690 /// More complex patterns with closures:
693 /// let v: Vec<&str> = "abc1def2ghi".rsplit(|c: char| c.is_numeric()).collect();
694 /// assert_eq!(v, ["ghi", "def", "abc"]);
696 /// let v: Vec<&str> = "lionXtigerXleopard".rsplit(char::is_uppercase).collect();
697 /// assert_eq!(v, ["leopard", "tiger", "lion"]);
699 #[stable(feature = "rust1", since = "1.0.0")]
700 pub fn rsplit
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> RSplit
<'a
, P
>
701 where P
::Searcher
: ReverseSearcher
<'a
>
703 core_str
::StrExt
::rsplit(&self[..], pat
)
706 /// An iterator over substrings of `self`, separated by characters
707 /// matched by a pattern.
709 /// The pattern can be a simple `&str`, `char`, or a closure that
710 /// determines the split.
711 /// Additional libraries might provide more complex patterns
712 /// like regular expressions.
714 /// Equivalent to `split`, except that the trailing substring
715 /// is skipped if empty.
717 /// This method can be used for string data that is _terminated_,
718 /// rather than _separated_ by a pattern.
720 /// # Iterator behavior
722 /// The returned iterator will be double ended if the pattern allows a
724 /// and forward/reverse search yields the same elements. This is true
725 /// for, eg, `char` but not for `&str`.
727 /// If the pattern allows a reverse search but its results might differ
728 /// from a forward search, `rsplit_terminator()` can be used.
735 /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
736 /// assert_eq!(v, ["A", "B"]);
738 /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
739 /// assert_eq!(v, ["A", "", "B", ""]);
742 /// More complex patterns with closures:
745 /// let v: Vec<&str> = "abc1def2ghi3".split_terminator(|c: char| c.is_numeric()).collect();
746 /// assert_eq!(v, ["abc", "def", "ghi"]);
748 #[stable(feature = "rust1", since = "1.0.0")]
749 pub fn split_terminator
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> SplitTerminator
<'a
, P
> {
750 core_str
::StrExt
::split_terminator(&self[..], pat
)
753 /// An iterator over substrings of `self`, separated by characters
754 /// matched by a pattern and yielded in reverse order.
756 /// The pattern can be a simple `&str`, `char`, or a closure that
757 /// determines the split.
758 /// Additional libraries might provide more complex patterns like
759 /// regular expressions.
761 /// Equivalent to `split`, except that the trailing substring is
762 /// skipped if empty.
764 /// This method can be used for string data that is _terminated_,
765 /// rather than _separated_ by a pattern.
767 /// # Iterator behavior
769 /// The returned iterator requires that the pattern supports a
770 /// reverse search, and it will be double ended if a forward/reverse
771 /// search yields the same elements.
773 /// For iterating from the front, `split_terminator()` can be used.
780 /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
781 /// assert_eq!(v, ["B", "A"]);
783 /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
784 /// assert_eq!(v, ["", "B", "", "A"]);
787 /// More complex patterns with closures:
790 /// let v: Vec<&str> = "abc1def2ghi3".rsplit_terminator(|c: char| c.is_numeric()).collect();
791 /// assert_eq!(v, ["ghi", "def", "abc"]);
793 #[stable(feature = "rust1", since = "1.0.0")]
794 pub fn rsplit_terminator
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> RSplitTerminator
<'a
, P
>
795 where P
::Searcher
: ReverseSearcher
<'a
>
797 core_str
::StrExt
::rsplit_terminator(&self[..], pat
)
800 /// An iterator over substrings of `self`, separated by a pattern,
801 /// restricted to returning
802 /// at most `count` items.
804 /// The last element returned, if any, will contain the remainder of the
806 /// The pattern can be a simple `&str`, `char`, or a closure that
807 /// determines the split.
808 /// Additional libraries might provide more complex patterns like
809 /// regular expressions.
811 /// # Iterator behavior
813 /// The returned iterator will not be double ended, because it is
814 /// not efficient to support.
816 /// If the pattern allows a reverse search, `rsplitn()` can be used.
823 /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
824 /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
826 /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
827 /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
829 /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
830 /// assert_eq!(v, ["abcXdef"]);
832 /// let v: Vec<&str> = "".splitn(1, 'X').collect();
833 /// assert_eq!(v, [""]);
836 /// More complex patterns with closures:
839 /// let v: Vec<&str> = "abc1def2ghi".splitn(2, |c: char| c.is_numeric()).collect();
840 /// assert_eq!(v, ["abc", "def2ghi"]);
842 #[stable(feature = "rust1", since = "1.0.0")]
843 pub fn splitn
<'a
, P
: Pattern
<'a
>>(&'a
self, count
: usize, pat
: P
) -> SplitN
<'a
, P
> {
844 core_str
::StrExt
::splitn(&self[..], count
, pat
)
847 /// An iterator over substrings of `self`, separated by a pattern,
848 /// starting from the end of the string, restricted to returning
849 /// at most `count` items.
851 /// The last element returned, if any, will contain the remainder of the
854 /// The pattern can be a simple `&str`, `char`, or a closure that
855 /// determines the split.
856 /// Additional libraries might provide more complex patterns like
857 /// regular expressions.
859 /// # Iterator behavior
861 /// The returned iterator will not be double ended, because it is not
862 /// efficient to support.
864 /// `splitn()` can be used for splitting from the front.
871 /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
872 /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
874 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
875 /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
877 /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
878 /// assert_eq!(v, ["leopard", "lion::tiger"]);
881 /// More complex patterns with closures:
884 /// let v: Vec<&str> = "abc1def2ghi".rsplitn(2, |c: char| c.is_numeric()).collect();
885 /// assert_eq!(v, ["ghi", "abc1def"]);
887 #[stable(feature = "rust1", since = "1.0.0")]
888 pub fn rsplitn
<'a
, P
: Pattern
<'a
>>(&'a
self, count
: usize, pat
: P
) -> RSplitN
<'a
, P
>
889 where P
::Searcher
: ReverseSearcher
<'a
>
891 core_str
::StrExt
::rsplitn(&self[..], count
, pat
)
894 /// An iterator over the matches of a pattern within `self`.
896 /// The pattern can be a simple `&str`, `char`, or a closure that
897 /// determines the split.
898 /// Additional libraries might provide more complex patterns like
899 /// regular expressions.
901 /// # Iterator behavior
903 /// The returned iterator will be double ended if the pattern allows
905 /// and forward/reverse search yields the same elements. This is true
906 /// for, eg, `char` but not
909 /// If the pattern allows a reverse search but its results might differ
910 /// from a forward search, `rmatches()` can be used.
915 /// # #![feature(collections)]
916 /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
917 /// assert_eq!(v, ["abc", "abc", "abc"]);
919 /// let v: Vec<&str> = "1abc2abc3".matches(|c: char| c.is_numeric()).collect();
920 /// assert_eq!(v, ["1", "2", "3"]);
922 #[unstable(feature = "collections",
923 reason
= "method got recently added")]
924 pub fn matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Matches
<'a
, P
> {
925 core_str
::StrExt
::matches(&self[..], pat
)
928 /// An iterator over the matches of a pattern within `self`, yielded in
931 /// The pattern can be a simple `&str`, `char`, or a closure that
932 /// determines the split.
933 /// Additional libraries might provide more complex patterns like
934 /// regular expressions.
936 /// # Iterator behavior
938 /// The returned iterator requires that the pattern supports a
940 /// and it will be double ended if a forward/reverse search yields
941 /// the same elements.
943 /// For iterating from the front, `matches()` can be used.
948 /// # #![feature(collections)]
949 /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
950 /// assert_eq!(v, ["abc", "abc", "abc"]);
952 /// let v: Vec<&str> = "1abc2abc3".rmatches(|c: char| c.is_numeric()).collect();
953 /// assert_eq!(v, ["3", "2", "1"]);
955 #[unstable(feature = "collections",
956 reason
= "method got recently added")]
957 pub fn rmatches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> RMatches
<'a
, P
>
958 where P
::Searcher
: ReverseSearcher
<'a
>
960 core_str
::StrExt
::rmatches(&self[..], pat
)
963 /// An iterator over the start and end indices of the disjoint matches
964 /// of a pattern within `self`.
966 /// For matches of `pat` within `self` that overlap, only the indices
967 /// corresponding to the first
968 /// match are returned.
970 /// The pattern can be a simple `&str`, `char`, or a closure that
973 /// Additional libraries might provide more complex patterns like
974 /// regular expressions.
976 /// # Iterator behavior
978 /// The returned iterator will be double ended if the pattern allows a
980 /// and forward/reverse search yields the same elements. This is true for,
981 /// eg, `char` but not
984 /// If the pattern allows a reverse search but its results might differ
985 /// from a forward search, `rmatch_indices()` can be used.
990 /// # #![feature(collections)]
991 /// let v: Vec<(usize, usize)> = "abcXXXabcYYYabc".match_indices("abc").collect();
992 /// assert_eq!(v, [(0, 3), (6, 9), (12, 15)]);
994 /// let v: Vec<(usize, usize)> = "1abcabc2".match_indices("abc").collect();
995 /// assert_eq!(v, [(1, 4), (4, 7)]);
997 /// let v: Vec<(usize, usize)> = "ababa".match_indices("aba").collect();
998 /// assert_eq!(v, [(0, 3)]); // only the first `aba`
1000 #[unstable(feature = "collections",
1001 reason
= "might have its iterator type changed")]
1002 // NB: Right now MatchIndices yields `(usize, usize)`, but it would
1003 // be more consistent with `matches` and `char_indices` to return `(usize, &str)`
1004 pub fn match_indices
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> MatchIndices
<'a
, P
> {
1005 core_str
::StrExt
::match_indices(&self[..], pat
)
1008 /// An iterator over the start and end indices of the disjoint matches of
1009 /// a pattern within
1010 /// `self`, yielded in reverse order.
1012 /// For matches of `pat` within `self` that overlap, only the indices
1013 /// corresponding to the last
1014 /// match are returned.
1016 /// The pattern can be a simple `&str`, `char`, or a closure that
1019 /// Additional libraries might provide more complex patterns like
1020 /// regular expressions.
1022 /// # Iterator behavior
1024 /// The returned iterator requires that the pattern supports a
1026 /// and it will be double ended if a forward/reverse search yields
1027 /// the same elements.
1029 /// For iterating from the front, `match_indices()` can be used.
1034 /// # #![feature(collections)]
1035 /// let v: Vec<(usize, usize)> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
1036 /// assert_eq!(v, [(12, 15), (6, 9), (0, 3)]);
1038 /// let v: Vec<(usize, usize)> = "1abcabc2".rmatch_indices("abc").collect();
1039 /// assert_eq!(v, [(4, 7), (1, 4)]);
1041 /// let v: Vec<(usize, usize)> = "ababa".rmatch_indices("aba").collect();
1042 /// assert_eq!(v, [(2, 5)]); // only the last `aba`
1044 #[unstable(feature = "collections",
1045 reason
= "might have its iterator type changed")]
1046 // NB: Right now RMatchIndices yields `(usize, usize)`, but it would
1047 // be more consistent with `rmatches` and `char_indices` to return `(usize, &str)`
1048 pub fn rmatch_indices
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> RMatchIndices
<'a
, P
>
1049 where P
::Searcher
: ReverseSearcher
<'a
>
1051 core_str
::StrExt
::rmatch_indices(&self[..], pat
)
1054 /// An iterator over the lines of a string, separated by `\n`.
1056 /// This does not include the empty string after a trailing `\n`.
1061 /// let four_lines = "foo\nbar\n\nbaz";
1062 /// let v: Vec<&str> = four_lines.lines().collect();
1064 /// assert_eq!(v, ["foo", "bar", "", "baz"]);
1067 /// Leaving off the trailing character:
1070 /// let four_lines = "foo\nbar\n\nbaz\n";
1071 /// let v: Vec<&str> = four_lines.lines().collect();
1073 /// assert_eq!(v, ["foo", "bar", "", "baz"]);
1075 #[stable(feature = "rust1", since = "1.0.0")]
1076 pub fn lines(&self) -> Lines
{
1077 core_str
::StrExt
::lines(&self[..])
1080 /// An iterator over the lines of a string, separated by either
1083 /// As with `.lines()`, this does not include an empty trailing line.
1088 /// let four_lines = "foo\r\nbar\n\r\nbaz";
1089 /// let v: Vec<&str> = four_lines.lines_any().collect();
1091 /// assert_eq!(v, ["foo", "bar", "", "baz"]);
1094 /// Leaving off the trailing character:
1097 /// let four_lines = "foo\r\nbar\n\r\nbaz\n";
1098 /// let v: Vec<&str> = four_lines.lines_any().collect();
1100 /// assert_eq!(v, ["foo", "bar", "", "baz"]);
1102 #[stable(feature = "rust1", since = "1.0.0")]
1103 pub fn lines_any(&self) -> LinesAny
{
1104 core_str
::StrExt
::lines_any(&self[..])
1106 /// Returns a slice of the string from the character range [`begin`..`end`).
1108 /// That is, start at the `begin`-th code point of the string and continue
1109 /// to the `end`-th code point. This does not detect or handle edge cases
1110 /// such as leaving a combining character as the first code point of the
1113 /// Due to the design of UTF-8, this operation is `O(end)`. See `slice`,
1114 /// `slice_to` and `slice_from` for `O(1)` variants that use byte indices
1115 /// rather than code point indices.
1119 /// Panics if `begin` > `end` or the either `begin` or `end` are beyond the
1120 /// last character of the string.
1125 /// # #![feature(collections)]
1126 /// let s = "Löwe 老虎 Léopard";
1128 /// assert_eq!(s.slice_chars(0, 4), "Löwe");
1129 /// assert_eq!(s.slice_chars(5, 7), "老虎");
1131 #[unstable(feature = "collections",
1132 reason
= "may have yet to prove its worth")]
1133 pub fn slice_chars(&self, begin
: usize, end
: usize) -> &str {
1134 core_str
::StrExt
::slice_chars(&self[..], begin
, end
)
1137 /// Takes a bytewise slice from a string.
1139 /// Returns the substring from [`begin`..`end`).
1143 /// Caller must check both UTF-8 character boundaries and the boundaries
1144 /// of the entire slice as
1150 /// let s = "Löwe 老虎 Léopard";
1153 /// assert_eq!(s.slice_unchecked(0, 21), "Löwe 老虎 Léopard");
1156 #[stable(feature = "rust1", since = "1.0.0")]
1157 pub unsafe fn slice_unchecked(&self, begin
: usize, end
: usize) -> &str {
1158 core_str
::StrExt
::slice_unchecked(&self[..], begin
, end
)
1161 /// Returns `true` if the given `&str` is a prefix of the string.
1166 /// assert!("banana".starts_with("ba"));
1168 #[stable(feature = "rust1", since = "1.0.0")]
1169 pub fn starts_with
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> bool
{
1170 core_str
::StrExt
::starts_with(&self[..], pat
)
1173 /// Returns true if the given `&str` is a suffix of the string.
1178 /// assert!("banana".ends_with("nana"));
1180 #[stable(feature = "rust1", since = "1.0.0")]
1181 pub fn ends_with
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> bool
1182 where P
::Searcher
: ReverseSearcher
<'a
>
1184 core_str
::StrExt
::ends_with(&self[..], pat
)
1187 /// Returns a string with all pre- and suffixes that match a pattern
1188 /// repeatedly removed.
1190 /// The pattern can be a simple `char`, or a closure that determines
1195 /// Simple patterns:
1198 /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
1200 /// let x: &[_] = &['1', '2'];
1201 /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
1204 /// More complex patterns with closures:
1207 /// assert_eq!("123foo1bar123".trim_matches(|c: char| c.is_numeric()), "foo1bar");
1209 #[stable(feature = "rust1", since = "1.0.0")]
1210 pub fn trim_matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> &'a
str
1211 where P
::Searcher
: DoubleEndedSearcher
<'a
>
1213 core_str
::StrExt
::trim_matches(&self[..], pat
)
1216 /// Returns a string with all prefixes that match a pattern
1217 /// repeatedly removed.
1219 /// The pattern can be a simple `&str`, `char`, or a closure that
1220 /// determines the split.
1224 /// Simple patterns:
1227 /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
1229 /// let x: &[_] = &['1', '2'];
1230 /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
1233 /// More complex patterns with closures:
1236 /// assert_eq!("123foo1bar123".trim_left_matches(|c: char| c.is_numeric()), "foo1bar123");
1238 #[stable(feature = "rust1", since = "1.0.0")]
1239 pub fn trim_left_matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> &'a
str {
1240 core_str
::StrExt
::trim_left_matches(&self[..], pat
)
1243 /// Returns a string with all suffixes that match a pattern
1244 /// repeatedly removed.
1246 /// The pattern can be a simple `&str`, `char`, or a closure that
1247 /// determines the split.
1251 /// Simple patterns:
1254 /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
1255 /// let x: &[_] = &['1', '2'];
1256 /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
1259 /// More complex patterns with closures:
1262 /// assert_eq!("123foo1bar123".trim_right_matches(|c: char| c.is_numeric()), "123foo1bar");
1264 #[stable(feature = "rust1", since = "1.0.0")]
1265 pub fn trim_right_matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> &'a
str
1266 where P
::Searcher
: ReverseSearcher
<'a
>
1268 core_str
::StrExt
::trim_right_matches(&self[..], pat
)
1271 /// Checks that `index`-th byte lies at the start and/or end of a
1272 /// UTF-8 code point sequence.
1274 /// The start and end of the string (when `index == self.len()`) are
1275 /// considered to be
1280 /// Panics if `index` is greater than `self.len()`.
1285 /// # #![feature(str_char)]
1286 /// let s = "Löwe 老虎 Léopard";
1287 /// assert!(s.is_char_boundary(0));
1289 /// assert!(s.is_char_boundary(6));
1290 /// assert!(s.is_char_boundary(s.len()));
1292 /// // second byte of `ö`
1293 /// assert!(!s.is_char_boundary(2));
1295 /// // third byte of `老`
1296 /// assert!(!s.is_char_boundary(8));
1298 #[unstable(feature = "str_char",
1299 reason
= "it is unclear whether this method pulls its weight \
1300 with the existence of the char_indices iterator or \
1301 this method may want to be replaced with checked \
1303 pub fn is_char_boundary(&self, index
: usize) -> bool
{
1304 core_str
::StrExt
::is_char_boundary(&self[..], index
)
1307 /// Given a byte position, return the next char and its index.
1309 /// This can be used to iterate over the Unicode characters of a string.
1313 /// If `i` is greater than or equal to the length of the string.
1314 /// If `i` is not the index of the beginning of a valid UTF-8 character.
1318 /// This example manually iterates through the characters of a string;
1319 /// this should normally be
1320 /// done by `.chars()` or `.char_indices()`.
1323 /// # #![feature(str_char, core)]
1324 /// use std::str::CharRange;
1326 /// let s = "中华Việt Nam";
1328 /// while i < s.len() {
1329 /// let CharRange {ch, next} = s.char_range_at(i);
1330 /// println!("{}: {}", i, ch);
1349 #[unstable(feature = "str_char",
1350 reason
= "often replaced by char_indices, this method may \
1351 be removed in favor of just char_at() or eventually \
1352 removed altogether")]
1353 pub fn char_range_at(&self, start
: usize) -> CharRange
{
1354 core_str
::StrExt
::char_range_at(&self[..], start
)
1357 /// Given a byte position, return the previous `char` and its position.
1359 /// This function can be used to iterate over a Unicode string in reverse.
1361 /// Returns 0 for next index if called on start index 0.
1365 /// If `i` is greater than the length of the string.
1366 /// If `i` is not an index following a valid UTF-8 character.
1370 /// This example manually iterates through the characters of a string;
1371 /// this should normally be
1372 /// done by `.chars().rev()` or `.char_indices()`.
1375 /// # #![feature(str_char, core)]
1376 /// use std::str::CharRange;
1378 /// let s = "中华Việt Nam";
1379 /// let mut i = s.len();
1381 /// let CharRange {ch, next} = s.char_range_at_reverse(i);
1382 /// println!("{}: {}", i, ch);
1401 #[unstable(feature = "str_char",
1402 reason
= "often replaced by char_indices, this method may \
1403 be removed in favor of just char_at_reverse() or \
1404 eventually removed altogether")]
1405 pub fn char_range_at_reverse(&self, start
: usize) -> CharRange
{
1406 core_str
::StrExt
::char_range_at_reverse(&self[..], start
)
1409 /// Given a byte position, return the `char` at that position.
1413 /// If `i` is greater than or equal to the length of the string.
1414 /// If `i` is not the index of the beginning of a valid UTF-8 character.
1419 /// # #![feature(str_char)]
1421 /// assert_eq!(s.char_at(1), 'b');
1422 /// assert_eq!(s.char_at(2), 'π');
1424 #[unstable(feature = "str_char",
1425 reason
= "frequently replaced by the chars() iterator, this \
1426 method may be removed or possibly renamed in the \
1427 future; it is normally replaced by chars/char_indices \
1428 iterators or by getting the first char from a \
1430 pub fn char_at(&self, i
: usize) -> char {
1431 core_str
::StrExt
::char_at(&self[..], i
)
1434 /// Given a byte position, return the `char` at that position, counting
1439 /// If `i` is greater than the length of the string.
1440 /// If `i` is not an index following a valid UTF-8 character.
1445 /// # #![feature(str_char)]
1447 /// assert_eq!(s.char_at_reverse(1), 'a');
1448 /// assert_eq!(s.char_at_reverse(2), 'b');
1450 #[unstable(feature = "str_char",
1451 reason
= "see char_at for more details, but reverse semantics \
1452 are also somewhat unclear, especially with which \
1453 cases generate panics")]
1454 pub fn char_at_reverse(&self, i
: usize) -> char {
1455 core_str
::StrExt
::char_at_reverse(&self[..], i
)
1458 /// Converts `self` to a byte slice.
1463 /// assert_eq!("bors".as_bytes(), b"bors");
1465 #[stable(feature = "rust1", since = "1.0.0")]
1466 pub fn as_bytes(&self) -> &[u8] {
1467 core_str
::StrExt
::as_bytes(&self[..])
1470 /// Returns the byte index of the first character of `self` that matches
1471 /// the pattern, if it
1474 /// Returns `None` if it doesn't exist.
1476 /// The pattern can be a simple `&str`, `char`, or a closure that
1482 /// Simple patterns:
1485 /// let s = "Löwe 老虎 Léopard";
1487 /// assert_eq!(s.find('L'), Some(0));
1488 /// assert_eq!(s.find('é'), Some(14));
1489 /// assert_eq!(s.find("Léopard"), Some(13));
1493 /// More complex patterns with closures:
1496 /// let s = "Löwe 老虎 Léopard";
1498 /// assert_eq!(s.find(|c: char| c.is_whitespace()), Some(5));
1499 /// assert_eq!(s.find(char::is_lowercase), Some(1));
1502 /// Not finding the pattern:
1505 /// let s = "Löwe 老虎 Léopard";
1506 /// let x: &[_] = &['1', '2'];
1508 /// assert_eq!(s.find(x), None);
1510 #[stable(feature = "rust1", since = "1.0.0")]
1511 pub fn find
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Option
<usize> {
1512 core_str
::StrExt
::find(&self[..], pat
)
1515 /// Returns the byte index of the last character of `self` that
1516 /// matches the pattern, if it
1519 /// Returns `None` if it doesn't exist.
1521 /// The pattern can be a simple `&str`, `char`,
1522 /// or a closure that determines the split.
1526 /// Simple patterns:
1529 /// let s = "Löwe 老虎 Léopard";
1531 /// assert_eq!(s.rfind('L'), Some(13));
1532 /// assert_eq!(s.rfind('é'), Some(14));
1535 /// More complex patterns with closures:
1538 /// let s = "Löwe 老虎 Léopard";
1540 /// assert_eq!(s.rfind(|c: char| c.is_whitespace()), Some(12));
1541 /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
1544 /// Not finding the pattern:
1547 /// let s = "Löwe 老虎 Léopard";
1548 /// let x: &[_] = &['1', '2'];
1550 /// assert_eq!(s.rfind(x), None);
1552 #[stable(feature = "rust1", since = "1.0.0")]
1553 pub fn rfind
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Option
<usize>
1554 where P
::Searcher
: ReverseSearcher
<'a
>
1556 core_str
::StrExt
::rfind(&self[..], pat
)
1559 /// Retrieves the first character from a `&str` and returns it.
1561 /// This does not allocate a new string; instead, it returns a slice that
1562 /// points one character
1563 /// beyond the character that was shifted.
1565 /// If the slice does not contain any characters, None is returned instead.
1570 /// # #![feature(str_char)]
1571 /// let s = "Löwe 老虎 Léopard";
1572 /// let (c, s1) = s.slice_shift_char().unwrap();
1574 /// assert_eq!(c, 'L');
1575 /// assert_eq!(s1, "öwe 老虎 Léopard");
1577 /// let (c, s2) = s1.slice_shift_char().unwrap();
1579 /// assert_eq!(c, 'ö');
1580 /// assert_eq!(s2, "we 老虎 Léopard");
1582 #[unstable(feature = "str_char",
1583 reason
= "awaiting conventions about shifting and slices and \
1584 may not be warranted with the existence of the chars \
1585 and/or char_indices iterators")]
1586 pub fn slice_shift_char(&self) -> Option
<(char, &str)> {
1587 core_str
::StrExt
::slice_shift_char(&self[..])
1590 /// Returns the byte offset of an inner slice relative to an enclosing
1595 /// Panics if `inner` is not a direct slice contained within self.
1600 /// # #![feature(collections)]
1601 /// let string = "a\nb\nc";
1602 /// let lines: Vec<&str> = string.lines().collect();
1604 /// assert!(string.subslice_offset(lines[0]) == 0); // &"a"
1605 /// assert!(string.subslice_offset(lines[1]) == 2); // &"b"
1606 /// assert!(string.subslice_offset(lines[2]) == 4); // &"c"
1608 #[unstable(feature = "collections",
1609 reason
= "awaiting convention about comparability of arbitrary slices")]
1610 pub fn subslice_offset(&self, inner
: &str) -> usize {
1611 core_str
::StrExt
::subslice_offset(&self[..], inner
)
1614 /// Returns an unsafe pointer to the `&str`'s buffer.
1616 /// The caller must ensure that the string outlives this pointer, and
1618 /// reallocated (e.g. by pushing to the string).
1623 /// let s = "Hello";
1624 /// let p = s.as_ptr();
1626 #[stable(feature = "rust1", since = "1.0.0")]
1628 pub fn as_ptr(&self) -> *const u8 {
1629 core_str
::StrExt
::as_ptr(&self[..])
1632 /// Returns an iterator of `u16` over the string encoded as UTF-16.
1633 #[unstable(feature = "collections",
1634 reason
= "this functionality may only be provided by libunicode")]
1635 pub fn utf16_units(&self) -> Utf16Units
{
1636 Utf16Units { encoder: Utf16Encoder::new(self[..].chars()) }
1639 /// Returns the length of `self` in bytes.
1644 /// assert_eq!("foo".len(), 3);
1645 /// assert_eq!("ƒoo".len(), 4); // fancy f!
1647 #[stable(feature = "rust1", since = "1.0.0")]
1649 pub fn len(&self) -> usize {
1650 core_str
::StrExt
::len(&self[..])
1653 /// Returns true if this slice has a length of zero bytes.
1658 /// assert!("".is_empty());
1661 #[stable(feature = "rust1", since = "1.0.0")]
1662 pub fn is_empty(&self) -> bool
{
1663 core_str
::StrExt
::is_empty(&self[..])
1666 /// Parses `self` into the specified type.
1670 /// Will return `Err` if it's not possible to parse `self` into the type.
1675 /// assert_eq!("4".parse::<u32>(), Ok(4));
1681 /// assert!("j".parse::<u32>().is_err());
1684 #[stable(feature = "rust1", since = "1.0.0")]
1685 pub fn parse
<F
: FromStr
>(&self) -> Result
<F
, F
::Err
> {
1686 core_str
::StrExt
::parse(&self[..])
1689 /// Returns an iterator over the [grapheme clusters][graphemes] of `self`.
1691 /// [graphemes]: http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries
1693 /// If `is_extended` is true, the iterator is over the
1694 /// *extended grapheme clusters*;
1695 /// otherwise, the iterator is over the *legacy grapheme clusters*.
1696 /// [UAX#29](http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries)
1697 /// recommends extended grapheme cluster boundaries for general processing.
1702 /// # #![feature(unicode, core)]
1703 /// let gr1 = "a\u{310}e\u{301}o\u{308}\u{332}".graphemes(true).collect::<Vec<&str>>();
1704 /// let b: &[_] = &["a\u{310}", "e\u{301}", "o\u{308}\u{332}"];
1706 /// assert_eq!(&gr1[..], b);
1708 /// let gr2 = "a\r\nb🇷🇺🇸🇹".graphemes(true).collect::<Vec<&str>>();
1709 /// let b: &[_] = &["a", "\r\n", "b", "🇷🇺🇸🇹"];
1711 /// assert_eq!(&gr2[..], b);
1713 #[deprecated(reason = "use the crates.io `unicode-segmentation` library instead",
1715 #[unstable(feature = "unicode",
1716 reason
= "this functionality may only be provided by libunicode")]
1717 pub fn graphemes(&self, is_extended
: bool
) -> Graphemes
{
1718 UnicodeStr
::graphemes(&self[..], is_extended
)
1721 /// Returns an iterator over the grapheme clusters of `self` and their
1722 /// byte offsets. See
1723 /// `graphemes()` for more information.
1728 /// # #![feature(unicode, core)]
1729 /// let gr_inds = "a̐éö̲\r\n".grapheme_indices(true).collect::<Vec<(usize, &str)>>();
1730 /// let b: &[_] = &[(0, "a̐"), (3, "é"), (6, "ö̲"), (11, "\r\n")];
1732 /// assert_eq!(&gr_inds[..], b);
1734 #[deprecated(reason = "use the crates.io `unicode-segmentation` library instead",
1736 #[unstable(feature = "unicode",
1737 reason
= "this functionality may only be provided by libunicode")]
1738 pub fn grapheme_indices(&self, is_extended
: bool
) -> GraphemeIndices
{
1739 UnicodeStr
::grapheme_indices(&self[..], is_extended
)
1742 /// An iterator over the non-empty substrings of `self` which contain no whitespace,
1743 /// and which are separated by any amount of whitespace.
1748 /// # #![feature(str_words)]
1749 /// # #![allow(deprecated)]
1750 /// let some_words = " Mary had\ta little \n\t lamb";
1751 /// let v: Vec<&str> = some_words.words().collect();
1753 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
1755 #[deprecated(reason = "words() will be removed. Use split_whitespace() instead",
1757 #[unstable(feature = "str_words",
1758 reason
= "the precise algorithm to use is unclear")]
1759 #[allow(deprecated)]
1760 pub fn words(&self) -> Words
{
1761 UnicodeStr
::words(&self[..])
1764 /// An iterator over the non-empty substrings of `self` which contain no whitespace,
1765 /// and which are separated by any amount of whitespace.
1770 /// let some_words = " Mary had\ta little \n\t lamb";
1771 /// let v: Vec<&str> = some_words.split_whitespace().collect();
1773 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
1775 #[stable(feature = "split_whitespace", since = "1.1.0")]
1776 pub fn split_whitespace(&self) -> SplitWhitespace
{
1777 UnicodeStr
::split_whitespace(&self[..])
1780 /// Returns a string's displayed width in columns.
1782 /// Control characters have zero width.
1784 /// `is_cjk` determines behavior for characters in the Ambiguous category:
1786 /// `true`, these are 2 columns wide; otherwise, they are 1.
1787 /// In CJK locales, `is_cjk` should be
1788 /// `true`, else it should be `false`.
1789 /// [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
1790 /// recommends that these
1791 /// characters be treated as 1 column (i.e., `is_cjk = false`) if the
1792 /// locale is unknown.
1793 #[deprecated(reason = "use the crates.io `unicode-width` library instead",
1795 #[unstable(feature = "unicode",
1796 reason
= "this functionality may only be provided by libunicode")]
1797 pub fn width(&self, is_cjk
: bool
) -> usize {
1798 UnicodeStr
::width(&self[..], is_cjk
)
1801 /// Returns a `&str` with leading and trailing whitespace removed.
1806 /// let s = " Hello\tworld\t";
1807 /// assert_eq!(s.trim(), "Hello\tworld");
1809 #[stable(feature = "rust1", since = "1.0.0")]
1810 pub fn trim(&self) -> &str {
1811 UnicodeStr
::trim(&self[..])
1814 /// Returns a `&str` with leading whitespace removed.
1819 /// let s = " Hello\tworld\t";
1820 /// assert_eq!(s.trim_left(), "Hello\tworld\t");
1822 #[stable(feature = "rust1", since = "1.0.0")]
1823 pub fn trim_left(&self) -> &str {
1824 UnicodeStr
::trim_left(&self[..])
1827 /// Returns a `&str` with trailing whitespace removed.
1832 /// let s = " Hello\tworld\t";
1833 /// assert_eq!(s.trim_right(), " Hello\tworld");
1835 #[stable(feature = "rust1", since = "1.0.0")]
1836 pub fn trim_right(&self) -> &str {
1837 UnicodeStr
::trim_right(&self[..])
1840 /// Returns the lowercase equivalent of this string.
1844 /// let s = "HELLO";
1845 /// assert_eq!(s.to_lowercase(), "hello");
1846 #[unstable(feature = "collections")]
1847 pub fn to_lowercase(&self) -> String
{
1848 let mut s
= String
::with_capacity(self.len());
1849 s
.extend(self[..].chars().flat_map(|c
| c
.to_lowercase()));
1853 /// Returns the uppercase equivalent of this string.
1857 /// let s = "hello";
1858 /// assert_eq!(s.to_uppercase(), "HELLO");
1859 #[unstable(feature = "collections")]
1860 pub fn to_uppercase(&self) -> String
{
1861 let mut s
= String
::with_capacity(self.len());
1862 s
.extend(self[..].chars().flat_map(|c
| c
.to_uppercase()));