bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Rollup merge of #23664 - bluss:std-docs, r=steveklabnik

Browse source 
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.
This commit is contained in:
Manish Goregaokar 2015-03-25 17:12:13 +05:30
commit 5535767228
5 changed files with 57 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

74
src/libcollections/slice.rs
View file

@ -13,25 +13,23 @@
//! The `slice` module contains useful code to help work with slice values. //! The `slice` module contains useful code to help work with slice values.
//! Slices are a view into a block of memory represented as a pointer and a length. //! Slices are a view into a block of memory represented as a pointer and a length.
//! //!
//! ```rust //! ```
//! # #![feature(core)]
//! // slicing a Vec //! // slicing a Vec
//! let vec = vec!(1, 2, 3); //! let vec = vec![1, 2, 3];
//! let int_slice = vec.as_slice(); //! let int_slice = &vec[..];
//! // coercing an array to a slice //! // coercing an array to a slice
//! let str_slice: &[&str] = &["one", "two", "three"]; //! let str_slice: &[&str] = &["one", "two", "three"];
//! ``` //! ```
//! //!
//! Slices are either mutable or shared. The shared slice type is `&[T]`, //! Slices are either mutable or shared. The shared slice type is `&[T]`,
//! while the mutable slice type is `&mut[T]`. For example, you can mutate the //! while the mutable slice type is `&mut [T]`, where `T` represents the element
//! block of memory that a mutable slice points to: //! type. For example, you can mutate the block of memory that a mutable slice
//! points to:
//! //!
//! ```rust //! ```
//! let x: &mut[i32] = &mut [1, 2, 3]; //! let x = &mut [1, 2, 3];
//! x[1] = 7; //! x[1] = 7;
//! assert_eq!(x[0], 1); //! assert_eq!(x, &[1, 7, 3]);
//! assert_eq!(x[1], 7);
//! assert_eq!(x[2], 3);
//! ``` //! ```
//! //!
//! Here are some of the things this module contains: //! Here are some of the things this module contains:
@ -41,49 +39,43 @@
//! There are several structs that are useful for slices, such as `Iter`, which //! There are several structs that are useful for slices, such as `Iter`, which
//! represents iteration over a slice. //! represents iteration over a slice.
//! //!
//! ## Traits //! ## Trait Implementations
//!
//! A number of traits add methods that allow you to accomplish tasks
//! with slices, the most important being `SliceExt`. Other traits
//! apply only to slices of elements satisfying certain bounds (like
//! `Ord`).
//!
//! An example is the `slice` method which enables slicing syntax `[a..b]` that
//! returns an immutable "view" into a `Vec` or another slice from the index
//! interval `[a, b)`:
//!
//! ```rust
//! fn main() {
//! let numbers = [0, 1, 2];
//! let last_numbers = &numbers[1..3];
//! // last_numbers is now &[1, 2]
//! }
//! ```
//!
//! ## Implementations of other traits
//! //!
//! There are several implementations of common traits for slices. Some examples //! There are several implementations of common traits for slices. Some examples
//! include: //! include:
//! //!
//! * `Clone` //! * `Clone`
//! * `Eq`, `Ord` - for immutable slices whose element type are `Eq` or `Ord`. //! * `Eq`, `Ord` - for slices whose element type are `Eq` or `Ord`.
//! * `Hash` - for slices whose element type is `Hash` //! * `Hash` - for slices whose element type is `Hash`
//! //!
//! ## Iteration //! ## Iteration
//! //!
//! The method `iter()` returns an iteration value for a slice. The iterator //! The slices implement `IntoIterator`. The iterators of yield references
//! yields references to the slice's elements, so if the element //! to the slice elements.
//! type of the slice is `isize`, the element type of the iterator is `&isize`.
//! //!
//! ```rust //! ```
//! let numbers = [0, 1, 2]; //! let numbers = &[0, 1, 2];
//! for &x in numbers.iter() { //! for n in numbers {
//! println!("{} is a number!", x); //! println!("{} is a number!", n);
//! } //! }
//! ``` //! ```
//! //!
//! * `.iter_mut()` returns an iterator that allows modifying each value. //! The mutable slice yields mutable references to the elements:
//! * Further iterators exist that split, chunk or permute the slice. //!
//! ```
//! let mut scores = [7, 8, 9];
//! for score in &mut scores[..] {
//! *score += 1;
//! }
//! ```
//!
//! This iterator yields mutable references to the slice's elements, so while the element
//! type of the slice is `i32`, the element type of the iterator is `&mut i32`.
//!
//! * `.iter()` and `.iter_mut()` are the explicit methods to return the default
//! iterators.
//! * Further methods that return iterators are `.split()`, `.splitn()`,
//! `.chunks()`, `.windows()` and more.
#![doc(primitive = "slice")] #![doc(primitive = "slice")]
#![stable(feature = "rust1", since = "1.0.0")] #![stable(feature = "rust1", since = "1.0.0")]

