- [proc_macro](language-features/proc-macro.md)
- [quote](language-features/quote.md)
- [relaxed_adts](language-features/relaxed-adts.md)
+ - [repr_align](language-features/repr-align.md)
- [repr_simd](language-features/repr-simd.md)
- [rustc_attrs](language-features/rustc-attrs.md)
- [rustc_diagnostic_macros](language-features/rustc-diagnostic-macros.md)
- [alloc_system](library-features/alloc-system.md)
- [alloc](library-features/alloc.md)
- [as_c_str](library-features/as-c-str.md)
- - [as_unsafe_cell](library-features/as-unsafe-cell.md)
- [ascii_ctype](library-features/ascii-ctype.md)
- - [binary_heap_extras](library-features/binary-heap-extras.md)
- [binary_heap_peek_mut_pop](library-features/binary-heap-peek-mut-pop.md)
- - [borrow_state](library-features/borrow-state.md)
- [box_heap](library-features/box-heap.md)
- [c_void_variant](library-features/c-void-variant.md)
- [char_escape_debug](library-features/char-escape-debug.md)
- [derive_clone_copy](library-features/derive-clone-copy.md)
- [derive_eq](library-features/derive-eq.md)
- [discriminant_value](library-features/discriminant-value.md)
- - [enumset](library-features/enumset.md)
- [error_type_id](library-features/error-type-id.md)
- [exact_size_is_empty](library-features/exact-size-is-empty.md)
- [fd](library-features/fd.md)
- [fd_read](library-features/fd-read.md)
- [fixed_size_array](library-features/fixed-size-array.md)
- [float_bits_conv](library-features/float-bits-conv.md)
- - [float_extras](library-features/float-extras.md)
- [flt2dec](library-features/flt2dec.md)
- [fmt_flags_align](library-features/fmt-flags-align.md)
- [fmt_internals](library-features/fmt-internals.md)
- [io_error_internals](library-features/io-error-internals.md)
- [io](library-features/io.md)
- [ip](library-features/ip.md)
- - [is_unique](library-features/is-unique.md)
- [iter_rfind](library-features/iter-rfind.md)
- [libstd_io_internals](library-features/libstd-io-internals.md)
- [libstd_sys_internals](library-features/libstd-sys-internals.md)
- [linked_list_extras](library-features/linked-list-extras.md)
- [lookup_host](library-features/lookup-host.md)
- [manually_drop](library-features/manually-drop.md)
- - [map_entry_recover_keys](library-features/map-entry-recover-keys.md)
+ - [more_io_inner_methods](library-features/more-io-inner-methods.md)
- [mpsc_select](library-features/mpsc-select.md)
- [n16](library-features/n16.md)
- [never_type_impls](library-features/never-type-impls.md)
- [rand](library-features/rand.md)
- [range_contains](library-features/range-contains.md)
- [raw](library-features/raw.md)
- - [rc_would_unwrap](library-features/rc-would-unwrap.md)
- [retain_hash_collection](library-features/retain-hash-collection.md)
- [reverse_cmp_key](library-features/reverse-cmp-key.md)
- [rt](library-features/rt.md)
- [slice_rsplit](library-features/slice-rsplit.md)
- [sort_internals](library-features/sort-internals.md)
- [sort_unstable](library-features/sort-unstable.md)
+ - [splice](library-features/splice.md)
- [step_by](library-features/step-by.md)
- [step_trait](library-features/step-trait.md)
- [str_checked_slicing](library-features/str-checked-slicing.md)
- [str_escape](library-features/str-escape.md)
- [str_internals](library-features/str-internals.md)
+ - [str_box_extras](library-features/str-box-extras.md)
- [str_mut_extras](library-features/str-mut-extras.md)
- [test](library-features/test.md)
- [thread_id](library-features/thread-id.md)
- [windows_handle](library-features/windows-handle.md)
- [windows_net](library-features/windows-net.md)
- [windows_stdio](library-features/windows-stdio.md)
- - [zero_one](library-features/zero-one.md)
->>>>>> Add top level sections to the Unstable Book.
#![stable(feature = "rust1", since = "1.0.0")]
+ use alloc::str as alloc_str;
+
use core::fmt;
use core::hash;
use core::iter::{FromIterator, FusedIterator};
- use core::mem;
use core::ops::{self, Add, AddAssign, Index, IndexMut};
use core::ptr;
use core::str as core_str;
self.vec.clear()
}
- /// Create a draining iterator that removes the specified range in the string
+ /// Creates a draining iterator that removes the specified range in the string
/// and yields the removed chars.
///
/// Note: The element range is removed even if the iterator is not
}
}
+ /// Creates a splicing iterator that removes the specified range in the string,
+ /// replaces with the given string, and yields the removed chars.
+ /// The given string doesn’t need to be the same length as the range.
+ ///
+ /// Note: The element range is removed when the `Splice` is dropped,
+ /// even if the iterator is not consumed until the end.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the starting point or end point do not lie on a [`char`]
+ /// boundary, or if they're out of bounds.
+ ///
+ /// [`char`]: ../../std/primitive.char.html
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// #![feature(splice)]
+ /// let mut s = String::from("α is alpha, β is beta");
+ /// let beta_offset = s.find('β').unwrap_or(s.len());
+ ///
+ /// // Replace the range up until the β from the string
+ /// let t: String = s.splice(..beta_offset, "Α is capital alpha; ").collect();
+ /// assert_eq!(t, "α is alpha, ");
+ /// assert_eq!(s, "Α is capital alpha; β is beta");
+ /// ```
+ #[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+ pub fn splice<'a, 'b, R>(&'a mut self, range: R, replace_with: &'b str) -> Splice<'a, 'b>
+ where R: RangeArgument<usize>
+ {
+ // Memory safety
+ //
+ // The String version of Splice does not have the memory safety issues
+ // of the vector version. The data is just plain bytes.
+ // Because the range removal happens in Drop, if the Splice iterator is leaked,
+ // the removal will not happen.
+ let len = self.len();
+ let start = match range.start() {
+ Included(&n) => n,
+ Excluded(&n) => n + 1,
+ Unbounded => 0,
+ };
+ let end = match range.end() {
+ Included(&n) => n + 1,
+ Excluded(&n) => n,
+ Unbounded => len,
+ };
+
+ // Take out two simultaneous borrows. The &mut String won't be accessed
+ // until iteration is over, in Drop.
+ let self_ptr = self as *mut _;
+ // slicing does the appropriate bounds checks
+ let chars_iter = self[start..end].chars();
+
+ Splice {
+ start: start,
+ end: end,
+ iter: chars_iter,
+ string: self_ptr,
+ replace_with: replace_with
+ }
+ }
+
/// Converts this `String` into a `Box<str>`.
///
/// This will drop any excess capacity.
#[stable(feature = "box_str", since = "1.4.0")]
pub fn into_boxed_str(self) -> Box<str> {
let slice = self.vec.into_boxed_slice();
- unsafe { mem::transmute::<Box<[u8]>, Box<str>>(slice) }
+ unsafe { alloc_str::from_boxed_utf8_unchecked(slice) }
}
}
#[unstable(feature = "fused", issue = "35602")]
impl<'a> FusedIterator for Drain<'a> {}
+
+/// A splicing iterator for `String`.
+///
+/// This struct is created by the [`splice()`] method on [`String`]. See its
+/// documentation for more.
+///
+/// [`splice()`]: struct.String.html#method.splice
+/// [`String`]: struct.String.html
+#[derive(Debug)]
+#[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+pub struct Splice<'a, 'b> {
+ /// Will be used as &'a mut String in the destructor
+ string: *mut String,
+ /// Start of part to remove
+ start: usize,
+ /// End of part to remove
+ end: usize,
+ /// Current remaining range to remove
+ iter: Chars<'a>,
+ replace_with: &'b str,
+}
+
+#[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+unsafe impl<'a, 'b> Sync for Splice<'a, 'b> {}
+#[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+unsafe impl<'a, 'b> Send for Splice<'a, 'b> {}
+
+#[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+impl<'a, 'b> Drop for Splice<'a, 'b> {
+ fn drop(&mut self) {
+ unsafe {
+ let vec = (*self.string).as_mut_vec();
+ vec.splice(self.start..self.end, self.replace_with.bytes());
+ }
+ }
+}
+
+#[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+impl<'a, 'b> Iterator for Splice<'a, 'b> {
+ type Item = char;
+
+ #[inline]
+ fn next(&mut self) -> Option<char> {
+ self.iter.next()
+ }
+
+ fn size_hint(&self) -> (usize, Option<usize>) {
+ self.iter.size_hint()
+ }
+}
+
+#[unstable(feature = "splice", reason = "recently added", issue = "32310")]
+impl<'a, 'b> DoubleEndedIterator for Splice<'a, 'b> {
+ #[inline]
+ fn next_back(&mut self) -> Option<char> {
+ self.iter.next_back()
+ }
+}