Skip to content

Commit 5535767

Browse files
committed
Rollup merge of rust-lang#23664 - bluss:std-docs, r=steveklabnik
Main motivation was to update docs for the removal or "demotion" of certain extension traits. The update to the slice docs was larger, since the text was largely outdated.
2 parents b6783e6 + 547a48e commit 5535767

File tree

5 files changed

+57
-66
lines changed

5 files changed

+57
-66
lines changed

src/libcollections/slice.rs

Lines changed: 33 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -13,25 +13,23 @@
1313
//! The `slice` module contains useful code to help work with slice values.
1414
//! Slices are a view into a block of memory represented as a pointer and a length.
1515
//!
16-
//! ```rust
17-
//! # #![feature(core)]
16+
//! ```
1817
//! // slicing a Vec
19-
//! let vec = vec!(1, 2, 3);
20-
//! let int_slice = vec.as_slice();
18+
//! let vec = vec![1, 2, 3];
19+
//! let int_slice = &vec[..];
2120
//! // coercing an array to a slice
2221
//! let str_slice: &[&str] = &["one", "two", "three"];
2322
//! ```
2423
//!
2524
//! Slices are either mutable or shared. The shared slice type is `&[T]`,
26-
//! while the mutable slice type is `&mut[T]`. For example, you can mutate the
27-
//! block of memory that a mutable slice points to:
25+
//! while the mutable slice type is `&mut [T]`, where `T` represents the element
26+
//! type. For example, you can mutate the block of memory that a mutable slice
27+
//! points to:
2828
//!
29-
//! ```rust
30-
//! let x: &mut[i32] = &mut [1, 2, 3];
29+
//! ```
30+
//! let x = &mut [1, 2, 3];
3131
//! x[1] = 7;
32-
//! assert_eq!(x[0], 1);
33-
//! assert_eq!(x[1], 7);
34-
//! assert_eq!(x[2], 3);
32+
//! assert_eq!(x, &[1, 7, 3]);
3533
//! ```
3634
//!
3735
//! Here are some of the things this module contains:
@@ -41,49 +39,43 @@
4139
//! There are several structs that are useful for slices, such as `Iter`, which
4240
//! represents iteration over a slice.
4341
//!
44-
//! ## Traits
45-
//!
46-
//! A number of traits add methods that allow you to accomplish tasks
47-
//! with slices, the most important being `SliceExt`. Other traits
48-
//! apply only to slices of elements satisfying certain bounds (like
49-
//! `Ord`).
50-
//!
51-
//! An example is the `slice` method which enables slicing syntax `[a..b]` that
52-
//! returns an immutable "view" into a `Vec` or another slice from the index
53-
//! interval `[a, b)`:
54-
//!
55-
//! ```rust
56-
//! fn main() {
57-
//! let numbers = [0, 1, 2];
58-
//! let last_numbers = &numbers[1..3];
59-
//! // last_numbers is now &[1, 2]
60-
//! }
61-
//! ```
62-
//!
63-
//! ## Implementations of other traits
42+
//! ## Trait Implementations
6443
//!
6544
//! There are several implementations of common traits for slices. Some examples
6645
//! include:
6746
//!
6847
//! * `Clone`
69-
//! * `Eq`, `Ord` - for immutable slices whose element type are `Eq` or `Ord`.
48+
//! * `Eq`, `Ord` - for slices whose element type are `Eq` or `Ord`.
7049
//! * `Hash` - for slices whose element type is `Hash`
7150
//!
7251
//! ## Iteration
7352
//!
74-
//! The method `iter()` returns an iteration value for a slice. The iterator
75-
//! yields references to the slice's elements, so if the element
76-
//! type of the slice is `isize`, the element type of the iterator is `&isize`.
53+
//! The slices implement `IntoIterator`. The iterators of yield references
54+
//! to the slice elements.
7755
//!
78-
//! ```rust
79-
//! let numbers = [0, 1, 2];
80-
//! for &x in numbers.iter() {
81-
//! println!("{} is a number!", x);
56+
//! ```
57+
//! let numbers = &[0, 1, 2];
58+
//! for n in numbers {
59+
//! println!("{} is a number!", n);
8260
//! }
8361
//! ```
8462
//!
85-
//! * `.iter_mut()` returns an iterator that allows modifying each value.
86-
//! * Further iterators exist that split, chunk or permute the slice.
63+
//! The mutable slice yields mutable references to the elements:
64+
//!
65+
//! ```
66+
//! let mut scores = [7, 8, 9];
67+
//! for score in &mut scores[..] {
68+
//! *score += 1;
69+
//! }
70+
//! ```
71+
//!
72+
//! This iterator yields mutable references to the slice's elements, so while the element
73+
//! type of the slice is `i32`, the element type of the iterator is `&mut i32`.
74+
//!
75+
//! * `.iter()` and `.iter_mut()` are the explicit methods to return the default
76+
//! iterators.
77+
//! * Further methods that return iterators are `.split()`, `.splitn()`,
78+
//! `.chunks()`, `.windows()` and more.
8779
8880
#![doc(primitive = "slice")]
8981
#![stable(feature = "rust1", since = "1.0.0")]

