From 60067f6b6d01b78253718583f67799b13624dbd0 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Fri, 8 May 2015 15:15:03 -0700 Subject: std: Update crate docs Attempted to organize them in a way more relevant to what newbies would be interested in hearing. --- src/libstd/lib.rs | 98 +++++++++++++++++++++++------------------------ src/libstd/prelude/mod.rs | 2 +- src/libstd/prelude/v1.rs | 2 +- 3 files changed, 49 insertions(+), 53 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 7821ebede02..4c6af14a7bc 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -12,33 +12,35 @@ //! //! The Rust Standard Library provides the essential runtime //! functionality for building portable Rust software. -//! It is linked to all Rust crates by default. //! -//! ## Intrinsic types and operations +//! It is linked to all Rust crates by default as though they +//! contained a crate-level `extern crate std` crate import. Therefore +//! the standard library can be accessed in `use` statements through +//! the path `std`, as in `use std::thread`, or in expressions through +//! the absolute path `::std`, as in `::std::thread::sleep_ms(100)`. //! -//! The [`ptr`](ptr/index.html) and [`mem`](mem/index.html) -//! modules deal with unsafe pointers and memory manipulation. -//! [`marker`](marker/index.html) defines the special built-in traits, -//! and [`raw`](raw/index.html) the runtime representation of Rust types. -//! These are some of the lowest-level building blocks in Rust. +//! Furthermore, the standard library defines [The Rust +//! Prelude](prelude/index.html), a small collection of items, mostly +//! traits, that are imported into and available in every module. //! -//! ## Math on primitive types and math traits +//! ## What is in the standard library //! -//! Although basic operations on primitive types are implemented -//! directly by the compiler, the standard library additionally -//! defines many common operations through traits defined in -//! mod [`num`](num/index.html). +//! The standard library is minimal, a set of battle-tested +//! core types and shared abstractions for the [broader Rust +//! ecosystem][https://crates.io] to build on. //! -//! ## Pervasive types +//! The [primitive types](#primitives), though not defined in the +//! standard library, are documented here, as are the predefined +//! [macros](#macros). //! -//! The [`option`](option/index.html) and [`result`](result/index.html) -//! modules define optional and error-handling types, `Option` and `Result`. -//! [`iter`](iter/index.html) defines Rust's iterator protocol -//! along with a wide variety of iterators. -//! [`Cell` and `RefCell`](cell/index.html) are for creating types that -//! manage their own mutability. +//! ## Containers and collections //! -//! ## Vectors, slices and strings +//! The [`option`](option/index.html) and +//! [`result`](result/index.html) modules define optional and +//! error-handling types, `Option` and `Result`. The +//! [`iter`](iter/index.html) module defines Rust's iterator trait, +//! [`Iterater`](iter/trait.Iterator.html), which works with the `for` +//! loop to access collections. //! //! The common container type, `Vec`, a growable vector backed by an array, //! lives in the [`vec`](vec/index.html) module. Contiguous, unsized regions @@ -56,42 +58,36 @@ //! macro, and for converting from strings use the //! [`FromStr`](str/trait.FromStr.html) trait. //! -//! ## Platform abstractions +//! Data may be shared by placing it a reference-counted box, the +//! [`Rc`][rc/index.html] type, and if further contained in a [`Cell` +//! or `RefCell`](cell/index.html), may be mutated as well as shared. +//! Likewise, in a concurrent setting it is common to pair an +//! atomically-reference-counted box, [`Arc`](sync/struct.Arc.html), +//! with a [`Mutex`](sync/struct.Mutex.html) to get the same effect. //! -//! Besides basic data types, the standard library is largely concerned -//! with abstracting over differences in common platforms, most notably -//! Windows and Unix derivatives. The [`os`](os/index.html) module -//! provides a number of basic functions for interacting with the -//! operating environment, including program arguments, environment -//! variables, and directory navigation. The [`path`](path/index.html) -//! module encapsulates the platform-specific rules for dealing -//! with file paths. -//! -//! `std` also includes the [`ffi`](ffi/index.html) module for interoperating -//! with the C language. -//! -//! ## Concurrency, I/O, and the runtime +//! The [`collections`](collections/index.html) module defines maps, +//! sets, linked lists and other typical collection types, including +//! the common [`HashMap`](collections/struct.HashMap.html). //! -//! The [`thread`](thread/index.html) module contains Rust's threading abstractions. -//! [`sync`](sync/index.html) contains further, primitive, shared memory types, -//! including [`atomic`](sync/atomic/index.html), and [`mpsc`](sync/mpsc/index.html), -//! which contains the channel types for message passing. +//! ## Platform abstractions and I/O //! -//! Common types of I/O, including files, TCP, UDP, pipes, Unix domain sockets, and -//! process spawning, are defined in the [`io`](io/index.html) module. -//! -//! Rust's I/O and concurrency depends on a small runtime interface -//! that lives, along with its support code, in mod [`rt`](rt/index.html). -//! While a notable part of the standard library's architecture, this -//! module is not intended for public use. +//! Besides basic data types, the standard library is largely concerned +//! with abstracting over differences in common platforms, most notably +//! Windows and Unix derivatives. //! -//! ## The Rust prelude and macros +//! Common types of I/O, including [files](fs/struct.File.html), +//! [TCP](net/struct.TcpStream.html), +//! [UDP](net/struct.UdpSocket.html), are defined in the +//! [`io`](io/index.html), [`fs`](fs/index.html), and +//! [`net`](net/index.html) modulesu. //! -//! Finally, the [`prelude`](prelude/index.html) defines a -//! common set of traits, types, and functions that are made available -//! to all code by default. [`macros`](macros/index.html) contains -//! all the standard macros, such as `assert!`, `panic!`, `println!`, -//! and `format!`, also available to all Rust code. +//! The [`thread`](thread/index.html) module contains Rust's threading +//! abstractions. [`sync`](sync/index.html) contains further, +//! primitive, shared memory types, including +//! [`atomic`](sync/atomic/index.html), and +//! [`mpsc`](sync/mpsc/index.html), which contains the channel types +//! for message passing. + // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364) #![cfg_attr(stage0, feature(custom_attribute))] #![crate_name = "std"] diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs index 4a8cceb202f..156a3d428de 100644 --- a/src/libstd/prelude/mod.rs +++ b/src/libstd/prelude/mod.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The Rust prelude +//! The Rust Prelude //! //! Because `std` is required by most serious Rust software, it is //! imported at the topmost level of every crate by default, as if the diff --git a/src/libstd/prelude/v1.rs b/src/libstd/prelude/v1.rs index 6dc11c505a9..46c0103e087 100644 --- a/src/libstd/prelude/v1.rs +++ b/src/libstd/prelude/v1.rs @@ -8,7 +8,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! The first version of the prelude of the standard library. +//! The first version of the prelude of The Rust Standard Library. #![stable(feature = "rust1", since = "1.0.0")] -- cgit 1.4.1-3-g733a5 From 86a1165f846f4f370c80de39f8b0bc59ac1da787 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Tue, 12 May 2015 10:53:57 -0700 Subject: doc: Address feedback --- src/libstd/lib.rs | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 4c6af14a7bc..7bdff48a548 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -13,11 +13,12 @@ //! The Rust Standard Library provides the essential runtime //! functionality for building portable Rust software. //! -//! It is linked to all Rust crates by default as though they -//! contained a crate-level `extern crate std` crate import. Therefore -//! the standard library can be accessed in `use` statements through -//! the path `std`, as in `use std::thread`, or in expressions through -//! the absolute path `::std`, as in `::std::thread::sleep_ms(100)`. +//! The rust standard library is available to all rust crates by +//! default, just as if contained an `extern crate std` import at the +//! crate root. Therefore the standard library can be accessed in +//! `use` statements through the path `std`, as in `use std::thread`, +//! or in expressions through the absolute path `::std`, as in +//! `::std::thread::sleep_ms(100)`. //! //! Furthermore, the standard library defines [The Rust //! Prelude](prelude/index.html), a small collection of items, mostly @@ -58,7 +59,7 @@ //! macro, and for converting from strings use the //! [`FromStr`](str/trait.FromStr.html) trait. //! -//! Data may be shared by placing it a reference-counted box, the +//! Data may be shared by placing it in a reference-counted box or the //! [`Rc`][rc/index.html] type, and if further contained in a [`Cell` //! or `RefCell`](cell/index.html), may be mutated as well as shared. //! Likewise, in a concurrent setting it is common to pair an @@ -79,12 +80,12 @@ //! [TCP](net/struct.TcpStream.html), //! [UDP](net/struct.UdpSocket.html), are defined in the //! [`io`](io/index.html), [`fs`](fs/index.html), and -//! [`net`](net/index.html) modulesu. +//! [`net`](net/index.html) modules. //! //! The [`thread`](thread/index.html) module contains Rust's threading -//! abstractions. [`sync`](sync/index.html) contains further, -//! primitive, shared memory types, including -//! [`atomic`](sync/atomic/index.html), and +//! abstractions. [`sync`](sync/index.html) contains further +//! primitive shared memory types, including +//! [`atomic`](sync/atomic/index.html) and //! [`mpsc`](sync/mpsc/index.html), which contains the channel types //! for message passing. -- cgit 1.4.1-3-g733a5 From 6a3524ea2ee52a5aa5c4465f1cf9460dff4c4e04 Mon Sep 17 00:00:00 2001 From: Ulrik Sverdrup Date: Sat, 9 May 2015 13:27:23 +0200 Subject: std: Add example for HashMap::entry() --- src/libstd/collections/hash/map.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 65d32106342..f5da5f0bf69 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -917,6 +917,24 @@ impl HashMap } /// Gets the given key's corresponding entry in the map for in-place manipulation. + /// + /// # Examples + /// + /// ``` + /// use std::collections::HashMap; + /// + /// let mut letters = HashMap::new(); + /// + /// for ch in "a short treatise on fungi".chars() { + /// let counter = letters.entry(ch).or_insert(0); + /// *counter += 1; + /// } + /// + /// assert_eq!(letters[&'s'], 2); + /// assert_eq!(letters[&'t'], 3); + /// assert_eq!(letters[&'u'], 1); + /// assert_eq!(letters.get(&'y'), None); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn entry(&mut self, key: K) -> Entry { // Gotta resize now. -- cgit 1.4.1-3-g733a5 From 708ad645cf49339169e5c5966031821984cfc499 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 10 May 2015 16:32:18 -0400 Subject: Update docs to stop referencing `BufReadExt` --- src/libstd/io/mod.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 07b43b6c5db..209c052ae06 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -845,7 +845,7 @@ impl fmt::Display for CharsError { /// An iterator over the contents of an instance of `BufRead` split on a /// particular byte. /// -/// See `BufReadExt::split` for more information. +/// See `BufRead::split` for more information. #[stable(feature = "rust1", since = "1.0.0")] pub struct Split { buf: B, @@ -874,7 +874,7 @@ impl Iterator for Split { /// An iterator over the lines of an instance of `BufRead` split on a newline /// byte. /// -/// See `BufReadExt::lines` for more information. +/// See `BufRead::lines` for more information. #[stable(feature = "rust1", since = "1.0.0")] pub struct Lines { buf: B, -- cgit 1.4.1-3-g733a5