/// Retrieves the value at index `i`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `i` is out of bounds.
+ /// Panics if `i` is out of bounds.
///
/// # Example
///
/// Sets the value of a bit at a index `i`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `i` is out of bounds.
+ /// Panics if `i` is out of bounds.
///
/// # Example
///
/// Sets `self` to the union of `self` and `other`. Both bitvectors must be
/// the same length. Returns `true` if `self` changed.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the bitvectors are of different lengths.
+ /// Panics if the bitvectors are of different lengths.
///
/// # Example
///
/// Sets `self` to the intersection of `self` and `other`. Both bitvectors
/// must be the same length. Returns `true` if `self` changed.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the bitvectors are of different lengths.
+ /// Panics if the bitvectors are of different lengths.
///
/// # Example
///
/// element of `other` at the same index. Both bitvectors must be the same
/// length. Returns `true` if `self` changed.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the bitvectors are of different length.
+ /// Panics if the bitvectors are of different length.
///
/// # Example
///
/// Compares a `Bitv` to a slice of `bool`s.
/// Both the `Bitv` and slice must have the same length.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the the `Bitv` and slice are of different length.
+ /// Panics if the the `Bitv` and slice are of different length.
///
/// # Example
///
/// Shortens by one element and returns the removed element.
///
- /// # Failure
+ /// # Panics
///
/// Assert if empty.
///
/// Shortens a string to the specified length.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `new_len` > current length,
+ /// Panics if `new_len` > current length,
/// or if `new_len` is not a character boundary.
///
/// # Example
/// Appends an element to the back of a collection.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the number of elements in the vector overflows a `uint`.
+ /// Panics if the number of elements in the vector overflows a `uint`.
///
/// # Example
///
/// Converts a `Vec<T>` to a `Vec<U>` where `T` and `U` have the same
/// size and in case they are not zero-sized the same minimal alignment.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `T` and `U` have differing sizes or are not zero-sized and
+ /// Panics if `T` and `U` have differing sizes or are not zero-sized and
/// have differing minimal alignments.
///
/// # Example
/// Load the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Release` or `AcqRel`.
+ /// Panics if `order` is `Release` or `AcqRel`.
#[inline]
pub fn load(&self, order: Ordering) -> bool {
unsafe { atomic_load(self.v.get() as *const uint, order) > 0 }
/// Store the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Acquire` or `AcqRel`.
+ /// Panics if `order` is `Acquire` or `AcqRel`.
#[inline]
pub fn store(&self, val: bool, order: Ordering) {
let val = if val { UINT_TRUE } else { 0 };
/// Load the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Release` or `AcqRel`.
+ /// Panics if `order` is `Release` or `AcqRel`.
#[inline]
pub fn load(&self, order: Ordering) -> int {
unsafe { atomic_load(self.v.get() as *const int, order) }
/// Store the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Acquire` or `AcqRel`.
+ /// Panics if `order` is `Acquire` or `AcqRel`.
#[inline]
pub fn store(&self, val: int, order: Ordering) {
unsafe { atomic_store(self.v.get(), val, order); }
/// Load the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Release` or `AcqRel`.
+ /// Panics if `order` is `Release` or `AcqRel`.
#[inline]
pub fn load(&self, order: Ordering) -> uint {
unsafe { atomic_load(self.v.get() as *const uint, order) }
/// Store the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Acquire` or `AcqRel`.
+ /// Panics if `order` is `Acquire` or `AcqRel`.
#[inline]
pub fn store(&self, val: uint, order: Ordering) {
unsafe { atomic_store(self.v.get(), val, order); }
/// Load the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Release` or `AcqRel`.
+ /// Panics if `order` is `Release` or `AcqRel`.
#[inline]
pub fn load(&self, order: Ordering) -> *mut T {
unsafe {
/// Store the value
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `order` is `Acquire` or `AcqRel`.
+ /// Panics if `order` is `Acquire` or `AcqRel`.
#[inline]
pub fn store(&self, ptr: *mut T, order: Ordering) {
unsafe { atomic_store(self.p.get(), ptr as uint, order); }
///
/// Accepts `Acquire`, `Release`, `AcqRel` and `SeqCst` orderings.
///
-/// # Failure
+/// # Panics
///
-/// Fails if `order` is `Relaxed`
+/// Panics if `order` is `Relaxed`
#[inline]
#[stable]
pub fn fence(order: Ordering) {
/// The borrow lasts until the returned `Ref` exits scope. Multiple
/// immutable borrows can be taken out at the same time.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the value is currently mutably borrowed.
+ /// Panics if the value is currently mutably borrowed.
#[unstable]
pub fn borrow<'a>(&'a self) -> Ref<'a, T> {
match self.try_borrow() {
/// The borrow lasts until the returned `RefMut` exits scope. The value
/// cannot be borrowed while this borrow is active.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the value is currently borrowed.
+ /// Panics if the value is currently borrowed.
#[unstable]
pub fn borrow_mut<'a>(&'a self) -> RefMut<'a, T> {
match self.try_borrow_mut() {
/// Returns `true` if `c` is a valid digit under `radix`, and `false`
/// otherwise.
///
-/// # Failure
+/// # Panics
///
-/// Fails if given a `radix` > 36.
+/// Panics if given a `radix` > 36.
///
/// # Note
///
/// 'b' or 'B', 11, etc. Returns none if the `char` does not
/// refer to a digit in the given radix.
///
-/// # Failure
+/// # Panics
///
-/// Fails if given a `radix` outside the range `[0..36]`.
+/// Panics if given a `radix` outside the range `[0..36]`.
///
#[inline]
pub fn to_digit(c: char, radix: uint) -> Option<uint> {
/// Returns `Some(char)` if `num` represents one digit under `radix`,
/// using one character of `0-9` or `a-z`, or `None` if it doesn't.
///
-/// # Failure
+/// # Panics
///
-/// Fails if given an `radix` > 36.
+/// Panics if given an `radix` > 36.
///
#[inline]
pub fn from_digit(num: uint, radix: uint) -> Option<char> {
/// Returns `true` if `c` is a valid digit under `radix`, and `false`
/// otherwise.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if given a radix > 36.
+ /// Panics if given a radix > 36.
fn is_digit_radix(&self, radix: uint) -> bool;
/// Converts a character to the corresponding digit.
/// 9. If `c` is 'a' or 'A', 10. If `c` is 'b' or 'B', 11, etc. Returns
/// none if the character does not refer to a digit in the given radix.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if given a radix outside the range [0..36].
+ /// Panics if given a radix outside the range [0..36].
fn to_digit(&self, radix: uint) -> Option<uint>;
/// Converts a number to the character representing it.
/// Returns `Some(char)` if `num` represents one digit under `radix`,
/// using one character of `0-9` or `a-z`, or `None` if it doesn't.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if given a radix > 36.
+ /// Panics if given a radix > 36.
fn from_digit(num: uint, radix: uint) -> Option<Self>;
/// Returns the hexadecimal Unicode escape of a character.
* - `f` - A closure to invoke with the bytes representing the
* float.
*
- * # Failure
- * - Fails if `radix` < 2 or `radix` > 36.
- * - Fails if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
+ * # Panics
+ * - Panics if `radix` < 2 or `radix` > 36.
+ * - Panics if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
* between digit and exponent sign `'e'`.
- * - Fails if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
+ * - Panics if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
* between digit and exponent sign `'p'`.
*/
pub fn float_to_str_bytes_common<T: Primitive + Float, U>(
pub trait SlicePrelude<T> for Sized? {
/// Returns a subslice spanning the interval [`start`, `end`).
///
- /// Fails when the end of the new slice lies beyond the end of the
+ /// Panics when the end of the new slice lies beyond the end of the
/// original slice (i.e. when `end > self.len()`) or when `start > end`.
///
/// Slicing with `start` equal to `end` yields an empty slice.
/// Returns a subslice from `start` to the end of the slice.
///
- /// Fails when `start` is strictly greater than the length of the original slice.
+ /// Panics when `start` is strictly greater than the length of the original slice.
///
/// Slicing from `self.len()` yields an empty slice.
#[unstable = "waiting on final error conventions/slicing syntax"]
/// Returns a subslice from the start of the slice to `end`.
///
- /// Fails when `end` is strictly greater than the length of the original slice.
+ /// Panics when `end` is strictly greater than the length of the original slice.
///
/// Slicing to `0` yields an empty slice.
#[unstable = "waiting on final error conventions/slicing syntax"]
/// the index `mid` itself) and the second will contain all
/// indices from `[mid, len)` (excluding the index `len` itself).
///
- /// Fails if `mid > len`.
+ /// Panics if `mid > len`.
#[unstable = "waiting on final error conventions"]
fn split_at<'a>(&'a self, mid: uint) -> (&'a [T], &'a [T]);
/// `size`. The windows overlap. If the slice is shorter than
/// `size`, the iterator returns no values.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `size` is 0.
+ /// Panics if `size` is 0.
///
/// # Example
///
/// length of the slice, then the last chunk will not have length
/// `size`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `size` is 0.
+ /// Panics if `size` is 0.
///
/// # Example
///
/// Returns a mutable subslice spanning the interval [`start`, `end`).
///
- /// Fails when the end of the new slice lies beyond the end of the
+ /// Panics when the end of the new slice lies beyond the end of the
/// original slice (i.e. when `end > self.len()`) or when `start > end`.
///
/// Slicing with `start` equal to `end` yields an empty slice.
/// Returns a mutable subslice from `start` to the end of the slice.
///
- /// Fails when `start` is strictly greater than the length of the original slice.
+ /// Panics when `start` is strictly greater than the length of the original slice.
///
/// Slicing from `self.len()` yields an empty slice.
#[unstable = "waiting on final error conventions"]
/// Returns a mutable subslice from the start of the slice to `end`.
///
- /// Fails when `end` is strictly greater than the length of the original slice.
+ /// Panics when `end` is strictly greater than the length of the original slice.
///
/// Slicing to `0` yields an empty slice.
#[unstable = "waiting on final error conventions"]
/// not divide the length of the slice, then the last chunk will not
/// have length `chunk_size`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if `chunk_size` is 0.
+ /// Panics if `chunk_size` is 0.
#[unstable = "waiting on iterator type name conventions"]
fn chunks_mut<'a>(&'a mut self, chunk_size: uint) -> MutChunks<'a, T>;
/// Swaps two elements in a slice.
///
- /// Fails if `a` or `b` are out of bounds.
+ /// Panics if `a` or `b` are out of bounds.
///
/// # Arguments
///
/// the index `mid` itself) and the second will contain all
/// indices from `[mid, len)` (excluding the index `len` itself).
///
- /// Fails if `mid > len`.
+ /// Panics if `mid > len`.
///
/// # Example
///
/// Copies data from `src` to `dst`
///
- /// `src` and `dst` must not overlap. Fails if the length of `dst`
+ /// `src` and `dst` must not overlap. Panics if the length of `dst`
/// is less than the length of `src`.
#[inline]
pub fn copy_memory(dst: &mut [u8], src: &[u8]) {
///
/// Returns the substring from [`begin`..`end`).
///
- /// # Failure
+ /// # Panics
///
/// If begin is greater than end.
/// If end is greater than the length of the string.
///
/// This operation is `O(1)`.
///
- /// Fails when `begin` and `end` do not point to valid characters
+ /// Panics when `begin` and `end` do not point to valid characters
/// or point beyond the last character of the string.
///
/// See also `slice_to` and `slice_from` for slicing prefixes and
///
/// Equivalent to `self.slice(begin, self.len())`.
///
- /// Fails when `begin` does not point to a valid character, or is
+ /// Panics when `begin` does not point to a valid character, or is
/// out of bounds.
///
/// See also `slice`, `slice_to` and `slice_chars`.
///
/// Equivalent to `self.slice(0, end)`.
///
- /// Fails when `end` does not point to a valid character, or is
+ /// Panics when `end` does not point to a valid character, or is
/// out of bounds.
///
/// See also `slice`, `slice_from` and `slice_chars`.
/// variants that use byte indices rather than code point
/// indices.
///
- /// Fails if `begin` > `end` or the either `begin` or `end` are
+ /// Panics if `begin` > `end` or the either `begin` or `end` are
/// beyond the last character of the string.
///
/// # Example
/// The start and end of the string (when `index == self.len()`)
/// are considered to be boundaries.
///
- /// Fails if `index` is greater than `self.len()`.
+ /// Panics if `index` is greater than `self.len()`.
///
/// # Example
///
/// A record {ch: char, next: uint} containing the char value and the byte
/// index of the next Unicode character.
///
- /// # Failure
+ /// # Panics
///
/// If `i` is greater than or equal to the length of the string.
/// If `i` is not the index of the beginning of a valid UTF-8 character.
///
/// Returns 0 for next index if called on start index 0.
///
- /// # Failure
+ /// # Panics
///
/// If `i` is greater than the length of the string.
/// If `i` is not an index following a valid UTF-8 character.
/// assert_eq!(s.char_at(4), 'c');
/// ```
///
- /// # Failure
+ /// # Panics
///
/// If `i` is greater than or equal to the length of the string.
/// If `i` is not the index of the beginning of a valid UTF-8 character.
/// Plucks the character ending at the `i`th byte of a string.
///
- /// # Failure
+ /// # Panics
///
/// If `i` is greater than the length of the string.
/// If `i` is not an index following a valid UTF-8 character.
/// Returns the byte offset of an inner slice relative to an enclosing outer slice.
///
- /// Fails if `inner` is not a direct slice contained within self.
+ /// Panics if `inner` is not a direct slice contained within self.
///
/// # Example
///
///
/// On success returns `Ok(Matches)`. Use methods such as `opt_present`
/// `opt_str`, etc. to interrogate results.
-/// # Failure
+/// # Errors
///
/// Returns `Err(Fail_)` on failure: use the `Show` implementation of `Fail_` to display
/// information about it.
/// API, so avoid calling it with a pointer to memory managed by Rust's
/// allocator API, as the behaviour would not be well defined.
///
- ///# Failure
+ ///# Panics
///
- /// Fails if `buf` is null
+ /// Panics if `buf` is null
pub unsafe fn new(buf: *const libc::c_char, owns_buffer: bool) -> CString {
assert!(!buf.is_null());
CString { buf: buf, owns_buffer_: owns_buffer }
pub trait ToCStr for Sized? {
/// Copy the receiver into a CString.
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the receiver has an interior null.
+ /// Panics the task if the receiver has an interior null.
fn to_c_str(&self) -> CString;
/// Unsafe variant of `to_c_str()` that doesn't check for nulls.
/// }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the receiver has an interior null.
+ /// Panics the task if the receiver has an interior null.
#[inline]
fn with_c_str<T>(&self, f: |*const libc::c_char| -> T) -> T {
let c_str = self.to_c_str();
/// Return a copy of the value corresponding to the key.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the key is not present.
+ /// Panics if the key is not present.
///
/// # Example
///
/// Rounds up to a multiple of a power of two. Returns the closest multiple
/// of `target_alignment` that is higher or equal to `unrounded`.
///
-/// # Failure
+/// # Panics
///
-/// Fails if `target_alignment` is not a power of two.
+/// Panics if `target_alignment` is not a power of two.
fn round_up_to_next(unrounded: uint, target_alignment: uint) -> uint {
assert!(is_power_of_two(target_alignment));
(unrounded + target_alignment - 1) & !(target_alignment - 1)
/// Similar to `slice()` except this function only bounds the slice on the
/// capacity of `v`, not the length.
///
-/// # Failure
+/// # Panics
///
-/// Fails when `start` or `end` point outside the capacity of `v`, or when
+/// Panics when `start` or `end` point outside the capacity of `v`, or when
/// `start` > `end`.
// Private function here because we aren't sure if we want to expose this as
// API yet. If so, it should be a method on Vec.
* It returns a tuple because there can be ambiguity between a special value
* and a number representation at higher bases.
*
- * # Failure
- * - Fails if `radix` < 2 or `radix` > 36.
+ * # Panics
+ * - Panics if `radix` < 2 or `radix` > 36.
*/
fn int_to_str_bytes_common<T: Int>(num: T, radix: uint, sign: SignFormat, f: |u8|) {
assert!(2 <= radix && radix <= 36);
* It returns a tuple because there can be ambiguity between a special value
* and a number representation at higher bases.
*
- * # Failure
- * - Fails if `radix` < 2 or `radix` > 36.
- * - Fails if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
+ * # Panics
+ * - Panics if `radix` < 2 or `radix` > 36.
+ * - Panics if `radix` > 14 and `exp_format` is `ExpDec` due to conflict
* between digit and exponent sign `'e'`.
- * - Fails if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
+ * - Panics if `radix` > 25 and `exp_format` is `ExpBin` due to conflict
* between digit and exponent sign `'p'`.
*/
pub fn float_to_str_bytes_common<T: Float>(
/// Any invalid UTF-8 bytes in the value are replaced by \uFFFD. See
/// `String::from_utf8_lossy()` for details.
///
-/// # Failure
+/// # Panics
///
-/// Fails if `n` has any interior NULs.
+/// Panics if `n` has any interior NULs.
///
/// # Example
///
/// Fetches the environment variable `n` byte vector from the current process,
/// returning None if the variable isn't set.
///
-/// # Failure
+/// # Panics
///
-/// Fails if `n` has any interior NULs.
+/// Panics if `n` has any interior NULs.
pub fn getenv_as_bytes(n: &str) -> Option<Vec<u8>> {
use c_str::CString;
#[cfg(windows)]
impl Drop for MemoryMap {
- /// Unmap the mapping. Fails the task if any of `VirtualFree`,
+ /// Unmap the mapping. Panics the task if any of `VirtualFree`,
/// `UnmapViewOfFile`, or `CloseHandle` fail.
fn drop(&mut self) {
use libc::types::os::arch::extra::{LPCVOID, HANDLE};
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the path contains a NUL.
+ /// Panics the task if the path contains a NUL.
///
/// See individual Path impls for additional restrictions.
#[inline]
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the filename contains a NUL.
+ /// Panics the task if the filename contains a NUL.
#[inline]
fn set_filename<T: BytesContainer>(&mut self, filename: T) {
assert!(!contains_nul(&filename));
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the extension contains a NUL.
+ /// Panics the task if the extension contains a NUL.
fn set_extension<T: BytesContainer>(&mut self, extension: T) {
assert!(!contains_nul(&extension));
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the filename contains a NUL.
+ /// Panics the task if the filename contains a NUL.
#[inline]
fn with_filename<T: BytesContainer>(&self, filename: T) -> Self {
let mut p = self.clone();
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the extension contains a NUL.
+ /// Panics the task if the extension contains a NUL.
#[inline]
fn with_extension<T: BytesContainer>(&self, extension: T) -> Self {
let mut p = self.clone();
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the path contains a NUL.
+ /// Panics the task if the path contains a NUL.
#[inline]
fn push<T: BytesContainer>(&mut self, path: T) {
assert!(!contains_nul(&path));
/// # }
/// ```
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the path contains a NUL.
+ /// Panics the task if the path contains a NUL.
#[inline]
fn join<T: BytesContainer>(&self, path: T) -> Self {
let mut p = self.clone();
impl Path {
/// Returns a new Path from a byte vector or string
///
- /// # Failure
+ /// # Panics
///
- /// Fails the task if the vector contains a NUL.
+ /// Panics the task if the vector contains a NUL.
#[inline]
pub fn new<T: BytesContainer>(path: T) -> Path {
GenericPath::new(path)
impl GenericPathUnsafe for Path {
/// See `GenericPathUnsafe::from_vec_unchecked`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if not valid UTF-8.
+ /// Panics if not valid UTF-8.
#[inline]
unsafe fn new_unchecked<T: BytesContainer>(path: T) -> Path {
let (prefix, path) = Path::normalize_(path.container_as_str().unwrap());
/// See `GenericPathUnsafe::set_filename_unchecked`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if not valid UTF-8.
+ /// Panics if not valid UTF-8.
unsafe fn set_filename_unchecked<T: BytesContainer>(&mut self, filename: T) {
let filename = filename.container_as_str().unwrap();
match self.sepidx_or_prefix_len() {
impl Path {
/// Returns a new `Path` from a `BytesContainer`.
///
- /// # Failure
+ /// # Panics
///
- /// Fails if the vector contains a `NUL`, or if it contains invalid UTF-8.
+ /// Panics if the vector contains a `NUL`, or if it contains invalid UTF-8.
///
/// # Example
///
//! "rendezvous" channel where each sender atomically hands off a message to
//! a receiver.
//!
-//! ## Failure Propagation
+//! ## Panic Propagation
//!
//! In addition to being a core primitive for communicating in rust, channels
//! are the points at which panics are propagated among tasks. Whenever the one
/// Access the underlying data immutably. May run concurrently with other
/// reading tasks.
///
- /// # Failure
+ /// # Panics
///
- /// Failing will unlock the lock while unwinding. However, unlike all other
+ /// Panicking will unlock the lock while unwinding. However, unlike all other
/// access modes, this will not poison the lock.
pub fn read<'a>(&'a self) -> RWLockReadGuard<'a, T> {
let guard = self.lock.read();
/// Load MetricDiff from a file.
///
- /// # Failure
+ /// # Panics
///
/// This function will panic if the path does not exist or the path does not
/// contain a valid metric map.
projects / rust.git / commitdiff