@@ -79,8 +79,82 @@ pub use intrinsics::copy_nonoverlapping;
7979#[ stable( feature = "rust1" , since = "1.0.0" ) ]
8080pub use intrinsics:: copy;
8181
82+ /// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
83+ /// `val`.
84+ ///
85+ /// `write_bytes` is similar to C's [`memset`], but sets `count *
86+ /// size_of::<T>()` bytes to `val`.
87+ ///
88+ /// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
89+ ///
90+ /// # Safety
91+ ///
92+ /// Behavior is undefined if any of the following conditions are violated:
93+ ///
94+ /// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
95+ ///
96+ /// * `dst` must be properly aligned.
97+ ///
98+ /// Additionally, the caller must ensure that writing `count *
99+ /// size_of::<T>()` bytes to the given region of memory results in a valid
100+ /// value of `T`. Using a region of memory typed as a `T` that contains an
101+ /// invalid value of `T` is undefined behavior.
102+ ///
103+ /// Note that even if the effectively copied size (`count * size_of::<T>()`) is
104+ /// `0`, the pointer must be non-NULL and properly aligned.
105+ ///
106+ /// [valid]: ../ptr/index.html#safety
107+ ///
108+ /// # Examples
109+ ///
110+ /// Basic usage:
111+ ///
112+ /// ```
113+ /// use std::ptr;
114+ ///
115+ /// let mut vec = vec![0u32; 4];
116+ /// unsafe {
117+ /// let vec_ptr = vec.as_mut_ptr();
118+ /// ptr::write_bytes(vec_ptr, 0xfe, 2);
119+ /// }
120+ /// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
121+ /// ```
122+ ///
123+ /// Creating an invalid value:
124+ ///
125+ /// ```
126+ /// use std::ptr;
127+ ///
128+ /// let mut v = Box::new(0i32);
129+ ///
130+ /// unsafe {
131+ /// // Leaks the previously held value by overwriting the `Box<T>` with
132+ /// // a null pointer.
133+ /// ptr::write_bytes(&mut v as *mut Box<i32>, 0, 1);
134+ /// }
135+ ///
136+ /// // At this point, using or dropping `v` results in undefined behavior.
137+ /// // drop(v); // ERROR
138+ ///
139+ /// // Even leaking `v` "uses" it, and hence is undefined behavior.
140+ /// // mem::forget(v); // ERROR
141+ ///
142+ /// // In fact, `v` is invalid according to basic type layout invariants, so *any*
143+ /// // operation touching it is undefined behavior.
144+ /// // let v2 = v; // ERROR
145+ ///
146+ /// unsafe {
147+ /// // Let us instead put in a valid value
148+ /// ptr::write(&mut v as *mut Box<i32>, Box::new(42i32));
149+ /// }
150+ ///
151+ /// // Now the box is fine
152+ /// assert_eq!(*v, 42);
153+ /// ```
82154#[ stable( feature = "rust1" , since = "1.0.0" ) ]
83- pub use intrinsics:: write_bytes;
155+ pub unsafe fn write_bytes < T > ( dst : * mut T , val : u8 , count : usize ) {
156+ intrinsics:: write_bytes ( dst, val, count) ;
157+ }
84158
85159/// Executes the destructor (if any) of the pointed-to value.
86160///
0 commit comments