std: Second pass stabilization for ptr

This commit performs a second pass for stabilization over the `std::ptr` module.
The specific actions taken were:

* The `RawPtr` trait was renamed to `PtrExt`
* The `RawMutPtr` trait was renamed to `MutPtrExt`
* The module name `ptr` is now stable.
* These functions were all marked `#[stable]` with no modification:
  * `null`
  * `null_mut`
  * `swap`
  * `replace`
  * `read`
  * `write`
  * `PtrExt::is_null`
  * `PtrExt::offset`
* These functions remain unstable:
  * `as_ref`, `as_mut` - the return value of an `Option` is not fully expressive
                         as null isn't the only bad value, and it's unclear
                         whether we want to commit to these functions at this
                         time. The reference/lifetime semantics as written are
                         also problematic in how they encourage arbitrary
                         lifetimes.
  * `zero_memory` - This function is currently not used at all in the
                    distribution, and in general it plays a broader role in the
                    "working with unsafe pointers" story. This story is not yet
                    fully developed, so at this time the function remains
                    unstable for now.
  * `read_and_zero` - This function remains unstable for largely the same
                      reasons as `zero_memory`.
* These functions are now all deprecated:
  * `PtrExt::null` - call `ptr::null` or `ptr::null_mut` instead.
  * `PtrExt::to_uint` - use an `as` expression instead.
  * `PtrExt::is_not_null` - use `!p.is_null()` instead.
This commit is contained in:
Alex Crichton 2014-12-19 08:57:12 -08:00
parent 71123902e1
commit 54452cdd68
20 changed files with 119 additions and 92 deletions

View File

@ -80,7 +80,7 @@ use core::nonzero::NonZero;
use core::ops::{Drop, Deref};
use core::option::Option;
use core::option::Option::{Some, None};
use core::ptr::{mod, RawPtr};
use core::ptr::{mod, PtrExt};
use heap::deallocate;
/// An atomically reference counted wrapper for shared state.

View File

