16
16
//! typically limited to a few patterns.
17
17
//!
18
18
//! Use the [`null` function](fn.null.html) to create null pointers,
19
- //! the [`is_null`](trait.RawPtr.html#tymethod.is_null)
20
- //! and [`is_not_null`](trait.RawPtr.html#method.is_not_null)
21
- //! methods of the [`RawPtr` trait](trait.RawPtr.html) to check for null.
22
- //! The `RawPtr` trait is imported by the prelude, so `is_null` etc.
23
- //! work everywhere. The `RawPtr` also defines the `offset` method,
19
+ //! the [`is_null`](trait.PtrExt.html#tymethod.is_null)
20
+ //! methods of the [`PtrExt` trait](trait.PtrExt.html) to check for null.
21
+ //! The `PtrExt` trait is imported by the prelude, so `is_null` etc.
22
+ //! work everywhere. The `PtrExt` also defines the `offset` method,
24
23
//! for pointer math.
25
24
//!
26
25
//! # Common ways to create unsafe pointers
87
86
//! but C APIs hand out a lot of pointers generally, so are a common source
88
87
//! of unsafe pointers in Rust.
89
88
89
+ #![ stable]
90
+
90
91
use mem;
91
92
use clone:: Clone ;
92
93
use intrinsics;
94
+ use option:: Option :: { mod, Some , None } ;
93
95
use kinds:: { Send , Sync } ;
94
- use option:: Option ;
95
- use option:: Option :: { Some , None } ;
96
96
97
97
use cmp:: { PartialEq , Eq , Ord , PartialOrd , Equiv } ;
98
- use cmp:: Ordering ;
99
- use cmp:: Ordering :: { Less , Equal , Greater } ;
98
+ use cmp:: Ordering :: { mod, Less , Equal , Greater } ;
100
99
101
100
// FIXME #19649: instrinsic docs don't render, so these have no docs :(
102
101
@@ -121,7 +120,7 @@ pub use intrinsics::set_memory;
121
120
/// assert!(p.is_null());
122
121
/// ```
123
122
#[ inline]
124
- #[ unstable = "may need a different name after pending changes to pointer types" ]
123
+ #[ stable ]
125
124
pub fn null < T > ( ) -> * const T { 0 as * const T }
126
125
127
126
/// Creates a null mutable raw pointer.
@@ -135,31 +134,31 @@ pub fn null<T>() -> *const T { 0 as *const T }
135
134
/// assert!(p.is_null());
136
135
/// ```
137
136
#[ inline]
138
- #[ unstable = "may need a different name after pending changes to pointer types" ]
137
+ #[ stable ]
139
138
pub fn null_mut < T > ( ) -> * mut T { 0 as * mut T }
140
139
141
- /// Zeroes out `count * size_of::<T>` bytes of memory at `dst`. `count` may be `0`.
140
+ /// Zeroes out `count * size_of::<T>` bytes of memory at `dst`. `count` may be
141
+ /// `0`.
142
142
///
143
143
/// # Safety
144
144
///
145
- /// Beyond accepting a raw pointer, this is unsafe because it will not drop the contents of `dst`,
146
- /// and may be used to create invalid instances of `T`.
145
+ /// Beyond accepting a raw pointer, this is unsafe because it will not drop the
146
+ /// contents of `dst`, and may be used to create invalid instances of `T`.
147
147
#[ inline]
148
- #[ experimental = "uncertain about naming and semantics" ]
149
- #[ allow( experimental) ]
148
+ #[ unstable = "may play a larger role in std::ptr future extensions" ]
150
149
pub unsafe fn zero_memory < T > ( dst : * mut T , count : uint ) {
151
150
set_memory ( dst, 0 , count) ;
152
151
}
153
152
154
153
/// Swaps the values at two mutable locations of the same type, without
155
- /// deinitialising either. They may overlap, unlike `mem::swap` which is otherwise
156
- /// equivalent.
154
+ /// deinitialising either. They may overlap, unlike `mem::swap` which is
155
+ /// otherwise equivalent.
157
156
///
158
157
/// # Safety
159
158
///
160
159
/// This is only unsafe because it accepts a raw pointer.
161
160
#[ inline]
162
- #[ unstable ]
161
+ #[ stable ]
163
162
pub unsafe fn swap < T > ( x : * mut T , y : * mut T ) {
164
163
// Give ourselves some scratch space to work with
165
164
let mut tmp: T = mem:: uninitialized ( ) ;
@@ -183,7 +182,7 @@ pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
183
182
/// This is only unsafe because it accepts a raw pointer.
184
183
/// Otherwise, this operation is identical to `mem::replace`.
185
184
#[ inline]
186
- #[ unstable ]
185
+ #[ stable ]
187
186
pub unsafe fn replace < T > ( dest : * mut T , mut src : T ) -> T {
188
187
mem:: swap ( mem:: transmute ( dest) , & mut src) ; // cannot overlap
189
188
src
@@ -201,7 +200,7 @@ pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
201
200
/// `zero_memory`, or `copy_memory`). Note that `*src = foo` counts as a use
202
201
/// because it will attempt to drop the value previously at `*src`.
203
202
#[ inline( always) ]
204
- #[ unstable ]
203
+ #[ stable ]
205
204
pub unsafe fn read < T > ( src : * const T ) -> T {
206
205
let mut tmp: T = mem:: uninitialized ( ) ;
207
206
copy_nonoverlapping_memory ( & mut tmp, src, 1 ) ;
@@ -214,8 +213,7 @@ pub unsafe fn read<T>(src: *const T) -> T {
214
213
///
215
214
/// This is unsafe for the same reasons that `read` is unsafe.
216
215
#[ inline( always) ]
217
- #[ experimental]
218
- #[ allow( experimental) ]
216
+ #[ unstable = "may play a larger role in std::ptr future extensions" ]
219
217
pub unsafe fn read_and_zero < T > ( dest : * mut T ) -> T {
220
218
// Copy the data out from `dest`:
221
219
let tmp = read ( & * dest) ;
@@ -226,85 +224,105 @@ pub unsafe fn read_and_zero<T>(dest: *mut T) -> T {
226
224
tmp
227
225
}
228
226
229
- /// Overwrites a memory location with the given value without reading or dropping
230
- /// the old value.
227
+ /// Overwrites a memory location with the given value without reading or
228
+ /// dropping the old value.
231
229
///
232
230
/// # Safety
233
231
///
234
232
/// Beyond accepting a raw pointer, this operation is unsafe because it does
235
233
/// not drop the contents of `dst`. This could leak allocations or resources,
236
234
/// so care must be taken not to overwrite an object that should be dropped.
237
235
///
238
- /// This is appropriate for initializing uninitialized memory, or overwritting memory
239
- /// that has previously been `read` from.
236
+ /// This is appropriate for initializing uninitialized memory, or overwritting
237
+ /// memory that has previously been `read` from.
240
238
#[ inline]
241
- #[ unstable ]
239
+ #[ stable ]
242
240
pub unsafe fn write < T > ( dst : * mut T , src : T ) {
243
241
intrinsics:: move_val_init ( & mut * dst, src)
244
242
}
245
243
246
244
/// Methods on raw pointers
247
- pub trait RawPtr < T > {
248
- /// Returns a null raw pointer.
245
+ #[ stable]
246
+ pub trait PtrExt < T > {
247
+ /// Returns the null pointer.
248
+ #[ deprecated = "call ptr::null instead" ]
249
249
fn null ( ) -> Self ;
250
250
251
251
/// Returns true if the pointer is null.
252
- fn is_null ( & self ) -> bool ;
252
+ #[ stable]
253
+ fn is_null ( self ) -> bool ;
253
254
254
- /// Returns true if the pointer is not null.
255
- fn is_not_null ( & self ) -> bool { !self . is_null ( ) }
255
+ /// Returns true if the pointer is not equal to the null pointer.
256
+ #[ deprecated = "use !p.is_null() instead" ]
257
+ fn is_not_null ( self ) -> bool { !self . is_null ( ) }
256
258
257
- /// Returns the address of the pointer.
258
- fn to_uint ( & self ) -> uint ;
259
+ /// Returns true if the pointer is not null.
260
+ #[ deprecated = "use `as uint` instead" ]
261
+ fn to_uint ( self ) -> uint ;
259
262
260
- /// Returns `None` if the pointer is null, or else returns a reference to the
261
- /// value wrapped in `Some`.
263
+ /// Returns `None` if the pointer is null, or else returns a reference to
264
+ /// the value wrapped in `Some`.
262
265
///
263
266
/// # Safety
264
267
///
265
- /// While this method and its mutable counterpart are useful for null-safety,
266
- /// it is important to note that this is still an unsafe operation because
267
- /// the returned value could be pointing to invalid memory.
268
+ /// While this method and its mutable counterpart are useful for
269
+ /// null-safety, it is important to note that this is still an unsafe
270
+ /// operation because the returned value could be pointing to invalid
271
+ /// memory.
272
+ #[ unstable = "Option is not clearly the right return type, and we may want \
273
+ to tie the return lifetime to a borrow of the raw pointer"]
268
274
unsafe fn as_ref < ' a > ( & self ) -> Option < & ' a T > ;
269
275
270
276
/// Calculates the offset from a pointer. `count` is in units of T; e.g. a
271
277
/// `count` of 3 represents a pointer offset of `3 * sizeof::<T>()` bytes.
272
278
///
273
279
/// # Safety
274
280
///
275
- /// The offset must be in-bounds of the object, or one-byte-past-the-end. Otherwise
276
- /// `offset` invokes Undefined Behaviour, regardless of whether the pointer is used.
281
+ /// The offset must be in-bounds of the object, or one-byte-past-the-end.
282
+ /// Otherwise `offset` invokes Undefined Behaviour, regardless of whether
283
+ /// the pointer is used.
284
+ #[ stable]
277
285
unsafe fn offset ( self , count : int ) -> Self ;
278
286
}
279
287
280
288
/// Methods on mutable raw pointers
281
- pub trait RawMutPtr < T > {
282
- /// Returns `None` if the pointer is null, or else returns a mutable reference
283
- /// to the value wrapped in `Some`.
289
+ #[ stable]
290
+ pub trait MutPtrExt < T > {
291
+ /// Returns `None` if the pointer is null, or else returns a mutable
292
+ /// reference to the value wrapped in `Some`.
284
293
///
285
294
/// # Safety
286
295
///
287
296
/// As with `as_ref`, this is unsafe because it cannot verify the validity
288
297
/// of the returned pointer.
298
+ #[ unstable = "Option is not clearly the right return type, and we may want \
299
+ to tie the return lifetime to a borrow of the raw pointer"]
289
300
unsafe fn as_mut < ' a > ( & self ) -> Option < & ' a mut T > ;
290
301
}
291
302
292
- impl < T > RawPtr < T > for * const T {
303
+ #[ stable]
304
+ impl < T > PtrExt < T > for * const T {
293
305
#[ inline]
306
+ #[ deprecated = "call ptr::null instead" ]
294
307
fn null ( ) -> * const T { null ( ) }
295
308
296
309
#[ inline]
297
- fn is_null ( & self ) -> bool { * self == RawPtr :: null ( ) }
310
+ #[ stable]
311
+ fn is_null ( self ) -> bool { self as uint == 0 }
298
312
299
313
#[ inline]
300
- fn to_uint ( & self ) -> uint { * self as uint }
314
+ #[ deprecated = "use `as uint` instead" ]
315
+ fn to_uint ( self ) -> uint { self as uint }
301
316
302
317
#[ inline]
318
+ #[ stable]
303
319
unsafe fn offset ( self , count : int ) -> * const T {
304
320
intrinsics:: offset ( self , count)
305
321
}
306
322
307
323
#[ inline]
324
+ #[ unstable = "return value does not necessarily convey all possible \
325
+ information"]
308
326
unsafe fn as_ref < ' a > ( & self ) -> Option < & ' a T > {
309
327
if self . is_null ( ) {
310
328
None
@@ -314,22 +332,29 @@ impl<T> RawPtr<T> for *const T {
314
332
}
315
333
}
316
334
317
- impl < T > RawPtr < T > for * mut T {
335
+ #[ stable]
336
+ impl < T > PtrExt < T > for * mut T {
318
337
#[ inline]
338
+ #[ deprecated = "call ptr::null instead" ]
319
339
fn null ( ) -> * mut T { null_mut ( ) }
320
340
321
341
#[ inline]
322
- fn is_null ( & self ) -> bool { * self == RawPtr :: null ( ) }
342
+ #[ stable]
343
+ fn is_null ( self ) -> bool { self as uint == 0 }
323
344
324
345
#[ inline]
325
- fn to_uint ( & self ) -> uint { * self as uint }
346
+ #[ deprecated = "use `as uint` instead" ]
347
+ fn to_uint ( self ) -> uint { self as uint }
326
348
327
349
#[ inline]
350
+ #[ stable]
328
351
unsafe fn offset ( self , count : int ) -> * mut T {
329
352
intrinsics:: offset ( self as * const T , count) as * mut T
330
353
}
331
354
332
355
#[ inline]
356
+ #[ unstable = "return value does not necessarily convey all possible \
357
+ information"]
333
358
unsafe fn as_ref < ' a > ( & self ) -> Option < & ' a T > {
334
359
if self . is_null ( ) {
335
360
None
@@ -339,8 +364,11 @@ impl<T> RawPtr<T> for *mut T {
339
364
}
340
365
}
341
366
342
- impl < T > RawMutPtr < T > for * mut T {
367
+ #[ stable]
368
+ impl < T > MutPtrExt < T > for * mut T {
343
369
#[ inline]
370
+ #[ unstable = "return value does not necessarily convey all possible \
371
+ information"]
344
372
unsafe fn as_mut < ' a > ( & self ) -> Option < & ' a mut T > {
345
373
if self . is_null ( ) {
346
374
None
@@ -510,28 +538,33 @@ impl<T> PartialOrd for *mut T {
510
538
/// raw `*mut T` (which conveys no particular ownership semantics).
511
539
/// Useful for building abstractions like `Vec<T>` or `Box<T>`, which
512
540
/// internally use raw pointers to manage the memory that they own.
541
+ #[ unstable = "recently added to this module" ]
513
542
pub struct Unique < T > ( pub * mut T ) ;
514
543
515
544
/// `Unique` pointers are `Send` if `T` is `Send` because the data they
516
545
/// reference is unaliased. Note that this aliasing invariant is
517
546
/// unenforced by the type system; the abstraction using the
518
547
/// `Unique` must enforce it.
548
+ #[ unstable = "recently added to this module" ]
519
549
unsafe impl < T : Send > Send for Unique < T > { }
520
550
521
551
/// `Unique` pointers are `Sync` if `T` is `Sync` because the data they
522
552
/// reference is unaliased. Note that this aliasing invariant is
523
553
/// unenforced by the type system; the abstraction using the
524
554
/// `Unique` must enforce it.
555
+ #[ unstable = "recently added to this module" ]
525
556
unsafe impl < T : Sync > Sync for Unique < T > { }
526
557
527
558
impl < T > Unique < T > {
528
559
/// Returns a null Unique.
560
+ #[ unstable = "recently added to this module" ]
529
561
pub fn null ( ) -> Unique < T > {
530
- Unique ( RawPtr :: null ( ) )
562
+ Unique ( null_mut ( ) )
531
563
}
532
564
533
565
/// Return an (unsafe) pointer into the memory owned by `self`.
566
+ #[ unstable = "recently added to this module" ]
534
567
pub unsafe fn offset ( self , offset : int ) -> * mut T {
535
- ( self . 0 as * const T ) . offset ( offset) as * mut T
568
+ self . 0 . offset ( offset)
536
569
}
537
570
}
0 commit comments