This brings comments in line with https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md#using-markdown
///
/// * `name` - The name of the person you'd like to greet.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// let name = "Steve";
/// An atomically reference counted wrapper for shared state.
///
-/// # Example
+/// # Examples
///
/// In this example, a large vector of floats is shared between several tasks.
/// With simple pipes, without `Arc`, a copy would have to be made for each
/// automatically managed that may lead to memory or other resource
/// leak.
///
-/// # Example
+/// # Examples
/// ```
/// use std::boxed;
///
///
/// If the `Rc<T>` is not unique, an `Err` is returned with the same `Rc<T>`.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::rc::{self, Rc};
///
/// Returns `None` if the `Rc<T>` is not unique.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::rc::{self, Rc};
/// is desired, `to_mut` will obtain a mutable references to an owned
/// value, cloning if necessary.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::borrow::Cow;
impl<K, V> BTreeMap<K, V> {
/// Gets an iterator over the entries of the map.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::BTreeMap;
///
/// * args - a structure of arguments generated via the `format_args!` macro.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::fmt;
/// Use the syntax described in `std::fmt` to create a value of type `String`.
/// See `std::fmt` for more information.
///
-/// # Example
+/// # Examples
///
/// ```
/// format!("test");
///
/// Panics if `size` is 0.
///
- /// # Example
+ /// # Examples
///
/// Print the adjacent pairs of a slice (i.e. `[1,2]`, `[2,3]`,
/// `[3,4]`):
///
/// Panics if `size` is 0.
///
- /// # Example
+ /// # Examples
///
/// Print the slice two elements at a time (i.e. `[1,2]`,
/// `[3,4]`, `[5]`):
/// `Err` is returned, containing the index where a matching
/// element could be inserted while maintaining sorted order.
///
- /// # Example
+ /// # Examples
///
/// Looks up a series of four elements. The first is found, with a
/// uniquely determined position; the second and third are not
/// Return the number of elements in the slice
///
- /// # Example
+ /// # Examples
///
/// ```
/// let a = [1, 2, 3];
/// Returns true if the slice has a length of 0
///
- /// # Example
+ /// # Examples
///
/// ```
/// let a = [1, 2, 3];
///
/// Panics if `a` or `b` are out of bounds.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let mut v = ["a", "b", "c", "d"];
///
/// Panics if `mid > len`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let mut v = [1, 2, 3, 4, 5, 6];
/// Reverse the order of elements in a slice, in place.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let mut v = [1, 2, 3];
/// shorter of `self.len()` and `src.len()`). Returns the number
/// of elements copied.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let mut dst = [0, 0, 0];
/// `Err` is returned, containing the index where a matching
/// element could be inserted while maintaining sorted order.
///
- /// # Example
+ /// # Examples
///
/// Looks up a series of four elements. The first is found, with a
/// uniquely determined position; the second and third are not
/// Returns `true` if successful and `false` if the slice is at the
/// last-ordered permutation.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let v: &mut [_] = &mut [0, 1, 2];
/// Returns `true` if successful and `false` if the slice is at the
/// first-ordered permutation.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let v: &mut [_] = &mut [1, 0, 2];
///
/// Will return `Err` if it's not possible to parse `self` into the type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// assert_eq!("4".parse::<u32>(), Ok(4));
//! "finally" case. For advanced cases, the `try_finally` function can
//! also be used. See that function for more details.
//!
-//! # Example
+//! # Examples
//!
//! ```
//! # #![feature(unboxed_closures)]
/// function could have panicked at any point, so the values of the shared
/// state may be inconsistent.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::finally::try_finally;
/// Constructs a radix formatter in the range of `2..36`.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::fmt::radix;
/// An iterator that passes mutable state to a closure and yields the result.
///
-/// # Example: The Fibonacci Sequence
+/// # Examples
///
/// An iterator that yields sequential Fibonacci numbers, and stops on overflow.
///
/// This will invoke the `panic!` macro if the provided expression cannot be
/// evaluated to `true` at runtime.
///
-/// # Example
+/// # Examples
///
/// ```
/// // the panic message for these assertions is the stringified value of the
///
/// On panic, this macro will print the values of the expressions.
///
-/// # Example
+/// # Examples
///
/// ```
/// let a = 3;
/// expensive to be present in a release build but may be helpful during
/// development.
///
-/// # Example
+/// # Examples
///
/// ```
/// // the panic message for these assertions is the stringified value of the
/// expensive to be present in a release build but may be helpful during
/// development.
///
-/// # Example
+/// # Examples
///
/// ```
/// let a = 3;
/// Use the `format!` syntax to write data into a buffer of type `&mut Writer`.
/// See `std::fmt` for more information.
///
-/// # Example
+/// # Examples
///
/// ```
/// # #![allow(unused_must_use)]
/// can extend `MarkerTrait`, which is equivalent to
/// `PhantomFn<Self>`.
///
-/// # Example
+/// # Examples
///
/// As an example, consider a trait with no methods like `Even`, meant
/// to represent types that are "even":
/// Returns the number of ones in the binary representation of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Returns the number of zeros in the binary representation of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Returns the number of leading zeros in the binary representation
/// of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Returns the number of trailing zeros in the binary representation
/// of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Shifts the bits to the left by a specified amount amount, `n`, wrapping
/// the truncated bits to the end of the resulting integer.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Shifts the bits to the right by a specified amount amount, `n`, wrapping
/// the truncated bits to the beginning of the resulting integer.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Reverses the byte order of the integer.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
///
/// On big endian this is a no-op. On little endian the bytes are swapped.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
///
/// On little endian this is a no-op. On big endian the bytes are swapped.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
///
/// On big endian this is a no-op. On little endian the bytes are swapped.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
///
/// On little endian this is a no-op. On big endian the bytes are swapped.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Checked integer addition. Computes `self + other`, returning `None` if
/// overflow occurred.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Checked integer subtraction. Computes `self - other`, returning `None`
/// if underflow occurred.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Checked integer multiplication. Computes `self * other`, returning
/// `None` if underflow or overflow occurred.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Checked integer division. Computes `self / other`, returning `None` if
/// `other == 0` or the operation results in underflow or overflow.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Raises self to the power of `exp`, using exponentiation by squaring.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::num::Int;
/// Cast from one machine scalar to another.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::num;
//! idea to have both `T` and `&T` implement the traits `Add<T>` and `Add<&T>`
//! so that generic code can be written without unnecessary cloning.
//!
-//! # Example
+//! # Examples
//!
//! This example creates a `Point` struct that implements `Add` and `Sub`, and then
//! demonstrates adding and subtracting two `Point`s.
/// The `Drop` trait is used to run some code when a value goes out of scope. This
/// is sometimes called a 'destructor'.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Drop`. The `drop` method is called when `_x` goes
/// out of scope, and therefore `main` prints `Dropping!`.
/// The `Add` trait is used to specify the functionality of `+`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Add`. When `Foo + Foo` happens, it ends up
/// calling `add`, and therefore, `main` prints `Adding!`.
/// The `Sub` trait is used to specify the functionality of `-`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Sub`. When `Foo - Foo` happens, it ends up
/// calling `sub`, and therefore, `main` prints `Subtracting!`.
/// The `Mul` trait is used to specify the functionality of `*`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Mul`. When `Foo * Foo` happens, it ends up
/// calling `mul`, and therefore, `main` prints `Multiplying!`.
/// The `Div` trait is used to specify the functionality of `/`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Div`. When `Foo / Foo` happens, it ends up
/// calling `div`, and therefore, `main` prints `Dividing!`.
/// The `Rem` trait is used to specify the functionality of `%`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Rem`. When `Foo % Foo` happens, it ends up
/// calling `rem`, and therefore, `main` prints `Remainder-ing!`.
/// The `Neg` trait is used to specify the functionality of unary `-`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Neg`. When `-Foo` happens, it ends up calling
/// `neg`, and therefore, `main` prints `Negating!`.
/// The `Not` trait is used to specify the functionality of unary `!`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Not`. When `!Foo` happens, it ends up calling
/// `not`, and therefore, `main` prints `Not-ing!`.
/// The `BitAnd` trait is used to specify the functionality of `&`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `BitAnd`. When `Foo & Foo` happens, it ends up
/// calling `bitand`, and therefore, `main` prints `Bitwise And-ing!`.
/// The `BitOr` trait is used to specify the functionality of `|`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `BitOr`. When `Foo | Foo` happens, it ends up
/// calling `bitor`, and therefore, `main` prints `Bitwise Or-ing!`.
/// The `BitXor` trait is used to specify the functionality of `^`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `BitXor`. When `Foo ^ Foo` happens, it ends up
/// calling `bitxor`, and therefore, `main` prints `Bitwise Xor-ing!`.
/// The `Shl` trait is used to specify the functionality of `<<`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Shl`. When `Foo << Foo` happens, it ends up
/// calling `shl`, and therefore, `main` prints `Shifting left!`.
/// The `Shr` trait is used to specify the functionality of `>>`.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Shr`. When `Foo >> Foo` happens, it ends up
/// calling `shr`, and therefore, `main` prints `Shifting right!`.
/// The `Index` trait is used to specify the functionality of indexing operations
/// like `arr[idx]` when used in an immutable context.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `Index`. When `Foo[Bar]` happens, it ends up
/// calling `index`, and therefore, `main` prints `Indexing!`.
/// The `IndexMut` trait is used to specify the functionality of indexing
/// operations like `arr[idx]`, when used in a mutable context.
///
-/// # Example
+/// # Examples
///
/// A trivial implementation of `IndexMut`. When `Foo[Bar]` happens, it ends up
/// calling `index_mut`, and therefore, `main` prints `Indexing!`.
/// The `Deref` trait is used to specify the functionality of dereferencing
/// operations like `*v`.
///
-/// # Example
+/// # Examples
///
/// A struct with a single field which is accessible via dereferencing the
/// struct.
/// The `DerefMut` trait is used to specify the functionality of dereferencing
/// mutably like `*v = 1;`
///
-/// # Example
+/// # Examples
///
/// A struct with a single field which is modifiable via dereferencing the
/// struct.
/// Returns `true` if the option is a `Some` value
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Option<u32> = Some(2);
/// Returns `true` if the option is a `None` value
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Option<u32> = Some(2);
/// Convert from `Option<T>` to `Option<&T>`
///
- /// # Example
+ /// # Examples
///
/// Convert an `Option<String>` into an `Option<usize>`, preserving the original.
/// The `map` method takes the `self` argument by value, consuming the original,
/// Convert from `Option<T>` to `Option<&mut T>`
///
- /// # Example
+ /// # Examples
///
/// ```
/// let mut x = Some(2);
/// Convert from `Option<T>` to `&mut [T]` (without copying)
///
- /// # Example
+ /// # Examples
///
/// ```
/// let mut x = Some("Diamonds");
/// Panics if the value is a `None` with a custom panic message provided by
/// `msg`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some("value");
/// Instead, prefer to use pattern matching and handle the `None`
/// case explicitly.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some("air");
/// Returns the contained value or a default.
///
- /// # Example
+ /// # Examples
///
/// ```
/// assert_eq!(Some("car").unwrap_or("bike"), "car");
/// Returns the contained value or computes it from a closure.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let k = 10;
/// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value
///
- /// # Example
+ /// # Examples
///
/// Convert an `Option<String>` into an `Option<usize>`, consuming the original:
///
/// Applies a function to the contained value or returns a default.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some("foo");
/// Applies a function to the contained value or computes a default.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let k = 21;
/// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
/// `Ok(v)` and `None` to `Err(err)`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some("foo");
/// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
/// `Ok(v)` and `None` to `Err(err())`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some("foo");
/// Returns an iterator over the possibly contained value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some(4);
/// Returns a mutable iterator over the possibly contained value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let mut x = Some(4);
/// Returns a consuming iterator over the possibly contained value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some("string");
/// Returns `None` if the option is `None`, otherwise returns `optb`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some(2);
///
/// Some languages call this operation flatmap.
///
- /// # Example
+ /// # Examples
///
/// ```
/// fn sq(x: u32) -> Option<u32> { Some(x * x) }
/// Returns the option if it contains a value, otherwise returns `optb`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x = Some(2);
/// Returns the option if it contains a value, otherwise calls `f` and
/// returns the result.
///
- /// # Example
+ /// # Examples
///
/// ```
/// fn nobody() -> Option<&'static str> { None }
/// Takes the value out of the option, leaving a `None` in its place.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let mut x = Some(2);
/// value, otherwise if `None`, returns the default value for that
/// type.
///
- /// # Example
+ /// # Examples
///
/// Convert a string to an integer, turning poorly-formed strings
/// into 0 (the default value for integers). `parse` converts
/// Returns true if the result is `Ok`
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<int, &str> = Ok(-3);
/// Returns true if the result is `Err`
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<int, &str> = Ok(-3);
/// Converts `self` into an `Option<T>`, consuming `self`,
/// and discarding the error, if any.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(2);
/// Converts `self` into an `Option<E>`, consuming `self`,
/// and discarding the value, if any.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(2);
///
/// This function can be used to compose the results of two functions.
///
- /// # Example
+ /// # Examples
///
/// Sum the lines of a buffer by mapping strings to numbers,
/// ignoring I/O and parse errors:
/// This function can be used to pass through a successful result while handling
/// an error.
///
- /// # Example
+ /// # Examples
///
/// ```
/// fn stringify(x: u32) -> String { format!("error code: {}", x) }
/// Returns an iterator over the possibly contained value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(7);
/// Returns a mutable iterator over the possibly contained value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let mut x: Result<u32, &str> = Ok(7);
/// Returns a consuming iterator over the possibly contained value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(5);
/// Returns `res` if the result is `Ok`, otherwise returns the `Err` value of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(2);
///
/// This function can be used for control flow based on result values.
///
- /// # Example
+ /// # Examples
///
/// ```
/// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
/// Returns `res` if the result is `Err`, otherwise returns the `Ok` value of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(2);
///
/// This function can be used for control flow based on result values.
///
- /// # Example
+ /// # Examples
///
/// ```
/// fn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }
/// Unwraps a result, yielding the content of an `Ok`.
/// Else it returns `optb`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let optb = 2;
/// Unwraps a result, yielding the content of an `Ok`.
/// If the value is an `Err` then it calls `op` with its value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// fn count(x: &str) -> usize { x.len() }
/// Panics if the value is an `Err`, with a custom panic message provided
/// by the `Err`'s value.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let x: Result<u32, &str> = Ok(2);
/// Panics if the value is an `Ok`, with a custom panic message provided
/// by the `Ok`'s value.
///
- /// # Example
+ /// # Examples
///
/// ```{.should_fail}
/// let x: Result<u32, &str> = Ok(2);
/// function taking the lifetime of a host value for the slice, or by explicit
/// annotation.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::slice;
/// valid for `len` elements, nor whether the lifetime provided is a suitable
/// lifetime for the returned slice.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::slice;
/// Panics when `begin` and `end` do not point to valid characters
/// or point beyond the last character of the string.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let s = "Löwe 老虎 Léopard";
/// the two ends of a range of values, that is they
/// can not "walk past each other".
///
-/// # Example
+/// # Examples
///
/// `char::Searcher` is a `DoubleEndedSearcher` because searching for a
/// `char` only requires looking at one at a time, which behaves the same
/// format!-based argument list. See documentation in `std::fmt` for details on
/// how to use the syntax.
///
-/// # Example
+/// # Examples
///
/// ```
/// #[macro_use] extern crate log;
/// A convenience macro for logging at the error log level.
///
-/// # Example
+/// # Examples
///
/// ```
/// #[macro_use] extern crate log;
/// A convenience macro for logging at the warning log level.
///
-/// # Example
+/// # Examples
///
/// ```
/// #[macro_use] extern crate log;
/// A convenience macro for logging at the info log level.
///
-/// # Example
+/// # Examples
///
/// ```
/// #[macro_use] extern crate log;
/// be omitted at compile time by passing `--cfg ndebug` to the compiler. If
/// this option is not passed, then debug statements will be compiled.
///
-/// # Example
+/// # Examples
///
/// ```
/// #[macro_use] extern crate log;
/// A macro to test whether a log level is enabled for the current module.
///
-/// # Example
+/// # Examples
///
/// ```
/// #[macro_use] extern crate log;
/// This distribution has density function: `f(x) = lambda *
/// exp(-lambda * x)` for `x > 0`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// == 1`, and using the boosting technique described in [1] for
/// `shape < 1`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// `k`, this uses the equivalent characterisation `χ²(k) = Gamma(k/2,
/// 2)`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// chi-squared distributions, that is, `F(m,n) = (χ²(m)/m) /
/// (χ²(n)/n)`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// The Student t distribution, `t(nu)`, where `nu` is the degrees of
/// freedom.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// all `T`, as is `uint`, so one can store references or indices into
/// another vector.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// This uses the ZIGNOR variant of the Ziggurat method, see
/// `StandardNormal` for more details.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// If `X` is log-normal distributed, then `ln(X)` is `N(mean,
/// std_dev**2)` distributed.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand;
/// primitive integer types satisfy this property, and the float types
/// normally satisfy it, but rounding may mean `high` can occur.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand::distributions::{IndependentSample, Range};
/// (e.g. reading past the end of a file that is being used as the
/// source of randomness).
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, Rng};
/// Return a random value of a `Rand` type.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, Rng};
/// Return an iterator that will yield an infinite number of randomly
/// generated items.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::rand::{thread_rng, Rng};
///
/// Panics if `low >= high`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, Rng};
/// Return a bool with a 1 in n chance of true
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, Rng};
/// Return an iterator of random characters from the set A-Z,a-z,0-9.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, Rng};
///
/// Return `None` if `values` is empty.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::rand::{thread_rng, Rng};
/// Shuffle a mutable slice in place.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, Rng};
pub trait SeedableRng<Seed>: Rng {
/// Reseed an RNG with the given seed.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{Rng, SeedableRng, StdRng};
/// Create a new RNG with the given seed.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::rand::{Rng, SeedableRng, StdRng};
/// `Rand` implementation for `f32` and `f64` for the half-open
/// `[0,1)`.
///
-/// # Example
+/// # Examples
/// ```rust
/// use std::rand::{random, Open01};
///
/// `Rand` implementation of `f32` and `f64` for the half-open
/// `[0,1)`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand::{random, Closed01};
/// Something that can be used to reseed an RNG via `ReseedingRng`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand::{Rng, SeedableRng, StdRng};
/// Writes to an owned, growable byte vector that supports seeking.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// ```
/// but currently it is not possible.
///
-/// # Example
+/// # Examples
/// ```
/// struct Context {
/// cache: RefCell<HashMap<uint, uint>>
/// The flags should only be defined for integer types, otherwise unexpected
/// type errors may occur at compile time.
///
-/// # Example
+/// # Examples
///
/// ```{.rust}
/// #[macro_use] extern crate rustc_bitflags;
impl ToHex for [u8] {
/// Turn a vector of `u8` bytes into a hexadecimal string.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// extern crate serialize;
/// You can use the `String::from_utf8` function to turn a
/// `Vec<u8>` into a string with characters corresponding to those values.
///
- /// # Example
+ /// # Examples
///
/// This converts a string literal to hexadecimal and back.
///
/// 3. Emmanuel Goossaert. ["Robin Hood hashing: backward shift
/// deletion"](http://codecapsule.com/2013/11/17/robin-hood-hashing-backward-shift-deletion/)
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::collections::HashMap;
impl<K: Hash + Eq, V> HashMap<K, V, RandomState> {
/// Create an empty HashMap.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Creates an empty hash map with the given initial capacity.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
///
/// The creates map has the default initial capacity.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// cause many collisions and very poor performance. Setting it
/// manually using this function can expose a DoS attack vector.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Returns the number of elements the map can hold without reallocating.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
///
/// Panics if the new allocation size overflows `usize`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// down as much as possible while maintaining the internal rules
/// and possibly leaving some space in accordance with the resize policy.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// An iterator visiting all keys in arbitrary order.
/// Iterator element type is `&'a K`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// An iterator visiting all values in arbitrary order.
/// Iterator element type is `&'a V`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// An iterator visiting all key-value pairs in arbitrary order.
/// Iterator element type is `(&'a K, &'a V)`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// with mutable references to the values.
/// Iterator element type is `(&'a K, &'a mut V)`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// pair out of the map in arbitrary order. The map cannot be used after
/// calling this.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Returns the number of elements in the map.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Returns true if the map contains no elements.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Clears the map, returning all key-value pairs as an iterator. Keeps the
/// allocated memory for reuse.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Clears the map, removing all key-value pairs. Keeps the allocated memory
/// for reuse.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// the key type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// the key type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// the key type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// Inserts a key-value pair from the map. If the key already had a value
/// present in the map, that value is returned. Otherwise, `None` is returned.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// the key type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashMap;
/// HashMap where the value is (). As with the `HashMap` type, a `HashSet`
/// requires that the elements implement the `Eq` and `Hash` traits.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::collections::HashSet;
impl<T: Hash + Eq> HashSet<T, RandomState> {
/// Create an empty HashSet.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Create an empty HashSet with space for at least `n` elements in
/// the hash table.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
///
/// The hash set is also created with the default initial capacity.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// cause many collisions and very poor performance. Setting it
/// manually using this function can expose a DoS attack vector.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Returns the number of elements the set can hold without reallocating.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
///
/// Panics if the new allocation size overflows `usize`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// down as much as possible while maintaining the internal rules
/// and possibly leaving some space in accordance with the resize policy.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// An iterator visiting all elements in arbitrary order.
/// Iterator element type is &'a T.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// of the set in arbitrary order. The set cannot be used after calling
/// this.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Visit the values representing the difference.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Visit the values representing the symmetric difference.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Visit the values representing the intersection.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Visit the values representing the union.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Return the number of elements in the set
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Returns true if the set contains no elements
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Clears the set, removing all values.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// the value type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Returns `true` if the set has no elements in common with `other`.
/// This is equivalent to checking for an empty intersection.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Returns `true` if the set is a subset of another.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Returns `true` if the set is a superset of another.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// Adds a value to the set. Returns `true` if the value was not already
/// present in the set.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// `Hash` and `Eq` on the borrowed form *must* match those for
/// the value type.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::collections::HashSet;
/// * There are insufficient permissions to access the current directory.
/// * The internal buffer is not large enough to hold the path.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// Changes the current working directory to the specified path, returning
/// whether the change was completed successfully or not.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// environment is not valid unicode. If this is not desired, consider using the
/// `env::vars_os` function.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// variables at the time of this invocation, modifications to environment
/// variables afterwards will not be reflected in the returned iterator.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// valid unicode. If the environment variable is not present, or it is not
/// valid unicode, then `Err` will be returned.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// Fetches the environment variable `key` from the current process, returning
/// None if the variable isn't set.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// Sets the environment variable `k` to the value `v` for the currently running
/// process.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
///
/// Returns an iterator over the paths contained in `unparsed`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// `Path`s contains an invalid character for constructing the `PATH`
/// variable (a double quote on Windows or a colon on Unix).
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// 'USERPROFILE' environment variable if it is set and not equal to the empty
/// string.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// process is not valid unicode. If this is not desired it is recommended to
/// use the `args_os` function instead.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// set to arbitrary text, and it may not even exist, so this property should
/// not be relied upon for security purposes.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::env;
/// a `CString` do *not* contain the trailing nul terminator unless otherwise
/// specified.
///
-/// # Example
+/// # Examples
///
/// ```no_run
/// # extern crate libc;
/// > currently implemented with an up-front calculation of the length of
/// > the string. This is not guaranteed to always be the case.
///
- /// # Example
+ /// # Examples
///
/// ```no_run
/// # extern crate libc;
/// it was opened with. Files also implement `Seek` to alter the logical cursor
/// that the file contains internally.
///
-/// # Example
+/// # Examples
///
/// ```no_run
/// use std::io::prelude::*;
/// Remove a file from the underlying filesystem.
///
-/// # Example
+/// # Examples
///
/// ```rust,no_run
/// use std::fs;
/// This function will traverse soft links to query information about the
/// destination file.
///
-/// # Example
+/// # Examples
///
/// ```rust,no_run
/// # fn foo() -> std::io::Result<()> {
/// Rename a file or directory to a new name.
///
-/// # Example
+/// # Examples
///
/// ```rust,no_run
/// use std::fs;
/// Note that if `from` and `to` both point to the same file, then the file
/// will likely get truncated by this operation.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::fs;
/// Create a new, empty directory at the provided path
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::fs;
/// Remove an existing, empty directory
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::fs;
/// The iterator will yield instances of `io::Result<DirEntry>`. New errors may
/// be encountered after an iterator is initially constructed.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::io;
/// Changes the permissions found on a file or a directory.
///
-/// # Example
+/// # Examples
///
/// ```
/// # fn foo() -> std::io::Result<()> {
/// The multi-argument form of this macro panics with a string and has the
/// `format!` syntax for building a string.
///
-/// # Example
+/// # Examples
///
/// ```should_fail
/// # #![allow(unreachable_code)]
/// The syntax of this macro is the same as that used for `format!`. For more
/// information, see `std::fmt` and `std::old_io::stdio`.
///
-/// # Example
+/// # Examples
///
/// ```
/// println!("hello there!");
///
/// For more information, see the documentation in `std::fmt`.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::fmt;
/// will be emitted. To not emit a compile error, use the `option_env!`
/// macro instead.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let path: &'static str = env!("PATH");
/// A compile time error is never emitted when using this macro regardless
/// of whether the environment variable is present or not.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let key: Option<&'static str> = option_env!("SECRET_KEY");
/// Integer and floating point literals are stringified in order to be
/// concatenated.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let s = concat!("test", 10, 'b', true);
/// the invocation of the `line!()` macro itself, but rather the first macro
/// invocation leading up to the invocation of the `line!()` macro.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let current_line = line!();
/// the invocation of the `column!()` macro itself, but rather the first macro
/// invocation leading up to the invocation of the `column!()` macro.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let current_col = column!();
/// first macro invocation leading up to the invocation of the `file!()`
/// macro.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let this_file = file!();
/// stringification of all the tokens passed to the macro. No restrictions
/// are placed on the syntax of the macro invocation itself.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let one_plus_one = stringify!(1 + 1);
/// contents of the filename specified. The file is located relative to the
/// current file (similarly to how modules are found),
///
- /// # Example
+ /// # Examples
///
/// ```rust,ignore
/// let secret_key = include_str!("secret-key.ascii");
/// the contents of the filename specified. The file is located relative to
/// the current file (similarly to how modules are found),
///
- /// # Example
+ /// # Examples
///
/// ```rust,ignore
/// let secret_key = include_bytes!("secret-key.bin");
/// leading back up to the crate root. The first component of the path
/// returned is the name of the crate currently being compiled.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// mod test {
/// The syntax given to this macro is the same syntax as the `cfg`
/// attribute.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// let my_directory = if cfg!(windows) {
/// This method may perform a DNS query to resolve `host` and may also inspect
/// system configuration to resolve the specified hostname.
///
-/// # Example
+/// # Examples
///
/// ```no_run
/// use std::net;
///
/// The socket will be closed when the value is dropped.
///
-/// # Example
+/// # Examples
///
/// ```no_run
/// use std::io::prelude::*;
/// IPv6 addresses, and there is no corresponding notion of a server because UDP
/// is a datagram protocol.
///
-/// # Example
+/// # Examples
///
/// ```no_run
/// use std::net::UdpSocket;
/// `BufferedReader` performs large, infrequent reads on the underlying
/// `Reader` and maintains an in-memory buffer of the results.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::old_io::{BufferedReader, File};
///
/// This writer will be flushed when it is dropped.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::old_io::{BufferedWriter, File};
///
/// The output half will be flushed when this stream is dropped.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Allows reading from a rx.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::mpsc::channel;
/// Allows writing to a tx.
///
-/// # Example
+/// # Examples
///
/// ```
/// # #![allow(unused_must_use)]
//! the metadata of a file. This includes getting the `stat` information,
//! reading off particular bits of it, etc.
//!
-//! # Example
+//! # Examples
//!
//! ```rust
//! # #![allow(unused_must_use)]
/// Open a file at `path` in the mode specified by the `mode` and `access`
/// arguments
///
- /// # Example
+ /// # Examples
///
/// ```rust,should_fail
/// use std::old_io::{File, Open, ReadWrite};
///
/// For more information, see the `File::open_mode` function.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::old_io::File;
///
/// For more information, see the `File::open_mode` function.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Unlink a file from the underlying filesystem.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// directory, etc. This function will traverse symlinks to query
/// information about the destination file.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::old_io::fs;
/// Rename a file or directory to a new name.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Note that if `from` and `to` both point to the same file, then the file
/// will likely get truncated by this operation.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Changes the permission mode bits found on a file or a directory. This
/// function takes a mask from the `io` module
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Create a new, empty directory at the provided path
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Remove an existing, empty directory
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Retrieve a vector containing all entries within a provided directory
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::old_io::fs::PathExtensions;
/// Writes to an owned, growable byte vector
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Reads from an owned byte vector
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// If a write will not fit in the buffer, it returns an error and does not
/// write any data.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// Reads from a fixed-size byte slice
///
-/// # Example
+/// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
/// A `RefWriter` is a struct implementing `Writer` which contains a reference
/// to another writer. This is often useful when composing streams.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::old_io::util::TeeReader;
/// encoded Unicode codepoints. If a newline is encountered, then the
/// newline is contained in the returned string.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::old_io::BufReader;
/// Creates a standard error for a commonly used flavor of error. The `detail`
/// field of the returned error will always be `None`.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::old_io as io;
///
/// The returned stream will be closed when the object falls out of scope.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// # #![allow(unused_must_use)]
///
/// This listener will be closed when it falls out of scope.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # fn foo() {
///
/// The socket will be closed when the value is dropped.
///
-/// # Example
+/// # Examples
///
/// ```no_run
/// use std::old_io::TcpStream;
/// This method will close the reading portion of this connection, causing
/// all pending and future reads to immediately return with an error.
///
- /// # Example
+ /// # Examples
///
/// ```no_run
/// # #![allow(unused_must_use)]
/// regardless of whether the timeout has expired or not (the accept will
/// not block in this case).
///
- /// # Example
+ /// # Examples
///
/// ```no_run
/// use std::old_io::TcpListener;
/// This is useful for waking up a thread in an accept loop to indicate that
/// it should exit.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::old_io::{TcpListener, Listener, Acceptor, EndOfFile};
/// IPv6 addresses, and there is no corresponding notion of a server because UDP
/// is a datagram protocol.
///
-/// # Example
+/// # Examples
///
/// ```rust,no_run
/// # #![allow(unused_must_use)]
/// This operation consumes ownership of the file descriptor and it will be
/// closed once the object is deallocated.
///
- /// # Example
+ /// # Examples
///
/// ```{rust,no_run}
/// # #![allow(unused_must_use)]
/// process is created via the `Command` struct, which configures the spawning
/// process and can itself be constructed using a builder-style interface.
///
-/// # Example
+/// # Examples
///
/// ```should_fail
/// use std::old_io::Command;
/// Executes the command as a child process, waiting for it to finish and
/// collecting all of its output.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::old_io::Command;
/// Executes a command as a child process, waiting for it to finish and
/// collecting its exit status.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::old_io::Command;
/// A value of `None` will clear any previous timeout, and a value of `Some`
/// will override any previously set timeout.
///
- /// # Example
+ /// # Examples
///
/// ```no_run
/// use std::old_io::{Command, IoResult};
//! inspected for information about terminal dimensions or for related information
//! about the stream or terminal to which it is attached.
//!
-//! # Example
+//! # Examples
//!
//! ```rust
//! # #![allow(unused_must_use)]
/// invalidated at the end of that statement, and all `recv` calls will
/// fail.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::old_io::Timer;
/// invalidated at the end of that statement, and all `recv` calls will
/// fail.
///
- /// # Example
+ /// # Examples
///
/// ```rust
/// use std::old_io::Timer;
//! suitable for passing to any API that actually operates on the path; it is only intended for
//! display.
//!
-//! ## Example
+//! ## Examples
//!
//! ```rust
//! use std::old_io::fs::PathExtensions;
/// Creates a new Path from a byte vector or string.
/// The resulting Path will always be normalized.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Creates a new Path from a byte vector or string, if possible.
/// The resulting Path will always be normalized.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the path as a string, if possible.
/// If the path is not representable in utf-8, this returns None.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the path as a byte vector
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Converts the Path into an owned byte vector
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns an object that implements `Display` for printing paths
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
///
/// If there is no filename, nothing will be printed.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the directory component of `self`, as a byte vector (with no trailing separator).
/// If `self` has no directory component, returns ['.'].
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the directory component of `self`, as a string, if possible.
/// See `dirname` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// If `self` represents the root of the file hierarchy, returns None.
/// If `self` is "." or "..", returns None.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the file component of `self`, as a string, if possible.
/// See `filename` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// The stem is the portion of the filename just before the last '.'.
/// If there is no '.', the entire filename is returned.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the stem of the filename of `self`, as a string, if possible.
/// See `filestem` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// If there is no extension, None is returned.
/// If the filename ends in '.', the empty vector is returned.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the extension of the filename of `self`, as a string, if possible.
/// See `extension` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Replaces the filename portion of the path with the given byte vector or string.
/// If the replacement name is [], this is equivalent to popping the path.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// If the argument is [] or "", this removes the extension.
/// If `self` has no filename, this is a no-op.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// byte vector or string.
/// See `set_filename` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// byte vector or string.
/// See `set_extension` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns the directory component of `self`, as a Path.
/// If `self` represents the root of the filesystem hierarchy, returns `self`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
///
/// If `self` is not absolute, or vol/cwd-relative in the case of Windows, this returns None.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Pushes a path (as a byte vector or string) onto `self`.
/// If the argument represents an absolute path, it replaces `self`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Pushes multiple paths (as byte vectors or strings) onto `self`.
/// See `push` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns `true` if the receiver was modified, or `false` if it already
/// represented the root of the file hierarchy.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// (as a byte vector or string).
/// If the given path is absolute, the new Path will represent just that.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// (as byte vectors or strings).
/// See `join` for details.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// An absolute path is defined as one that, when joined to another path, will
/// yield back the same absolute path.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// But for Windows paths, it also means the path is not volume-relative or
/// relative to the current working directory.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// If both paths are relative, they are compared as though they are relative
/// to the same parent path.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// If `self` is absolute and `base` is relative, or on Windows if both
/// paths refer to separate drives, an absolute path is returned.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
/// Returns whether the relative path `child` is a suffix of `self`.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # foo();
///
/// Panics if the vector contains a `NUL`, or if it contains invalid UTF-8.
///
- /// # Example
+ /// # Examples
///
/// ```
/// println!("{}", Path::new(r"C:\some\path").display());
///
/// Returns `None` if the vector contains a `NUL`, or if it contains invalid UTF-8.
///
- /// # Example
+ /// # Examples
///
/// ```
/// let path = Path::new_opt(r"C:\some\path");
/// * There are insufficient permissions to access the current directory.
/// * The internal buffer is not large enough to hold the path.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
/// Invalid UTF-8 bytes are replaced with \uFFFD. See `String::from_utf8_lossy()`
/// for details.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
///
/// Panics if `n` has any interior NULs.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
/// Sets the environment variable `n` to the value `v` for the currently running
/// process.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
/// Parses input according to platform conventions for the `PATH`
/// environment variable.
///
-/// # Example
+/// # Examples
/// ```rust
/// use std::os;
///
/// `Path`s contains an invalid character for constructing the `PATH`
/// variable (a double quote on Windows or a colon on Unix).
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
///
/// Like self_exe_name() but without the binary's name.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
/// 'USERPROFILE' environment variable if it is set and not equal to the empty
/// string.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
/// directory. If the given path is already an absolute path, return it
/// as is.
///
-/// # Example
+/// # Examples
/// ```rust
/// use std::os;
/// use std::old_path::Path;
/// Changes the current working directory to the specified path, returning
/// whether the change was completed successfully or not.
///
-/// # Example
+/// # Examples
/// ```rust
/// use std::os;
/// use std::old_path::Path;
/// Return the string corresponding to an `errno()` value of `errnum`.
///
-/// # Example
+/// # Examples
/// ```rust
/// use std::os;
///
///
/// The arguments are interpreted as utf-8, with invalid bytes replaced with \uFFFD.
/// See `String::from_utf8_lossy` for details.
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::os;
/// More details about the overall approach can be found in
/// the module documentation.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::path::PathBuf;
/// This is an *unsized* type, meaning that it must always be used with behind a
/// pointer like `&` or `Box`.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::path::Path;
/// process is created via the `Command` struct, which configures the spawning
/// process and can itself be constructed using a builder-style interface.
///
-/// # Example
+/// # Examples
///
/// ```should_fail
/// # #![feature(process)]
///
/// By default, stdin, stdout and stderr are inherited by the parent.
///
- /// # Example
+ /// # Examples
///
/// ```
/// # #![feature(process)]
/// Randomly sample up to `amount` elements from an iterator.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand::{thread_rng, sample};
///
/// It will panic if it there is insufficient data to fulfill a request.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::rand::{reader, Rng};
/// in a runtime panic. If this is not desired, then the unsafe primitives in
/// `sys` do not have this restriction but may result in undefined behavior.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::{Arc, Mutex, Condvar};
/// This structure is identical to `Condvar` except that it is suitable for use
/// in static initializers for other structures.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::{StaticCondvar, CONDVAR_INIT};
/// All data sent on the sender will become available on the receiver, and no
/// send will block the calling task (this channel has an "infinite buffer").
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::mpsc::channel;
/// As with asynchronous channels, all senders will panic in `send` if the
/// `Receiver` has been destroyed.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::mpsc::sync_channel;
///
/// This method will never block the current thread.
///
- /// # Example
+ /// # Examples
///
/// ```
/// use std::sync::mpsc::channel;
//! received values of receivers in a much more natural syntax then usage of the
//! `Select` structure directly.
//!
-//! # Example
+//! # Examples
//!
//! ```rust
//! use std::sync::mpsc::channel;
/// to a `Mutex`, a `destroy` method. This method is unsafe to call, and
/// documentation can be found directly on the method.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::sync::{StaticMutex, MUTEX_INIT};
/// functionality. This type can only be constructed with the `ONCE_INIT`
/// value.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::sync::{Once, ONCE_INIT};
/// automatic global access as well as lazy initialization. The internal
/// resources of this RwLock, however, must be manually deallocated.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::{StaticRwLock, RW_LOCK_INIT};
/// until the counter is positive, and each release will increment the counter
/// and unblock any threads if necessary.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::sync::Semaphore;
/// Spawns `n` worker threads and replenishes the pool if any worker threads
/// panic.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use std::sync::TaskPool;
//! more useful in practice than this OS-based version which likely requires
//! unsafe code to interoperate with.
//!
-//! # Example
+//! # Examples
//!
//! Using a dynamically allocated TLS key. Note that this key can be shared
//! among many threads via an `Arc`.
/// time. The key is also deallocated when the Rust runtime exits or `destroy`
/// is called, whichever comes first.
///
-/// # Example
+/// # Examples
///
/// ```ignore
/// use tls::os::{StaticKey, INIT};
/// Implementations will likely, however, contain unsafe code as this type only
/// operates on `*mut u8`, an unsafe pointer.
///
-/// # Example
+/// # Examples
///
/// ```rust,ignore
/// use tls::os::Key;
/// Macro for creating a compatibility fallback for a Windows function
///
- /// # Example
+ /// # Examples
/// ```
/// compat_fn!(adll32::SomeFunctionW(_arg: LPCWSTR) {
/// // Fallback implementation
/// within a thread, and values support destructors which will be run when a
/// thread exits.
///
-/// # Example
+/// # Examples
///
/// ```
/// use std::cell::RefCell;
//! period of time and it is not required to relinquish ownership of the
//! contents.
//!
-//! # Example
+//! # Examples
//!
//! ```
//! scoped_thread_local!(static FOO: u32);
/// Upon return, this function will restore the previous value, if any
/// was available.
///
- /// # Example
+ /// # Examples
///
/// ```
/// scoped_thread_local!(static FOO: u32);
///
/// This function will panic if `set` has not previously been called.
///
- /// # Example
+ /// # Examples
///
/// ```no_run
/// scoped_thread_local!(static FOO: u32);
/// Parse extern crate links
///
- /// # Example
+ /// # Examples
///
/// extern crate url;
/// extern crate foo = "bar"; //deprecated
/// Create an iterator over the UTF-16 encoded codepoints in `v`,
/// returning invalid surrogates as `LoneSurrogate`s.
///
-/// # Example
+/// # Examples
///
/// ```rust
/// use unicode::str::Utf16Item::{ScalarValue, LoneSurrogate};
projects / rust.git / commitdiff