@ -8,7 +8,7 @@
// option. This file may not be copied, modified, or distributed
// except according to those terms.
use core::ptr::RawPtr;
use core::ptr::PtrExt;
// FIXME: #13996: mark the `allocate` and `reallocate` return value as `noalias`
@ -371,7 +371,7 @@ mod imp {
mod test {
extern crate test;
use self::test::Bencher;
use core::ptr::RawPtr;
use core::ptr::PtrExt;
use heap;
#[test]

View File

@ -154,7 +154,7 @@ use core::nonzero::NonZero;
use core::ops::{Deref, Drop};
use core::option::Option;
use core::option::Option::{Some, None};
use core::ptr::{mod, RawPtr};
use core::ptr::{mod, PtrExt};
use core::result::Result;
use core::result::Result::{Ok, Err};

View File

@ -95,7 +95,7 @@ impl<T> Rawlink<T> {
/// Convert the `Rawlink` into an Option value
fn resolve_immut<'a>(&self) -> Option<&'a T> {
unsafe {
self.p.as_ref()
mem::transmute(self.p.as_ref())
}
}

View File

@ -96,7 +96,7 @@ use core::mem::size_of;
use core::mem;
use core::ops::FnMut;
use core::prelude::{Clone, Greater, Iterator, IteratorExt, Less, None, Option};
use core::prelude::{Ord, Ordering, RawPtr, Some, range};
use core::prelude::{Ord, Ordering, PtrExt, Some, range};
use core::ptr;
use core::slice as core_slice;
use self::Direction::*;

View File

@ -1768,19 +1768,12 @@ impl StrExt for str {}
#[cfg(test)]
mod tests {
use std::iter::AdditiveIterator;
use std::iter::range;
use std::default::Default;
use std::char::Char;
use std::clone::Clone;
use std::cmp::{Ord, PartialOrd, Equiv};
use std::cmp::Ordering::{Equal, Greater, Less};
use std::option::Option::{mod, Some, None};
use std::result::Result::{Ok, Err};
use std::ptr::RawPtr;
use std::iter::{Iterator, IteratorExt, DoubleEndedIteratorExt};
use prelude::*;
use super::*;
use core::default::Default;
use core::iter::AdditiveIterator;
use super::{eq_slice, from_utf8, is_utf8, is_utf16, raw};
use super::truncate_utf16_at_nul;
use super::MaybeOwned::{Owned, Slice};
use std::slice::{AsSlice, SliceExt};
use string::{String, ToString};

View File

@ -57,7 +57,7 @@ pub use iter::{IteratorOrdExt, MutableDoubleEndedIterator, ExactSizeIterator};
pub use num::{ToPrimitive, FromPrimitive};
pub use option::Option;
pub use option::Option::{Some, None};
pub use ptr::RawPtr;
pub use ptr::{PtrExt, MutPtrExt};
pub use result::Result;
pub use result::Result::{Ok, Err};
pub use str::{Str, StrExt};

View File

@ -16,11 +16,10 @@
//! typically limited to a few patterns.
//!
//! Use the [`null` function](fn.null.html) to create null pointers,
//! the [`is_null`](trait.RawPtr.html#tymethod.is_null)
//! and [`is_not_null`](trait.RawPtr.html#method.is_not_null)
//! methods of the [`RawPtr` trait](trait.RawPtr.html) to check for null.
//! The `RawPtr` trait is imported by the prelude, so `is_null` etc.
//! work everywhere. The `RawPtr` also defines the `offset` method,
//! the [`is_null`](trait.PtrExt.html#tymethod.is_null)
//! methods of the [`PtrExt` trait](trait.PtrExt.html) to check for null.
//! The `PtrExt` trait is imported by the prelude, so `is_null` etc.
//! work everywhere. The `PtrExt` also defines the `offset` method,
//! for pointer math.
//!
//! # Common ways to create unsafe pointers
@ -87,16 +86,16 @@
//! but C APIs hand out a lot of pointers generally, so are a common source
//! of unsafe pointers in Rust.
#![stable]
use mem;
use clone::Clone;
use intrinsics;
use option::Option::{mod, Some, None};
use kinds::{Send, Sync};
use option::Option;
use option::Option::{Some, None};
use cmp::{PartialEq, Eq, Ord, PartialOrd, Equiv};
use cmp::Ordering;
use cmp::Ordering::{Less, Equal, Greater};
use cmp::Ordering::{mod, Less, Equal, Greater};
// FIXME #19649: instrinsic docs don't render, so these have no docs :(
@ -121,7 +120,7 @@ pub use intrinsics::set_memory;
/// assert!(p.is_null());
/// ```
#[inline]
#[unstable = "may need a different name after pending changes to pointer types"]
#[stable]
pub fn null<T>() -> *const T { 0 as *const T }
/// Creates a null mutable raw pointer.
@ -135,31 +134,31 @@ pub fn null<T>() -> *const T { 0 as *const T }
/// assert!(p.is_null());
/// ```
#[inline]
#[unstable = "may need a different name after pending changes to pointer types"]
#[stable]
pub fn null_mut<T>() -> *mut T { 0 as *mut T }
/// Zeroes out `count * size_of::<T>` bytes of memory at `dst`. `count` may be `0`.
/// Zeroes out `count * size_of::<T>` bytes of memory at `dst`. `count` may be
/// `0`.
///
/// # Safety
///
/// Beyond accepting a raw pointer, this is unsafe because it will not drop the contents of `dst`,
/// and may be used to create invalid instances of `T`.
/// Beyond accepting a raw pointer, this is unsafe because it will not drop the
/// contents of `dst`, and may be used to create invalid instances of `T`.
#[inline]
#[experimental = "uncertain about naming and semantics"]
#[allow(experimental)]
#[unstable = "may play a larger role in std::ptr future extensions"]
pub unsafe fn zero_memory<T>(dst: *mut T, count: uint) {
set_memory(dst, 0, count);
}
/// Swaps the values at two mutable locations of the same type, without
/// deinitialising either. They may overlap, unlike `mem::swap` which is otherwise
/// equivalent.
/// deinitialising either. They may overlap, unlike `mem::swap` which is
/// otherwise equivalent.
///
/// # Safety
///
/// This is only unsafe because it accepts a raw pointer.
#[inline]
#[unstable]
#[stable]
pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
// Give ourselves some scratch space to work with
let mut tmp: T = mem::uninitialized();
@ -183,7 +182,7 @@ pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
/// This is only unsafe because it accepts a raw pointer.
/// Otherwise, this operation is identical to `mem::replace`.
#[inline]
#[unstable]
#[stable]
pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
mem::swap(mem::transmute(dest), &mut src); // cannot overlap
src
@ -201,7 +200,7 @@ pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
/// `zero_memory`, or `copy_memory`). Note that `*src = foo` counts as a use
/// because it will attempt to drop the value previously at `*src`.
#[inline(always)]
#[unstable]
#[stable]
pub unsafe fn read<T>(src: *const T) -> T {
let mut tmp: T = mem::uninitialized();
copy_nonoverlapping_memory(&mut tmp, src, 1);
@ -214,8 +213,7 @@ pub unsafe fn read<T>(src: *const T) -> T {
///
/// This is unsafe for the same reasons that `read` is unsafe.
#[inline(always)]
#[experimental]
#[allow(experimental)]
#[unstable = "may play a larger role in std::ptr future extensions"]
pub unsafe fn read_and_zero<T>(dest: *mut T) -> T {
// Copy the data out from `dest`:
let tmp = read(&*dest);
@ -226,8 +224,8 @@ pub unsafe fn read_and_zero<T>(dest: *mut T) -> T {
tmp
}
/// Overwrites a memory location with the given value without reading or dropping
/// the old value.
/// Overwrites a memory location with the given value without reading or
/// dropping the old value.
///
/// # Safety
///
@ -235,36 +233,44 @@ pub unsafe fn read_and_zero<T>(dest: *mut T) -> T {
/// not drop the contents of `dst`. This could leak allocations or resources,
/// so care must be taken not to overwrite an object that should be dropped.
///
/// This is appropriate for initializing uninitialized memory, or overwritting memory
/// that has previously been `read` from.
/// This is appropriate for initializing uninitialized memory, or overwritting
/// memory that has previously been `read` from.
#[inline]
#[unstable]
#[stable]
pub unsafe fn write<T>(dst: *mut T, src: T) {
intrinsics::move_val_init(&mut *dst, src)
}
/// Methods on raw pointers
pub trait RawPtr<T> {
/// Returns a null raw pointer.
#[stable]
pub trait PtrExt<T> {
/// Returns the null pointer.
#[deprecated = "call ptr::null instead"]
fn null() -> Self;
/// Returns true if the pointer is null.
fn is_null(&self) -> bool;
#[stable]
fn is_null(self) -> bool;
/// Returns true if the pointer is not equal to the null pointer.
#[deprecated = "use !p.is_null() instead"]
fn is_not_null(self) -> bool { !self.is_null() }
/// Returns true if the pointer is not null.
fn is_not_null(&self) -> bool { !self.is_null() }
#[deprecated = "use `as uint` instead"]
fn to_uint(self) -> uint;
/// Returns the address of the pointer.
fn to_uint(&self) -> uint;
/// Returns `None` if the pointer is null, or else returns a reference to the
/// value wrapped in `Some`.
/// Returns `None` if the pointer is null, or else returns a reference to
/// the value wrapped in `Some`.
///
/// # Safety
///
/// While this method and its mutable counterpart are useful for null-safety,
/// it is important to note that this is still an unsafe operation because
/// the returned value could be pointing to invalid memory.
/// While this method and its mutable counterpart are useful for
/// null-safety, it is important to note that this is still an unsafe
/// operation because the returned value could be pointing to invalid
/// memory.
#[unstable = "Option is not clearly the right return type, and we may want \
to tie the return lifetime to a borrow of the raw pointer"]
unsafe fn as_ref<'a>(&self) -> Option<&'a T>;
/// Calculates the offset from a pointer. `count` is in units of T; e.g. a
@ -272,39 +278,51 @@ pub trait RawPtr<T> {
///
/// # Safety
///
/// The offset must be in-bounds of the object, or one-byte-past-the-end. Otherwise
/// `offset` invokes Undefined Behaviour, regardless of whether the pointer is used.
/// The offset must be in-bounds of the object, or one-byte-past-the-end.
/// Otherwise `offset` invokes Undefined Behaviour, regardless of whether
/// the pointer is used.
#[stable]
unsafe fn offset(self, count: int) -> Self;
}
/// Methods on mutable raw pointers
pub trait RawMutPtr<T>{
/// Returns `None` if the pointer is null, or else returns a mutable reference
/// to the value wrapped in `Some`.
#[stable]
pub trait MutPtrExt<T>{
/// Returns `None` if the pointer is null, or else returns a mutable
/// reference to the value wrapped in `Some`.
///
/// # Safety
///
/// As with `as_ref`, this is unsafe because it cannot verify the validity
/// of the returned pointer.
#[unstable = "Option is not clearly the right return type, and we may want \
to tie the return lifetime to a borrow of the raw pointer"]
unsafe fn as_mut<'a>(&self) -> Option<&'a mut T>;
}
impl<T> RawPtr<T> for *const T {
#[stable]
impl<T> PtrExt<T> for *const T {
#[inline]
#[deprecated = "call ptr::null instead"]
fn null() -> *const T { null() }
#[inline]
fn is_null(&self) -> bool { *self == RawPtr::null() }
#[stable]
fn is_null(self) -> bool { self as uint == 0 }
#[inline]
fn to_uint(&self) -> uint { *self as uint }
#[deprecated = "use `as uint` instead"]
fn to_uint(self) -> uint { self as uint }
#[inline]
#[stable]
unsafe fn offset(self, count: int) -> *const T {
intrinsics::offset(self, count)
}
#[inline]
#[unstable = "return value does not necessarily convey all possible \
information"]
unsafe fn as_ref<'a>(&self) -> Option<&'a T> {
if self.is_null() {
None
@ -314,22 +332,29 @@ impl<T> RawPtr<T> for *const T {
}
}
impl<T> RawPtr<T> for *mut T {
#[stable]
impl<T> PtrExt<T> for *mut T {
#[inline]
#[deprecated = "call ptr::null instead"]
fn null() -> *mut T { null_mut() }
#[inline]
fn is_null(&self) -> bool { *self == RawPtr::null() }
#[stable]
fn is_null(self) -> bool { self as uint == 0 }
#[inline]
fn to_uint(&self) -> uint { *self as uint }
#[deprecated = "use `as uint` instead"]
fn to_uint(self) -> uint { self as uint }
#[inline]
#[stable]
unsafe fn offset(self, count: int) -> *mut T {
intrinsics::offset(self as *const T, count) as *mut T
}
#[inline]
#[unstable = "return value does not necessarily convey all possible \
information"]
unsafe fn as_ref<'a>(&self) -> Option<&'a T> {
if self.is_null() {
None
@ -339,8 +364,11 @@ impl<T> RawPtr<T> for *mut T {
}
}
impl<T> RawMutPtr<T> for *mut T {
#[stable]
impl<T> MutPtrExt<T> for *mut T {
#[inline]
#[unstable = "return value does not necessarily convey all possible \
information"]
unsafe fn as_mut<'a>(&self) -> Option<&'a mut T> {
if self.is_null() {
None
@ -510,28 +538,33 @@ impl<T> PartialOrd for *mut T {
/// raw `*mut T` (which conveys no particular ownership semantics).
/// Useful for building abstractions like `Vec<T>` or `Box<T>`, which
/// internally use raw pointers to manage the memory that they own.
#[unstable = "recently added to this module"]
pub struct Unique<T>(pub *mut T);
/// `Unique` pointers are `Send` if `T` is `Send` because the data they
/// reference is unaliased. Note that this aliasing invariant is
/// unenforced by the type system; the abstraction using the
/// `Unique` must enforce it.
#[unstable = "recently added to this module"]
unsafe impl<T:Send> Send for Unique<T> { }
/// `Unique` pointers are `Sync` if `T` is `Sync` because the data they
/// reference is unaliased. Note that this aliasing invariant is
/// unenforced by the type system; the abstraction using the
/// `Unique` must enforce it.
#[unstable = "recently added to this module"]
unsafe impl<T:Sync> Sync for Unique<T> { }
impl<T> Unique<T> {
/// Returns a null Unique.
#[unstable = "recently added to this module"]
pub fn null() -> Unique<T> {
Unique(RawPtr::null())
Unique(null_mut())
}
/// Return an (unsafe) pointer into the memory owned by `self`.
#[unstable = "recently added to this module"]
pub unsafe fn offset(self, offset: int) -> *mut T {
(self.0 as *const T).offset(offset) as *mut T
self.0.offset(offset)
}
}

View File

@ -47,7 +47,7 @@ use ops::{FnMut, mod};
use option::Option;
use option::Option::{None, Some};
use ptr;
use ptr::RawPtr;
use ptr::PtrExt;
use mem;
use mem::size_of;
use kinds::{Sized, marker};
@ -1334,7 +1334,7 @@ pub unsafe fn from_raw_mut_buf<'a, T>(p: &'a *mut T, len: uint) -> &'a mut [T] {
#[deprecated]
pub mod raw {
use mem::transmute;
use ptr::RawPtr;
use ptr::PtrExt;
use raw::Slice;
use ops::FnOnce;
use option::Option;

View File

@ -28,7 +28,7 @@ use mem;
use num::Int;
use ops::{Fn, FnMut};
use option::Option::{mod, None, Some};
use ptr::RawPtr;
use ptr::PtrExt;
use raw::{Repr, Slice};
use result::Result::{mod, Ok, Err};
use slice::{mod, SliceExt};
@ -1072,7 +1072,7 @@ const TAG_CONT_U8: u8 = 0b1000_0000u8;
/// Unsafe operations
#[deprecated]
pub mod raw {
use ptr::RawPtr;
use ptr::PtrExt;
use raw::Slice;
use slice::SliceExt;
use str::StrExt;

View File

@ -501,7 +501,7 @@ impl<'a, 'tcx> Builder<'a, 'tcx> {
debug!("Store {} -> {}",
self.ccx.tn().val_to_string(val),
self.ccx.tn().val_to_string(ptr));
assert!(self.llbuilder.is_not_null());
assert!(!self.llbuilder.is_null());
self.count_insn("store");
unsafe {
llvm::LLVMBuildStore(self.llbuilder, val, ptr);
@ -512,7 +512,7 @@ impl<'a, 'tcx> Builder<'a, 'tcx> {
debug!("Store {} -> {}",
self.ccx.tn().val_to_string(val),
self.ccx.tn().val_to_string(ptr));
assert!(self.llbuilder.is_not_null());
assert!(!self.llbuilder.is_null());
self.count_insn("store.volatile");
unsafe {
let insn = llvm::LLVMBuildStore(self.llbuilder, val, ptr);

View File

@ -20,7 +20,7 @@ pub struct Value(pub ValueRef);
macro_rules! opt_val { ($e:expr) => (
unsafe {
match $e {
p if p.is_not_null() => Some(Value(p)),
p if !p.is_null() => Some(Value(p)),
_ => None
}
}
@ -37,7 +37,7 @@ impl Value {
pub fn get_parent(self) -> Option<BasicBlock> {
unsafe {
match llvm::LLVMGetInstructionParent(self.get()) {
p if p.is_not_null() => Some(BasicBlock(p)),
p if !p.is_null() => Some(BasicBlock(p)),
_ => None
}
}
@ -77,7 +77,7 @@ impl Value {
pub fn get_first_use(self) -> Option<Use> {
unsafe {
match llvm::LLVMGetFirstUse(self.get()) {
u if u.is_not_null() => Some(Use(u)),
u if !u.is_null() => Some(Use(u)),
_ => None
}
}
@ -119,7 +119,7 @@ impl Value {
/// Tests if this value is a terminator instruction
pub fn is_a_terminator_inst(self) -> bool {
unsafe {
llvm::LLVMIsATerminatorInst(self.get()).is_not_null()
!llvm::LLVMIsATerminatorInst(self.get()).is_null()
}
}
}
@ -142,7 +142,7 @@ impl Use {
pub fn get_next_use(self) -> Option<Use> {
unsafe {
match llvm::LLVMGetNextUse(self.get()) {
u if u.is_not_null() => Some(Use(u)),
u if !u.is_null() => Some(Use(u)),
_ => None
}
}

View File

@ -40,7 +40,7 @@ use mem;
use ops::{Drop, FnOnce};
use option::Option;
use option::Option::{Some, None};
use ptr::RawPtr;
use ptr::PtrExt;
use ptr;
use raw;
use slice::AsSlice;

View File

@ -23,7 +23,7 @@ use num::{Int, UnsignedInt};
use ops::{Deref, DerefMut, Drop};
use option::Option;
use option::Option::{Some, None};
use ptr::{Unique, RawPtr, copy_nonoverlapping_memory, zero_memory};
use ptr::{Unique, PtrExt, copy_nonoverlapping_memory, zero_memory};
use ptr;
use rt::heap::{allocate, deallocate};

View File

@ -22,7 +22,7 @@ use num::Int;
use ops::FnOnce;
use option::Option;
use option::Option::{Some, None};
use ptr::RawPtr;
use ptr::PtrExt;
use result::Result::{Ok, Err};
use slice::{SliceExt, AsSlice};

View File

@ -935,7 +935,7 @@ impl<'a> Reader for &'a mut (Reader+'a) {
// API yet. If so, it should be a method on Vec.
unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec<T>, start: uint, end: uint) -> &'a mut [T] {
use raw::Slice;
use ptr::RawPtr;
use ptr::PtrExt;
assert!(start <= end);
assert!(end <= v.capacity());

View File

@ -46,7 +46,8 @@ use option::Option;
use option::Option::{Some, None};
use path::{Path, GenericPath, BytesContainer};
use sys;
use ptr::RawPtr;
use sys::os as os_imp;
use ptr::PtrExt;
use ptr;
use result::Result;
use result::Result::{Err, Ok};

View File

@ -73,7 +73,7 @@
#[doc(no_inline)] pub use option::Option;
#[doc(no_inline)] pub use option::Option::{Some, None};
#[doc(no_inline)] pub use path::{GenericPath, Path, PosixPath, WindowsPath};
#[doc(no_inline)] pub use ptr::{RawPtr, RawMutPtr};
#[doc(no_inline)] pub use ptr::{PtrExt, MutPtrExt};
#[doc(no_inline)] pub use result::Result;
#[doc(no_inline)] pub use result::Result::{Ok, Err};
#[doc(no_inline)] pub use io::{Buffer, Writer, Reader, Seek, BufferPrelude};

View File

@ -269,7 +269,7 @@ pub fn get_host_addresses(host: Option<&str>, servname: Option<&str>,
// Collect all the results we found
let mut addrs = Vec::new();
let mut rp = res;
while rp.is_not_null() {
while !rp.is_null() {
unsafe {
let addr = try!(sockaddr_to_addr(mem::transmute((*rp).ai_addr),
(*rp).ai_addrlen as uint));

View File

@ -244,7 +244,7 @@ fn print(w: &mut Writer, idx: int, addr: *mut libc::c_void) -> IoResult<()> {
use iter::{Iterator, IteratorExt};
use os;
use path::GenericPath;
use ptr::RawPtr;
use ptr::PtrExt;
use ptr;
use slice::SliceExt;