2
src/libcollections/str.rs
View file

@ -19,7 +19,7 @@
//! are owned elsewhere. //! are owned elsewhere.
//! //!
//! Basic operations are implemented directly by the compiler, but more advanced //! Basic operations are implemented directly by the compiler, but more advanced
//! operations are defined on the [`StrExt`](trait.StrExt.html) trait. //! operations are defined as methods on the `str` type.
//! //!
//! # Examples //! # Examples
//! //!

15
src/libcore/str/mod.rs
View file

@ -165,8 +165,7 @@ impl FromStr for bool {
/// assert!(<bool as FromStr>::from_str("not even a boolean").is_err()); /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
/// ``` /// ```
/// ///
/// Note, in many cases, the StrExt::parse() which is based on /// Note, in many cases, the `.parse()` method on `str` is more proper.
/// this FromStr::from_str() is more proper.
/// ///
/// ``` /// ```
/// assert_eq!("true".parse(), Ok(true)); /// assert_eq!("true".parse(), Ok(true));
@ -531,7 +530,7 @@ impl<'a> DoubleEndedIterator for CharIndices<'a> {
/// External iterator for a string's bytes. /// External iterator for a string's bytes.
/// Use with the `std::iter` module. /// Use with the `std::iter` module.
/// ///
/// Created with `StrExt::bytes` /// Created with `str::bytes`
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
#[derive(Clone)] #[derive(Clone)]
pub struct Bytes<'a>(Map<slice::Iter<'a, u8>, BytesDeref>); 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 {
fn as_slice(&self) -> &str { Str::as_slice(*self) } fn as_slice(&self) -> &str { Str::as_slice(*self) }
} }
/// Return type of `StrExt::split` /// Return type of `str::split`
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Split<'a, P: Pattern<'a>>(CharSplits<'a, P>); pub struct Split<'a, P: Pattern<'a>>(CharSplits<'a, P>);
delegate_iter!{pattern &'a str : Split<'a, P>} delegate_iter!{pattern &'a str : Split<'a, P>}
/// Return type of `StrExt::split_terminator` /// Return type of `str::split_terminator`
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct SplitTerminator<'a, P: Pattern<'a>>(CharSplits<'a, P>); pub struct SplitTerminator<'a, P: Pattern<'a>>(CharSplits<'a, P>);
delegate_iter!{pattern &'a str : SplitTerminator<'a, P>} delegate_iter!{pattern &'a str : SplitTerminator<'a, P>}
/// Return type of `StrExt::splitn` /// Return type of `str::splitn`
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct SplitN<'a, P: Pattern<'a>>(CharSplitsN<'a, P>); pub struct SplitN<'a, P: Pattern<'a>>(CharSplitsN<'a, P>);
delegate_iter!{pattern forward &'a str : SplitN<'a, P>} delegate_iter!{pattern forward &'a str : SplitN<'a, P>}
/// Return type of `StrExt::rsplit` /// Return type of `str::rsplit`
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct RSplit<'a, P: Pattern<'a>>(RCharSplits<'a, P>); pub struct RSplit<'a, P: Pattern<'a>>(RCharSplits<'a, P>);
delegate_iter!{pattern reverse &'a str : RSplit<'a, P>} delegate_iter!{pattern reverse &'a str : RSplit<'a, P>}
/// Return type of `StrExt::rsplitn` /// Return type of `str::rsplitn`
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct RSplitN<'a, P: Pattern<'a>>(RCharSplitsN<'a, P>); pub struct RSplitN<'a, P: Pattern<'a>>(RCharSplitsN<'a, P>);
delegate_iter!{pattern reverse &'a str : RSplitN<'a, P>} delegate_iter!{pattern reverse &'a str : RSplitN<'a, P>}

30
src/libstd/io/mod.rs
View file

