Skip to content

Commit

Permalink
Improve documentation for unreachable
Browse files Browse the repository at this point in the history
Fixes #18876
  • Loading branch information
steveklabnik committed Nov 25, 2014
1 parent 48ca6d1 commit 4ce3ba4
Showing 1 changed file with 33 additions and 17 deletions.
50 changes: 33 additions & 17 deletions src/libstd/macros.rs
Original file line number Diff line number Diff line change
Expand Up @@ -186,26 +186,42 @@ macro_rules! debug_assert_eq(
($($arg:tt)*) => (if cfg!(not(ndebug)) { assert_eq!($($arg)*); })
)

/// A utility macro for indicating unreachable code. It will panic if
/// executed. This is occasionally useful to put after loops that never
/// terminate normally, but instead directly return from a function.
/// A utility macro for indicating unreachable code.
///
/// # Example
/// This is useful any time that the compiler can't determine that some code is unreachable. For
/// example:
///
/// * Match arms with guard conditions.
/// * Loops that dynamically terminate.
/// * Iterators that dynamically terminate.
///
/// # Panics
///
/// This will always panic.
///
/// # Examples
///
/// Match arms:
///
/// ```{.rust}
/// struct Item { weight: uint }
///
/// fn choose_weighted_item(v: &[Item]) -> Item {
/// assert!(!v.is_empty());
/// let mut so_far = 0u;
/// for item in v.iter() {
/// so_far += item.weight;
/// if so_far > 100 {
/// return *item;
/// }
/// ```rust
/// fn foo(x: Option<int>) {
/// match x {
/// Some(n) if n >= 0 => println!("Some(Non-negative)"),
/// Some(n) if n < 0 => println!("Some(Negative)"),
/// Some(_) => unreachable!(), // compile error if commented out
/// None => println!("None")
/// }
/// ```
///
/// Iterators:
///
/// ```rust
/// fn divide_by_three(x: i32) -> i32 { // one of the poorest implementations of x/3
/// for i in std::iter::count(0_i32, 1) {
/// if i < 0 { panic!("i32 overflow"); }
/// if x < 3*i { return i; }
/// }
/// // The above loop always returns, so we must hint to the
/// // type checker that it isn't possible to get down here
///
/// unreachable!();
/// }
/// ```
Expand Down

0 comments on commit 4ce3ba4

Please sign in to comment.