1 // SPDX-License-Identifier: (BSD-2-Clause OR Apache-2.0) OR MIT
5 // Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
6 // <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0>, or the MIT
7 // license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
30     /// [covariant]: https://doc.rust-lang.org/reference/subtyping.html
38         /// 0. If `ptr`'s referent is not zero sized, then `ptr` has valid
41         /// 1. If `ptr`'s referent is not zero sized, `A` is guaranteed to live
48         /// - `ptr`'s referent is not larger than `isize::MAX` bytes \[1\]
49         /// - `ptr`'s referent does not wrap around the address space \[1\]
51         /// \[1\] Per <https://doc.rust-lang.org/1.85.0/std/ptr/index.html#allocated-object>:
56         ///   - `size <= isize::MAX`
61         ///   - It is guaranteed that, given `o = a - base` (i.e., the offset of
70         // [1] https://doc.rust-lang.org/1.81.0/reference/subtyping.html#variance
77         fn clone(&self) -> PtrInner<'a, T> {  in clone()
91         /// 0. If `ptr`'s referent is not zero sized, then `ptr` has valid
94         /// 1. If `ptr`'s referent is not zero sized, `A` is guaranteed to live
98         pub const unsafe fn new(ptr: NonNull<T>) -> PtrInner<'a, T> {  in new()
111         pub const fn as_non_null(&self) -> NonNull<T> {  in as_non_null()
122         pub const fn as_ptr(&self) -> *mut T {  in as_ptr()
131     pub fn from_ref(ptr: &'a T) -> Self {  in from_ref()
134         // 0. If `ptr`'s referent is not zero sized, then `ptr`, by invariant on  in from_ref()
137         // 1. If `ptr`'s referent is not zero sized, then `A`, by invariant on  in from_ref()
140         // [1] Per https://doc.rust-lang.org/1.85.0/std/primitive.reference.html#safety:  in from_ref()
146         //   - if `size_of_val(t) > 0`, then `t` is dereferenceable for  in from_ref()
157     pub fn from_mut(ptr: &'a mut T) -> Self {  in from_mut()
160         // 0. If `ptr`'s referent is not zero sized, then `ptr`, by invariant on  in from_mut()
163         // 1. If `ptr`'s referent is not zero sized, then `A`, by invariant on  in from_mut()
166         // [1] Per https://doc.rust-lang.org/1.85.0/std/primitive.reference.html#safety:  in from_mut()
172         //   - if `size_of_val(t) > 0`, then `t` is dereferenceable for  in from_mut()
187     pub fn project<U: ?Sized, C: cast::Project<T, U>>(self) -> PtrInner<'a, U> {  in project()
191         // zero-sized or lives in an allocation. In either case, it does not  in project()
193         // contained in it or one-past-the-end of it are null.  in project()
195         // By invariant on `C: Project`, `C::project` is a provenance-preserving  in project()
200         // [1] https://doc.rust-lang.org/1.92.0/std/ptr/index.html#allocation  in project()
206         // - Addresses zero bytes or,  in project()
207         // - Addresses a subset of the referent of `self`. In this case, `self`  in project()
210         //   provenance-preserving operations, it also has provenance for its  in project()
225     pub fn meta(self) -> MetadataOf<T> {  in meta()
237     /// The caller promises that if `self`'s referent is not zero sized, then
242     pub unsafe fn with_meta(self, meta: T::PointerMetadata) -> Self  in with_meta()
250         // Lemma 0: `raw` either addresses zero bytes, or addresses a subset of  in with_meta()
253         //          provenance-preserving operations, and the caller has  in with_meta()
254         //          promised that, if `self`'s referent is not zero-sized, the  in with_meta()
259         //    zero sized, then `ptr` is derived from some valid Rust allocation,  in with_meta()
262         //    zero sized, then `ptr` has valid provenance for `A`.  in with_meta()
264         //    zero sized, then `ptr` addresses a byte range which is entirely  in with_meta()
271         //    zero sized, then `A` is guaranteed to live for at least `'a`.  in with_meta()
286     ///  - `l_len.get() <= self.meta()`.
288     /// ## (Non-)Overlap
291     /// `left` and `right` are contiguous and non-overlapping if
301     ) -> (Self, PtrInner<'a, [T::Elem]>)  in split_at_unchecked()
317         // are non-overlapping. Proof: `left` is constructed `slf` with `l_len`  in split_at_unchecked()
335     pub fn trailing_slice(self) -> PtrInner<'a, [T::Elem]>  in trailing_slice()
344         // - By invariant on `T: KnownLayout`, `T::LAYOUT` describes `T`'s  in trailing_slice()
346         //   which is by definition in-bounds or one byte past the end of any  in trailing_slice()
351         // - If `offset > 0`, then by invariant on `PtrInner`, `self` (and thus  in trailing_slice()
359         // ensures that it is non-null.  in trailing_slice()
365         // 0. If `ptr`'s referent is not zero sized, then `ptr` is derived from  in trailing_slice()
368         // 1. If `ptr`'s referent is not zero sized, then `ptr` has valid  in trailing_slice()
370         //    allocated object as `self` via provenance-preserving operations.  in trailing_slice()
371         // 2. If `ptr`'s referent is not zero sized, then `ptr` addresses a byte  in trailing_slice()
378         // 5. If `ptr`'s referent is not zero sized, then `A` is guaranteed to  in trailing_slice()
393     pub unsafe fn slice_unchecked(self, range: Range<usize>) -> Self {  in slice_unchecked()
397         // invariant, if `self`'s referent is not zero-sized, then `self` refers  in slice_unchecked()
401         // in-bounds of the same allocation, and does not wrap around the  in slice_unchecked()
404         // If `self`'s referent is zero-sized, then these conditions are  in slice_unchecked()
417         // the end of that referent. Thus, in either case, `ptr` is non-null.  in slice_unchecked()
425         //          in-bounds of `self`, and `base + (end - start)` is also  in slice_unchecked()
426         //          in-bounds of self. Finally, `ptr` is constructed using  in slice_unchecked()
427         //          provenance-preserving operations.  in slice_unchecked()
430         //    zero sized, then `ptr` has valid provenance for its referent,  in slice_unchecked()
433         //    zero sized, then `A` is guaranteed to live for at least `'a`.  in slice_unchecked()
439     pub fn iter(&self) -> impl Iterator<Item = PtrInner<'a, T>> {  in iter()
444             // FIXME(https://github.com/rust-lang/rust/issues/74265): Use  in iter()
450             // > - The computed offset, `count * size_of::<T>()` bytes, must not  in iter()
452             // > - If the computed offset is non-zero, then `self` must be  in iter()
458             // [1] https://doc.rust-lang.org/std/primitive.pointer.html#method.add  in iter()
461             // - By invariant on `Ptr`, `self` addresses a byte range whose  in iter()
464             // - If the computed offset is non-zero, then this means that the  in iter()
465             //   referent is not zero-sized. In this case, `base` points to an  in iter()
467             //   - By contract, `self.meta()` accurately reflects the number of  in iter()
471             //   - By invariant on `Ptr`, `self` addresses a byte range which  in iter()
490             // 0. If `elem`'s referent is not zero sized, then `elem` has valid  in iter()
492             //    using a series of provenance-preserving operations, and  in iter()
496             // 1. If `elem`'s referent is not zero sized, then the allocation of  in iter()
506     /// Casts this pointer-to-array into a slice.
515     pub fn as_slice(self) -> PtrInner<'a, [T]> {  in as_slice()
519         // which is non-null.  in as_slice()
527         // 0. By the above lemma, if `slice`'s referent is not zero sized, then  in as_slice()
530         //    Because `slice` was constructed using provenance-preserving  in as_slice()
532         // 1. By the above lemma, if `slice`'s referent is not zero sized, then  in as_slice()
547     /// Returns `None` if the resulting `U` would be invalidly-aligned, if no
550     /// largest-possible `U` which fits in `self`.
557     /// remainder))`, then `ptr` and `remainder` refer to non-overlapping byte
560     /// - If this is a prefix cast, `ptr` has the same address as `self`.
561     /// - If this is a suffix cast, `remainder` has the same address as `self`.
567     ) -> Result<(PtrInner<'a, U>, PtrInner<'a, [u8]>), CastError<Self, U>>  in try_cast_into()
577         // whose trailing slice element is zero-sized.  in try_cast_into()
600         // Lemma 0: `l_slice` and `r_slice` are non-overlapping. Proof: By  in try_cast_into()
602         // are always non-overlapping if `self` is a `[T]`; here it is a `[u8]`.  in try_cast_into()
615         // 0. By invariant, if `target`'s referent is not zero sized, then  in try_cast_into()
617         //    Because `ptr` is derived from `target` via provenance-preserving  in try_cast_into()
623         //    `target`'s referent is not zero sized, then `target` refers to an  in try_cast_into()
658             let n: usize = BUFFER_SIZE - OFFSET;  in test_split_at()
690                 assert_eq!(r_sum, n - i.get());  in test_split_at()
710             let n: usize = BUFFER_SIZE - OFFSET;  in test_trailing_slice()