src/libcollections/str.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
//! are owned elsewhere.
2020
//!
2121
//! Basic operations are implemented directly by the compiler, but more advanced
22-
//! operations are defined on the [`StrExt`](trait.StrExt.html) trait.
22+
//! operations are defined as methods on the `str` type.
2323
//!
2424
//! # Examples
2525
//!

src/libcore/str/mod.rs

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,7 @@ impl FromStr for bool {
165165
/// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
166166
/// ```
167167
///
168-
/// Note, in many cases, the StrExt::parse() which is based on
169-
/// this FromStr::from_str() is more proper.
168+
/// Note, in many cases, the `.parse()` method on `str` is more proper.
170169
///
171170
/// ```
172171
/// assert_eq!("true".parse(), Ok(true));
@@ -531,7 +530,7 @@ impl<'a> DoubleEndedIterator for CharIndices<'a> {
531530
/// External iterator for a string's bytes.
532531
/// Use with the `std::iter` module.
533532
///
534-
/// Created with `StrExt::bytes`
533+
/// Created with `str::bytes`
535534
#[stable(feature = "rust1", since = "1.0.0")]
536535
#[derive(Clone)]
537536
pub struct Bytes<'a>(Map<slice::Iter<'a, u8>, BytesDeref>);
@@ -1489,27 +1488,27 @@ impl<'a, S: ?Sized> Str for &'a S where S: Str {
14891488
fn as_slice(&self) -> &str { Str::as_slice(*self) }
14901489
}
14911490

1492-
/// Return type of `StrExt::split`
1491+
/// Return type of `str::split`
14931492
#[stable(feature = "rust1", since = "1.0.0")]
14941493
pub struct Split<'a, P: Pattern<'a>>(CharSplits<'a, P>);
14951494
delegate_iter!{pattern &'a str : Split<'a, P>}
14961495

1497-
/// Return type of `StrExt::split_terminator`
1496+
/// Return type of `str::split_terminator`
14981497
#[stable(feature = "rust1", since = "1.0.0")]
14991498
pub struct SplitTerminator<'a, P: Pattern<'a>>(CharSplits<'a, P>);
15001499
delegate_iter!{pattern &'a str : SplitTerminator<'a, P>}
15011500

1502-
/// Return type of `StrExt::splitn`
1501+
/// Return type of `str::splitn`
15031502
#[stable(feature = "rust1", since = "1.0.0")]
15041503
pub struct SplitN<'a, P: Pattern<'a>>(CharSplitsN<'a, P>);
15051504
delegate_iter!{pattern forward &'a str : SplitN<'a, P>}
15061505

1507-
/// Return type of `StrExt::rsplit`
1506+
/// Return type of `str::rsplit`
15081507
#[stable(feature = "rust1", since = "1.0.0")]
15091508
pub struct RSplit<'a, P: Pattern<'a>>(RCharSplits<'a, P>);
15101509
delegate_iter!{pattern reverse &'a str : RSplit<'a, P>}
15111510

1512-
/// Return type of `StrExt::rsplitn`
1511+
/// Return type of `str::rsplitn`
15131512
#[stable(feature = "rust1", since = "1.0.0")]
15141513
pub struct RSplitN<'a, P: Pattern<'a>>(RCharSplitsN<'a, P>);
15151514
delegate_iter!{pattern reverse &'a str : RSplitN<'a, P>}

src/libstd/io/mod.rs

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -631,14 +631,14 @@ pub trait BufRead: Read {
631631

632632
/// A `Write` adaptor which will write data to multiple locations.
633633
///
634-
/// For more information, see `WriteExt::broadcast`.
635-
#[unstable(feature = "io", reason = "awaiting stability of WriteExt::broadcast")]
634+
/// For more information, see `Write::broadcast`.
635+
#[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
636636
pub struct Broadcast<T, U> {
637637
first: T,
638638
second: U,
639639
}
640640

641-
#[unstable(feature = "io", reason = "awaiting stability of WriteExt::broadcast")]
641+
#[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
642642
impl<T: Write, U: Write> Write for Broadcast<T, U> {
643643
fn write(&mut self, data: &[u8]) -> Result<usize> {
644644
let n = try!(self.first.write(data));
@@ -654,7 +654,7 @@ impl<T: Write, U: Write> Write for Broadcast<T, U> {
654654

655655
/// Adaptor to chain together two instances of `Read`.
656656
///
657-
/// For more information, see `ReadExt::chain`.
657+
/// For more information, see `Read::chain`.
658658
#[stable(feature = "rust1", since = "1.0.0")]
659659
pub struct Chain<T, U> {
660660
first: T,
@@ -677,7 +677,7 @@ impl<T: Read, U: Read> Read for Chain<T, U> {
677677

678678
/// Reader adaptor which limits the bytes read from an underlying reader.
679679
///
680-
/// For more information, see `ReadExt::take`.
680+
/// For more information, see `Read::take`.
681681
#[stable(feature = "rust1", since = "1.0.0")]
682682
pub struct Take<T> {
683683
inner: T,
@@ -730,14 +730,14 @@ impl<T: BufRead> BufRead for Take<T> {
730730

731731
/// An adaptor which will emit all read data to a specified writer as well.
732732
///
733-
/// For more information see `ReadExt::tee`
734-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::tee")]
733+
/// For more information see `Read::tee`
734+
#[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
735735
pub struct Tee<R, W> {
736736
reader: R,
737737
writer: W,
738738
}
739739

740-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::tee")]
740+
#[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
741741
impl<R: Read, W: Write> Read for Tee<R, W> {
742742
fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
743743
let n = try!(self.reader.read(buf));
@@ -749,7 +749,7 @@ impl<R: Read, W: Write> Read for Tee<R, W> {
749749

750750
/// A bridge from implementations of `Read` to an `Iterator` of `u8`.
751751
///
752-
/// See `ReadExt::bytes` for more information.
752+
/// See `Read::bytes` for more information.
753753
#[stable(feature = "rust1", since = "1.0.0")]
754754
pub struct Bytes<R> {
755755
inner: R,
@@ -771,16 +771,16 @@ impl<R: Read> Iterator for Bytes<R> {
771771

772772
/// A bridge from implementations of `Read` to an `Iterator` of `char`.
773773
///
774-
/// See `ReadExt::chars` for more information.
775-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
774+
/// See `Read::chars` for more information.
775+
#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
776776
pub struct Chars<R> {
777777
inner: R,
778778
}
779779

780780
/// An enumeration of possible errors that can be generated from the `Chars`
781781
/// adapter.
782782
#[derive(PartialEq, Clone, Debug)]
783-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
783+
#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
784784
pub enum CharsError {
785785
/// Variant representing that the underlying stream was read successfully
786786
/// but it did not contain valid utf8 data.
@@ -790,7 +790,7 @@ pub enum CharsError {
790790
Other(Error),
791791
}
792792

793-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
793+
#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
794794
impl<R: Read> Iterator for Chars<R> {
795795
type Item = result::Result<char, CharsError>;
796796

@@ -822,7 +822,7 @@ impl<R: Read> Iterator for Chars<R> {
822822
}
823823
}
824824

825-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
825+
#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
826826
impl std_error::Error for CharsError {
827827
fn description(&self) -> &str {
828828
match *self {
@@ -838,7 +838,7 @@ impl std_error::Error for CharsError {
838838
}
839839
}
840840

841-
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")]
841+
#[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
842842
impl fmt::Display for CharsError {
843843
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
844844
match *self {

src/libstd/io/prelude.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
//! ```
1919
//!
2020
//! This module contains reexports of many core I/O traits such as `Read`,
21-
//! `Write`, `ReadExt`, and `WriteExt`. Structures and functions are not
21+
//! `Write` and `BufRead`. Structures and functions are not
2222
//! contained in this module.
2323
2424
#![stable(feature = "rust1", since = "1.0.0")]

0 commit comments

Comments
 (0)