diff options
| -rw-r--r-- | src/doc/book/patterns.md | 27 | ||||
| -rw-r--r-- | src/libcollections/btree/map.rs | 4 | ||||
| -rw-r--r-- | src/libcollections/btree/set.rs | 2 | ||||
| -rw-r--r-- | src/libcore/macros.rs | 13 | ||||
| -rw-r--r-- | src/libstd/env.rs | 20 | ||||
| -rw-r--r-- | src/libstd/sys/unix/ext/ffi.rs | 60 |
6 files changed, 111 insertions, 15 deletions
diff --git a/src/doc/book/patterns.md b/src/doc/book/patterns.md index b50fa01b8e2..24f71608a5b 100644 --- a/src/doc/book/patterns.md +++ b/src/doc/book/patterns.md @@ -23,6 +23,33 @@ match x { This prints `one`. +It's possible to create a binding for the value in the any case: + +```rust +let x = 1; + +match x { + y => println!("x: {} y: {}", x, y), +} +``` + +This prints: + +```text +x: 1 y: 1 +``` + +Note it is an error to have both a catch-all `_` and a catch-all binding in the same match block: + +```rust +let x = 1; + +match x { + y => println!("x: {} y: {}", x, y), + _ => println!("anything"), // this causes an error as it is unreachable +} +``` + There’s one pitfall with patterns: like anything that introduces a new binding, they introduce shadowing. For example: diff --git a/src/libcollections/btree/map.rs b/src/libcollections/btree/map.rs index 782a5e31d2d..4755f8a4c55 100644 --- a/src/libcollections/btree/map.rs +++ b/src/libcollections/btree/map.rs @@ -656,7 +656,7 @@ impl<K: Ord, V> BTreeMap<K, V> { } /// Constructs a double-ended iterator over a sub-range of elements in the map. - /// The simplest way is to use the range synax `min..max`, thus `range(min..max)` will + /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will /// yield elements from min (inclusive) to max (exclusive). /// The range may also be entered as `(Bound<T>, Bound<T>)`, so for example /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive @@ -748,7 +748,7 @@ impl<K: Ord, V> BTreeMap<K, V> { } /// Constructs a mutable double-ended iterator over a sub-range of elements in the map. - /// The simplest way is to use the range synax `min..max`, thus `range(min..max)` will + /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will /// yield elements from min (inclusive) to max (exclusive). /// The range may also be entered as `(Bound<T>, Bound<T>)`, so for example /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs index f472b593b67..f006ba95371 100644 --- a/src/libcollections/btree/set.rs +++ b/src/libcollections/btree/set.rs @@ -208,7 +208,7 @@ impl<T> BTreeSet<T> { impl<T: Ord> BTreeSet<T> { /// Constructs a double-ended iterator over a sub-range of elements in the set. - /// The simplest way is to use the range synax `min..max`, thus `range(min..max)` will + /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will /// yield elements from min (inclusive) to max (exclusive). /// The range may also be entered as `(Bound<T>, Bound<T>)`, so for example /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index ba52edb1ae8..bc5392f6b88 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -45,7 +45,8 @@ macro_rules! panic { /// Other use-cases of `assert!` include [testing] and enforcing run-time /// invariants in safe code (whose violation cannot result in unsafety). /// -/// This macro has a second version, where a custom panic message can be provided. +/// This macro has a second version, where a custom panic message can +/// be provided with or without arguments for formatting. /// /// [testing]: ../book/testing.html /// @@ -87,12 +88,17 @@ macro_rules! assert { /// On panic, this macro will print the values of the expressions with their /// debug representations. /// +/// Like `assert!()`, this macro has a second version, where a custom +/// panic message can be provided. +/// /// # Examples /// /// ``` /// let a = 3; /// let b = 1 + 2; /// assert_eq!(a, b); +/// +/// assert_eq!(a, b, "we are testing addition with {} and {}", a, b); /// ``` #[macro_export] #[stable(feature = "rust1", since = "1.0.0")] @@ -125,12 +131,17 @@ macro_rules! assert_eq { /// On panic, this macro will print the values of the expressions with their /// debug representations. /// +/// Like `assert!()`, this macro has a second version, where a custom +/// panic message can be provided. +/// /// # Examples /// /// ``` /// let a = 3; /// let b = 2; /// assert_ne!(a, b); +/// +/// assert_ne!(a, b, "we are testing that the values are not equal"); /// ``` #[macro_export] #[stable(feature = "assert_ne", since = "1.12.0")] diff --git a/src/libstd/env.rs b/src/libstd/env.rs index d843d97420a..ae83312ec94 100644 --- a/src/libstd/env.rs +++ b/src/libstd/env.rs @@ -10,7 +10,7 @@ //! Inspection and manipulation of the process's environment. //! -//! This module contains methods to inspect various aspects such as +//! This module contains functions to inspect various aspects such as //! environment variables, process arguments, the current directory, and various //! other important directories. @@ -68,15 +68,17 @@ pub fn set_current_dir<P: AsRef<Path>>(p: P) -> io::Result<()> { /// An iterator over a snapshot of the environment variables of this process. /// -/// This iterator is created through `std::env::vars()` and yields `(String, -/// String)` pairs. +/// This structure is created through the [`std::env::vars`] function. +/// +/// [`std::env::vars`]: fn.vars.html #[stable(feature = "env", since = "1.0.0")] pub struct Vars { inner: VarsOs } /// An iterator over a snapshot of the environment variables of this process. /// -/// This iterator is created through `std::env::vars_os()` and yields -/// `(OsString, OsString)` pairs. +/// This structure is created through the [`std::env::vars_os`] function. +/// +/// [`std::env::vars_os`]: fn.vars_os.html #[stable(feature = "env", since = "1.0.0")] pub struct VarsOs { inner: os_imp::Env } @@ -218,7 +220,9 @@ fn _var_os(key: &OsStr) -> Option<OsString> { }) } -/// Possible errors from the `env::var` method. +/// Possible errors from the [`env::var`] function. +/// +/// [env::var]: fn.var.html #[derive(Debug, PartialEq, Eq, Clone)] #[stable(feature = "env", since = "1.0.0")] pub enum VarError { @@ -570,7 +574,7 @@ pub fn current_exe() -> io::Result<PathBuf> { /// An iterator over the arguments of a process, yielding a [`String`] value /// for each argument. /// -/// This structure is created through the [`std::env::args`] method. +/// This structure is created through the [`std::env::args`] function. /// /// [`String`]: ../string/struct.String.html /// [`std::env::args`]: ./fn.args.html @@ -580,7 +584,7 @@ pub struct Args { inner: ArgsOs } /// An iterator over the arguments of a process, yielding an [`OsString`] value /// for each argument. /// -/// This structure is created through the [`std::env::args_os`] method. +/// This structure is created through the [`std::env::args_os`] function. /// /// [`OsString`]: ../ffi/struct.OsString.html /// [`std::env::args_os`]: ./fn.args_os.html diff --git a/src/libstd/sys/unix/ext/ffi.rs b/src/libstd/sys/unix/ext/ffi.rs index d59b4fc0b70..fb9984ccbdd 100644 --- a/src/libstd/sys/unix/ext/ffi.rs +++ b/src/libstd/sys/unix/ext/ffi.rs @@ -20,11 +20,38 @@ use sys_common::{FromInner, IntoInner, AsInner}; /// Unix-specific extensions to `OsString`. #[stable(feature = "rust1", since = "1.0.0")] pub trait OsStringExt { - /// Creates an `OsString` from a byte vector. + /// Creates an [`OsString`] from a byte vector. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsString; + /// use std::os::unix::ffi::OsStringExt; + /// + /// let bytes = b"foo".to_vec(); + /// let os_string = OsString::from_vec(bytes); + /// assert_eq!(os_string.to_str(), Some("foo")); + /// ``` + /// + /// [`OsString`]: ../../../ffi/struct.OsString.html #[stable(feature = "rust1", since = "1.0.0")] fn from_vec(vec: Vec<u8>) -> Self; - /// Yields the underlying byte vector of this `OsString`. + /// Yields the underlying byte vector of this [`OsString`]. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsString; + /// use std::os::unix::ffi::OsStringExt; + /// + /// let mut os_string = OsString::new(); + /// os_string.push("foo"); + /// let bytes = os_string.into_vec(); + /// assert_eq!(bytes, b"foo"); + /// ``` + /// + /// [`OsString`]: ../../../ffi/struct.OsString.html #[stable(feature = "rust1", since = "1.0.0")] fn into_vec(self) -> Vec<u8>; } @@ -43,9 +70,36 @@ impl OsStringExt for OsString { #[stable(feature = "rust1", since = "1.0.0")] pub trait OsStrExt { #[stable(feature = "rust1", since = "1.0.0")] + /// Creates an [`OsStr`] from a byte slice. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsStr; + /// use std::os::unix::ffi::OsStrExt; + /// + /// let bytes = b"foo"; + /// let os_str = OsStr::from_bytes(bytes); + /// assert_eq!(os_str.to_str(), Some("foo")); + /// ``` + /// + /// [`OsStr`]: ../../../ffi/struct.OsStr.html fn from_bytes(slice: &[u8]) -> &Self; - /// Gets the underlying byte view of the `OsStr` slice. + /// Gets the underlying byte view of the [`OsStr`] slice. + /// + /// # Examples + /// + /// ``` + /// use std::ffi::OsStr; + /// use std::os::unix::ffi::OsStrExt; + /// + /// let mut os_str = OsStr::new("foo"); + /// let bytes = os_str.as_bytes(); + /// assert_eq!(bytes, b"foo"); + /// ``` + /// + /// [`OsStr`]: ../../../ffi/struct.OsStr.html #[stable(feature = "rust1", since = "1.0.0")] fn as_bytes(&self) -> &[u8]; } |