Skip to content

Commit 8a60536

Browse files
author
Lukas Markeffsky
committed
docs cleanup
* Fix doc examples for Platforms with underaligned integer primitives. * Mutable pointer doc examples use mutable pointers. * Fill out tracking issue. * Minor formatting changes.
1 parent daccb8c commit 8a60536

File tree

2 files changed

+140
-72
lines changed

2 files changed

+140
-72
lines changed

‎library/core/src/ptr/const_ptr.rs‎

Lines changed: 68 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1367,8 +1367,12 @@ impl<T: ?Sized> *const T {
13671367
/// #![feature(pointer_is_aligned)]
13681368
/// #![feature(pointer_byte_offsets)]
13691369
///
1370-
/// let data: i32 = 42;
1371-
/// let ptr: *const i32 = &data;
1370+
/// // On some platforms, the alignment of i32 is less than 4.
1371+
/// #[repr(align(4))]
1372+
/// struct AlignedI32(i32);
1373+
///
1374+
/// let data = AlignedI32(42);
1375+
/// let ptr = &data as *const AlignedI32;
13721376
///
13731377
/// assert!(ptr.is_aligned());
13741378
/// assert!(!ptr.wrapping_byte_add(1).is_aligned());
@@ -1389,15 +1393,20 @@ impl<T: ?Sized> *const T {
13891393
/// #![feature(pointer_is_aligned)]
13901394
/// #![feature(const_pointer_is_aligned)]
13911395
///
1396+
/// // On some platforms, the alignment of primitives is less than their size.
1397+
/// #[repr(align(4))]
1398+
/// struct AlignedI32(i32);
1399+
/// #[repr(align(8))]
1400+
/// struct AlignedI64(i64);
1401+
///
13921402
/// const _: () = {
1393-
/// let data: i32 = 42;
1394-
/// let ptr: *const i32 = &data;
1403+
/// let data = AlignedI32(42);
1404+
/// let ptr = &data as *const AlignedI32;
13951405
/// assert!(ptr.is_aligned());
13961406
///
1397-
/// // At runtime either `ptr1` or `ptr2` would be aligned,
1398-
/// // but at compiletime neither is aligned.
1399-
/// let ptr1: *const i64 = ptr.cast();
1400-
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1407+
/// // At runtime either `ptr1` or `ptr2` would be aligned, but at compiletime neither is aligned.
1408+
/// let ptr1 = ptr.cast::<AlignedI64>();
1409+
/// let ptr2 = ptr.wrapping_add(1).cast::<AlignedI64>();
14011410
/// assert!(!ptr1.is_aligned());
14021411
/// assert!(!ptr2.is_aligned());
14031412
/// };
@@ -1411,16 +1420,22 @@ impl<T: ?Sized> *const T {
14111420
/// #![feature(pointer_is_aligned)]
14121421
/// #![feature(const_pointer_is_aligned)]
14131422
///
1414-
/// // At compiletime, neither `CONST_PTR` nor `CONST_PTR + 1` is aligned.
1415-
/// const CONST_PTR: *const i32 = &42;
1416-
/// const _: () = assert!(!CONST_PTR.cast::<i64>().is_aligned());
1417-
/// const _: () = assert!(!CONST_PTR.wrapping_add(1).cast::<i64>().is_aligned());
1423+
/// // On some platforms, the alignment of primitives is less than their size.
1424+
/// #[repr(align(4))]
1425+
/// struct AlignedI32(i32);
1426+
/// #[repr(align(8))]
1427+
/// struct AlignedI64(i64);
1428+
///
1429+
/// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned.
1430+
/// const COMPTIME_PTR: *const AlignedI32 = &AlignedI32(42);
1431+
/// const _: () = assert!(!COMPTIME_PTR.cast::<AlignedI64>().is_aligned());
1432+
/// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).cast::<AlignedI64>().is_aligned());
14181433
///
14191434
/// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned.
1420-
/// let runtime_ptr = CONST_PTR;
1435+
/// let runtime_ptr = COMPTIME_PTR;
14211436
/// assert_ne!(
1422-
/// runtime_ptr.cast::<i64>().is_aligned(),
1423-
/// runtime_ptr.wrapping_add(1).cast::<i64>().is_aligned(),
1437+
/// runtime_ptr.cast::<AlignedI64>().is_aligned(),
1438+
/// runtime_ptr.wrapping_add(1).cast::<AlignedI64>().is_aligned(),
14241439
/// );
14251440
/// ```
14261441
///
@@ -1432,29 +1447,34 @@ impl<T: ?Sized> *const T {
14321447
/// #![feature(pointer_is_aligned)]
14331448
/// #![feature(const_pointer_is_aligned)]
14341449
///
1450+
/// // On some platforms, the alignment of primitives is less than their size.
1451+
/// #[repr(align(4))]
1452+
/// struct AlignedI32(i32);
1453+
/// #[repr(align(8))]
1454+
/// struct AlignedI64(i64);
1455+
///
14351456
/// const _: () = {
1436-
/// let ptr = 40 as *const i32;
1457+
/// let ptr = 40 as *const AlignedI32;
14371458
/// assert!(ptr.is_aligned());
14381459
///
1439-
/// // For pointers with a known address, runtime and
1440-
/// // compiletime behavior are identical.
1441-
/// let ptr1: *const i64 = ptr.cast();
1442-
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1460+
/// // For pointers with a known address, runtime and compiletime behavior are identical.
1461+
/// let ptr1 = ptr.cast::<AlignedI64>();
1462+
/// let ptr2 = ptr.wrapping_add(1).cast::<AlignedI64>();
14431463
/// assert!(ptr1.is_aligned());
14441464
/// assert!(!ptr2.is_aligned());
14451465
/// };
14461466
/// ```
14471467
///
1448-
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
1468+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/104203
14491469
#[must_use]
14501470
#[inline]
14511471
#[unstable(feature = "pointer_is_aligned", issue = "96284")]
1452-
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "none")]
1472+
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")]
14531473
pub const fn is_aligned(self) -> bool
14541474
where
14551475
T: Sized,
14561476
{
1457-
self.is_aligned_to(core::mem::align_of::<T>())
1477+
self.is_aligned_to(mem::align_of::<T>())
14581478
}
14591479

14601480
/// Returns whether the pointer is aligned to `align`.
@@ -1473,8 +1493,12 @@ impl<T: ?Sized> *const T {
14731493
/// #![feature(pointer_is_aligned)]
14741494
/// #![feature(pointer_byte_offsets)]
14751495
///
1476-
/// let data: i32 = 42;
1477-
/// let ptr: *const i32 = &data;
1496+
/// // On some platforms, the alignment of i32 is less than 4.
1497+
/// #[repr(align(4))]
1498+
/// struct AlignedI32(i32);
1499+
///
1500+
/// let data = AlignedI32(42);
1501+
/// let ptr = &data as *const AlignedI32;
14781502
///
14791503
/// assert!(ptr.is_aligned_to(1));
14801504
/// assert!(ptr.is_aligned_to(2));
@@ -1500,9 +1524,13 @@ impl<T: ?Sized> *const T {
15001524
/// #![feature(pointer_is_aligned)]
15011525
/// #![feature(const_pointer_is_aligned)]
15021526
///
1527+
/// // On some platforms, the alignment of i32 is less than 4.
1528+
/// #[repr(align(4))]
1529+
/// struct AlignedI32(i32);
1530+
///
15031531
/// const _: () = {
1504-
/// let data: i32 = 42;
1505-
/// let ptr: *const i32 = &data;
1532+
/// let data = AlignedI32(42);
1533+
/// let ptr = &data as *const AlignedI32;
15061534
///
15071535
/// assert!(ptr.is_aligned_to(1));
15081536
/// assert!(ptr.is_aligned_to(2));
@@ -1522,13 +1550,17 @@ impl<T: ?Sized> *const T {
15221550
/// #![feature(pointer_is_aligned)]
15231551
/// #![feature(const_pointer_is_aligned)]
15241552
///
1525-
/// // At compiletime, neither `CONST_PTR` nor `CONST_PTR + 1` is aligned.
1526-
/// const CONST_PTR: *const i32 = &42;
1527-
/// const _: () = assert!(!CONST_PTR.is_aligned_to(8));
1528-
/// const _: () = assert!(!CONST_PTR.wrapping_add(1).is_aligned_to(8));
1553+
/// // On some platforms, the alignment of i32 is less than 4.
1554+
/// #[repr(align(4))]
1555+
/// struct AlignedI32(i32);
1556+
///
1557+
/// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned.
1558+
/// const COMPTIME_PTR: *const AlignedI32 = &AlignedI32(42);
1559+
/// const _: () = assert!(!COMPTIME_PTR.is_aligned_to(8));
1560+
/// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).is_aligned_to(8));
15291561
///
15301562
/// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned.
1531-
/// let runtime_ptr = CONST_PTR;
1563+
/// let runtime_ptr = COMPTIME_PTR;
15321564
/// assert_ne!(
15331565
/// runtime_ptr.is_aligned_to(8),
15341566
/// runtime_ptr.wrapping_add(1).is_aligned_to(8),
@@ -1544,7 +1576,7 @@ impl<T: ?Sized> *const T {
15441576
/// #![feature(const_pointer_is_aligned)]
15451577
///
15461578
/// const _: () = {
1547-
/// let ptr = 40 as *const i32;
1579+
/// let ptr = 40 as *const u8;
15481580
/// assert!(ptr.is_aligned_to(1));
15491581
/// assert!(ptr.is_aligned_to(2));
15501582
/// assert!(ptr.is_aligned_to(4));
@@ -1553,14 +1585,14 @@ impl<T: ?Sized> *const T {
15531585
/// };
15541586
/// ```
15551587
///
1556-
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
1588+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/104203
15571589
#[must_use]
15581590
#[inline]
15591591
#[unstable(feature = "pointer_is_aligned", issue = "96284")]
1560-
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "none")]
1592+
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")]
15611593
pub const fn is_aligned_to(self, align: usize) -> bool {
15621594
if !align.is_power_of_two() {
1563-
panic!("is_aligned_to: align is not a power-of-two")
1595+
panic!("is_aligned_to: align is not a power-of-two");
15641596
}
15651597

15661598
// We can't use the address of `self` in a `const fn`, so we use `align_offset` instead.

‎library/core/src/ptr/mut_ptr.rs‎

Lines changed: 72 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1635,8 +1635,12 @@ impl<T: ?Sized> *mut T {
16351635
/// #![feature(pointer_is_aligned)]
16361636
/// #![feature(pointer_byte_offsets)]
16371637
///
1638-
/// let data: i32 = 42;
1639-
/// let ptr: *const i32 = &data;
1638+
/// // On some platforms, the alignment of i32 is less than 4.
1639+
/// #[repr(align(4))]
1640+
/// struct AlignedI32(i32);
1641+
///
1642+
/// let mut data = AlignedI32(42);
1643+
/// let ptr = &mut data as *mut AlignedI32;
16401644
///
16411645
/// assert!(ptr.is_aligned());
16421646
/// assert!(!ptr.wrapping_byte_add(1).is_aligned());
@@ -1656,16 +1660,22 @@ impl<T: ?Sized> *mut T {
16561660
#[cfg_attr(not(bootstrap), doc = "```")]
16571661
/// #![feature(pointer_is_aligned)]
16581662
/// #![feature(const_pointer_is_aligned)]
1663+
/// #![feature(const_mut_refs)]
1664+
///
1665+
/// // On some platforms, the alignment of primitives is less than their size.
1666+
/// #[repr(align(4))]
1667+
/// struct AlignedI32(i32);
1668+
/// #[repr(align(8))]
1669+
/// struct AlignedI64(i64);
16591670
///
16601671
/// const _: () = {
1661-
/// let data: i32 = 42;
1662-
/// let ptr: *const i32 = &data;
1672+
/// let mut data = AlignedI32(42);
1673+
/// let ptr = &mut data as *mut AlignedI32;
16631674
/// assert!(ptr.is_aligned());
16641675
///
1665-
/// // At runtime either `ptr1` or `ptr2` would be aligned,
1666-
/// // but at compiletime neither is aligned.
1667-
/// let ptr1: *const i64 = ptr.cast();
1668-
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1676+
/// // At runtime either `ptr1` or `ptr2` would be aligned, but at compiletime neither is aligned.
1677+
/// let ptr1 = ptr.cast::<AlignedI64>();
1678+
/// let ptr2 = ptr.wrapping_add(1).cast::<AlignedI64>();
16691679
/// assert!(!ptr1.is_aligned());
16701680
/// assert!(!ptr2.is_aligned());
16711681
/// };
@@ -1679,16 +1689,23 @@ impl<T: ?Sized> *mut T {
16791689
/// #![feature(pointer_is_aligned)]
16801690
/// #![feature(const_pointer_is_aligned)]
16811691
///
1682-
/// // At compiletime, neither `CONST_PTR` nor `CONST_PTR + 1` is aligned.
1683-
/// const CONST_PTR: *const i32 = &42;
1684-
/// const _: () = assert!(!CONST_PTR.cast::<i64>().is_aligned());
1685-
/// const _: () = assert!(!CONST_PTR.wrapping_add(1).cast::<i64>().is_aligned());
1692+
/// // On some platforms, the alignment of primitives is less than their size.
1693+
/// #[repr(align(4))]
1694+
/// struct AlignedI32(i32);
1695+
/// #[repr(align(8))]
1696+
/// struct AlignedI64(i64);
1697+
///
1698+
/// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned.
1699+
/// // Also, note that mutable references are not allowed in the final value of constants.
1700+
/// const COMPTIME_PTR: *mut AlignedI32 = (&AlignedI32(42) as *const AlignedI32).cast_mut();
1701+
/// const _: () = assert!(!COMPTIME_PTR.cast::<AlignedI64>().is_aligned());
1702+
/// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).cast::<AlignedI64>().is_aligned());
16861703
///
16871704
/// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned.
1688-
/// let runtime_ptr = CONST_PTR;
1705+
/// let runtime_ptr = COMPTIME_PTR;
16891706
/// assert_ne!(
1690-
/// runtime_ptr.cast::<i64>().is_aligned(),
1691-
/// runtime_ptr.wrapping_add(1).cast::<i64>().is_aligned(),
1707+
/// runtime_ptr.cast::<AlignedI64>().is_aligned(),
1708+
/// runtime_ptr.wrapping_add(1).cast::<AlignedI64>().is_aligned(),
16921709
/// );
16931710
/// ```
16941711
///
@@ -1700,29 +1717,34 @@ impl<T: ?Sized> *mut T {
17001717
/// #![feature(pointer_is_aligned)]
17011718
/// #![feature(const_pointer_is_aligned)]
17021719
///
1720+
/// // On some platforms, the alignment of primitives is less than their size.
1721+
/// #[repr(align(4))]
1722+
/// struct AlignedI32(i32);
1723+
/// #[repr(align(8))]
1724+
/// struct AlignedI64(i64);
1725+
///
17031726
/// const _: () = {
1704-
/// let ptr = 40 as *const i32;
1727+
/// let ptr = 40 as *mut AlignedI32;
17051728
/// assert!(ptr.is_aligned());
17061729
///
1707-
/// // For pointers with a known address, runtime and
1708-
/// // compiletime behavior are identical.
1709-
/// let ptr1: *const i64 = ptr.cast();
1710-
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1730+
/// // For pointers with a known address, runtime and compiletime behavior are identical.
1731+
/// let ptr1 = ptr.cast::<AlignedI64>();
1732+
/// let ptr2 = ptr.wrapping_add(1).cast::<AlignedI64>();
17111733
/// assert!(ptr1.is_aligned());
17121734
/// assert!(!ptr2.is_aligned());
17131735
/// };
17141736
/// ```
17151737
///
1716-
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
1738+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/104203
17171739
#[must_use]
17181740
#[inline]
17191741
#[unstable(feature = "pointer_is_aligned", issue = "96284")]
1720-
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "none")]
1742+
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")]
17211743
pub const fn is_aligned(self) -> bool
17221744
where
17231745
T: Sized,
17241746
{
1725-
self.is_aligned_to(core::mem::align_of::<T>())
1747+
self.is_aligned_to(mem::align_of::<T>())
17261748
}
17271749

17281750
/// Returns whether the pointer is aligned to `align`.
@@ -1741,8 +1763,12 @@ impl<T: ?Sized> *mut T {
17411763
/// #![feature(pointer_is_aligned)]
17421764
/// #![feature(pointer_byte_offsets)]
17431765
///
1744-
/// let data: i32 = 42;
1745-
/// let ptr: *const i32 = &data;
1766+
/// // On some platforms, the alignment of i32 is less than 4.
1767+
/// #[repr(align(4))]
1768+
/// struct AlignedI32(i32);
1769+
///
1770+
/// let mut data = AlignedI32(42);
1771+
/// let ptr = &mut data as *mut AlignedI32;
17461772
///
17471773
/// assert!(ptr.is_aligned_to(1));
17481774
/// assert!(ptr.is_aligned_to(2));
@@ -1767,10 +1793,15 @@ impl<T: ?Sized> *mut T {
17671793
#[cfg_attr(not(bootstrap), doc = "```")]
17681794
/// #![feature(pointer_is_aligned)]
17691795
/// #![feature(const_pointer_is_aligned)]
1796+
/// #![feature(const_mut_refs)]
1797+
///
1798+
/// // On some platforms, the alignment of i32 is less than 4.
1799+
/// #[repr(align(4))]
1800+
/// struct AlignedI32(i32);
17701801
///
17711802
/// const _: () = {
1772-
/// let data: i32 = 42;
1773-
/// let ptr: *const i32 = &data;
1803+
/// let mut data = AlignedI32(42);
1804+
/// let ptr = &mut data as *mut AlignedI32;
17741805
///
17751806
/// assert!(ptr.is_aligned_to(1));
17761807
/// assert!(ptr.is_aligned_to(2));
@@ -1790,13 +1821,18 @@ impl<T: ?Sized> *mut T {
17901821
/// #![feature(pointer_is_aligned)]
17911822
/// #![feature(const_pointer_is_aligned)]
17921823
///
1793-
/// // At compiletime, neither `CONST_PTR` nor `CONST_PTR + 1` is aligned.
1794-
/// const CONST_PTR: *const i32 = &42;
1795-
/// const _: () = assert!(!CONST_PTR.is_aligned_to(8));
1796-
/// const _: () = assert!(!CONST_PTR.wrapping_add(1).is_aligned_to(8));
1824+
/// // On some platforms, the alignment of i32 is less than 4.
1825+
/// #[repr(align(4))]
1826+
/// struct AlignedI32(i32);
1827+
///
1828+
/// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned.
1829+
/// // Also, note that mutable references are not allowed in the final value of constants.
1830+
/// const COMPTIME_PTR: *mut AlignedI32 = (&AlignedI32(42) as *const AlignedI32).cast_mut();
1831+
/// const _: () = assert!(!COMPTIME_PTR.is_aligned_to(8));
1832+
/// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).is_aligned_to(8));
17971833
///
17981834
/// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned.
1799-
/// let runtime_ptr = CONST_PTR;
1835+
/// let runtime_ptr = COMPTIME_PTR;
18001836
/// assert_ne!(
18011837
/// runtime_ptr.is_aligned_to(8),
18021838
/// runtime_ptr.wrapping_add(1).is_aligned_to(8),
@@ -1812,7 +1848,7 @@ impl<T: ?Sized> *mut T {
18121848
/// #![feature(const_pointer_is_aligned)]
18131849
///
18141850
/// const _: () = {
1815-
/// let ptr = 40 as *const i32;
1851+
/// let ptr = 40 as *mut u8;
18161852
/// assert!(ptr.is_aligned_to(1));
18171853
/// assert!(ptr.is_aligned_to(2));
18181854
/// assert!(ptr.is_aligned_to(4));
@@ -1821,14 +1857,14 @@ impl<T: ?Sized> *mut T {
18211857
/// };
18221858
/// ```
18231859
///
1824-
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
1860+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/104203
18251861
#[must_use]
18261862
#[inline]
18271863
#[unstable(feature = "pointer_is_aligned", issue = "96284")]
1828-
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "none")]
1864+
#[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")]
18291865
pub const fn is_aligned_to(self, align: usize) -> bool {
18301866
if !align.is_power_of_two() {
1831-
panic!("is_aligned_to: align is not a power-of-two")
1867+
panic!("is_aligned_to: align is not a power-of-two");
18321868
}
18331869

18341870
// We can't use the address of `self` in a `const fn`, so we use `align_offset` instead.

0 commit comments

Comments
 (0)