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 //! String manipulation
13 //! For more details, see std::str
15 #![doc(primitive = "str")]
22 use cmp::{PartialEq, Eq};
23 use collections::Collection;
25 use iter::{Filter, Map, Iterator};
26 use iter::{DoubleEndedIterator, ExactSize};
28 use num::{CheckedMul, Saturating};
29 use option::{None, Option, Some};
31 use slice::ImmutableVector;
36 Section: Creating a string
39 /// Converts a vector to a string slice without performing any allocations.
41 /// Once the slice has been validated as utf-8, it is transmuted in-place and
42 /// returned as a '&str' instead of a '&[u8]'
44 /// Returns None if the slice is not utf-8.
45 pub fn from_utf8<'a>(v: &'a [u8]) -> Option<&'a str> {
47 Some(unsafe { raw::from_utf8(v) })
51 /// Something that can be used to compare against a character
53 /// Determine if the splitter should split at the given character
54 fn matches(&mut self, char) -> bool;
55 /// Indicate if this is only concerned about ASCII characters,
56 /// which can allow for a faster implementation.
57 fn only_ascii(&self) -> bool;
60 impl CharEq for char {
62 fn matches(&mut self, c: char) -> bool { *self == c }
65 fn only_ascii(&self) -> bool { (*self as uint) < 128 }
68 impl<'a> CharEq for |char|: 'a -> bool {
70 fn matches(&mut self, c: char) -> bool { (*self)(c) }
73 fn only_ascii(&self) -> bool { false }
76 impl CharEq for extern "Rust" fn(char) -> bool {
78 fn matches(&mut self, c: char) -> bool { (*self)(c) }
81 fn only_ascii(&self) -> bool { false }
84 impl<'a> CharEq for &'a [char] {
86 fn matches(&mut self, c: char) -> bool {
87 self.iter().any(|&mut m| m.matches(c))
91 fn only_ascii(&self) -> bool {
92 self.iter().all(|m| m.only_ascii())
100 /// External iterator for a string's characters.
101 /// Use with the `std::iter` module.
103 pub struct Chars<'a> {
104 /// The slice remaining to be iterated
108 impl<'a> Iterator<char> for Chars<'a> {
110 fn next(&mut self) -> Option<char> {
111 // Decode the next codepoint, then update
112 // the slice to be just the remaining part
113 if self.string.len() != 0 {
114 let CharRange {ch, next} = self.string.char_range_at(0);
116 self.string = raw::slice_unchecked(self.string, next, self.string.len());
125 fn size_hint(&self) -> (uint, Option<uint>) {
126 (self.string.len().saturating_add(3)/4, Some(self.string.len()))
130 impl<'a> DoubleEndedIterator<char> for Chars<'a> {
132 fn next_back(&mut self) -> Option<char> {
133 if self.string.len() != 0 {
134 let CharRange {ch, next} = self.string.char_range_at_reverse(self.string.len());
136 self.string = raw::slice_unchecked(self.string, 0, next);
145 /// External iterator for a string's characters and their byte offsets.
146 /// Use with the `std::iter` module.
148 pub struct CharOffsets<'a> {
149 /// The original string to be iterated
154 impl<'a> Iterator<(uint, char)> for CharOffsets<'a> {
156 fn next(&mut self) -> Option<(uint, char)> {
157 // Compute the byte offset by using the pointer offset between
158 // the original string slice and the iterator's remaining part
159 let offset = self.iter.string.as_ptr() as uint - self.string.as_ptr() as uint;
160 self.iter.next().map(|ch| (offset, ch))
164 fn size_hint(&self) -> (uint, Option<uint>) {
165 self.iter.size_hint()
169 impl<'a> DoubleEndedIterator<(uint, char)> for CharOffsets<'a> {
171 fn next_back(&mut self) -> Option<(uint, char)> {
172 self.iter.next_back().map(|ch| {
173 let offset = self.iter.string.len() +
174 self.iter.string.as_ptr() as uint - self.string.as_ptr() as uint;
180 /// External iterator for a string's bytes.
181 /// Use with the `std::iter` module.
183 Map<'a, &'a u8, u8, slice::Items<'a, u8>>;
185 /// An iterator over the substrings of a string, separated by `sep`.
187 pub struct CharSplits<'a, Sep> {
188 /// The slice remaining to be iterated
191 /// Whether an empty string at the end is allowed
192 allow_trailing_empty: bool,
197 /// An iterator over the substrings of a string, separated by `sep`,
198 /// splitting at most `count` times.
200 pub struct CharSplitsN<'a, Sep> {
201 iter: CharSplits<'a, Sep>,
202 /// The number of splits remaining
207 /// An iterator over the words of a string, separated by a sequence of whitespace
209 Filter<'a, &'a str, CharSplits<'a, extern "Rust" fn(char) -> bool>>;
211 /// An iterator over the lines of a string, separated by either `\n` or (`\r\n`).
212 pub type AnyLines<'a> =
213 Map<'a, &'a str, &'a str, CharSplits<'a, char>>;
215 impl<'a, Sep> CharSplits<'a, Sep> {
217 fn get_end(&mut self) -> Option<&'a str> {
218 if !self.finished && (self.allow_trailing_empty || self.string.len() > 0) {
219 self.finished = true;
227 impl<'a, Sep: CharEq> Iterator<&'a str> for CharSplits<'a, Sep> {
229 fn next(&mut self) -> Option<&'a str> {
230 if self.finished { return None }
232 let mut next_split = None;
234 for (idx, byte) in self.string.bytes().enumerate() {
235 if self.sep.matches(byte as char) && byte < 128u8 {
236 next_split = Some((idx, idx + 1));
241 for (idx, ch) in self.string.char_indices() {
242 if self.sep.matches(ch) {
243 next_split = Some((idx, self.string.char_range_at(idx).next));
249 Some((a, b)) => unsafe {
250 let elt = raw::slice_unchecked(self.string, 0, a);
251 self.string = raw::slice_unchecked(self.string, b, self.string.len());
254 None => self.get_end(),
259 impl<'a, Sep: CharEq> DoubleEndedIterator<&'a str>
260 for CharSplits<'a, Sep> {
262 fn next_back(&mut self) -> Option<&'a str> {
263 if self.finished { return None }
265 if !self.allow_trailing_empty {
266 self.allow_trailing_empty = true;
267 match self.next_back() {
268 Some(elt) if !elt.is_empty() => return Some(elt),
269 _ => if self.finished { return None }
272 let len = self.string.len();
273 let mut next_split = None;
276 for (idx, byte) in self.string.bytes().enumerate().rev() {
277 if self.sep.matches(byte as char) && byte < 128u8 {
278 next_split = Some((idx, idx + 1));
283 for (idx, ch) in self.string.char_indices().rev() {
284 if self.sep.matches(ch) {
285 next_split = Some((idx, self.string.char_range_at(idx).next));
291 Some((a, b)) => unsafe {
292 let elt = raw::slice_unchecked(self.string, b, len);
293 self.string = raw::slice_unchecked(self.string, 0, a);
296 None => { self.finished = true; Some(self.string) }
301 impl<'a, Sep: CharEq> Iterator<&'a str> for CharSplitsN<'a, Sep> {
303 fn next(&mut self) -> Option<&'a str> {
306 if self.invert { self.iter.next_back() } else { self.iter.next() }
313 /// The internal state of an iterator that searches for matches of a substring
314 /// within a larger string using naive search
316 struct NaiveSearcher {
321 fn new() -> NaiveSearcher {
322 NaiveSearcher { position: 0 }
325 fn next(&mut self, haystack: &[u8], needle: &[u8]) -> Option<(uint, uint)> {
326 while self.position + needle.len() <= haystack.len() {
327 if haystack.slice(self.position, self.position + needle.len()) == needle {
328 let matchPos = self.position;
329 self.position += needle.len(); // add 1 for all matches
330 return Some((matchPos, matchPos + needle.len()));
339 /// The internal state of an iterator that searches for matches of a substring
340 /// within a larger string using two-way search
342 struct TwoWaySearcher {
353 impl TwoWaySearcher {
354 fn new(needle: &[u8]) -> TwoWaySearcher {
355 let (critPos1, period1) = TwoWaySearcher::maximal_suffix(needle, false);
356 let (critPos2, period2) = TwoWaySearcher::maximal_suffix(needle, true);
360 if critPos1 > critPos2 {
368 let byteset = needle.iter()
369 .fold(0, |a, &b| (1 << ((b & 0x3f) as uint)) | a);
371 if needle.slice_to(critPos) == needle.slice_from(needle.len() - critPos) {
383 period: cmp::max(critPos, needle.len() - critPos) + 1,
387 memory: uint::MAX // Dummy value to signify that the period is long
393 fn next(&mut self, haystack: &[u8], needle: &[u8], longPeriod: bool) -> Option<(uint, uint)> {
395 // Check that we have room to search in
396 if self.position + needle.len() > haystack.len() {
400 // Quickly skip by large portions unrelated to our substring
402 ((haystack[self.position + needle.len() - 1] & 0x3f)
404 self.position += needle.len();
408 // See if the right part of the needle matches
409 let start = if longPeriod { self.critPos } else { cmp::max(self.critPos, self.memory) };
410 for i in range(start, needle.len()) {
411 if needle[i] != haystack[self.position + i] {
412 self.position += i - self.critPos + 1;
420 // See if the left part of the needle matches
421 let start = if longPeriod { 0 } else { self.memory };
422 for i in range(start, self.critPos).rev() {
423 if needle[i] != haystack[self.position + i] {
424 self.position += self.period;
426 self.memory = needle.len() - self.period;
432 // We have found a match!
433 let matchPos = self.position;
434 self.position += needle.len(); // add self.period for all matches
436 self.memory = 0; // set to needle.len() - self.period for all matches
438 return Some((matchPos, matchPos + needle.len()));
443 fn maximal_suffix(arr: &[u8], reversed: bool) -> (uint, uint) {
444 let mut left = -1; // Corresponds to i in the paper
445 let mut right = 0; // Corresponds to j in the paper
446 let mut offset = 1; // Corresponds to k in the paper
447 let mut period = 1; // Corresponds to p in the paper
449 while right + offset < arr.len() {
453 a = arr[left + offset];
454 b = arr[right + offset];
456 a = arr[right + offset];
457 b = arr[left + offset];
460 // Suffix is smaller, period is entire prefix so far.
463 period = right - left;
465 // Advance through repetition of the current period.
466 if offset == period {
473 // Suffix is larger, start over from current location.
484 /// The internal state of an iterator that searches for matches of a substring
485 /// within a larger string using a dynamically chosen search algorithm
488 Naive(NaiveSearcher),
489 TwoWay(TwoWaySearcher),
490 TwoWayLong(TwoWaySearcher)
494 fn new(haystack: &[u8], needle: &[u8]) -> Searcher {
496 if needle.len() > haystack.len() - 20 {
497 Naive(NaiveSearcher::new())
499 let searcher = TwoWaySearcher::new(needle);
500 if searcher.memory == uint::MAX { // If the period is long
509 /// An iterator over the start and end indices of the matches of a
510 /// substring within a larger string
512 pub struct MatchIndices<'a> {
519 /// An iterator over the substrings of a string separated by a given
522 pub struct StrSplits<'a> {
523 it: MatchIndices<'a>,
528 impl<'a> Iterator<(uint, uint)> for MatchIndices<'a> {
530 fn next(&mut self) -> Option<(uint, uint)> {
531 match self.searcher {
532 Naive(ref mut searcher)
533 => searcher.next(self.haystack.as_bytes(), self.needle.as_bytes()),
534 TwoWay(ref mut searcher)
535 => searcher.next(self.haystack.as_bytes(), self.needle.as_bytes(), false),
536 TwoWayLong(ref mut searcher)
537 => searcher.next(self.haystack.as_bytes(), self.needle.as_bytes(), true)
542 impl<'a> Iterator<&'a str> for StrSplits<'a> {
544 fn next(&mut self) -> Option<&'a str> {
545 if self.finished { return None; }
547 match self.it.next() {
548 Some((from, to)) => {
549 let ret = Some(self.it.haystack.slice(self.last_end, from));
554 self.finished = true;
555 Some(self.it.haystack.slice(self.last_end, self.it.haystack.len()))
561 /// External iterator for a string's UTF16 codeunits.
562 /// Use with the `std::iter` module.
564 pub struct Utf16CodeUnits<'a> {
569 impl<'a> Iterator<u16> for Utf16CodeUnits<'a> {
571 fn next(&mut self) -> Option<u16> {
573 let tmp = self.extra;
578 let mut buf = [0u16, ..2];
579 self.chars.next().map(|ch| {
580 let n = ch.encode_utf16(buf /* as mut slice! */);
581 if n == 2 { self.extra = buf[1]; }
587 fn size_hint(&self) -> (uint, Option<uint>) {
588 let (low, high) = self.chars.size_hint();
589 // every char gets either one u16 or two u16,
590 // so this iterator is between 1 or 2 times as
591 // long as the underlying iterator.
592 (low, high.and_then(|n| n.checked_mul(&2)))
597 Section: Comparing strings
600 // share the implementation of the lang-item vs. non-lang-item
602 /// NOTE: This function is (ab)used in rustc::middle::trans::_match
603 /// to compare &[u8] byte slices that are not necessarily valid UTF-8.
605 fn eq_slice_(a: &str, b: &str) -> bool {
607 extern { fn memcmp(s1: *const i8, s2: *const i8, n: uint) -> i32; }
608 a.len() == b.len() && unsafe {
609 memcmp(a.as_ptr() as *const i8,
610 b.as_ptr() as *const i8,
615 /// Bytewise slice equality
616 /// NOTE: This function is (ab)used in rustc::middle::trans::_match
617 /// to compare &[u8] byte slices that are not necessarily valid UTF-8.
620 pub fn eq_slice(a: &str, b: &str) -> bool {
628 /// Walk through `iter` checking that it's a valid UTF-8 sequence,
629 /// returning `true` in that case, or, if it is invalid, `false` with
630 /// `iter` reset such that it is pointing at the first byte in the
631 /// invalid sequence.
633 fn run_utf8_validation_iterator(iter: &mut slice::Items<u8>) -> bool {
635 // save the current thing we're pointing at.
638 // restore the iterator we had at the start of this codepoint.
639 macro_rules! err ( () => { {*iter = old; return false} });
640 macro_rules! next ( () => {
643 // we needed data, but there was none: error!
648 let first = match iter.next() {
650 // we're at the end of the iterator and a codepoint
651 // boundary at the same time, so this string is valid.
655 // ASCII characters are always valid, so only large
656 // bytes need more examination.
658 let w = utf8_char_width(first);
659 let second = next!();
660 // 2-byte encoding is for codepoints \u0080 to \u07ff
661 // first C2 80 last DF BF
662 // 3-byte encoding is for codepoints \u0800 to \uffff
663 // first E0 A0 80 last EF BF BF
664 // excluding surrogates codepoints \ud800 to \udfff
665 // ED A0 80 to ED BF BF
666 // 4-byte encoding is for codepoints \u10000 to \u10ffff
667 // first F0 90 80 80 last F4 8F BF BF
669 // Use the UTF-8 syntax from the RFC
671 // https://tools.ietf.org/html/rfc3629
673 // UTF8-2 = %xC2-DF UTF8-tail
674 // UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
675 // %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
676 // UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
677 // %xF4 %x80-8F 2( UTF8-tail )
679 2 => if second & 192 != TAG_CONT_U8 {err!()},
681 match (first, second, next!() & 192) {
682 (0xE0 , 0xA0 .. 0xBF, TAG_CONT_U8) |
683 (0xE1 .. 0xEC, 0x80 .. 0xBF, TAG_CONT_U8) |
684 (0xED , 0x80 .. 0x9F, TAG_CONT_U8) |
685 (0xEE .. 0xEF, 0x80 .. 0xBF, TAG_CONT_U8) => {}
690 match (first, second, next!() & 192, next!() & 192) {
691 (0xF0 , 0x90 .. 0xBF, TAG_CONT_U8, TAG_CONT_U8) |
692 (0xF1 .. 0xF3, 0x80 .. 0xBF, TAG_CONT_U8, TAG_CONT_U8) |
693 (0xF4 , 0x80 .. 0x8F, TAG_CONT_U8, TAG_CONT_U8) => {}
703 /// Determines if a vector of bytes contains valid UTF-8.
704 pub fn is_utf8(v: &[u8]) -> bool {
705 run_utf8_validation_iterator(&mut v.iter())
708 /// Determines if a vector of `u16` contains valid UTF-16
709 pub fn is_utf16(v: &[u16]) -> bool {
710 let mut it = v.iter();
711 macro_rules! next ( ($ret:expr) => {
712 match it.next() { Some(u) => *u, None => return $ret }
718 match char::from_u32(u as u32) {
721 let u2 = next!(false);
722 if u < 0xD7FF || u > 0xDBFF ||
723 u2 < 0xDC00 || u2 > 0xDFFF { return false; }
729 /// An iterator that decodes UTF-16 encoded codepoints from a vector
732 pub struct Utf16Items<'a> {
733 iter: slice::Items<'a, u16>
735 /// The possibilities for values decoded from a `u16` stream.
736 #[deriving(PartialEq, Eq, Clone, Show)]
738 /// A valid codepoint.
740 /// An invalid surrogate without its pair.
745 /// Convert `self` to a `char`, taking `LoneSurrogate`s to the
746 /// replacement character (U+FFFD).
748 pub fn to_char_lossy(&self) -> char {
751 LoneSurrogate(_) => '\uFFFD'
756 impl<'a> Iterator<Utf16Item> for Utf16Items<'a> {
757 fn next(&mut self) -> Option<Utf16Item> {
758 let u = match self.iter.next() {
763 if u < 0xD800 || 0xDFFF < u {
765 Some(ScalarValue(unsafe {mem::transmute(u as u32)}))
766 } else if u >= 0xDC00 {
767 // a trailing surrogate
768 Some(LoneSurrogate(u))
770 // preserve state for rewinding.
773 let u2 = match self.iter.next() {
776 None => return Some(LoneSurrogate(u))
778 if u2 < 0xDC00 || u2 > 0xDFFF {
779 // not a trailing surrogate so we're not a valid
780 // surrogate pair, so rewind to redecode u2 next time.
782 return Some(LoneSurrogate(u))
785 // all ok, so lets decode it.
786 let c = ((u - 0xD800) as u32 << 10 | (u2 - 0xDC00) as u32) + 0x1_0000;
787 Some(ScalarValue(unsafe {mem::transmute(c)}))
792 fn size_hint(&self) -> (uint, Option<uint>) {
793 let (low, high) = self.iter.size_hint();
794 // we could be entirely valid surrogates (2 elements per
795 // char), or entirely non-surrogates (1 element per char)
800 /// Create an iterator over the UTF-16 encoded codepoints in `v`,
801 /// returning invalid surrogates as `LoneSurrogate`s.
807 /// use std::str::{ScalarValue, LoneSurrogate};
809 /// // 𝄞mus<invalid>ic<invalid>
810 /// let v = [0xD834, 0xDD1E, 0x006d, 0x0075,
811 /// 0x0073, 0xDD1E, 0x0069, 0x0063,
814 /// assert_eq!(str::utf16_items(v).collect::<Vec<_>>(),
815 /// vec![ScalarValue('𝄞'),
816 /// ScalarValue('m'), ScalarValue('u'), ScalarValue('s'),
817 /// LoneSurrogate(0xDD1E),
818 /// ScalarValue('i'), ScalarValue('c'),
819 /// LoneSurrogate(0xD834)]);
821 pub fn utf16_items<'a>(v: &'a [u16]) -> Utf16Items<'a> {
822 Utf16Items { iter : v.iter() }
825 /// Return a slice of `v` ending at (and not including) the first NUL
834 /// let mut v = ['a' as u16, 'b' as u16, 'c' as u16, 'd' as u16];
835 /// // no NULs so no change
836 /// assert_eq!(str::truncate_utf16_at_nul(v), v.as_slice());
840 /// assert_eq!(str::truncate_utf16_at_nul(v),
841 /// &['a' as u16, 'b' as u16]);
843 pub fn truncate_utf16_at_nul<'a>(v: &'a [u16]) -> &'a [u16] {
844 match v.iter().position(|c| *c == 0) {
845 // don't include the 0
846 Some(i) => v.slice_to(i),
851 // https://tools.ietf.org/html/rfc3629
852 static UTF8_CHAR_WIDTH: [u8, ..256] = [
853 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
854 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // 0x1F
855 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
856 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // 0x3F
857 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
858 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // 0x5F
859 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
860 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, // 0x7F
861 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
862 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, // 0x9F
863 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
864 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0, // 0xBF
865 0,0,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
866 2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2, // 0xDF
867 3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3, // 0xEF
868 4,4,4,4,4,0,0,0,0,0,0,0,0,0,0,0, // 0xFF
871 /// Given a first byte, determine how many bytes are in this UTF-8 character
873 pub fn utf8_char_width(b: u8) -> uint {
874 return UTF8_CHAR_WIDTH[b as uint] as uint;
877 /// Struct that contains a `char` and the index of the first byte of
878 /// the next `char` in a string. This can be used as a data structure
879 /// for iterating over the UTF-8 bytes of a string.
880 pub struct CharRange {
883 /// Index of the first byte of the next `char`
887 // Return the initial codepoint accumulator for the first byte.
888 // The first byte is special, only want bottom 5 bits for width 2, 4 bits
889 // for width 3, and 3 bits for width 4
890 macro_rules! utf8_first_byte(
891 ($byte:expr, $width:expr) => (($byte & (0x7F >> $width)) as u32)
894 // return the value of $ch updated with continuation byte $byte
895 macro_rules! utf8_acc_cont_byte(
896 ($ch:expr, $byte:expr) => (($ch << 6) | ($byte & 63u8) as u32)
899 static TAG_CONT_U8: u8 = 128u8;
901 /// Unsafe operations
904 use collections::Collection;
907 use slice::{ImmutableVector};
908 use str::{is_utf8, StrSlice};
910 /// Converts a slice of bytes to a string slice without checking
911 /// that the string contains valid UTF-8.
912 pub unsafe fn from_utf8<'a>(v: &'a [u8]) -> &'a str {
916 /// Form a slice from a C string. Unsafe because the caller must ensure the
917 /// C string has the static lifetime, or else the return value may be
918 /// invalidated later.
919 pub unsafe fn c_str_to_static_slice(s: *const i8) -> &'static str {
920 let s = s as *const u8;
925 curr = s.offset(len as int);
927 let v = Slice { data: s, len: len };
928 assert!(is_utf8(::mem::transmute(v)));
932 /// Takes a bytewise (not UTF-8) slice from a string.
934 /// Returns the substring from [`begin`..`end`).
938 /// If begin is greater than end.
939 /// If end is greater than the length of the string.
941 pub unsafe fn slice_bytes<'a>(s: &'a str, begin: uint, end: uint) -> &'a str {
942 assert!(begin <= end);
943 assert!(end <= s.len());
944 slice_unchecked(s, begin, end)
947 /// Takes a bytewise (not UTF-8) slice from a string.
949 /// Returns the substring from [`begin`..`end`).
951 /// Caller must check slice boundaries!
953 pub unsafe fn slice_unchecked<'a>(s: &'a str, begin: uint, end: uint) -> &'a str {
954 mem::transmute(Slice {
955 data: s.as_ptr().offset(begin as int),
962 Section: Trait implementations
965 #[allow(missing_doc)]
967 use cmp::{Ord, Ordering, Less, Equal, Greater, PartialEq, PartialOrd, Equiv, Eq};
968 use collections::Collection;
970 use option::{Option, Some, None};
971 use str::{Str, StrSlice, eq_slice};
973 impl<'a> Ord for &'a str {
975 fn cmp(&self, other: & &'a str) -> Ordering {
976 for (s_b, o_b) in self.bytes().zip(other.bytes()) {
977 match s_b.cmp(&o_b) {
978 Greater => return Greater,
984 self.len().cmp(&other.len())
988 impl<'a> PartialEq for &'a str {
990 fn eq(&self, other: & &'a str) -> bool {
991 eq_slice((*self), (*other))
994 fn ne(&self, other: & &'a str) -> bool { !(*self).eq(other) }
997 impl<'a> Eq for &'a str {}
999 impl<'a> PartialOrd for &'a str {
1001 fn partial_cmp(&self, other: &&'a str) -> Option<Ordering> {
1002 Some(self.cmp(other))
1006 impl<'a, S: Str> Equiv<S> for &'a str {
1008 fn equiv(&self, other: &S) -> bool { eq_slice(*self, other.as_slice()) }
1012 /// Any string that can be represented as a slice
1014 /// Work with `self` as a slice.
1015 fn as_slice<'a>(&'a self) -> &'a str;
1018 impl<'a> Str for &'a str {
1020 fn as_slice<'a>(&'a self) -> &'a str { *self }
1023 impl<'a> Collection for &'a str {
1025 fn len(&self) -> uint {
1030 /// Methods for string slices
1031 pub trait StrSlice<'a> {
1032 /// Returns true if one string contains another
1036 /// - needle - The string to look for
1037 fn contains<'a>(&self, needle: &'a str) -> bool;
1039 /// Returns true if a string contains a char.
1043 /// - needle - The char to look for
1044 fn contains_char(&self, needle: char) -> bool;
1046 /// An iterator over the characters of `self`. Note, this iterates
1047 /// over unicode code-points, not unicode graphemes.
1052 /// let v: Vec<char> = "abc åäö".chars().collect();
1053 /// assert_eq!(v, vec!['a', 'b', 'c', ' ', 'å', 'ä', 'ö']);
1055 fn chars(&self) -> Chars<'a>;
1057 /// An iterator over the bytes of `self`
1058 fn bytes(&self) -> Bytes<'a>;
1060 /// An iterator over the characters of `self` and their byte offsets.
1061 fn char_indices(&self) -> CharOffsets<'a>;
1063 /// An iterator over substrings of `self`, separated by characters
1064 /// matched by `sep`.
1069 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
1070 /// assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]);
1072 /// let v: Vec<&str> = "abc1def2ghi".split(|c: char| c.is_digit()).collect();
1073 /// assert_eq!(v, vec!["abc", "def", "ghi"]);
1075 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
1076 /// assert_eq!(v, vec!["lion", "", "tiger", "leopard"]);
1078 /// let v: Vec<&str> = "".split('X').collect();
1079 /// assert_eq!(v, vec![""]);
1081 fn split<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep>;
1083 /// An iterator over substrings of `self`, separated by characters
1084 /// matched by `sep`, restricted to splitting at most `count`
1090 /// let v: Vec<&str> = "Mary had a little lambda".splitn(' ', 2).collect();
1091 /// assert_eq!(v, vec!["Mary", "had", "a little lambda"]);
1093 /// let v: Vec<&str> = "abc1def2ghi".splitn(|c: char| c.is_digit(), 1).collect();
1094 /// assert_eq!(v, vec!["abc", "def2ghi"]);
1096 /// let v: Vec<&str> = "lionXXtigerXleopard".splitn('X', 2).collect();
1097 /// assert_eq!(v, vec!["lion", "", "tigerXleopard"]);
1099 /// let v: Vec<&str> = "abcXdef".splitn('X', 0).collect();
1100 /// assert_eq!(v, vec!["abcXdef"]);
1102 /// let v: Vec<&str> = "".splitn('X', 1).collect();
1103 /// assert_eq!(v, vec![""]);
1105 fn splitn<Sep: CharEq>(&self, sep: Sep, count: uint) -> CharSplitsN<'a, Sep>;
1107 /// An iterator over substrings of `self`, separated by characters
1108 /// matched by `sep`.
1110 /// Equivalent to `split`, except that the trailing substring
1111 /// is skipped if empty (terminator semantics).
1116 /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
1117 /// assert_eq!(v, vec!["A", "B"]);
1119 /// let v: Vec<&str> = "A..B..".split_terminator('.').collect();
1120 /// assert_eq!(v, vec!["A", "", "B", ""]);
1122 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').rev().collect();
1123 /// assert_eq!(v, vec!["lamb", "little", "a", "had", "Mary"]);
1125 /// let v: Vec<&str> = "abc1def2ghi".split(|c: char| c.is_digit()).rev().collect();
1126 /// assert_eq!(v, vec!["ghi", "def", "abc"]);
1128 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').rev().collect();
1129 /// assert_eq!(v, vec!["leopard", "tiger", "", "lion"]);
1131 fn split_terminator<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep>;
1133 /// An iterator over substrings of `self`, separated by characters
1134 /// matched by `sep`, starting from the end of the string.
1135 /// Restricted to splitting at most `count` times.
1140 /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(' ', 2).collect();
1141 /// assert_eq!(v, vec!["lamb", "little", "Mary had a"]);
1143 /// let v: Vec<&str> = "abc1def2ghi".rsplitn(|c: char| c.is_digit(), 1).collect();
1144 /// assert_eq!(v, vec!["ghi", "abc1def"]);
1146 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn('X', 2).collect();
1147 /// assert_eq!(v, vec!["leopard", "tiger", "lionX"]);
1149 fn rsplitn<Sep: CharEq>(&self, sep: Sep, count: uint) -> CharSplitsN<'a, Sep>;
1151 /// An iterator over the start and end indices of the disjoint
1152 /// matches of `sep` within `self`.
1154 /// That is, each returned value `(start, end)` satisfies
1155 /// `self.slice(start, end) == sep`. For matches of `sep` within
1156 /// `self` that overlap, only the indices corresponding to the
1157 /// first match are returned.
1162 /// let v: Vec<(uint, uint)> = "abcXXXabcYYYabc".match_indices("abc").collect();
1163 /// assert_eq!(v, vec![(0,3), (6,9), (12,15)]);
1165 /// let v: Vec<(uint, uint)> = "1abcabc2".match_indices("abc").collect();
1166 /// assert_eq!(v, vec![(1,4), (4,7)]);
1168 /// let v: Vec<(uint, uint)> = "ababa".match_indices("aba").collect();
1169 /// assert_eq!(v, vec![(0, 3)]); // only the first `aba`
1171 fn match_indices(&self, sep: &'a str) -> MatchIndices<'a>;
1173 /// An iterator over the substrings of `self` separated by `sep`.
1178 /// let v: Vec<&str> = "abcXXXabcYYYabc".split_str("abc").collect();
1179 /// assert_eq!(v, vec!["", "XXX", "YYY", ""]);
1181 /// let v: Vec<&str> = "1abcabc2".split_str("abc").collect();
1182 /// assert_eq!(v, vec!["1", "", "2"]);
1184 fn split_str(&self, &'a str) -> StrSplits<'a>;
1186 /// An iterator over the lines of a string (subsequences separated
1187 /// by `\n`). This does not include the empty string after a
1193 /// let four_lines = "foo\nbar\n\nbaz\n";
1194 /// let v: Vec<&str> = four_lines.lines().collect();
1195 /// assert_eq!(v, vec!["foo", "bar", "", "baz"]);
1197 fn lines(&self) -> CharSplits<'a, char>;
1199 /// An iterator over the lines of a string, separated by either
1200 /// `\n` or `\r\n`. As with `.lines()`, this does not include an
1201 /// empty trailing line.
1206 /// let four_lines = "foo\r\nbar\n\r\nbaz\n";
1207 /// let v: Vec<&str> = four_lines.lines_any().collect();
1208 /// assert_eq!(v, vec!["foo", "bar", "", "baz"]);
1210 fn lines_any(&self) -> AnyLines<'a>;
1212 /// An iterator over the words of a string (subsequences separated
1213 /// by any sequence of whitespace). Sequences of whitespace are
1214 /// collapsed, so empty "words" are not included.
1219 /// let some_words = " Mary had\ta little \n\t lamb";
1220 /// let v: Vec<&str> = some_words.words().collect();
1221 /// assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]);
1223 fn words(&self) -> Words<'a>;
1225 /// Returns true if the string contains only whitespace.
1227 /// Whitespace characters are determined by `char::is_whitespace`.
1232 /// assert!(" \t\n".is_whitespace());
1233 /// assert!("".is_whitespace());
1235 /// assert!( !"abc".is_whitespace());
1237 fn is_whitespace(&self) -> bool;
1239 /// Returns true if the string contains only alphanumeric code
1242 /// Alphanumeric characters are determined by `char::is_alphanumeric`.
1247 /// assert!("Löwe老虎Léopard123".is_alphanumeric());
1248 /// assert!("".is_alphanumeric());
1250 /// assert!( !" &*~".is_alphanumeric());
1252 fn is_alphanumeric(&self) -> bool;
1254 /// Returns the number of Unicode code points (`char`) that a
1257 /// This does not perform any normalization, and is `O(n)`, since
1258 /// UTF-8 is a variable width encoding of code points.
1260 /// *Warning*: The number of code points in a string does not directly
1261 /// correspond to the number of visible characters or width of the
1262 /// visible text due to composing characters, and double- and
1263 /// zero-width ones.
1265 /// See also `.len()` for the byte length.
1270 /// // composed forms of `ö` and `é`
1271 /// let c = "Löwe 老虎 Léopard"; // German, Simplified Chinese, French
1272 /// // decomposed forms of `ö` and `é`
1273 /// let d = "Lo\u0308we 老虎 Le\u0301opard";
1275 /// assert_eq!(c.char_len(), 15);
1276 /// assert_eq!(d.char_len(), 17);
1278 /// assert_eq!(c.len(), 21);
1279 /// assert_eq!(d.len(), 23);
1281 /// // the two strings *look* the same
1282 /// println!("{}", c);
1283 /// println!("{}", d);
1285 fn char_len(&self) -> uint;
1287 /// Returns a slice of the given string from the byte range
1288 /// [`begin`..`end`).
1290 /// This operation is `O(1)`.
1292 /// Fails when `begin` and `end` do not point to valid characters
1293 /// or point beyond the last character of the string.
1295 /// See also `slice_to` and `slice_from` for slicing prefixes and
1296 /// suffixes of strings, and `slice_chars` for slicing based on
1297 /// code point counts.
1302 /// let s = "Löwe 老虎 Léopard";
1303 /// assert_eq!(s.slice(0, 1), "L");
1305 /// assert_eq!(s.slice(1, 9), "öwe 老");
1307 /// // these will fail:
1308 /// // byte 2 lies within `ö`:
1309 /// // s.slice(2, 3);
1311 /// // byte 8 lies within `老`
1312 /// // s.slice(1, 8);
1314 /// // byte 100 is outside the string
1315 /// // s.slice(3, 100);
1317 fn slice(&self, begin: uint, end: uint) -> &'a str;
1319 /// Returns a slice of the string from `begin` to its end.
1321 /// Equivalent to `self.slice(begin, self.len())`.
1323 /// Fails when `begin` does not point to a valid character, or is
1326 /// See also `slice`, `slice_to` and `slice_chars`.
1327 fn slice_from(&self, begin: uint) -> &'a str;
1329 /// Returns a slice of the string from the beginning to byte
1332 /// Equivalent to `self.slice(0, end)`.
1334 /// Fails when `end` does not point to a valid character, or is
1337 /// See also `slice`, `slice_from` and `slice_chars`.
1338 fn slice_to(&self, end: uint) -> &'a str;
1340 /// Returns a slice of the string from the character range
1341 /// [`begin`..`end`).
1343 /// That is, start at the `begin`-th code point of the string and
1344 /// continue to the `end`-th code point. This does not detect or
1345 /// handle edge cases such as leaving a combining character as the
1346 /// first code point of the string.
1348 /// Due to the design of UTF-8, this operation is `O(end)`.
1349 /// See `slice`, `slice_to` and `slice_from` for `O(1)`
1350 /// variants that use byte indices rather than code point
1353 /// Fails if `begin` > `end` or the either `begin` or `end` are
1354 /// beyond the last character of the string.
1359 /// let s = "Löwe 老虎 Léopard";
1360 /// assert_eq!(s.slice_chars(0, 4), "Löwe");
1361 /// assert_eq!(s.slice_chars(5, 7), "老虎");
1363 fn slice_chars(&self, begin: uint, end: uint) -> &'a str;
1365 /// Returns true if `needle` is a prefix of the string.
1366 fn starts_with(&self, needle: &str) -> bool;
1368 /// Returns true if `needle` is a suffix of the string.
1369 fn ends_with(&self, needle: &str) -> bool;
1371 /// Returns a string with leading and trailing whitespace removed.
1372 fn trim(&self) -> &'a str;
1374 /// Returns a string with leading whitespace removed.
1375 fn trim_left(&self) -> &'a str;
1377 /// Returns a string with trailing whitespace removed.
1378 fn trim_right(&self) -> &'a str;
1380 /// Returns a string with characters that match `to_trim` removed.
1384 /// * to_trim - a character matcher
1389 /// assert_eq!("11foo1bar11".trim_chars('1'), "foo1bar")
1390 /// assert_eq!("12foo1bar12".trim_chars(&['1', '2']), "foo1bar")
1391 /// assert_eq!("123foo1bar123".trim_chars(|c: char| c.is_digit()), "foo1bar")
1393 fn trim_chars<C: CharEq>(&self, to_trim: C) -> &'a str;
1395 /// Returns a string with leading `chars_to_trim` removed.
1399 /// * to_trim - a character matcher
1404 /// assert_eq!("11foo1bar11".trim_left_chars('1'), "foo1bar11")
1405 /// assert_eq!("12foo1bar12".trim_left_chars(&['1', '2']), "foo1bar12")
1406 /// assert_eq!("123foo1bar123".trim_left_chars(|c: char| c.is_digit()), "foo1bar123")
1408 fn trim_left_chars<C: CharEq>(&self, to_trim: C) -> &'a str;
1410 /// Returns a string with trailing `chars_to_trim` removed.
1414 /// * to_trim - a character matcher
1419 /// assert_eq!("11foo1bar11".trim_right_chars('1'), "11foo1bar")
1420 /// assert_eq!("12foo1bar12".trim_right_chars(&['1', '2']), "12foo1bar")
1421 /// assert_eq!("123foo1bar123".trim_right_chars(|c: char| c.is_digit()), "123foo1bar")
1423 fn trim_right_chars<C: CharEq>(&self, to_trim: C) -> &'a str;
1425 /// Check that `index`-th byte lies at the start and/or end of a
1426 /// UTF-8 code point sequence.
1428 /// The start and end of the string (when `index == self.len()`)
1429 /// are considered to be boundaries.
1431 /// Fails if `index` is greater than `self.len()`.
1436 /// let s = "Löwe 老虎 Léopard";
1437 /// assert!(s.is_char_boundary(0));
1439 /// assert!(s.is_char_boundary(6));
1440 /// assert!(s.is_char_boundary(s.len()));
1442 /// // second byte of `ö`
1443 /// assert!(!s.is_char_boundary(2));
1445 /// // third byte of `老`
1446 /// assert!(!s.is_char_boundary(8));
1448 fn is_char_boundary(&self, index: uint) -> bool;
1450 /// Pluck a character out of a string and return the index of the next
1453 /// This function can be used to iterate over the unicode characters of a
1458 /// This example manually iterate through the characters of a
1459 /// string; this should normally by done by `.chars()` or
1460 /// `.char_indices`.
1463 /// use std::str::CharRange;
1465 /// let s = "中华Việt Nam";
1467 /// while i < s.len() {
1468 /// let CharRange {ch, next} = s.char_range_at(i);
1469 /// println!("{}: {}", i, ch);
1491 /// * s - The string
1492 /// * i - The byte offset of the char to extract
1496 /// A record {ch: char, next: uint} containing the char value and the byte
1497 /// index of the next unicode character.
1501 /// If `i` is greater than or equal to the length of the string.
1502 /// If `i` is not the index of the beginning of a valid UTF-8 character.
1503 fn char_range_at(&self, start: uint) -> CharRange;
1505 /// Given a byte position and a str, return the previous char and its position.
1507 /// This function can be used to iterate over a unicode string in reverse.
1509 /// Returns 0 for next index if called on start index 0.
1513 /// If `i` is greater than the length of the string.
1514 /// If `i` is not an index following a valid UTF-8 character.
1515 fn char_range_at_reverse(&self, start: uint) -> CharRange;
1517 /// Plucks the character starting at the `i`th byte of a string.
1521 /// If `i` is greater than or equal to the length of the string.
1522 /// If `i` is not the index of the beginning of a valid UTF-8 character.
1523 fn char_at(&self, i: uint) -> char;
1525 /// Plucks the character ending at the `i`th byte of a string.
1529 /// If `i` is greater than the length of the string.
1530 /// If `i` is not an index following a valid UTF-8 character.
1531 fn char_at_reverse(&self, i: uint) -> char;
1533 /// Work with the byte buffer of a string as a byte slice.
1534 fn as_bytes(&self) -> &'a [u8];
1536 /// Returns the byte index of the first character of `self` that
1537 /// matches `search`.
1541 /// `Some` containing the byte index of the last matching character
1542 /// or `None` if there is no match
1547 /// let s = "Löwe 老虎 Léopard";
1549 /// assert_eq!(s.find('L'), Some(0));
1550 /// assert_eq!(s.find('é'), Some(14));
1552 /// // the first space
1553 /// assert_eq!(s.find(|c: char| c.is_whitespace()), Some(5));
1555 /// // neither are found
1556 /// assert_eq!(s.find(&['1', '2']), None);
1558 fn find<C: CharEq>(&self, search: C) -> Option<uint>;
1560 /// Returns the byte index of the last character of `self` that
1561 /// matches `search`.
1565 /// `Some` containing the byte index of the last matching character
1566 /// or `None` if there is no match.
1571 /// let s = "Löwe 老虎 Léopard";
1573 /// assert_eq!(s.rfind('L'), Some(13));
1574 /// assert_eq!(s.rfind('é'), Some(14));
1576 /// // the second space
1577 /// assert_eq!(s.rfind(|c: char| c.is_whitespace()), Some(12));
1579 /// // searches for an occurrence of either `1` or `2`, but neither are found
1580 /// assert_eq!(s.rfind(&['1', '2']), None);
1582 fn rfind<C: CharEq>(&self, search: C) -> Option<uint>;
1584 /// Returns the byte index of the first matching substring
1588 /// * `needle` - The string to search for
1592 /// `Some` containing the byte index of the first matching substring
1593 /// or `None` if there is no match.
1598 /// let s = "Löwe 老虎 Léopard";
1600 /// assert_eq!(s.find_str("老虎 L"), Some(6));
1601 /// assert_eq!(s.find_str("muffin man"), None);
1603 fn find_str(&self, &str) -> Option<uint>;
1605 /// Retrieves the first character from a string slice and returns
1606 /// it. This does not allocate a new string; instead, it returns a
1607 /// slice that point one character beyond the character that was
1608 /// shifted. If the string does not contain any characters,
1609 /// a tuple of None and an empty string is returned instead.
1614 /// let s = "Löwe 老虎 Léopard";
1615 /// let (c, s1) = s.slice_shift_char();
1616 /// assert_eq!(c, Some('L'));
1617 /// assert_eq!(s1, "öwe 老虎 Léopard");
1619 /// let (c, s2) = s1.slice_shift_char();
1620 /// assert_eq!(c, Some('ö'));
1621 /// assert_eq!(s2, "we 老虎 Léopard");
1623 fn slice_shift_char(&self) -> (Option<char>, &'a str);
1625 /// Returns the byte offset of an inner slice relative to an enclosing outer slice.
1627 /// Fails if `inner` is not a direct slice contained within self.
1632 /// let string = "a\nb\nc";
1633 /// let lines: Vec<&str> = string.lines().collect();
1634 /// let lines = lines.as_slice();
1636 /// assert!(string.subslice_offset(lines[0]) == 0); // &"a"
1637 /// assert!(string.subslice_offset(lines[1]) == 2); // &"b"
1638 /// assert!(string.subslice_offset(lines[2]) == 4); // &"c"
1640 fn subslice_offset(&self, inner: &str) -> uint;
1642 /// Return an unsafe pointer to the strings buffer.
1644 /// The caller must ensure that the string outlives this pointer,
1645 /// and that it is not reallocated (e.g. by pushing to the
1647 fn as_ptr(&self) -> *const u8;
1649 /// Return an iterator of `u16` over the string encoded as UTF-16.
1650 fn utf16_units(&self) -> Utf16CodeUnits<'a>;
1653 impl<'a> StrSlice<'a> for &'a str {
1655 fn contains<'a>(&self, needle: &'a str) -> bool {
1656 self.find_str(needle).is_some()
1660 fn contains_char(&self, needle: char) -> bool {
1661 self.find(needle).is_some()
1665 fn chars(&self) -> Chars<'a> {
1666 Chars{string: *self}
1670 fn bytes(&self) -> Bytes<'a> {
1671 self.as_bytes().iter().map(|&b| b)
1675 fn char_indices(&self) -> CharOffsets<'a> {
1676 CharOffsets{string: *self, iter: self.chars()}
1680 fn split<Sep: CharEq>(&self, sep: Sep) -> CharSplits<'a, Sep> {
1683 only_ascii: sep.only_ascii(),
1685 allow_trailing_empty: true,
1691 fn splitn<Sep: CharEq>(&self, sep: Sep, count: uint)
1692 -> CharSplitsN<'a, Sep> {
1694 iter: self.split(sep),
1701 fn split_terminator<Sep: CharEq>(&self, sep: Sep)
1702 -> CharSplits<'a, Sep> {
1704 allow_trailing_empty: false,
1710 fn rsplitn<Sep: CharEq>(&self, sep: Sep, count: uint)
1711 -> CharSplitsN<'a, Sep> {
1713 iter: self.split(sep),
1720 fn match_indices(&self, sep: &'a str) -> MatchIndices<'a> {
1721 assert!(!sep.is_empty())
1725 searcher: Searcher::new(self.as_bytes(), sep.as_bytes())
1730 fn split_str(&self, sep: &'a str) -> StrSplits<'a> {
1732 it: self.match_indices(sep),
1739 fn lines(&self) -> CharSplits<'a, char> {
1740 self.split_terminator('\n')
1743 fn lines_any(&self) -> AnyLines<'a> {
1744 self.lines().map(|line| {
1746 if l > 0 && line[l - 1] == '\r' as u8 { line.slice(0, l - 1) }
1752 fn words(&self) -> Words<'a> {
1753 self.split(char::is_whitespace).filter(|s| !s.is_empty())
1757 fn is_whitespace(&self) -> bool { self.chars().all(char::is_whitespace) }
1760 fn is_alphanumeric(&self) -> bool { self.chars().all(char::is_alphanumeric) }
1763 fn char_len(&self) -> uint { self.chars().count() }
1766 fn slice(&self, begin: uint, end: uint) -> &'a str {
1767 assert!(self.is_char_boundary(begin) && self.is_char_boundary(end));
1768 unsafe { raw::slice_bytes(*self, begin, end) }
1772 fn slice_from(&self, begin: uint) -> &'a str {
1773 self.slice(begin, self.len())
1777 fn slice_to(&self, end: uint) -> &'a str {
1778 assert!(self.is_char_boundary(end));
1779 unsafe { raw::slice_bytes(*self, 0, end) }
1782 fn slice_chars(&self, begin: uint, end: uint) -> &'a str {
1783 assert!(begin <= end);
1785 let mut begin_byte = None;
1786 let mut end_byte = None;
1788 // This could be even more efficient by not decoding,
1789 // only finding the char boundaries
1790 for (idx, _) in self.char_indices() {
1791 if count == begin { begin_byte = Some(idx); }
1792 if count == end { end_byte = Some(idx); break; }
1795 if begin_byte.is_none() && count == begin { begin_byte = Some(self.len()) }
1796 if end_byte.is_none() && count == end { end_byte = Some(self.len()) }
1798 match (begin_byte, end_byte) {
1799 (None, _) => fail!("slice_chars: `begin` is beyond end of string"),
1800 (_, None) => fail!("slice_chars: `end` is beyond end of string"),
1801 (Some(a), Some(b)) => unsafe { raw::slice_bytes(*self, a, b) }
1806 fn starts_with<'a>(&self, needle: &'a str) -> bool {
1807 let n = needle.len();
1808 self.len() >= n && needle.as_bytes() == self.as_bytes().slice_to(n)
1812 fn ends_with(&self, needle: &str) -> bool {
1813 let (m, n) = (self.len(), needle.len());
1814 m >= n && needle.as_bytes() == self.as_bytes().slice_from(m - n)
1818 fn trim(&self) -> &'a str {
1819 self.trim_left().trim_right()
1823 fn trim_left(&self) -> &'a str {
1824 self.trim_left_chars(char::is_whitespace)
1828 fn trim_right(&self) -> &'a str {
1829 self.trim_right_chars(char::is_whitespace)
1833 fn trim_chars<C: CharEq>(&self, mut to_trim: C) -> &'a str {
1834 let cur = match self.find(|c: char| !to_trim.matches(c)) {
1836 Some(i) => unsafe { raw::slice_bytes(*self, i, self.len()) }
1838 match cur.rfind(|c: char| !to_trim.matches(c)) {
1841 let right = cur.char_range_at(i).next;
1842 unsafe { raw::slice_bytes(cur, 0, right) }
1848 fn trim_left_chars<C: CharEq>(&self, mut to_trim: C) -> &'a str {
1849 match self.find(|c: char| !to_trim.matches(c)) {
1851 Some(first) => unsafe { raw::slice_bytes(*self, first, self.len()) }
1856 fn trim_right_chars<C: CharEq>(&self, mut to_trim: C) -> &'a str {
1857 match self.rfind(|c: char| !to_trim.matches(c)) {
1860 let next = self.char_range_at(last).next;
1861 unsafe { raw::slice_bytes(*self, 0u, next) }
1867 fn is_char_boundary(&self, index: uint) -> bool {
1868 if index == self.len() { return true; }
1869 if index > self.len() { return false; }
1870 let b = self[index];
1871 return b < 128u8 || b >= 192u8;
1875 fn char_range_at(&self, i: uint) -> CharRange {
1876 if self[i] < 128u8 {
1877 return CharRange {ch: self[i] as char, next: i + 1 };
1880 // Multibyte case is a fn to allow char_range_at to inline cleanly
1881 fn multibyte_char_range_at(s: &str, i: uint) -> CharRange {
1882 let mut val = s[i] as u32;
1883 let w = UTF8_CHAR_WIDTH[val as uint] as uint;
1886 val = utf8_first_byte!(val, w);
1887 val = utf8_acc_cont_byte!(val, s[i + 1]);
1888 if w > 2 { val = utf8_acc_cont_byte!(val, s[i + 2]); }
1889 if w > 3 { val = utf8_acc_cont_byte!(val, s[i + 3]); }
1891 return CharRange {ch: unsafe { mem::transmute(val) }, next: i + w};
1894 return multibyte_char_range_at(*self, i);
1898 fn char_range_at_reverse(&self, start: uint) -> CharRange {
1899 let mut prev = start;
1901 prev = prev.saturating_sub(1);
1902 if self[prev] < 128 { return CharRange{ch: self[prev] as char, next: prev} }
1904 // Multibyte case is a fn to allow char_range_at_reverse to inline cleanly
1905 fn multibyte_char_range_at_reverse(s: &str, mut i: uint) -> CharRange {
1906 // while there is a previous byte == 10......
1907 while i > 0 && s[i] & 192u8 == TAG_CONT_U8 {
1911 let mut val = s[i] as u32;
1912 let w = UTF8_CHAR_WIDTH[val as uint] as uint;
1915 val = utf8_first_byte!(val, w);
1916 val = utf8_acc_cont_byte!(val, s[i + 1]);
1917 if w > 2 { val = utf8_acc_cont_byte!(val, s[i + 2]); }
1918 if w > 3 { val = utf8_acc_cont_byte!(val, s[i + 3]); }
1920 return CharRange {ch: unsafe { mem::transmute(val) }, next: i};
1923 return multibyte_char_range_at_reverse(*self, prev);
1927 fn char_at(&self, i: uint) -> char {
1928 self.char_range_at(i).ch
1932 fn char_at_reverse(&self, i: uint) -> char {
1933 self.char_range_at_reverse(i).ch
1937 fn as_bytes(&self) -> &'a [u8] {
1938 unsafe { mem::transmute(*self) }
1941 fn find<C: CharEq>(&self, mut search: C) -> Option<uint> {
1942 if search.only_ascii() {
1943 self.bytes().position(|b| search.matches(b as char))
1945 for (index, c) in self.char_indices() {
1946 if search.matches(c) { return Some(index); }
1952 fn rfind<C: CharEq>(&self, mut search: C) -> Option<uint> {
1953 if search.only_ascii() {
1954 self.bytes().rposition(|b| search.matches(b as char))
1956 for (index, c) in self.char_indices().rev() {
1957 if search.matches(c) { return Some(index); }
1963 fn find_str(&self, needle: &str) -> Option<uint> {
1964 if needle.is_empty() {
1967 self.match_indices(needle)
1969 .map(|(start, _end)| start)
1974 fn slice_shift_char(&self) -> (Option<char>, &'a str) {
1975 if self.is_empty() {
1976 return (None, *self);
1978 let CharRange {ch, next} = self.char_range_at(0u);
1979 let next_s = unsafe { raw::slice_bytes(*self, next, self.len()) };
1980 return (Some(ch), next_s);
1984 fn subslice_offset(&self, inner: &str) -> uint {
1985 let a_start = self.as_ptr() as uint;
1986 let a_end = a_start + self.len();
1987 let b_start = inner.as_ptr() as uint;
1988 let b_end = b_start + inner.len();
1990 assert!(a_start <= b_start);
1991 assert!(b_end <= a_end);
1996 fn as_ptr(&self) -> *const u8 {
2001 fn utf16_units(&self) -> Utf16CodeUnits<'a> {
2002 Utf16CodeUnits{ chars: self.chars(), extra: 0}
2006 impl<'a> Default for &'a str {
2007 fn default() -> &'a str { "" }