self.set(insert_pos, elem);
}
- /// Return the total number of bits in this vector
+ /// Returns the total number of bits in this vector
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> usize { self.nbits }
self.other_op(other, |w1, w2| w1 ^ w2);
}
- /// Return the number of set bits in this set.
+ /// Returns the number of set bits in this set.
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> usize {
Values { inner: self.iter().map(second) }
}
- /// Return the number of elements in the map.
+ /// Returns the number of elements in the map.
///
/// # Examples
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> usize { self.length }
- /// Return true if the map contains no elements.
+ /// Returns true if the map contains no elements.
///
/// # Examples
///
Union{a: self.iter().peekable(), b: other.iter().peekable()}
}
- /// Return the number of elements in the set
+ /// Returns the number of elements in the set.
///
/// # Examples
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> usize { self.map.len() }
- /// Returns true if the set contains no elements
+ /// Returns true if the set contains no elements.
///
/// # Examples
///
core_slice::SliceExt::binary_search_by(self, f)
}
- /// Return the number of elements in the slice
+ /// Returns the number of elements in the slice.
///
/// # Example
///
core_slice::SliceExt::get_unchecked_mut(self, index)
}
- /// Return an unsafe mutable pointer to the slice's buffer.
+ /// Returns an unsafe mutable pointer to the slice's buffer.
///
/// The caller must ensure that the slice outlives the pointer this
/// function returns, or else it will end up pointing to garbage.
core_slice::SliceExt::ends_with(self, needle)
}
- /// Convert `self` into a vector without clones or allocation.
+ /// Converts `self` into a vector without clones or allocation.
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
pub fn into_vec(self: Box<Self>) -> Vec<T> {
core_str::StrExt::trim_right_matches(&self[..], pat)
}
- /// Check that `index`-th byte lies at the start and/or end of a
+ /// Checks that `index`-th byte lies at the start and/or end of a
/// UTF-8 code point sequence.
///
/// The start and end of the string (when `index == self.len()`) are
core_str::StrExt::char_at_reverse(&self[..], i)
}
- /// Convert `self` to a byte slice.
+ /// Converts `self` to a byte slice.
///
/// # Examples
///
core_str::StrExt::subslice_offset(&self[..], inner)
}
- /// Return an unsafe pointer to the `&str`'s buffer.
+ /// Returns an unsafe pointer to the `&str`'s buffer.
///
/// The caller must ensure that the string outlives this pointer, and
/// that it is not
core_str::StrExt::as_ptr(&self[..])
}
- /// Return an iterator of `u16` over the string encoded as UTF-16.
+ /// Returns an iterator of `u16` over the string encoded as UTF-16.
#[unstable(feature = "collections",
reason = "this functionality may only be provided by libunicode")]
pub fn utf16_units(&self) -> Utf16Units {
String { vec: bytes }
}
- /// Return the underlying byte buffer, encoded as UTF-8.
+ /// Returns the underlying byte buffer, encoded as UTF-8.
///
/// # Examples
///
self.vec
}
- /// Extract a string slice containing the entire string.
+ /// Extracts a string slice containing the entire string.
#[inline]
#[unstable(feature = "convert",
reason = "waiting on RFC revision")]
ch
}
- /// Insert a character into the string buffer at byte position `idx`.
+ /// Inserts a character into the string buffer at byte position `idx`.
///
/// # Warning
///
&mut self.vec
}
- /// Return the number of bytes in this string.
+ /// Returns the number of bytes in this string.
///
/// # Examples
///
}
impl FromUtf8Error {
- /// Consume this error, returning the bytes that were attempted to make a
+ /// Consumes this error, returning the bytes that were attempted to make a
/// `String` with.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn into_bytes(self) -> Vec<u8> { self.bytes }
- /// Access the underlying UTF8-error that was the cause of this error.
+ /// Accesss the underlying UTF8-error that was the cause of this error.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn utf8_error(&self) -> Utf8Error { self.error }
}
}
}
-/// Convert a string slice to a wrapper type providing a `&String` reference.
+/// Converts a string slice to a wrapper type providing a `&String` reference.
///
/// # Examples
///
}
}
- /// Convert the vector into Box<[T]>.
+ /// Converts the vector into Box<[T]>.
///
/// Note that this will drop any excess capacity. Calling this and
/// converting back to a vector with `into_vec()` is equivalent to calling
}
}
- /// Extract a slice containing the entire vector.
+ /// Extracts a slice containing the entire vector.
#[inline]
#[unstable(feature = "convert",
reason = "waiting on RFC revision")]
}
}
-/// Convert a slice to a wrapper type providing a `&Vec<T>` reference.
+/// Converts a slice to a wrapper type providing a `&Vec<T>` reference.
#[unstable(feature = "collections")]
pub fn as_vec<'a, T>(x: &'a [T]) -> DerefVec<'a, T> {
unsafe {
}
}
- /// Shorten a ringbuf, dropping excess elements from the back.
+ /// Shortens a ringbuf, dropping excess elements from the back.
///
/// If `len` is greater than the ringbuf's current length, this has no
/// effect.
Drain { iter: self.v.drain().enumerate().filter_map(filter) }
}
- /// Return the number of elements in the map.
+ /// Returns the number of elements in the map.
///
/// # Examples
///
self.v.iter().filter(|elt| elt.is_some()).count()
}
- /// Return true if the map contains no elements.
+ /// Returns true if the map contains no elements.
///
/// # Examples
///
/// [mod]: index.html
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Any: Reflect + 'static {
- /// Get the `TypeId` of `self`
+ /// Gets the `TypeId` of `self`.
#[unstable(feature = "core",
reason = "this method will likely be replaced by an associated static")]
fn get_type_id(&self) -> TypeId;
}
}
- /// Get a reference to the underlying `UnsafeCell`.
+ /// Gets a reference to the underlying `UnsafeCell`.
///
/// # Unsafety
///
}
}
- /// Get a reference to the underlying `UnsafeCell`.
+ /// Gets a reference to the underlying `UnsafeCell`.
///
/// This can be used to circumvent `RefCell`'s safety checks.
///
}
}
-/// Copy a `Ref`.
+/// Copies a `Ref`.
///
/// The `RefCell` is already immutably borrowed, so this cannot fail.
///
impl<T> !Sync for UnsafeCell<T> {}
impl<T> UnsafeCell<T> {
- /// Construct a new instance of `UnsafeCell` which will wrap the specified
+ /// Constructs a new instance of `UnsafeCell` which will wrap the specified
/// value.
///
/// All access to the inner value through methods is `unsafe`, and it is highly discouraged to
&self.value as *const T as *mut T
}
- /// Unwraps the value
+ /// Unwraps the value.
///
/// # Unsafety
///
#[stable(feature = "rust1", since = "1.0.0")]
fn clone(&self) -> Self;
- /// Perform copy-assignment from `source`.
+ /// Performs copy-assignment from `source`.
///
/// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality,
/// but can be overridden to reuse the resources of `a` to avoid unnecessary
#[stable(feature = "rust1", since = "1.0.0")]
impl<'a, T: ?Sized> Clone for &'a T {
- /// Return a shallow copy of the reference.
+ /// Returns a shallow copy of the reference.
#[inline]
fn clone(&self) -> &'a T { *self }
}
($t:ty) => {
#[stable(feature = "rust1", since = "1.0.0")]
impl Clone for $t {
- /// Return a deep copy of the value.
+ /// Returns a deep copy of the value.
#[inline]
fn clone(&self) -> $t { *self }
}
#[unstable(feature = "core",
reason = "this may not be sufficient for fns with region parameters")]
impl<$($A,)* ReturnType> Clone for extern "Rust" fn($($A),*) -> ReturnType {
- /// Return a copy of a function pointer
+ /// Returns a copy of a function pointer.
#[inline]
fn clone(&self) -> extern "Rust" fn($($A),*) -> ReturnType { *self }
}
#[unstable(feature = "core", reason = "brand new")]
impl<$($A,)* ReturnType> Clone for extern "C" fn($($A),*) -> ReturnType {
- /// Return a copy of a function pointer
+ /// Returns a copy of a function pointer.
#[inline]
fn clone(&self) -> extern "C" fn($($A),*) -> ReturnType { *self }
}
#[unstable(feature = "core", reason = "brand new")]
impl<$($A,)* ReturnType> Clone for unsafe extern "Rust" fn($($A),*) -> ReturnType {
- /// Return a copy of a function pointer
+ /// Returns a copy of a function pointer.
#[inline]
fn clone(&self) -> unsafe extern "Rust" fn($($A),*) -> ReturnType { *self }
}
#[unstable(feature = "core", reason = "brand new")]
impl<$($A,)* ReturnType> Clone for unsafe extern "C" fn($($A),*) -> ReturnType {
- /// Return a copy of a function pointer
+ /// Returns a copy of a function pointer.
#[inline]
fn clone(&self) -> unsafe extern "C" fn($($A),*) -> ReturnType { *self }
}
pub fn atomic_fence_rel();
pub fn atomic_fence_acqrel();
- /// Abort the execution of the process.
+ /// Aborts the execution of the process.
pub fn abort() -> !;
- /// Tell LLVM that this point in the code is not reachable,
+ /// Tells LLVM that this point in the code is not reachable,
/// enabling further optimizations.
///
/// NB: This is very different from the `unreachable!()` macro!
pub fn unreachable() -> !;
- /// Inform the optimizer that a condition is always true.
+ /// Informs the optimizer that a condition is always true.
/// If the condition is false, the behavior is undefined.
///
/// No code is generated for this intrinsic, but the optimizer will try
/// own, or if it does not enable any significant optimizations.
pub fn assume(b: bool);
- /// Execute a breakpoint trap, for inspection by a debugger.
+ /// Executes a breakpoint trap, for inspection by a debugger.
pub fn breakpoint();
/// The size of a type in bytes.
/// elements.
pub fn size_of<T>() -> usize;
- /// Move a value to an uninitialized memory location.
+ /// Moves a value to an uninitialized memory location.
///
/// Drop glue is not run on the destination.
pub fn move_val_init<T>(dst: &mut T, src: T);
/// crate it is invoked in.
pub fn type_id<T: ?Sized + 'static>() -> u64;
- /// Create a value initialized to so that its drop flag,
+ /// Creates a value initialized to so that its drop flag,
/// if any, says that it has been dropped.
///
/// `init_dropped` is unsafe because it returns a datum with all
/// intrinsic).
pub fn init_dropped<T>() -> T;
- /// Create a value initialized to zero.
+ /// Creates a value initialized to zero.
///
/// `init` is unsafe because it returns a zeroed-out datum,
/// which is unsafe unless T is `Copy`. Also, even if T is
/// state for the type in question.
pub fn init<T>() -> T;
- /// Create an uninitialized value.
+ /// Creates an uninitialized value.
///
/// `uninit` is unsafe because there is no guarantee of what its
/// contents are. In particular its drop-flag may be set to any
/// initialize memory previous set to the result of `uninit`.
pub fn uninit<T>() -> T;
- /// Move a value out of scope without running drop glue.
+ /// Moves a value out of scope without running drop glue.
///
/// `forget` is unsafe because the caller is responsible for
/// ensuring the argument is deallocated already.
#[stable(feature = "rust1", since = "1.0.0")]
type Item;
- /// Advance the iterator and return the next value. Return `None` when the
+ /// Advances the iterator and returns the next value. Returns `None` when the
/// end is reached.
#[stable(feature = "rust1", since = "1.0.0")]
fn next(&mut self) -> Option<Self::Item>;
None
}
- /// Return the index of the first element satisfying the specified predicate
+ /// Returns the index of the first element satisfying the specified predicate
///
/// Does not consume the iterator past the first found element.
///
None
}
- /// Return the index of the last element satisfying the specified predicate
+ /// Returns the index of the last element satisfying the specified predicate
///
/// If no element matches, None is returned.
///
MinMax(min, max)
}
- /// Return the element that gives the maximum value from the
+ /// Returns the element that gives the maximum value from the
/// specified function.
///
/// Returns the rightmost element if the comparison determines two elements
.map(|(_, x)| x)
}
- /// Return the element that gives the minimum value from the
+ /// Returns the element that gives the minimum value from the
/// specified function.
///
/// Returns the leftmost element if the comparison determines two elements
#[rustc_on_unimplemented="a collection of type `{Self}` cannot be \
built from an iterator over elements of type `{A}`"]
pub trait FromIterator<A> {
- /// Build a container with elements from something iterable.
+ /// Builds a container with elements from something iterable.
///
/// # Examples
///
/// A type growable from an `Iterator` implementation
#[stable(feature = "rust1", since = "1.0.0")]
pub trait Extend<A> {
- /// Extend a container with the elements yielded by an arbitrary iterator
+ /// Extends a container with the elements yielded by an arbitrary iterator
#[stable(feature = "rust1", since = "1.0.0")]
fn extend<T: IntoIterator<Item=A>>(&mut self, iterable: T);
}
/// independently of each other.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait DoubleEndedIterator: Iterator {
- /// Yield an element from the end of the range, returning `None` if the
+ /// Yields an element from the end of the range, returning `None` if the
/// range is empty.
#[stable(feature = "rust1", since = "1.0.0")]
fn next_back(&mut self) -> Option<Self::Item>;
reason = "not widely used, may be better decomposed into Index \
and ExactSizeIterator")]
pub trait RandomAccessIterator: Iterator {
- /// Return the number of indexable elements. At most `std::usize::MAX`
+ /// Returns the number of indexable elements. At most `std::usize::MAX`
/// elements are indexable, even if the iterator represents a longer range.
fn indexable(&self) -> usize;
- /// Return an element at an index, or `None` if the index is out of bounds
+ /// Returns an element at an index, or `None` if the index is out of bounds
fn idx(&mut self, index: usize) -> Option<Self::Item>;
}
pub trait ExactSizeIterator: Iterator {
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
- /// Return the exact length of the iterator.
+ /// Returns the exact length of the iterator.
fn len(&self) -> usize {
let (lower, upper) = self.size_hint();
// Note: This assertion is overly defensive, but it checks the invariant
#[stable(feature = "rust1", since = "1.0.0")]
impl<I: Iterator> Peekable<I> {
- /// Return a reference to the next element of the iterator with out
+ /// Returns a reference to the next element of the iterator with out
/// advancing it, or None if the iterator is exhausted.
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
}
}
- /// Check whether peekable iterator is empty or not.
+ /// Checks whether peekable iterator is empty or not.
#[inline]
pub fn is_empty(&mut self) -> bool {
self.peek().is_none()
/// Steps `self` if possible.
fn step(&self, by: &Self) -> Option<Self>;
- /// The number of steps between two step objects.
+ /// Returns the number of steps between two step objects.
///
/// `start` should always be less than `end`, so the result should never
/// be negative.
///
- /// Return `None` if it is not possible to calculate steps_between
+ /// Returns `None` if it is not possible to calculate steps_between
/// without overflow.
fn steps_between(start: &Self, end: &Self, by: &Self) -> Option<usize>;
}
done: bool,
}
-/// Return an iterator over the range [start, stop]
+/// Returns an iterator over the range [start, stop].
#[inline]
#[unstable(feature = "core",
reason = "likely to be replaced by range notation and adapters")]
done: bool,
}
-/// Return an iterator over the range [start, stop] by `step`.
+/// Returns an iterator over the range [start, stop] by `step`.
///
/// It handles overflow by stopping.
///
#[unstable(feature = "core")]
pub type Iterate<T, F> = Unfold<IterateState<T, F>, fn(&mut IterateState<T, F>) -> Option<T>>;
-/// Create a new iterator that produces an infinite sequence of
+/// Creates a new iterator that produces an infinite sequence of
/// repeated applications of the given function `f`.
#[unstable(feature = "core")]
pub fn iterate<T, F>(seed: T, f: F) -> Iterate<T, F> where
Unfold::new((f, Some(seed), true), next)
}
-/// Create a new iterator that endlessly repeats the element `elt`.
+/// Creates a new iterator that endlessly repeats the element `elt`.
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn repeat<T: Clone>(elt: T) -> Repeat<T> {
}
}
- /// Compare `a` and `b` for nonequality (Using partial equality, `PartialEq`)
+ /// Compares `a` and `b` for nonequality (Using partial equality, `PartialEq`)
pub fn ne<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
L::Item: PartialEq<R::Item>,
{
}
}
- /// Return `a` < `b` lexicographically (Using partial order, `PartialOrd`)
+ /// Returns `a` < `b` lexicographically (Using partial order, `PartialOrd`)
pub fn lt<R: Iterator, L: Iterator>(mut a: L, mut b: R) -> bool where
L::Item: PartialOrd<R::Item>,
{
}
}
- /// Return `a` <= `b` lexicographically (Using partial order, `PartialOrd`)
+ /// Returns `a` <= `b` lexicographically (Using partial order, `PartialOrd`)
pub fn le<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
L::Item: PartialOrd<R::Item>,
{
}
}
- /// Return `a` > `b` lexicographically (Using partial order, `PartialOrd`)
+ /// Returns `a` > `b` lexicographically (Using partial order, `PartialOrd`)
pub fn gt<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
L::Item: PartialOrd<R::Item>,
{
}
}
- /// Return `a` >= `b` lexicographically (Using partial order, `PartialOrd`)
+ /// Returns `a` >= `b` lexicographically (Using partial order, `PartialOrd`)
pub fn ge<L: Iterator, R: Iterator>(mut a: L, mut b: R) -> bool where
L::Item: PartialOrd<R::Item>,
{
align_of::<T>()
}
-/// Create a value initialized to zero.
+/// Creates a value initialized to zero.
///
/// This function is similar to allocating space for a local variable and zeroing it out (an unsafe
/// operation).
intrinsics::init()
}
-/// Create a value initialized to an unspecified series of bytes.
+/// Creates a value initialized to an unspecified series of bytes.
///
/// The byte sequence usually indicates that the value at the memory
/// in question has been dropped. Thus, *if* T carries a drop flag,
dropped_impl()
}
-/// Create an uninitialized value.
+/// Creates an uninitialized value.
///
/// Care must be taken when using this function, if the type `T` has a destructor and the value
/// falls out of scope (due to unwinding or returning) before being initialized, then the
}
}
-/// Replace the value at a mutable location with a new one, returning the old value, without
+/// Replaces the value at a mutable location with a new one, returning the old value, without
/// deinitialising or copying either one.
///
/// This is primarily used for transferring and swapping ownership of a value in a mutable
pub struct NonZero<T: Zeroable>(T);
impl<T: Zeroable> NonZero<T> {
- /// Create an instance of NonZero with the provided value.
+ /// Creates an instance of NonZero with the provided value.
/// You must indeed ensure that the value is actually "non-zero".
#[inline(always)]
pub unsafe fn new(inner: T) -> NonZero<T> {
#[stable(feature = "rust1", since = "1.0.0")]
fn swap_bytes(self) -> Self;
- /// Convert an integer from big endian to the target's endianness.
+ /// Converts an integer from big endian to the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are swapped.
///
if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
}
- /// Convert an integer from little endian to the target's endianness.
+ /// Converts an integer from little endian to the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are swapped.
///
if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
}
- /// Convert `self` to big endian from the target's endianness.
+ /// Converts `self` to big endian from the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are swapped.
///
if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
}
- /// Convert `self` to little endian from the target's endianness.
+ /// Converts `self` to little endian from the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are swapped.
///
let min: $T = Int::min_value(); !min
}
- /// Convert a string slice in a given base to an integer.
+ /// Converts a string slice in a given base to an integer.
///
/// Leading and trailing whitespace represent an error.
///
(self as $UnsignedT).swap_bytes() as $T
}
- /// Convert an integer from big endian to the target's endianness.
+ /// Converts an integer from big endian to the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are
/// swapped.
if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
}
- /// Convert an integer from little endian to the target's endianness.
+ /// Converts an integer from little endian to the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are
/// swapped.
if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
}
- /// Convert `self` to big endian from the target's endianness.
+ /// Converts `self` to big endian from the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are
/// swapped.
if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
}
- /// Convert `self` to little endian from the target's endianness.
+ /// Converts `self` to little endian from the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are
/// swapped.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn max_value() -> $T { !0 }
- /// Convert a string slice in a given base to an integer.
+ /// Converts a string slice in a given base to an integer.
///
/// Leading and trailing whitespace represent an error.
///
unsafe { $bswap(self as $ActualT) as $T }
}
- /// Convert an integer from big endian to the target's endianness.
+ /// Converts an integer from big endian to the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are
/// swapped.
if cfg!(target_endian = "big") { x } else { x.swap_bytes() }
}
- /// Convert an integer from little endian to the target's endianness.
+ /// Converts an integer from little endian to the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are
/// swapped.
if cfg!(target_endian = "little") { x } else { x.swap_bytes() }
}
- /// Convert `self` to big endian from the target's endianness.
+ /// Converts `self` to big endian from the target's endianness.
///
/// On big endian this is a no-op. On little endian the bytes are
/// swapped.
if cfg!(target_endian = "big") { self } else { self.swap_bytes() }
}
- /// Convert `self` to little endian from the target's endianness.
+ /// Converts `self` to little endian from the target's endianness.
///
/// On little endian this is a no-op. On big endian the bytes are
/// swapped.
/// A generic trait for converting a number to a value.
#[unstable(feature = "core", reason = "trait is likely to be removed")]
pub trait FromPrimitive : ::marker::Sized {
- /// Convert an `isize` to return an optional value of this type. If the
+ /// Converts an `isize` to return an optional value of this type. If the
/// value cannot be represented by this value, the `None` is returned.
#[inline]
#[unstable(feature = "core")]
FromPrimitive::from_i64(n as i64)
}
- /// Convert an `isize` to return an optional value of this type. If the
+ /// Converts an `isize` to return an optional value of this type. If the
/// value cannot be represented by this value, the `None` is returned.
#[inline]
fn from_isize(n: isize) -> Option<Self> {
FromPrimitive::from_i64(n as i64)
}
- /// Convert an `i8` to return an optional value of this type. If the
+ /// Converts an `i8` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_i8(n: i8) -> Option<Self> {
FromPrimitive::from_i64(n as i64)
}
- /// Convert an `i16` to return an optional value of this type. If the
+ /// Converts an `i16` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_i16(n: i16) -> Option<Self> {
FromPrimitive::from_i64(n as i64)
}
- /// Convert an `i32` to return an optional value of this type. If the
+ /// Converts an `i32` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_i32(n: i32) -> Option<Self> {
FromPrimitive::from_i64(n as i64)
}
- /// Convert an `i64` to return an optional value of this type. If the
+ /// Converts an `i64` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
fn from_i64(n: i64) -> Option<Self>;
- /// Convert an `usize` to return an optional value of this type. If the
+ /// Converts an `usize` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
#[unstable(feature = "core")]
FromPrimitive::from_u64(n as u64)
}
- /// Convert a `usize` to return an optional value of this type. If the
+ /// Converts a `usize` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_usize(n: usize) -> Option<Self> {
FromPrimitive::from_u64(n as u64)
}
- /// Convert an `u8` to return an optional value of this type. If the
+ /// Converts an `u8` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_u8(n: u8) -> Option<Self> {
FromPrimitive::from_u64(n as u64)
}
- /// Convert an `u16` to return an optional value of this type. If the
+ /// Converts an `u16` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_u16(n: u16) -> Option<Self> {
FromPrimitive::from_u64(n as u64)
}
- /// Convert an `u32` to return an optional value of this type. If the
+ /// Converts an `u32` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_u32(n: u32) -> Option<Self> {
FromPrimitive::from_u64(n as u64)
}
- /// Convert an `u64` to return an optional value of this type. If the
+ /// Converts an `u64` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
fn from_u64(n: u64) -> Option<Self>;
- /// Convert a `f32` to return an optional value of this type. If the
+ /// Converts a `f32` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_f32(n: f32) -> Option<Self> {
FromPrimitive::from_f64(n as f64)
}
- /// Convert a `f64` to return an optional value of this type. If the
+ /// Converts a `f64` to return an optional value of this type. If the
/// type cannot be represented by this value, the `None` is returned.
#[inline]
fn from_f64(n: f64) -> Option<Self> {
impl_from_primitive! { f32, to_f32 }
impl_from_primitive! { f64, to_f64 }
-/// Cast from one machine scalar to another.
+/// Casts from one machine scalar to another.
///
/// # Examples
///
/// Returns the mantissa, exponent and sign as integers, respectively.
fn integer_decode(self) -> (u64, i16, i8);
- /// Return the largest integer less than or equal to a number.
+ /// Returns the largest integer less than or equal to a number.
fn floor(self) -> Self;
- /// Return the smallest integer greater than or equal to a number.
+ /// Returns the smallest integer greater than or equal to a number.
fn ceil(self) -> Self;
- /// Return the nearest integer to a number. Round half-way cases away from
+ /// Returns the nearest integer to a number. Round half-way cases away from
/// `0.0`.
fn round(self) -> Self;
- /// Return the integer part of a number.
+ /// Returns the integer part of a number.
fn trunc(self) -> Self;
- /// Return the fractional part of a number.
+ /// Returns the fractional part of a number.
fn fract(self) -> Self;
/// Computes the absolute value of `self`. Returns `Float::nan()` if the
/// error. This produces a more accurate result with better performance than
/// a separate multiplication operation followed by an add.
fn mul_add(self, a: Self, b: Self) -> Self;
- /// Take the reciprocal (inverse) of a number, `1/x`.
+ /// Takes the reciprocal (inverse) of a number, `1/x`.
fn recip(self) -> Self;
- /// Raise a number to an integer power.
+ /// Raises a number to an integer power.
///
/// Using this function is generally faster than using `powf`
fn powi(self, n: i32) -> Self;
- /// Raise a number to a floating point power.
+ /// Raises a number to a floating point power.
fn powf(self, n: Self) -> Self;
- /// Take the square root of a number.
+ /// Takes the square root of a number.
///
/// Returns NaN if `self` is a negative number.
fn sqrt(self) -> Self;
- /// Take the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
+ /// Takes the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
fn rsqrt(self) -> Self;
/// Returns `e^(self)`, (the exponential function).
/// Returns the base 10 logarithm of the number.
fn log10(self) -> Self;
- /// Convert radians to degrees.
+ /// Converts radians to degrees.
fn to_degrees(self) -> Self;
- /// Convert degrees to radians.
+ /// Converts degrees to radians.
fn to_radians(self) -> Self;
}
impl FromStr for $T {
type Err = ParseFloatError;
- /// Convert a string in base 10 to a float.
+ /// Converts a string in base 10 to a float.
/// Accepts an optional decimal exponent.
///
/// This function accepts strings such as
impl FromStrRadix for $T {
type Err = ParseFloatError;
- /// Convert a string in a given base to a float.
+ /// Converts a string in a given base to a float.
///
/// Due to possible conflicts, this function does **not** accept
/// the special values `inf`, `-inf`, `+inf` and `NaN`, **nor**
// Adapter for working with references
/////////////////////////////////////////////////////////////////////////
- /// Convert from `Option<T>` to `Option<&T>`
+ /// Converts from `Option<T>` to `Option<&T>`
///
/// # Examples
///
}
}
- /// Convert from `Option<T>` to `Option<&mut T>`
+ /// Converts from `Option<T>` to `Option<&mut T>`
///
/// # Examples
///
}
}
- /// Convert from `Option<T>` to `&mut [T]` (without copying)
+ /// Converts from `Option<T>` to `&mut [T]` (without copying)
///
/// # Examples
///
mem::replace(self, None)
}
- /// Convert from `Option<T>` to `&[T]` (without copying)
+ /// Converts from `Option<T>` to `&[T]` (without copying)
#[inline]
#[unstable(feature = "as_slice", since = "unsure of the utility here")]
pub fn as_slice<'a>(&'a self) -> &'a [T] {
unsafe impl<T: Sync + ?Sized> Sync for Unique<T> { }
impl<T: ?Sized> Unique<T> {
- /// Create a new `Unique`.
+ /// Creates a new `Unique`.
#[unstable(feature = "unique")]
pub unsafe fn new(ptr: *mut T) -> Unique<T> {
Unique { pointer: NonZero::new(ptr), _marker: PhantomData }
}
- /// Dereference the content.
+ /// Dereferences the content.
#[unstable(feature = "unique")]
pub unsafe fn get(&self) -> &T {
&**self.pointer
}
- /// Mutably dereference the content.
+ /// Mutably dereferences the content.
#[unstable(feature = "unique")]
pub unsafe fn get_mut(&mut self) -> &mut T {
&mut ***self
// Adapter for each variant
/////////////////////////////////////////////////////////////////////////
- /// Convert from `Result<T, E>` to `Option<T>`
+ /// Converts from `Result<T, E>` to `Option<T>`
///
/// Converts `self` into an `Option<T>`, consuming `self`,
/// and discarding the error, if any.
}
}
- /// Convert from `Result<T, E>` to `Option<E>`
+ /// Converts from `Result<T, E>` to `Option<E>`
///
/// Converts `self` into an `Option<E>`, consuming `self`,
/// and discarding the success value, if any.
// Adapter for working with references
/////////////////////////////////////////////////////////////////////////
- /// Convert from `Result<T, E>` to `Result<&T, &E>`
+ /// Converts from `Result<T, E>` to `Result<&T, &E>`
///
/// Produces a new `Result`, containing a reference
/// into the original, leaving the original in place.
}
}
- /// Convert from `Result<T, E>` to `Result<&mut T, &mut E>`
+ /// Converts from `Result<T, E>` to `Result<&mut T, &mut E>`
///
/// ```
/// fn mutate(r: &mut Result<i32, i32>) {
}
}
- /// Convert from `Result<T, E>` to `&[T]` (without copying)
+ /// Converts from `Result<T, E>` to `&[T]` (without copying)
#[inline]
#[unstable(feature = "as_slice", since = "unsure of the utility here")]
pub fn as_slice(&self) -> &[T] {
}
}
- /// Convert from `Result<T, E>` to `&mut [T]` (without copying)
+ /// Converts from `Result<T, E>` to `&mut [T]` (without copying)
///
/// ```
/// # #![feature(core)]
reason = "use inherent method instead")]
#[allow(deprecated)]
impl<T, E> AsSlice<T> for Result<T, E> {
- /// Convert from `Result<T, E>` to `&[T]` (without copying)
+ /// Converts from `Result<T, E>` to `&[T]` (without copying)
#[inline]
fn as_slice<'a>(&'a self) -> &'a [T] {
match *self {
// FromIterator
/////////////////////////////////////////////////////////////////////////////
-/// Perform a fold operation over the result values from an iterator.
+/// Performs a fold operation over the result values from an iterator.
///
/// If an `Err` is encountered, it is immediately returned.
/// Otherwise, the folded value is returned.
/// Associated searcher for this pattern
type Searcher: Searcher<'a>;
- /// Construct the associated searcher from
+ /// Constructs the associated searcher from
/// `self` and the `haystack` to search in.
fn into_searcher(self, haystack: &'a str) -> Self::Searcher;
- /// Check whether the pattern matches anywhere in the haystack
+ /// Checks whether the pattern matches anywhere in the haystack
#[inline]
fn is_contained_in(self, haystack: &'a str) -> bool {
self.into_searcher(haystack).next_match().is_some()
}
- /// Check whether the pattern matches at the front of the haystack
+ /// Checks whether the pattern matches at the front of the haystack
#[inline]
fn is_prefix_of(self, haystack: &'a str) -> bool {
match self.into_searcher(haystack).next() {
}
}
- /// Check whether the pattern matches at the back of the haystack
+ /// Checks whether the pattern matches at the back of the haystack
#[inline]
fn is_suffix_of(self, haystack: &'a str) -> bool
where Self::Searcher: ReverseSearcher<'a>
#[unstable(feature = "std_misc",
reason = "would prefer to do this in a more general way")]
pub trait OwnedAsciiExt {
- /// Convert the string to ASCII upper case:
+ /// Converts the string to ASCII upper case:
/// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
/// but non-ASCII letters are unchanged.
fn into_ascii_uppercase(self) -> Self;
- /// Convert the string to ASCII lower case:
+ /// Converts the string to ASCII lower case:
/// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
/// but non-ASCII letters are unchanged.
fn into_ascii_lowercase(self) -> Self;
#[stable(feature = "rust1", since = "1.0.0")]
type Owned;
- /// Check if within the ASCII range.
+ /// Checks if within the ASCII range.
///
/// # Examples
///
#[stable(feature = "rust1", since = "1.0.0")]
fn to_ascii_lowercase(&self) -> Self::Owned;
- /// Check that two strings are an ASCII case-insensitive match.
+ /// Checks that two strings are an ASCII case-insensitive match.
///
/// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
/// but without allocating and copying temporary strings.
#[stable(feature = "rust1", since = "1.0.0")]
fn eq_ignore_ascii_case(&self, other: &Self) -> bool;
- /// Convert this type to its ASCII upper case equivalent in-place.
+ /// Converts this type to its ASCII upper case equivalent in-place.
///
/// See `to_ascii_uppercase` for more information.
///
#[unstable(feature = "ascii")]
fn make_ascii_uppercase(&mut self);
- /// Convert this type to its ASCII lower case equivalent in-place.
+ /// Converts this type to its ASCII lower case equivalent in-place.
///
/// See `to_ascii_lowercase` for more information.
///
}
impl<K: Hash + Eq, V> HashMap<K, V, RandomState> {
- /// Create an empty HashMap.
+ /// Creates an empty HashMap.
///
/// # Examples
///
}
}
- /// Create an empty HashMap with space for at least `capacity`
+ /// Creates an empty HashMap with space for at least `capacity`
/// elements, using `hasher` to hash the keys.
///
/// Warning: `hasher` is normally randomly generated, and
#[unstable(feature = "std_misc",
reason = "hashing an hash maps may be altered")]
impl RandomState {
- /// Construct a new `RandomState` that is initialized with random keys.
+ /// Constructs a new `RandomState` that is initialized with random keys.
#[inline]
#[allow(deprecated)]
pub fn new() -> RandomState {
}
impl<T: Hash + Eq> HashSet<T, RandomState> {
- /// Create an empty HashSet.
+ /// Creates an empty HashSet.
///
/// # Examples
///
HashSet::with_capacity(INITIAL_CAPACITY)
}
- /// Create an empty HashSet with space for at least `n` elements in
+ /// Creates an empty HashSet with space for at least `n` elements in
/// the hash table.
///
/// # Examples
HashSet::with_capacity_and_hash_state(INITIAL_CAPACITY, hash_state)
}
- /// Create an empty HashSet with space for at least `capacity`
+ /// Creates an empty HashSet with space for at least `capacity`
/// elements in the hash table, using `hasher` to hash the keys.
///
/// Warning: `hasher` is normally randomly generated, and
Union { iter: self.iter().chain(other.difference(self)) }
}
- /// Return the number of elements in the set
+ /// Returns the number of elements in the set.
///
/// # Examples
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn len(&self) -> usize { self.map.len() }
- /// Returns true if the set contains no elements
+ /// Returns true if the set contains no elements.
///
/// # Examples
///
}
}
- /// Access the value at the symbol of the dynamic library
+ /// Accesses the value at the symbol of the dynamic library.
pub unsafe fn symbol<T>(&self, symbol: &str) -> Result<*mut T, String> {
// This function should have a lifetime constraint of 'a on
// T but that feature is still unimplemented
os_imp::setenv(k.as_ref(), v.as_ref())
}
-/// Remove an environment variable from the environment of the currently running process.
+/// Removes an environment variable from the environment of the currently running process.
///
/// # Examples
///
pub struct NulError(usize, Vec<u8>);
impl CString {
- /// Create a new C-compatible string from a container of bytes.
+ /// Creates a new C-compatible string from a container of bytes.
///
/// This method will consume the provided data and use the underlying bytes
/// to construct a new string, ensuring that there is a trailing 0 byte.
}
}
- /// Create a C-compatible string from a byte vector without checking for
+ /// Creates a C-compatible string from a byte vector without checking for
/// interior 0 bytes.
///
/// This method is equivalent to `from_vec` except that no runtime assertion
}
impl CStr {
- /// Cast a raw C string to a safe C string wrapper.
+ /// Casts a raw C string to a safe C string wrapper.
///
/// This function will cast the provided `ptr` to the `CStr` wrapper which
/// allows inspection and interoperation of non-owned C strings. This method
mem::transmute(slice::from_raw_parts(ptr, len as usize + 1))
}
- /// Return the inner pointer to this C string.
+ /// Returns the inner pointer to this C string.
///
/// The returned pointer will be valid for as long as `self` is and points
/// to a contiguous region of memory terminated with a 0 byte to represent
self.inner.as_ptr()
}
- /// Convert this C string to a byte slice.
+ /// Converts this C string to a byte slice.
///
/// This function will calculate the length of this string (which normally
/// requires a linear amount of work to be done) and then return the
&bytes[..bytes.len() - 1]
}
- /// Convert this C string to a byte slice containing the trailing 0 byte.
+ /// Converts this C string to a byte slice containing the trailing 0 byte.
///
/// This function is the equivalent of `to_bytes` except that it will retain
/// the trailing nul instead of chopping it off.
/// Freely convertible to an `&OsStr` slice.
#[unstable(feature = "std_misc")]
pub trait AsOsStr {
- /// Convert to an `&OsStr` slice.
+ /// Converts to an `&OsStr` slice.
fn as_os_str(&self) -> &OsStr;
}
OsString { inner: Buf::from_string(String::new()) }
}
- /// Construct an `OsString` from a byte sequence.
+ /// Constructs an `OsString` from a byte sequence.
///
/// # Platform behavior
///
from_bytes_inner(bytes.into())
}
- /// Convert to an `OsStr` slice.
+ /// Converts to an `OsStr` slice.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_os_str(&self) -> &OsStr {
self
}
- /// Convert the `OsString` into a `String` if it contains valid Unicode data.
+ /// Converts the `OsString` into a `String` if it contains valid Unicode data.
///
/// On failure, ownership of the original `OsString` is returned.
#[stable(feature = "rust1", since = "1.0.0")]
self.inner.into_string().map_err(|buf| OsString { inner: buf} )
}
- /// Extend the string with the given `&OsStr` slice.
+ /// Extends the string with the given `&OsStr` slice.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn push<T: AsRef<OsStr>>(&mut self, s: T) {
self.inner.push_slice(&s.as_ref().inner)
}
impl OsStr {
- /// Coerce into an `OsStr` slice.
+ /// Coerces into an `OsStr` slice.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new<S: AsRef<OsStr> + ?Sized>(s: &S) -> &OsStr {
s.as_ref()
}
- /// Coerce directly from a `&str` slice to a `&OsStr` slice.
+ /// Coerces directly from a `&str` slice to a `&OsStr` slice.
#[stable(feature = "rust1", since = "1.0.0")]
#[deprecated(since = "1.0.0",
reason = "use `OsStr::new` instead")]
unsafe { mem::transmute(Slice::from_str(s)) }
}
- /// Yield a `&str` slice if the `OsStr` is valid unicode.
+ /// Yields a `&str` slice if the `OsStr` is valid unicode.
///
/// This conversion may entail doing a check for UTF-8 validity.
#[stable(feature = "rust1", since = "1.0.0")]
self.inner.to_str()
}
- /// Convert an `OsStr` to a `Cow<str>`.
+ /// Converts an `OsStr` to a `Cow<str>`.
///
/// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
#[stable(feature = "rust1", since = "1.0.0")]
self.inner.to_string_lossy()
}
- /// Copy the slice into an owned `OsString`.
+ /// Copies the slice into an owned `OsString`.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn to_os_string(&self) -> OsString {
OsString { inner: self.inner.to_owned() }
}
- /// Yield this `OsStr` as a byte slice.
+ /// Yields this `OsStr` as a byte slice.
///
/// # Platform behavior
///
}
}
- /// Create a `CString` containing this `OsStr` data.
+ /// Creates a `CString` containing this `OsStr` data.
///
/// Fails if the `OsStr` contains interior nulls.
///
self.to_bytes().and_then(|b| CString::new(b).ok())
}
- /// Get the underlying byte representation.
+ /// Gets the underlying byte representation.
///
/// Note: it is *crucial* that this API is private, to avoid
/// revealing the internal, platform-specific encodings.
OpenOptions::new().read(true).open(path)
}
- /// Open a file in write-only mode.
+ /// Opens a file in write-only mode.
///
/// This function will create a file if it does not exist,
/// and will truncate it if it does.
self.path.as_ref().map(|p| &**p)
}
- /// Attempt to sync all OS-internal metadata to disk.
+ /// Attempts to sync all OS-internal metadata to disk.
///
/// This function will attempt to ensure that all in-core data reaches the
/// filesystem before returning.
OpenOptions(fs_imp::OpenOptions::new())
}
- /// Set the option for read access.
+ /// Sets the option for read access.
///
/// This option, when true, will indicate that the file should be
/// `read`-able if opened.
self.0.read(read); self
}
- /// Set the option for write access.
+ /// Sets the option for write access.
///
/// This option, when true, will indicate that the file should be
/// `write`-able if opened.
self.0.write(write); self
}
- /// Set the option for the append mode.
+ /// Sets the option for the append mode.
///
/// This option, when true, means that writes will append to a file instead
/// of overwriting previous contents.
self.0.append(append); self
}
- /// Set the option for truncating a previous file.
+ /// Sets the option for truncating a previous file.
///
/// If a file is successfully opened with this option set it will truncate
/// the file to 0 length if it already exists.
self.0.truncate(truncate); self
}
- /// Set the option for creating a new file.
+ /// Sets the option for creating a new file.
///
/// This option indicates whether a new file will be created if the file
/// does not yet already exist.
self.0.create(create); self
}
- /// Open a file at `path` with the options specified by `self`.
+ /// Opens a file at `path` with the options specified by `self`.
///
/// # Errors
///
#[stable(feature = "rust1", since = "1.0.0")]
pub fn readonly(&self) -> bool { self.0.readonly() }
- /// Modify the readonly flag for this set of permissions.
+ /// Modifies the readonly flag for this set of permissions.
///
/// This operation does **not** modify the filesystem. To modify the
/// filesystem use the `fs::set_permissions` function.
pub fn path(&self) -> PathBuf { self.0.path() }
}
-/// Remove a file from the underlying filesystem.
+/// Removes a file from the underlying filesystem.
///
/// Note that, just because an unlink call was successful, it is not
/// guaranteed that a file is immediately deleted (e.g. depending on
fs_imp::readlink(path.as_ref())
}
-/// Create a new, empty directory at the provided path
+/// Creates a new, empty directory at the provided path
///
/// # Errors
///
create_dir(path)
}
-/// Remove an existing, empty directory
+/// Removes an existing, empty directory.
///
/// # Errors
///
reason = "the precise set of methods exposed on this trait may \
change and some methods may be removed")]
pub trait PathExt {
- /// Get information on the file, directory, etc at this path.
+ /// Gets information on the file, directory, etc at this path.
///
/// Consult the `fs::stat` documentation for more info.
///
}
impl<T> Cursor<T> {
- /// Create a new cursor wrapping the provided underlying I/O object.
+ /// Creates a new cursor wrapping the provided underlying I/O object.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new(inner: T) -> Cursor<T> {
Cursor { pos: 0, inner: inner }
}
- /// Consume this cursor, returning the underlying value.
+ /// Consumes this cursor, returning the underlying value.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn into_inner(self) -> T { self.inner }
- /// Get a reference to the underlying value in this cursor.
+ /// Gets a reference to the underlying value in this cursor.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn get_ref(&self) -> &T { &self.inner }
- /// Get a mutable reference to the underlying value in this cursor.
+ /// Gets a mutable reference to the underlying value in this cursor.
///
/// Care should be taken to avoid modifying the internal I/O state of the
/// underlying value as it may corrupt this cursor's position.
}
}
- /// Return the corresponding `ErrorKind` for this error.
+ /// Returns the corresponding `ErrorKind` for this error.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn kind(&self) -> ErrorKind {
match self.repr {
append_to_string(buf, |b| read_to_end(self, b))
}
- /// Create a "by reference" adaptor for this instance of `Read`.
+ /// Creates a "by reference" adaptor for this instance of `Read`.
///
/// The returned adaptor also implements `Read` and will simply borrow this
/// current reader.
#[stable(feature = "rust1", since = "1.0.0")]
fn by_ref(&mut self) -> &mut Self where Self: Sized { self }
- /// Transform this `Read` instance to an `Iterator` over its bytes.
+ /// Transforms this `Read` instance to an `Iterator` over its bytes.
///
/// The returned type implements `Iterator` where the `Item` is `Result<u8,
/// R::Err>`. The yielded item is `Ok` if a byte was successfully read and
Bytes { inner: self }
}
- /// Transform this `Read` instance to an `Iterator` over `char`s.
+ /// Transforms this `Read` instance to an `Iterator` over `char`s.
///
/// This adaptor will attempt to interpret this reader as an UTF-8 encoded
/// sequence of characters. The returned iterator will return `None` once
Chars { inner: self }
}
- /// Create an adaptor which will chain this stream with another.
+ /// Creates an adaptor which will chain this stream with another.
///
/// The returned `Read` instance will first read all bytes from this object
/// until EOF is encountered. Afterwards the output is equivalent to the
Chain { first: self, second: next, done_first: false }
}
- /// Create an adaptor which will read at most `limit` bytes from it.
+ /// Creates an adaptor which will read at most `limit` bytes from it.
///
/// This function returns a new instance of `Read` which will read at most
/// `limit` bytes, after which it will always return EOF (`Ok(0)`). Any
}
}
- /// Create a "by reference" adaptor for this instance of `Write`.
+ /// Creates a "by reference" adaptor for this instance of `Write`.
///
/// The returned adaptor also implements `Write` and will simply borrow this
/// current writer.
/// the `std::io::stdio::stderr_raw` function.
struct StderrRaw(stdio::Stderr);
-/// Construct a new raw handle to the standard input of this process.
+/// Constructs a new raw handle to the standard input of this process.
///
/// The returned handle does not interact with any other handles created nor
/// handles returned by `std::io::stdin`. Data buffered by the `std::io::stdin`
/// The returned handle has no external synchronization or buffering.
fn stdin_raw() -> StdinRaw { StdinRaw(stdio::Stdin::new()) }
-/// Construct a new raw handle to the standard input stream of this process.
+/// Constructs a new raw handle to the standard input stream of this process.
///
/// The returned handle does not interact with any other handles created nor
/// handles returned by `std::io::stdout`. Note that data is buffered by the
/// top.
fn stdout_raw() -> StdoutRaw { StdoutRaw(stdio::Stdout::new()) }
-/// Construct a new raw handle to the standard input stream of this process.
+/// Constructs a new raw handle to the standard input stream of this process.
///
/// The returned handle does not interact with any other handles created nor
/// handles returned by `std::io::stdout`.
inner: MutexGuard<'a, BufReader<StdinRaw>>,
}
-/// Create a new handle to the global standard input stream of this process.
+/// Creates a new handle to the global standard input stream of this process.
///
/// The handle returned refers to a globally shared buffer between all threads.
/// Access is synchronized and can be explicitly controlled with the `lock()`
}
impl Stdin {
- /// Lock this handle to the standard input stream, returning a readable
+ /// Locks this handle to the standard input stream, returning a readable
/// guard.
///
/// The lock is released when the returned lock goes out of scope. The
}
impl Stdout {
- /// Lock this handle to the standard output stream, returning a writable
+ /// Locks this handle to the standard output stream, returning a writable
/// guard.
///
/// The lock is released when the returned lock goes out of scope. The
}
impl Stderr {
- /// Lock this handle to the standard error stream, returning a writable
+ /// Locks this handle to the standard error stream, returning a writable
/// guard.
///
/// The lock is released when the returned lock goes out of scope. The
}
impl Ipv4Addr {
- /// Create a new IPv4 address from four eight-bit octets.
+ /// Creates a new IPv4 address from four eight-bit octets.
///
/// The result will represent the IP address a.b.c.d
#[stable(feature = "rust1", since = "1.0.0")]
self.octets()[0] >= 224 && self.octets()[0] <= 239
}
- /// Convert this address to an IPv4-compatible IPv6 address
+ /// Converts this address to an IPv4-compatible IPv6 address
///
/// a.b.c.d becomes ::a.b.c.d
#[stable(feature = "rust1", since = "1.0.0")]
((self.octets()[2] as u16) << 8) | self.octets()[3] as u16)
}
- /// Convert this address to an IPv4-mapped IPv6 address
+ /// Converts this address to an IPv4-mapped IPv6 address
///
/// a.b.c.d becomes ::ffff:a.b.c.d
#[stable(feature = "rust1", since = "1.0.0")]
}
impl Ipv6Addr {
- /// Create a new IPv6 address from eight 16-bit segments.
+ /// Creates a new IPv6 address from eight 16-bit segments.
///
/// The result will represent the IP address a:b:c:d:e:f:g:h
#[stable(feature = "rust1", since = "1.0.0")]
}
}
- /// Return the eight 16-bit segments that make up this address
+ /// Returns the eight 16-bit segments that make up this address
#[stable(feature = "rust1", since = "1.0.0")]
pub fn segments(&self) -> [u16; 8] {
[ntoh(self.inner.s6_addr[0]),
(self.segments()[0] & 0xff00) == 0xff00
}
- /// Convert this address to an IPv4 address. Returns None if this address is
+ /// Converts this address to an IPv4 address. Returns None if this address is
/// neither IPv4-compatible or IPv4-mapped.
///
/// ::a.b.c.d and ::ffff:a.b.c.d become a.b.c.d
pub struct Incoming<'a> { listener: &'a TcpListener }
impl TcpStream {
- /// Open a TCP connection to a remote host.
+ /// Opens a TCP connection to a remote host.
///
/// `addr` is an address of the remote host. Anything which implements
/// `ToSocketAddrs` trait can be supplied for the address; see this trait
self.0.socket_addr()
}
- /// Shut down the read, write, or both halves of this connection.
+ /// Shuts down the read, write, or both halves of this connection.
///
/// This function will cause all pending and future I/O on the specified
/// portions to return immediately with an appropriate value (see the
self.0.shutdown(how)
}
- /// Create a new independently owned handle to the underlying socket.
+ /// Creates a new independently owned handle to the underlying socket.
///
/// The returned `TcpStream` is a reference to the same stream that this
/// object references. Both handles will read and write the same stream of
self.0.socket_addr()
}
- /// Create a new independently owned handle to the underlying socket.
+ /// Creates a new independently owned handle to the underlying socket.
///
/// The returned `TcpListener` is a reference to the same socket that this
/// object references. Both handles can be used to accept incoming
self.0.socket_addr()
}
- /// Create a new independently owned handle to the underlying socket.
+ /// Creates a new independently owned handle to the underlying socket.
///
/// The returned `UdpSocket` is a reference to the same socket that this
/// object references. Both handles will read and write the same port, and
self.0.set_broadcast(on)
}
- /// Set the multicast loop flag to the specified value
+ /// Sets the multicast loop flag to the specified value
///
/// This lets multicast packets loop back to local sockets (if enabled)
pub fn set_multicast_loop(&self, on: bool) -> io::Result<()> {
#[inline]
pub fn round(self) -> f32 { num::Float::round(self) }
- /// Return the integer part of a number.
+ /// Returns the integer part of a number.
///
/// ```
/// let f = 3.3_f32;
#[inline]
pub fn mul_add(self, a: f32, b: f32) -> f32 { num::Float::mul_add(self, a, b) }
- /// Take the reciprocal (inverse) of a number, `1/x`.
+ /// Takes the reciprocal (inverse) of a number, `1/x`.
///
/// ```
/// use std::f32;
#[inline]
pub fn recip(self) -> f32 { num::Float::recip(self) }
- /// Raise a number to an integer power.
+ /// Raises a number to an integer power.
///
/// Using this function is generally faster than using `powf`
///
#[inline]
pub fn powi(self, n: i32) -> f32 { num::Float::powi(self, n) }
- /// Raise a number to a floating point power.
+ /// Raises a number to a floating point power.
///
/// ```
/// use std::f32;
#[inline]
pub fn powf(self, n: f32) -> f32 { num::Float::powf(self, n) }
- /// Take the square root of a number.
+ /// Takes the square root of a number.
///
/// Returns NaN if `self` is a negative number.
///
#[inline]
pub fn sqrt(self) -> f32 { num::Float::sqrt(self) }
- /// Take the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
+ /// Takes the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
///
/// ```
/// # #![feature(std_misc)]
#[inline]
pub fn log10(self) -> f32 { num::Float::log10(self) }
- /// Convert radians to degrees.
+ /// Converts radians to degrees.
///
/// ```
/// # #![feature(std_misc)]
#[inline]
pub fn to_degrees(self) -> f32 { num::Float::to_degrees(self) }
- /// Convert degrees to radians.
+ /// Converts degrees to radians.
///
/// ```
/// # #![feature(std_misc)]
unsafe { cmath::fdimf(self, other) }
}
- /// Take the cubic root of a number.
+ /// Takes the cubic root of a number.
///
/// ```
/// use std::f32;
unsafe { cmath::cbrtf(self) }
}
- /// Calculate the length of the hypotenuse of a right-angle triangle given
+ /// Calculates the length of the hypotenuse of a right-angle triangle given
/// legs of length `x` and `y`.
///
/// ```
#[inline]
pub fn round(self) -> f64 { num::Float::round(self) }
- /// Return the integer part of a number.
+ /// Returns the integer part of a number.
///
/// ```
/// let f = 3.3_f64;
#[inline]
pub fn mul_add(self, a: f64, b: f64) -> f64 { num::Float::mul_add(self, a, b) }
- /// Take the reciprocal (inverse) of a number, `1/x`.
+ /// Takes the reciprocal (inverse) of a number, `1/x`.
///
/// ```
/// let x = 2.0_f64;
#[inline]
pub fn recip(self) -> f64 { num::Float::recip(self) }
- /// Raise a number to an integer power.
+ /// Raises a number to an integer power.
///
/// Using this function is generally faster than using `powf`
///
#[inline]
pub fn powi(self, n: i32) -> f64 { num::Float::powi(self, n) }
- /// Raise a number to a floating point power.
+ /// Raises a number to a floating point power.
///
/// ```
/// let x = 2.0_f64;
#[inline]
pub fn powf(self, n: f64) -> f64 { num::Float::powf(self, n) }
- /// Take the square root of a number.
+ /// Takes the square root of a number.
///
/// Returns NaN if `self` is a negative number.
///
#[inline]
pub fn sqrt(self) -> f64 { num::Float::sqrt(self) }
- /// Take the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
+ /// Takes the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
///
/// ```
/// # #![feature(std_misc)]
#[inline]
pub fn log10(self) -> f64 { num::Float::log10(self) }
- /// Convert radians to degrees.
+ /// Converts radians to degrees.
///
/// ```
/// use std::f64::consts;
#[inline]
pub fn to_degrees(self) -> f64 { num::Float::to_degrees(self) }
- /// Convert degrees to radians.
+ /// Converts degrees to radians.
///
/// ```
/// use std::f64::consts;
unsafe { cmath::fdim(self, other) }
}
- /// Take the cubic root of a number.
+ /// Takes the cubic root of a number.
///
/// ```
/// let x = 8.0_f64;
unsafe { cmath::cbrt(self) }
}
- /// Calculate the length of the hypotenuse of a right-angle triangle given
+ /// Calculates the length of the hypotenuse of a right-angle triangle given
/// legs of length `x` and `y`.
///
/// ```
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn round(self) -> Self;
- /// Return the integer part of a number.
+ /// Returns the integer part of a number.
///
/// ```
/// use std::num::Float;
#[unstable(feature = "std_misc",
reason = "unsure about its place in the world")]
fn mul_add(self, a: Self, b: Self) -> Self;
- /// Take the reciprocal (inverse) of a number, `1/x`.
+ /// Takes the reciprocal (inverse) of a number, `1/x`.
///
/// ```
/// # #![feature(std_misc)]
reason = "unsure about its place in the world")]
fn recip(self) -> Self;
- /// Raise a number to an integer power.
+ /// Raises a number to an integer power.
///
/// Using this function is generally faster than using `powf`
///
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn powi(self, n: i32) -> Self;
- /// Raise a number to a floating point power.
+ /// Raises a number to a floating point power.
///
/// ```
/// use std::num::Float;
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn powf(self, n: Self) -> Self;
- /// Take the square root of a number.
+ /// Takes the square root of a number.
///
/// Returns NaN if `self` is a negative number.
///
#[stable(feature = "rust1", since = "1.0.0")]
fn sqrt(self) -> Self;
- /// Take the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
+ /// Takes the reciprocal (inverse) square root of a number, `1/sqrt(x)`.
///
/// ```
/// # #![feature(std_misc)]
#[stable(feature = "rust1", since = "1.0.0")]
fn log10(self) -> Self;
- /// Convert radians to degrees.
+ /// Converts radians to degrees.
///
/// ```
/// use std::num::Float;
/// ```
#[unstable(feature = "std_misc", reason = "desirability is unclear")]
fn to_degrees(self) -> Self;
- /// Convert degrees to radians.
+ /// Converts degrees to radians.
///
/// ```
/// # #![feature(std_misc)]
/// ```
#[unstable(feature = "std_misc", reason = "may be renamed")]
fn abs_sub(self, other: Self) -> Self;
- /// Take the cubic root of a number.
+ /// Takes the cubic root of a number.
///
/// ```
/// # #![feature(std_misc)]
/// ```
#[unstable(feature = "std_misc", reason = "may be renamed")]
fn cbrt(self) -> Self;
- /// Calculate the length of the hypotenuse of a right-angle triangle given
+ /// Calculates the length of the hypotenuse of a right-angle triangle given
/// legs of length `x` and `y`.
///
/// ```
}
- /// Determine if the prefix is verbatim, i.e. begins `\\?\`.
+ /// Determines if the prefix is verbatim, i.e. begins `\\?\`.
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_verbatim(&self) -> bool {
// Exposed parsing helpers
////////////////////////////////////////////////////////////////////////////////
-/// Determine whether the character is one of the permitted path
+/// Determines whether the character is one of the permitted path
/// separators for the current platform.
///
/// # Examples
}
impl<'a> Component<'a> {
- /// Extract the underlying `OsStr` slice
+ /// Extracts the underlying `OsStr` slice
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_os_str(self) -> &'a OsStr {
match self {
}
}
- /// Extract a slice corresponding to the portion of the path remaining for iteration.
+ /// Extracts a slice corresponding to the portion of the path remaining for iteration.
///
/// # Examples
///
}
impl<'a> Iter<'a> {
- /// Extract a slice corresponding to the portion of the path remaining for iteration.
+ /// Extracts a slice corresponding to the portion of the path remaining for iteration.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_path(&self) -> &'a Path {
self.inner.as_path()
unsafe { mem::transmute(self) }
}
- /// Allocate an empty `PathBuf`.
+ /// Allocates an empty `PathBuf`.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new() -> PathBuf {
PathBuf { inner: OsString::new() }
}
- /// Coerce to a `Path` slice.
+ /// Coerces to a `Path` slice.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn as_path(&self) -> &Path {
self
}
- /// Extend `self` with `path`.
+ /// Extends `self` with `path`.
///
/// If `path` is absolute, it replaces the current path.
///
true
}
- /// Consume the `PathBuf`, yielding its internal `OsString` storage
+ /// Consumes the `PathBuf`, yielding its internal `OsString` storage.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn into_os_string(self) -> OsString {
self.inner
unsafe { mem::transmute(s.as_ref()) }
}
- /// Yield the underlying `OsStr` slice.
+ /// Yields the underlying `OsStr` slice.
///
/// # Examples
///
&self.inner
}
- /// Yield a `&str` slice if the `Path` is valid unicode.
+ /// Yields a `&str` slice if the `Path` is valid unicode.
///
/// This conversion may entail doing a check for UTF-8 validity.
///
self.inner.to_str()
}
- /// Convert a `Path` to a `Cow<str>`.
+ /// Converts a `Path` to a `Cow<str>`.
///
/// Any non-Unicode sequences are replaced with U+FFFD REPLACEMENT CHARACTER.
///
self.inner.to_string_lossy()
}
- /// Convert a `Path` to an owned `PathBuf`.
+ /// Converts a `Path` to an owned `PathBuf`.
///
/// # Examples
///
iter_after(self.components().rev(), child.as_ref().components().rev()).is_some()
}
- /// Extract the stem (non-extension) portion of `self.file()`.
+ /// Extracts the stem (non-extension) portion of `self.file()`.
///
/// The stem is:
///
self.file_name().map(split_file_at_dot).and_then(|(before, after)| before.or(after))
}
- /// Extract the extension of `self.file()`, if possible.
+ /// Extracts the extension of `self.file()`, if possible.
///
/// The extension is:
///
#[unstable(feature = "std_misc")]
#[deprecated(since = "1.0.0", reason = "use std::convert::AsRef<Path> instead")]
pub trait AsPath {
- /// Convert to a `Path`.
+ /// Converts to a `Path`.
#[unstable(feature = "std_misc")]
fn as_path(&self) -> &Path;
}
self
}
- /// Set the working directory for the child process.
+ /// Sets the working directory for the child process.
#[stable(feature = "process", since = "1.0.0")]
pub fn current_dir<P: AsRef<path::Path>>(&mut self, dir: P) -> &mut Command {
self.inner.cwd(dir.as_ref().as_ref());
self.0.success()
}
- /// Return the exit code of the process, if any.
+ /// Returns the exit code of the process, if any.
///
/// On Unix, this will return `None` if the process was terminated
/// by a signal; `std::os::unix` provides an extension trait for
unsafe { self.handle.kill() }
}
- /// Wait for the child to exit completely, returning the status that it
+ /// Waits for the child to exit completely, returning the status that it
/// exited with. This function will continue to have the same return value
/// after it has been called at least once.
///
}
}
- /// Simultaneously wait for the child to exit and collect all remaining
+ /// Simultaneously waits for the child to exit and collect all remaining
/// output on the stdout/stderr handles, returning a `Output`
/// instance.
///
pub struct BarrierWaitResult(bool);
impl Barrier {
- /// Create a new barrier that can block a given number of threads.
+ /// Creates a new barrier that can block a given number of threads.
///
/// A barrier will block `n`-1 threads which call `wait` and then wake up
/// all threads at once when the `n`th thread calls `wait`.
}
}
- /// Block the current thread until all threads has rendezvoused here.
+ /// Blocks the current thread until all threads has rendezvoused here.
///
/// Barriers are re-usable after all threads have rendezvoused once, and can
/// be used continuously.
}
impl BarrierWaitResult {
- /// Return whether this thread from `wait` is the "leader thread".
+ /// Returns whether this thread from `wait` is the "leader thread".
///
/// Only one thread will have `true` returned from their result, all other
/// threads will have `false` returned.
}
}
- /// Block the current thread until this condition variable receives a
+ /// Blocks the current thread until this condition variable receives a
/// notification.
///
/// This function will atomically unlock the mutex specified (represented by
}
}
- /// Wait on this condition variable for a notification, timing out after a
+ /// Waits on this condition variable for a notification, timing out after a
/// specified duration.
///
/// The semantics of this function are equivalent to `wait()`
self.wait_timeout_ms(guard, dur.num_milliseconds() as u32)
}
- /// Wait on this condition variable for a notification, timing out after a
+ /// Waits on this condition variable for a notification, timing out after a
/// specified duration.
///
/// The semantics of this function are equivalent to `wait_timeout` except
}
}
- /// Wake up one blocked thread on this condvar.
+ /// Wakes up one blocked thread on this condvar.
///
/// If there is a blocked thread on this condition variable, then it will
/// be woken up from its call to `wait` or `wait_timeout`. Calls to
#[stable(feature = "rust1", since = "1.0.0")]
pub fn notify_one(&self) { unsafe { self.inner.inner.notify_one() } }
- /// Wake up all blocked threads on this condvar.
+ /// Wakes up all blocked threads on this condvar.
///
/// This method will ensure that any current waiters on the condition
/// variable are awoken. Calls to `notify_all()` are not buffered in any
}
impl StaticCondvar {
- /// Block the current thread until this condition variable receives a
+ /// Blocks the current thread until this condition variable receives a
/// notification.
///
/// See `Condvar::wait`.
}
}
- /// Wait on this condition variable for a notification, timing out after a
+ /// Waits on this condition variable for a notification, timing out after a
/// specified duration.
///
/// See `Condvar::wait_timeout`.
}
}
- /// Wait on this condition variable for a notification, timing out after a
+ /// Waits on this condition variable for a notification, timing out after a
/// specified duration.
///
/// The implementation will repeatedly wait while the duration has not
poison::map_result(guard_result, |g| (g, true))
}
- /// Wake up one blocked thread on this condvar.
+ /// Wakes up one blocked thread on this condvar.
///
/// See `Condvar::notify_one`.
#[unstable(feature = "std_misc",
reason = "may be merged with Condvar in the future")]
pub fn notify_one(&'static self) { unsafe { self.inner.notify_one() } }
- /// Wake up all blocked threads on this condvar.
+ /// Wakes up all blocked threads on this condvar.
///
/// See `Condvar::notify_all`.
#[unstable(feature = "std_misc",
reason = "may be merged with Condvar in the future")]
pub fn notify_all(&'static self) { unsafe { self.inner.notify_all() } }
- /// Deallocate all resources associated with this static condvar.
+ /// Deallocates all resources associated with this static condvar.
///
/// This method is unsafe to call as there is no guarantee that there are no
/// active users of the condvar, and this also doesn't prevent any future
}
}
- /// Attempt to wait for a value on this receiver, returning an error if the
+ /// Attempts to wait for a value on this receiver, returning an error if the
/// corresponding channel has hung up.
///
/// This function will always block the current thread if there is no data
}
impl<'rx, T: Send> Handle<'rx, T> {
- /// Retrieve the id of this handle.
+ /// Retrieves the id of this handle.
#[inline]
pub fn id(&self) -> usize { self.id }
- /// Block to receive a value on the underlying receiver, returning `Some` on
+ /// Blocks to receive a value on the underlying receiver, returning `Some` on
/// success or `None` if the channel disconnects. This function has the same
/// semantics as `Receiver.recv`
pub fn recv(&mut self) -> Result<T, RecvError> { self.rx.recv() }
}
}
- /// Determine whether the lock is poisoned.
+ /// Determines whether the lock is poisoned.
///
/// If another thread is active, the lock can still become poisoned at any
/// time. You should not trust a `false` value for program correctness
};
impl Once {
- /// Perform an initialization routine once and only once. The given closure
+ /// Performs an initialization routine once and only once. The given closure
/// will be executed if this is the first time `call_once` has been called,
/// and otherwise the routine will *not* be invoked.
///
RwLockReadGuard::new(&*self.inner, &self.data)
}
- /// Attempt to acquire this lock with shared read access.
+ /// Attempts to acquire this lock with shared read access.
///
/// This function will never block and will return immediately if `read`
/// would otherwise succeed. Returns `Some` of an RAII guard which will
}
}
- /// Lock this rwlock with exclusive write access, blocking the current
+ /// Locks this rwlock with exclusive write access, blocking the current
/// thread until it can be acquired.
///
/// This function will not return while other writers or other readers
RwLockWriteGuard::new(&*self.inner, &self.data)
}
- /// Attempt to lock this rwlock with exclusive write access.
+ /// Attempts to lock this rwlock with exclusive write access.
///
/// This function does not ever block, and it will return `None` if a call
/// to `write` would otherwise block. If successful, an RAII guard is
}
}
- /// Determine whether the lock is poisoned.
+ /// Determines whether the lock is poisoned.
///
/// If another thread is active, the lock can still become poisoned at any
/// time. You should not trust a `false` value for program correctness
RwLockReadGuard::new(self, &DUMMY.0)
}
- /// Attempt to acquire this lock with shared read access.
+ /// Attempts to acquire this lock with shared read access.
///
/// See `RwLock::try_read`.
#[inline]
}
}
- /// Lock this rwlock with exclusive write access, blocking the current
+ /// Locks this rwlock with exclusive write access, blocking the current
/// thread until it can be acquired.
///
/// See `RwLock::write`.
RwLockWriteGuard::new(self, &DUMMY.0)
}
- /// Attempt to lock this rwlock with exclusive write access.
+ /// Attempts to lock this rwlock with exclusive write access.
///
/// See `RwLock::try_write`.
#[inline]
}
}
- /// Deallocate all resources associated with this static lock.
+ /// Deallocates all resources associated with this static lock.
///
/// This method is unsafe to call as there is no guarantee that there are no
/// active users of the lock, and this also doesn't prevent any future users
#[inline]
pub unsafe fn new() -> Condvar { Condvar(imp::Condvar::new()) }
- /// Signal one waiter on this condition variable to wake up.
+ /// Signals one waiter on this condition variable to wake up.
#[inline]
pub unsafe fn notify_one(&self) { self.0.notify_one() }
- /// Awaken all current waiters on this condition variable.
+ /// Awakens all current waiters on this condition variable.
#[inline]
pub unsafe fn notify_all(&self) { self.0.notify_all() }
- /// Wait for a signal on the specified mutex.
+ /// Waits for a signal on the specified mutex.
///
/// Behavior is undefined if the mutex is not locked by the current thread.
/// Behavior is also undefined if more than one mutex is used concurrently
#[inline]
pub unsafe fn wait(&self, mutex: &Mutex) { self.0.wait(mutex::raw(mutex)) }
- /// Wait for a signal on the specified mutex with a timeout duration
+ /// Waits for a signal on the specified mutex with a timeout duration
/// specified by `dur` (a relative time into the future).
///
/// Behavior is undefined if the mutex is not locked by the current thread.
self.0.wait_timeout(mutex::raw(mutex), dur)
}
- /// Deallocate all resources associated with this condition variable.
+ /// Deallocates all resources associated with this condition variable.
///
/// Behavior is undefined if there are current or will be future users of
/// this condition variable.
pub const MUTEX_INIT: Mutex = Mutex(imp::MUTEX_INIT);
impl Mutex {
- /// Lock the mutex blocking the current thread until it is available.
+ /// Locks the mutex blocking the current thread until it is available.
///
/// Behavior is undefined if the mutex has been moved between this and any
/// previous function call.
#[inline]
pub unsafe fn lock(&self) { self.0.lock() }
- /// Attempt to lock the mutex without blocking, returning whether it was
+ /// Attempts to lock the mutex without blocking, returning whether it was
/// successfully acquired or not.
///
/// Behavior is undefined if the mutex has been moved between this and any
#[inline]
pub unsafe fn try_lock(&self) -> bool { self.0.try_lock() }
- /// Unlock the mutex.
+ /// Unlocks the mutex.
///
/// Behavior is undefined if the current thread does not actually hold the
/// mutex.
#[inline]
pub unsafe fn unlock(&self) { self.0.unlock() }
- /// Deallocate all resources associated with this mutex.
+ /// Deallocates all resources associated with this mutex.
///
/// Behavior is undefined if there are current or will be future users of
/// this mutex.
}
impl<T> PoisonError<T> {
- /// Create a `PoisonError`.
+ /// Creates a `PoisonError`.
#[unstable(feature = "std_misc")]
pub fn new(guard: T) -> PoisonError<T> {
PoisonError { guard: guard }
pub const RWLOCK_INIT: RWLock = RWLock(imp::RWLOCK_INIT);
impl RWLock {
- /// Acquire shared access to the underlying lock, blocking the current
+ /// Acquires shared access to the underlying lock, blocking the current
/// thread to do so.
///
/// Behavior is undefined if the rwlock has been moved between this and any
#[inline]
pub unsafe fn read(&self) { self.0.read() }
- /// Attempt to acquire shared access to this lock, returning whether it
+ /// Attempts to acquire shared access to this lock, returning whether it
/// succeeded or not.
///
/// This function does not block the current thread.
#[inline]
pub unsafe fn try_read(&self) -> bool { self.0.try_read() }
- /// Acquire write access to the underlying lock, blocking the current thread
+ /// Acquires write access to the underlying lock, blocking the current thread
/// to do so.
///
/// Behavior is undefined if the rwlock has been moved between this and any
#[inline]
pub unsafe fn write(&self) { self.0.write() }
- /// Attempt to acquire exclusive access to this lock, returning whether it
+ /// Attempts to acquire exclusive access to this lock, returning whether it
/// succeeded or not.
///
/// This function does not block the current thread.
#[inline]
pub unsafe fn try_write(&self) -> bool { self.0.try_write() }
- /// Unlock previously acquired shared access to this lock.
+ /// Unlocks previously acquired shared access to this lock.
///
/// Behavior is undefined if the current thread does not have shared access.
#[inline]
pub unsafe fn read_unlock(&self) { self.0.read_unlock() }
- /// Unlock previously acquired exclusive access to this lock.
+ /// Unlocks previously acquired exclusive access to this lock.
///
/// Behavior is undefined if the current thread does not currently have
/// exclusive access.
#[inline]
pub unsafe fn write_unlock(&self) { self.0.write_unlock() }
- /// Destroy OS-related resources with this RWLock.
+ /// Destroys OS-related resources with this RWLock.
///
/// Behavior is undefined if there are any currently active users of this
/// lock.
}
impl Key {
- /// Create a new managed OS TLS key.
+ /// Creates a new managed OS TLS key.
///
/// This key will be deallocated when the key falls out of scope.
///
}
impl CodePoint {
- /// Unsafely create a new `CodePoint` without checking the value.
+ /// Unsafely creates a new `CodePoint` without checking the value.
///
/// Only use when `value` is known to be less than or equal to 0x10FFFF.
#[inline]
CodePoint { value: value }
}
- /// Create a new `CodePoint` if the value is a valid code point.
+ /// Creates a new `CodePoint` if the value is a valid code point.
///
- /// Return `None` if `value` is above 0x10FFFF.
+ /// Returns `None` if `value` is above 0x10FFFF.
#[inline]
pub fn from_u32(value: u32) -> Option<CodePoint> {
match value {
}
}
- /// Create a new `CodePoint` from a `char`.
+ /// Creates a new `CodePoint` from a `char`.
///
/// Since all Unicode scalar values are code points, this always succeeds.
#[inline]
CodePoint { value: value as u32 }
}
- /// Return the numeric value of the code point.
+ /// Returns the numeric value of the code point.
#[inline]
pub fn to_u32(&self) -> u32 {
self.value
}
- /// Optionally return a Unicode scalar value for the code point.
+ /// Optionally returns a Unicode scalar value for the code point.
///
- /// Return `None` if the code point is a surrogate (from U+D800 to U+DFFF).
+ /// Returns `None` if the code point is a surrogate (from U+D800 to U+DFFF).
#[inline]
pub fn to_char(&self) -> Option<char> {
match self.value {
}
}
- /// Return a Unicode scalar value for the code point.
+ /// Returns a Unicode scalar value for the code point.
///
- /// Return `'\u{FFFD}'` (the replacement character “�”)
+ /// Returns `'\u{FFFD}'` (the replacement character “�”)
/// if the code point is a surrogate (from U+D800 to U+DFFF).
#[inline]
pub fn to_char_lossy(&self) -> char {
}
impl Wtf8Buf {
- /// Create an new, empty WTF-8 string.
+ /// Creates an new, empty WTF-8 string.
#[inline]
pub fn new() -> Wtf8Buf {
Wtf8Buf { bytes: Vec::new() }
}
- /// Create an new, empty WTF-8 string with pre-allocated capacity for `n` bytes.
+ /// Creates an new, empty WTF-8 string with pre-allocated capacity for `n` bytes.
#[inline]
pub fn with_capacity(n: usize) -> Wtf8Buf {
Wtf8Buf { bytes: Vec::with_capacity(n) }
}
- /// Create a WTF-8 string from an UTF-8 `String`.
+ /// Creates a WTF-8 string from an UTF-8 `String`.
///
/// This takes ownership of the `String` and does not copy.
///
Wtf8Buf { bytes: string.into_bytes() }
}
- /// Create a WTF-8 string from an UTF-8 `&str` slice.
+ /// Creates a WTF-8 string from an UTF-8 `&str` slice.
///
/// This copies the content of the slice.
///
Wtf8Buf { bytes: <[_]>::to_vec(str.as_bytes()) }
}
- /// Create a WTF-8 string from a potentially ill-formed UTF-16 slice of 16-bit code units.
+ /// Creates a WTF-8 string from a potentially ill-formed UTF-16 slice of 16-bit code units.
///
/// This is lossless: calling `.encode_wide()` on the resulting string
/// will always return the original code units.
self.bytes.truncate(new_len)
}
- /// Consume the WTF-8 string and try to convert it to UTF-8.
+ /// Consumes the WTF-8 string and tries to convert it to UTF-8.
///
/// This does not copy the data.
///
}
}
- /// Consume the WTF-8 string and convert it lossily to UTF-8.
+ /// Consumes the WTF-8 string and converts it lossily to UTF-8.
///
/// This does not copy the data (but may overwrite parts of it in place).
///
}
impl Wtf8 {
- /// Create a WTF-8 slice from a UTF-8 `&str` slice.
+ /// Creates a WTF-8 slice from a UTF-8 `&str` slice.
///
/// Since WTF-8 is a superset of UTF-8, this always succeeds.
#[inline]
unsafe { mem::transmute(value.as_bytes()) }
}
- /// Return the length, in WTF-8 bytes.
+ /// Returns the length, in WTF-8 bytes.
#[inline]
pub fn len(&self) -> usize {
self.bytes.len()
}
- /// Return the code point at `position` if it is in the ASCII range,
+ /// Returns the code point at `position` if it is in the ASCII range,
/// or `b'\xFF' otherwise.
///
/// # Panics
}
}
- /// Return the code point at `position`.
+ /// Returns the code point at `position`.
///
/// # Panics
///
code_point
}
- /// Return the code point at `position`
+ /// Returns the code point at `position`
/// and the position of the next code point.
///
/// # Panics
(CodePoint { value: c }, n)
}
- /// Return an iterator for the string’s code points.
+ /// Returns an iterator for the string’s code points.
#[inline]
pub fn code_points(&self) -> Wtf8CodePoints {
Wtf8CodePoints { bytes: self.bytes.iter() }
}
- /// Try to convert the string to UTF-8 and return a `&str` slice.
+ /// Tries to convert the string to UTF-8 and return a `&str` slice.
///
- /// Return `None` if the string contains surrogates.
+ /// Returns `None` if the string contains surrogates.
///
/// This does not copy the data.
#[inline]
}
}
- /// Lossily convert the string to UTF-8.
- /// Return an UTF-8 `&str` slice if the contents are well-formed in UTF-8.
+ /// Lossily converts the string to UTF-8.
+ /// Returns an UTF-8 `&str` slice if the contents are well-formed in UTF-8.
///
/// Surrogates are replaced with `"\u{FFFD}"` (the replacement character “�”).
///
}
}
- /// Convert the WTF-8 string to potentially ill-formed UTF-16
+ /// Converts the WTF-8 string to potentially ill-formed UTF-16
/// and return an iterator of 16-bit code units.
///
/// This is lossless:
/// and `AsRawSocket` set of traits.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRawFd {
- /// Extract the raw file descriptor.
+ /// Extracts the raw file descriptor.
///
/// This method does **not** pass ownership of the raw file descriptor
/// to the caller. The descriptor is only guarantee to be valid while
/// Unix-specific extensions to `OsString`.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait OsStringExt {
- /// Create an `OsString` from a byte vector.
+ /// Creates an `OsString` from a byte vector.
#[stable(feature = "rust1", since = "1.0.0")]
fn from_vec(vec: Vec<u8>) -> Self;
- /// Yield the underlying byte vector of this `OsString`.
+ /// Yields the underlying byte vector of this `OsString`.
#[stable(feature = "rust1", since = "1.0.0")]
fn into_vec(self) -> Vec<u8>;
}
#[stable(feature = "rust1", since = "1.0.0")]
fn from_bytes(slice: &[u8]) -> &Self;
- /// Get the underlying byte view of the `OsStr` slice.
+ /// Gets the underlying byte view of the `OsStr` slice.
#[stable(feature = "rust1", since = "1.0.0")]
fn as_bytes(&self) -> &[u8];
}
/// Unix-specific extensions to `OpenOptions`
pub trait OpenOptionsExt {
- /// Set the mode bits that a new file will be created with.
+ /// Sets the mode bits that a new file will be created with.
///
/// If a new file is created as part of a `File::open_opts` call then this
/// specified `mode` will be used as the permission bits for the new file.
pub fn raw(&self) -> c_int { self.fd }
- /// Extract the actual filedescriptor without closing it.
+ /// Extracts the actual filedescriptor without closing it.
pub fn into_raw(self) -> c_int {
let fd = self.fd;
unsafe { mem::forget(self) };
}
}
- /// Extract the actual filedescriptor without closing it.
+ /// Extracts the actual filedescriptor without closing it.
pub fn unwrap(self) -> fd_t {
let fd = self.fd;
unsafe { mem::forget(self) };
err
}
-/// Convert an `errno` value into a high-level error variant and description.
+/// Converts an `errno` value into a high-level error variant and description.
#[allow(deprecated)]
pub fn decode_error(errno: i32) -> IoError {
// FIXME: this should probably be a bit more descriptive...
}
}
-/// Get a detailed string description for the given error number
+/// Gets a detailed string description for the given error number.
pub fn error_string(errno: i32) -> String {
#[cfg(target_os = "linux")]
extern {
/// Extract raw handles.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRawHandle {
- /// Extract the raw handle, without taking any ownership.
+ /// Extracts the raw handle, without taking any ownership.
#[stable(feature = "rust1", since = "1.0.0")]
fn as_raw_handle(&self) -> RawHandle;
}
#[unstable(feature = "from_raw_os",
reason = "recent addition to the std::os::windows::io module")]
pub trait FromRawHandle {
- /// Construct a new I/O object from the specified raw handle.
+ /// Constructs a new I/O object from the specified raw handle.
///
/// This function will **consume ownership** of the handle given,
/// passing responsibility for closing the handle to the returned
/// Extract raw sockets.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait AsRawSocket {
- /// Extract the underlying raw socket from this object.
+ /// Extracts the underlying raw socket from this object.
#[stable(feature = "rust1", since = "1.0.0")]
fn as_raw_socket(&self) -> RawSocket;
}
/// Windows-specific extensions to `OsString`.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait OsStringExt {
- /// Create an `OsString` from a potentially ill-formed UTF-16 slice of
+ /// Creates an `OsString` from a potentially ill-formed UTF-16 slice of
/// 16-bit code units.
///
/// This is lossless: calling `.encode_wide()` on the resulting string
/// Windows-specific extensions to `OsStr`.
#[stable(feature = "rust1", since = "1.0.0")]
pub trait OsStrExt {
- /// Re-encode an `OsStr` as a wide character sequence,
+ /// Re-encodes an `OsStr` as a wide character sequence,
/// i.e. potentially ill-formed UTF-16.
///
/// This is lossless. Note that the encoding does not include a final
/// Windows-specific extensions to `OpenOptions`
pub trait OpenOptionsExt {
- /// Override the `dwDesiredAccess` argument to the call to `CreateFile`
+ /// Overrides the `dwDesiredAccess` argument to the call to `CreateFile`
/// with the specified value.
fn desired_access(&mut self, access: i32) -> &mut Self;
- /// Override the `dwCreationDisposition` argument to the call to
+ /// Overrides the `dwCreationDisposition` argument to the call to
/// `CreateFile` with the specified value.
///
/// This will override any values of the standard `create` flags, for
/// example.
fn creation_disposition(&mut self, val: i32) -> &mut Self;
- /// Override the `dwFlagsAndAttributes` argument to the call to
+ /// Overrides the `dwFlagsAndAttributes` argument to the call to
/// `CreateFile` with the specified value.
///
/// This will override any values of the standard flags on the
/// `OpenOptions` structure.
fn flags_and_attributes(&mut self, val: i32) -> &mut Self;
- /// Override the `dwShareMode` argument to the call to `CreateFile` with
+ /// Overrides the `dwShareMode` argument to the call to `CreateFile` with
/// the specified value.
///
/// This will override any values of the standard flags on the
last_net_error()
}
-/// Convert an `errno` value into a high-level error variant and description.
+/// Converts an `errno` value into a high-level error variant and description.
#[allow(deprecated)]
pub fn decode_error(errno: i32) -> IoError {
let (kind, desc) = match errno {
unsafe { libc::GetLastError() as i32 }
}
-/// Get a detailed string description for the given error number
+/// Gets a detailed string description for the given error number.
pub fn error_string(errnum: i32) -> String {
use libc::types::os::arch::extra::DWORD;
use libc::types::os::arch::extra::LPWSTR;
}
impl<T: 'static> LocalKey<T> {
- /// Acquire a reference to the value in this TLS key.
+ /// Acquires a reference to the value in this TLS key.
///
/// This will lazily initialize the value if this thread has not referenced
/// this key yet.
}
impl Builder {
- /// Generate the base configuration for spawning a thread, from which
+ /// Generates the base configuration for spawning a thread, from which
/// configuration methods can be chained.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn new() -> Builder {
}
}
- /// Name the thread-to-be. Currently the name is used for identification
+ /// Names the thread-to-be. Currently the name is used for identification
/// only in panic messages.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn name(mut self, name: String) -> Builder {
self
}
- /// Set the size of the stack for the new thread.
+ /// Sets the size of the stack for the new thread.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn stack_size(mut self, size: usize) -> Builder {
self.stack_size = Some(size);
self
}
- /// Spawn a new thread, and return a join handle for it.
+ /// Spawns a new thread, and returns a join handle for it.
///
/// The child thread may outlive the parent (unless the parent thread
/// is the main thread; the whole process is terminated when the main
self.spawn_inner(Box::new(f)).map(|i| JoinHandle(i))
}
- /// Spawn a new child thread that must be joined within a given
- /// scope, and return a `JoinGuard`.
+ /// Spawns a new child thread that must be joined within a given
+ /// scope, and returns a `JoinGuard`.
///
/// The join guard can be used to explicitly join the child thread (via
/// `join`), returning `Result<T>`, or it will implicitly join the child
// Free functions
////////////////////////////////////////////////////////////////////////////////
-/// Spawn a new thread, returning a `JoinHandle` for it.
+/// Spawns a new thread, returning a `JoinHandle` for it.
///
/// The join handle will implicitly *detach* the child thread upon being
/// dropped. In this case, the child thread may outlive the parent (unless
Builder::new().spawn(f).unwrap()
}
-/// Spawn a new *scoped* thread, returning a `JoinGuard` for it.
+/// Spawns a new *scoped* thread, returning a `JoinGuard` for it.
///
/// The join guard can be used to explicitly join the child thread (via
/// `join`), returning `Result<T>`, or it will implicitly join the child
thread_info::current_thread()
}
-/// Cooperatively give up a timeslice to the OS scheduler.
+/// Cooperatively gives up a timeslice to the OS scheduler.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn yield_now() {
unsafe { imp::yield_now() }
unwind::panicking()
}
-/// Invoke a closure, capturing the cause of panic if one occurs.
+/// Invokes a closure, capturing the cause of panic if one occurs.
///
/// This function will return `Ok(())` if the closure does not panic, and will
/// return `Err(cause)` if the closure panics. The `cause` returned is the
Ok(result.unwrap())
}
-/// Put the current thread to sleep for the specified amount of time.
+/// Puts the current thread to sleep for the specified amount of time.
///
/// The thread may sleep longer than the duration specified due to scheduling
/// specifics or platform-dependent functionality. Note that on unix platforms
imp::sleep(dur)
}
-/// Block unless or until the current thread's token is made available (may wake spuriously).
+/// Blocks unless or until the current thread's token is made available (may wake spuriously).
///
/// See the module doc for more detail.
//
*guard = false;
}
-/// Block unless or until the current thread's token is made available or
+/// Blocks unless or until the current thread's token is made available or
/// the specified duration has been reached (may wake spuriously).
///
/// The semantics of this function are equivalent to `park()` except that the
}
}
- /// Get the thread's name.
+ /// Gets the thread's name.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn name(&self) -> Option<&str> {
self.inner.name.as_ref().map(|s| &**s)
pub struct JoinHandle(JoinInner<()>);
impl JoinHandle {
- /// Extract a handle to the underlying thread
+ /// Extracts a handle to the underlying thread
#[stable(feature = "rust1", since = "1.0.0")]
pub fn thread(&self) -> &Thread {
&self.0.thread
}
- /// Wait for the associated thread to finish.
+ /// Waits for the associated thread to finish.
///
/// If the child thread panics, `Err` is returned with the parameter given
/// to `panic`.
unsafe impl<'a, T: Send + 'a> Sync for JoinGuard<'a, T> {}
impl<'a, T: Send + 'a> JoinGuard<'a, T> {
- /// Extract a handle to the thread this guard will join on.
+ /// Extracts a handle to the thread this guard will join on.
#[stable(feature = "rust1", since = "1.0.0")]
pub fn thread(&self) -> &Thread {
&self.inner.thread
}
- /// Wait for the associated thread to finish, returning the result of the
+ /// Waits for the associated thread to finish, returning the result of the
/// thread's calculation.
///
/// # Panics
reason = "scoped TLS has yet to have wide enough use to fully consider \
stabilizing its interface")]
impl<T> ScopedKey<T> {
- /// Insert a value into this scoped thread local storage slot for a
+ /// Inserts a value into this scoped thread local storage slot for a
/// duration of a closure.
///
/// While `cb` is running, the value `t` will be returned by `get` unless
cb()
}
- /// Get a value out of this scoped variable.
+ /// Gets a value out of this scoped variable.
///
/// This function takes a closure which receives the value of this
/// variable.
projects / rust.git / commitdiff