Skip to content

Commit 4f8466b

Browse files
borsbors
committed
Auto merge of #57997 - nitnelave:master, r=<try>
Wrap write_bytes in a function. Move docs This will allow us to add debug assertions. See issue #53871.
2 parents 43b4c4a + 1c8b67b commit 4f8466b

File tree

2 files changed

+218
-212
lines changed

2 files changed

+218
-212
lines changed

‎src/libcore/intrinsics.rs

-209
Original file line numberDiff line numberDiff line change
@@ -962,219 +962,10 @@ extern "rust-intrinsic" {
962962
/// value is not necessarily valid to be used to actually access memory.
963963
pub fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
964964

965-
/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
966-
/// and destination must *not* overlap.
967-
///
968-
/// For regions of memory which might overlap, use [`copy`] instead.
969-
///
970-
/// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but
971-
/// with the argument order swapped.
972-
///
973-
/// [`copy`]: ./fn.copy.html
974-
/// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy
975-
///
976-
/// # Safety
977-
///
978-
/// Behavior is undefined if any of the following conditions are violated:
979-
///
980-
/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
981-
///
982-
/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
983-
///
984-
/// * Both `src` and `dst` must be properly aligned.
985-
///
986-
/// * The region of memory beginning at `src` with a size of `count *
987-
/// size_of::<T>()` bytes must *not* overlap with the region of memory
988-
/// beginning at `dst` with the same size.
989-
///
990-
/// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of
991-
/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values
992-
/// in the region beginning at `*src` and the region beginning at `*dst` can
993-
/// [violate memory safety][read-ownership].
994-
///
995-
/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
996-
/// `0`, the pointers must be non-NULL and properly aligned.
997-
///
998-
/// [`Copy`]: ../marker/trait.Copy.html
999-
/// [`read`]: ../ptr/fn.read.html
1000-
/// [read-ownership]: ../ptr/fn.read.html#ownership-of-the-returned-value
1001-
/// [valid]: ../ptr/index.html#safety
1002-
///
1003-
/// # Examples
1004-
///
1005-
/// Manually implement [`Vec::append`]:
1006-
///
1007-
/// ```
1008-
/// use std::ptr;
1009-
///
1010-
/// /// Moves all the elements of `src` into `dst`, leaving `src` empty.
1011-
/// fn append<T>(dst: &mut Vec<T>, src: &mut Vec<T>) {
1012-
/// let src_len = src.len();
1013-
/// let dst_len = dst.len();
1014-
///
1015-
/// // Ensure that `dst` has enough capacity to hold all of `src`.
1016-
/// dst.reserve(src_len);
1017-
///
1018-
/// unsafe {
1019-
/// // The call to offset is always safe because `Vec` will never
1020-
/// // allocate more than `isize::MAX` bytes.
1021-
/// let dst_ptr = dst.as_mut_ptr().offset(dst_len as isize);
1022-
/// let src_ptr = src.as_ptr();
1023-
///
1024-
/// // Truncate `src` without dropping its contents. We do this first,
1025-
/// // to avoid problems in case something further down panics.
1026-
/// src.set_len(0);
1027-
///
1028-
/// // The two regions cannot overlap because mutable references do
1029-
/// // not alias, and two different vectors cannot own the same
1030-
/// // memory.
1031-
/// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len);
1032-
///
1033-
/// // Notify `dst` that it now holds the contents of `src`.
1034-
/// dst.set_len(dst_len + src_len);
1035-
/// }
1036-
/// }
1037-
///
1038-
/// let mut a = vec!['r'];
1039-
/// let mut b = vec!['u', 's', 't'];
1040-
///
1041-
/// append(&mut a, &mut b);
1042-
///
1043-
/// assert_eq!(a, &['r', 'u', 's', 't']);
1044-
/// assert!(b.is_empty());
1045-
/// ```
1046-
///
1047-
/// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append
1048-
#[stable(feature = "rust1", since = "1.0.0")]
1049965
pub fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
1050966

1051-
/// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
1052-
/// and destination may overlap.
1053-
///
1054-
/// If the source and destination will *never* overlap,
1055-
/// [`copy_nonoverlapping`] can be used instead.
1056-
///
1057-
/// `copy` is semantically equivalent to C's [`memmove`], but with the argument
1058-
/// order swapped. Copying takes place as if the bytes were copied from `src`
1059-
/// to a temporary array and then copied from the array to `dst`.
1060-
///
1061-
/// [`copy_nonoverlapping`]: ./fn.copy_nonoverlapping.html
1062-
/// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove
1063-
///
1064-
/// # Safety
1065-
///
1066-
/// Behavior is undefined if any of the following conditions are violated:
1067-
///
1068-
/// * `src` must be [valid] for reads of `count * size_of::<T>()` bytes.
1069-
///
1070-
/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
1071-
///
1072-
/// * Both `src` and `dst` must be properly aligned.
1073-
///
1074-
/// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of
1075-
/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values
1076-
/// in the region beginning at `*src` and the region beginning at `*dst` can
1077-
/// [violate memory safety][read-ownership].
1078-
///
1079-
/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
1080-
/// `0`, the pointers must be non-NULL and properly aligned.
1081-
///
1082-
/// [`Copy`]: ../marker/trait.Copy.html
1083-
/// [`read`]: ../ptr/fn.read.html
1084-
/// [read-ownership]: ../ptr/fn.read.html#ownership-of-the-returned-value
1085-
/// [valid]: ../ptr/index.html#safety
1086-
///
1087-
/// # Examples
1088-
///
1089-
/// Efficiently create a Rust vector from an unsafe buffer:
1090-
///
1091-
/// ```
1092-
/// use std::ptr;
1093-
///
1094-
/// # #[allow(dead_code)]
1095-
/// unsafe fn from_buf_raw<T>(ptr: *const T, elts: usize) -> Vec<T> {
1096-
/// let mut dst = Vec::with_capacity(elts);
1097-
/// dst.set_len(elts);
1098-
/// ptr::copy(ptr, dst.as_mut_ptr(), elts);
1099-
/// dst
1100-
/// }
1101-
/// ```
1102-
#[stable(feature = "rust1", since = "1.0.0")]
1103967
pub fn copy<T>(src: *const T, dst: *mut T, count: usize);
1104968

1105-
/// Sets `count * size_of::<T>()` bytes of memory starting at `dst` to
1106-
/// `val`.
1107-
///
1108-
/// `write_bytes` is similar to C's [`memset`], but sets `count *
1109-
/// size_of::<T>()` bytes to `val`.
1110-
///
1111-
/// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset
1112-
///
1113-
/// # Safety
1114-
///
1115-
/// Behavior is undefined if any of the following conditions are violated:
1116-
///
1117-
/// * `dst` must be [valid] for writes of `count * size_of::<T>()` bytes.
1118-
///
1119-
/// * `dst` must be properly aligned.
1120-
///
1121-
/// Additionally, the caller must ensure that writing `count *
1122-
/// size_of::<T>()` bytes to the given region of memory results in a valid
1123-
/// value of `T`. Using a region of memory typed as a `T` that contains an
1124-
/// invalid value of `T` is undefined behavior.
1125-
///
1126-
/// Note that even if the effectively copied size (`count * size_of::<T>()`) is
1127-
/// `0`, the pointer must be non-NULL and properly aligned.
1128-
///
1129-
/// [valid]: ../ptr/index.html#safety
1130-
///
1131-
/// # Examples
1132-
///
1133-
/// Basic usage:
1134-
///
1135-
/// ```
1136-
/// use std::ptr;
1137-
///
1138-
/// let mut vec = vec![0u32; 4];
1139-
/// unsafe {
1140-
/// let vec_ptr = vec.as_mut_ptr();
1141-
/// ptr::write_bytes(vec_ptr, 0xfe, 2);
1142-
/// }
1143-
/// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]);
1144-
/// ```
1145-
///
1146-
/// Creating an invalid value:
1147-
///
1148-
/// ```
1149-
/// use std::ptr;
1150-
///
1151-
/// let mut v = Box::new(0i32);
1152-
///
1153-
/// unsafe {
1154-
/// // Leaks the previously held value by overwriting the `Box<T>` with
1155-
/// // a null pointer.
1156-
/// ptr::write_bytes(&mut v as *mut Box<i32>, 0, 1);
1157-
/// }
1158-
///
1159-
/// // At this point, using or dropping `v` results in undefined behavior.
1160-
/// // drop(v); // ERROR
1161-
///
1162-
/// // Even leaking `v` "uses" it, and hence is undefined behavior.
1163-
/// // mem::forget(v); // ERROR
1164-
///
1165-
/// // In fact, `v` is invalid according to basic type layout invariants, so *any*
1166-
/// // operation touching it is undefined behavior.
1167-
/// // let v2 = v; // ERROR
1168-
///
1169-
/// unsafe {
1170-
/// // Let us instead put in a valid value
1171-
/// ptr::write(&mut v as *mut Box<i32>, Box::new(42i32));
1172-
/// }
1173-
///
1174-
/// // Now the box is fine
1175-
/// assert_eq!(*v, 42);
1176-
/// ```
1177-
#[stable(feature = "rust1", since = "1.0.0")]
1178969
pub fn write_bytes<T>(dst: *mut T, val: u8, count: usize);
1179970

1180971
/// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with

0 commit comments

Comments
 (0)