@ -631,14 +631,14 @@ pub trait BufRead: Read {
/// A `Write` adaptor which will write data to multiple locations. /// A `Write` adaptor which will write data to multiple locations.
/// ///
/// For more information, see `WriteExt::broadcast`. /// For more information, see `Write::broadcast`.
#[unstable(feature = "io", reason = "awaiting stability of WriteExt::broadcast")] #[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
pub struct Broadcast<T, U> { pub struct Broadcast<T, U> {
first: T, first: T,
second: U, second: U,
} }
#[unstable(feature = "io", reason = "awaiting stability of WriteExt::broadcast")] #[unstable(feature = "io", reason = "awaiting stability of Write::broadcast")]
impl<T: Write, U: Write> Write for Broadcast<T, U> { impl<T: Write, U: Write> Write for Broadcast<T, U> {
fn write(&mut self, data: &[u8]) -> Result<usize> { fn write(&mut self, data: &[u8]) -> Result<usize> {
let n = try!(self.first.write(data)); let n = try!(self.first.write(data));
@ -654,7 +654,7 @@ impl<T: Write, U: Write> Write for Broadcast<T, U> {
/// Adaptor to chain together two instances of `Read`. /// Adaptor to chain together two instances of `Read`.
/// ///
/// For more information, see `ReadExt::chain`. /// For more information, see `Read::chain`.
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Chain<T, U> { pub struct Chain<T, U> {
first: T, first: T,
@ -677,7 +677,7 @@ impl<T: Read, U: Read> Read for Chain<T, U> {
/// Reader adaptor which limits the bytes read from an underlying reader. /// Reader adaptor which limits the bytes read from an underlying reader.
/// ///
/// For more information, see `ReadExt::take`. /// For more information, see `Read::take`.
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Take<T> { pub struct Take<T> {
inner: T, inner: T,
@ -730,14 +730,14 @@ impl<T: BufRead> BufRead for Take<T> {
/// An adaptor which will emit all read data to a specified writer as well. /// An adaptor which will emit all read data to a specified writer as well.
/// ///
/// For more information see `ReadExt::tee` /// For more information see `Read::tee`
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::tee")] #[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
pub struct Tee<R, W> { pub struct Tee<R, W> {
reader: R, reader: R,
writer: W, writer: W,
} }
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::tee")] #[unstable(feature = "io", reason = "awaiting stability of Read::tee")]
impl<R: Read, W: Write> Read for Tee<R, W> { impl<R: Read, W: Write> Read for Tee<R, W> {
fn read(&mut self, buf: &mut [u8]) -> Result<usize> { fn read(&mut self, buf: &mut [u8]) -> Result<usize> {
let n = try!(self.reader.read(buf)); let n = try!(self.reader.read(buf));
@ -749,7 +749,7 @@ impl<R: Read, W: Write> Read for Tee<R, W> {
/// A bridge from implementations of `Read` to an `Iterator` of `u8`. /// A bridge from implementations of `Read` to an `Iterator` of `u8`.
/// ///
/// See `ReadExt::bytes` for more information. /// See `Read::bytes` for more information.
#[stable(feature = "rust1", since = "1.0.0")] #[stable(feature = "rust1", since = "1.0.0")]
pub struct Bytes<R> { pub struct Bytes<R> {
inner: R, inner: R,
@ -771,8 +771,8 @@ impl<R: Read> Iterator for Bytes<R> {
/// A bridge from implementations of `Read` to an `Iterator` of `char`. /// A bridge from implementations of `Read` to an `Iterator` of `char`.
/// ///
/// See `ReadExt::chars` for more information. /// See `Read::chars` for more information.
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")] #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
pub struct Chars<R> { pub struct Chars<R> {
inner: R, inner: R,
} }
@ -780,7 +780,7 @@ pub struct Chars<R> {
/// An enumeration of possible errors that can be generated from the `Chars` /// An enumeration of possible errors that can be generated from the `Chars`
/// adapter. /// adapter.
#[derive(PartialEq, Clone, Debug)] #[derive(PartialEq, Clone, Debug)]
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")] #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
pub enum CharsError { pub enum CharsError {
/// Variant representing that the underlying stream was read successfully /// Variant representing that the underlying stream was read successfully
/// but it did not contain valid utf8 data. /// but it did not contain valid utf8 data.
@ -790,7 +790,7 @@ pub enum CharsError {
Other(Error), Other(Error),
} }
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")] #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
impl<R: Read> Iterator for Chars<R> { impl<R: Read> Iterator for Chars<R> {
type Item = result::Result<char, CharsError>; type Item = result::Result<char, CharsError>;
@ -822,7 +822,7 @@ impl<R: Read> Iterator for Chars<R> {
} }
} }
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")] #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
impl std_error::Error for CharsError { impl std_error::Error for CharsError {
fn description(&self) -> &str { fn description(&self) -> &str {
match *self { match *self {
@ -838,7 +838,7 @@ impl std_error::Error for CharsError {
} }
} }
#[unstable(feature = "io", reason = "awaiting stability of ReadExt::chars")] #[unstable(feature = "io", reason = "awaiting stability of Read::chars")]
impl fmt::Display for CharsError { impl fmt::Display for CharsError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match *self { match *self {

2
src/libstd/io/prelude.rs
View file

@ -18,7 +18,7 @@
//! ``` //! ```
//! //!
//! This module contains reexports of many core I/O traits such as `Read`, //! This module contains reexports of many core I/O traits such as `Read`,
//! `Write`, `ReadExt`, and `WriteExt`. Structures and functions are not //! `Write` and `BufRead`. Structures and functions are not
//! contained in this module. //! contained in this module.
#![stable(feature = "rust1", since = "1.0.0")] #![stable(feature = "rust1", since = "1.0.0")]