@@ -73,14 +73,229 @@ use mem::{self, MaybeUninit};
7373
7474use cmp:: Ordering :: { self , Less , Equal , Greater } ;
7575
76+ /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
77+ /// and destination must *not* overlap.
78+ ///
79+ /// For regions of memory which might overlap, use [`copy`] instead.
80+ ///
81+ /// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
82+ /// with the argument order swapped.
83+ ///
84+ /// [`copy`]: ./fn.copy.html
85+ /// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
86+ ///
87+ /// # Safety
88+ ///
89+ /// Behavior is undefined if any of the following conditions are violated:
90+ ///
91+ /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
92+ ///
93+ /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
94+ ///
95+ /// * Both `src` and `dst` must be properly aligned.
96+ ///
97+ /// * The region of memory beginning at `src` with a size of `count *
98+ /// size_of::<T>()` bytes must *not* overlap with the region of memory
99+ /// beginning at `dst` with the same size.
100+ ///
101+ /// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
102+ /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
103+ /// in the region beginning at `*src` and the region beginning at `*dst` can
104+ /// [violate memory safety][read-ownership].
105+ ///
106+ /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
107+ /// `0`, the pointers must be non-NULL and properly aligned.
108+ ///
109+ /// [`Copy`]: ../marker/trait.Copy.html
110+ /// [`read`]: ../ptr/fn.read.html
111+ /// [read-ownership]: ../ptr/fn.read.html#ownership-of-the-returned-value
112+ /// [valid]: ../ptr/index.html#safety
113+ ///
114+ /// # Examples
115+ ///
116+ /// Manually implement [`Vec::append`]:
117+ ///
118+ /// ```
119+ /// use std::ptr;
120+ ///
121+ /// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
122+ /// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
123+ /// let src_len = src.len();
124+ /// let dst_len = dst.len();
125+ ///
126+ /// // Ensure that `dst` has enough capacity to hold all of `src`.
127+ /// dst.reserve(src_len);
128+ ///
129+ /// unsafe {
130+ /// // The call to offset is always safe because `Vec` will never
131+ /// // allocate more than `isize::MAX` bytes.
132+ /// let dst_ptr = dst.as_mut_ptr().offset(dst_len as isize);
133+ /// let src_ptr = src.as_ptr();
134+ ///
135+ /// // Truncate `src` without dropping its contents. We do this first,
136+ /// // to avoid problems in case something further down panics.
137+ /// src.set_len(0);
138+ ///
139+ /// // The two regions cannot overlap because mutable references do
140+ /// // not alias, and two different vectors cannot own the same
141+ /// // memory.
142+ /// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
143+ ///
144+ /// // Notify `dst` that it now holds the contents of `src`.
145+ /// dst.set_len(dst_len + src_len);
146+ /// }
147+ /// }
148+ ///
149+ /// let mut a = vec!['r'];
150+ /// let mut b = vec!['u', 's', 't'];
151+ ///
152+ /// append(&mut a, &mut b);
153+ ///
154+ /// assert_eq!(a, &['r', 'u', 's', 't']);
155+ /// assert!(b.is_empty());
156+ /// ```
157+ ///
158+ /// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
76159#[ stable( feature = "rust1" , since = "1.0.0" ) ]
77- pub use intrinsics:: copy_nonoverlapping;
160+ #[ inline]
161+ pub unsafe fn copy_nonoverlapping < T > ( src : * const T , dst : * mut T , count : usize ) {
162+ intrinsics:: copy_nonoverlapping ( src, dst, count) ;
163+ }
78164
165+ /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
166+ /// and destination may overlap.
167+ ///
168+ /// If the source and destination will *never* overlap,
169+ /// [`copy_nonoverlapping`] can be used instead.
170+ ///
171+ /// `copy` is semantically equivalent to C's [`memmove`], but with the argument
172+ /// order swapped. Copying takes place as if the bytes were copied from `src`
173+ /// to a temporary array and then copied from the array to `dst`.
174+ ///
175+ /// [`copy_nonoverlapping`]: ./fn.copy_nonoverlapping.html
176+ /// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
177+ ///
178+ /// # Safety
179+ ///
180+ /// Behavior is undefined if any of the following conditions are violated:
181+ ///
182+ /// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
183+ ///
184+ /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
185+ ///
186+ /// * Both `src` and `dst` must be properly aligned.
187+ ///
188+ /// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
189+ /// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
190+ /// in the region beginning at `*src` and the region beginning at `*dst` can
191+ /// [violate memory safety][read-ownership].
192+ ///
193+ /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
194+ /// `0`, the pointers must be non-NULL and properly aligned.
195+ ///
196+ /// [`Copy`]: ../marker/trait.Copy.html
197+ /// [`read`]: ../ptr/fn.read.html
198+ /// [read-ownership]: ../ptr/fn.read.html#ownership-of-the-returned-value
199+ /// [valid]: ../ptr/index.html#safety
200+ ///
201+ /// # Examples
202+ ///
203+ /// Efficiently create a Rust vector from an unsafe buffer:
204+ ///
205+ /// ```
206+ /// use std::ptr;
207+ ///
208+ /// # #[allow(dead_code)]
209+ /// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
210+ /// let mut dst = Vec::with_capacity(elts);
211+ /// dst.set_len(elts);
212+ /// ptr::copy(ptr, dst.as_mut_ptr(), elts);
213+ /// dst
214+ /// }
215+ /// ```
79216#[ stable( feature = "rust1" , since = "1.0.0" ) ]
80- pub use intrinsics:: copy;
217+ #[ inline]
218+ pub unsafe fn copy < T > ( src : * const T , dst : * mut T , count : usize ) {
219+ intrinsics:: copy ( src, dst, count) ;
220+ }
81221
222+ /// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
223+ /// `val`.
224+ ///
225+ /// `write_bytes` is similar to C's [`memset`], but sets `count *
226+ /// size_of::<T>()` bytes to `val`.
227+ ///
228+ /// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
229+ ///
230+ /// # Safety
231+ ///
232+ /// Behavior is undefined if any of the following conditions are violated:
233+ ///
234+ /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
235+ ///
236+ /// * `dst` must be properly aligned.
237+ ///
238+ /// Additionally, the caller must ensure that writing `count *
239+ /// size_of::<T>()` bytes to the given region of memory results in a valid
240+ /// value of `T`. Using a region of memory typed as a `T` that contains an
241+ /// invalid value of `T` is undefined behavior.
242+ ///
243+ /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
244+ /// `0`, the pointer must be non-NULL and properly aligned.
245+ ///
246+ /// [valid]: ../ptr/index.html#safety
247+ ///
248+ /// # Examples
249+ ///
250+ /// Basic usage:
251+ ///
252+ /// ```
253+ /// use std::ptr;
254+ ///
255+ /// let mut vec = vec![0u32; 4];
256+ /// unsafe {
257+ /// let vec_ptr = vec.as_mut_ptr();
258+ /// ptr::write_bytes(vec_ptr, 0xfe, 2);
259+ /// }
260+ /// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
261+ /// ```
262+ ///
263+ /// Creating an invalid value:
264+ ///
265+ /// ```
266+ /// use std::ptr;
267+ ///
268+ /// let mut v = Box::new(0i32);
269+ ///
270+ /// unsafe {
271+ /// // Leaks the previously held value by overwriting the `Box<T>` with
272+ /// // a null pointer.
273+ /// ptr::write_bytes(&mut v as *mut Box<i32>, 0, 1);
274+ /// }
275+ ///
276+ /// // At this point, using or dropping `v` results in undefined behavior.
277+ /// // drop(v); // ERROR
278+ ///
279+ /// // Even leaking `v` "uses" it, and hence is undefined behavior.
280+ /// // mem::forget(v); // ERROR
281+ ///
282+ /// // In fact, `v` is invalid according to basic type layout invariants, so *any*
283+ /// // operation touching it is undefined behavior.
284+ /// // let v2 = v; // ERROR
285+ ///
286+ /// unsafe {
287+ /// // Let us instead put in a valid value
288+ /// ptr::write(&mut v as *mut Box<i32>, Box::new(42i32));
289+ /// }
290+ ///
291+ /// // Now the box is fine
292+ /// assert_eq!(*v, 42);
293+ /// ```
82294#[ stable( feature = "rust1" , since = "1.0.0" ) ]
83- pub use intrinsics:: write_bytes;
295+ #[ inline]
296+ pub unsafe fn write_bytes < T > ( dst : * mut T , val : u8 , count : usize ) {
297+ intrinsics:: write_bytes ( dst, val, count) ;
298+ }
84299
85300/// Executes the destructor (if any) of the pointed-to value.
86301///
0 commit comments