Skip to content

Commit 093c02e

Browse files
author
Lukas Markeffsky
committed
document is_aligned{,_to} 
1 parent a906f6c commit 093c02e

File tree

2 files changed

+268
-8
lines changed

2 files changed

+268
-8
lines changed

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

Lines changed: 134 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1364,8 +1364,72 @@ impl<T: ?Sized> *const T {
13641364
}
13651365

13661366
/// Returns whether the pointer is properly aligned for `T`.
1367-
// #[cfg(not(bootstrap))] -- Calling this function in a const context from the bootstrap
1368-
// compiler will always return false.
1367+
///
1368+
/// # Examples
1369+
///
1370+
/// Basic usage:
1371+
/// ```
1372+
/// #![feature(pointer_is_aligned)]
1373+
/// #![feature(pointer_byte_offsets)]
1374+
///
1375+
/// let data: i32 = 42;
1376+
/// let ptr: *const i32 = &data;
1377+
///
1378+
/// assert!(ptr.is_aligned());
1379+
/// assert!(!ptr.wrapping_byte_add(1).is_aligned());
1380+
/// ```
1381+
///
1382+
/// # At compiletime
1383+
/// **Note: Alignment at compiletime is experimental and subject to change. See the
1384+
/// [tracking issue] for details.**
1385+
///
1386+
/// At compiletime, the compiler may not know where a value will end up in memory.
1387+
/// Calling this function on a pointer created from a reference at compiletime will only
1388+
/// return `true` if the pointer is guaranteed to be aligned. This means that the pointer
1389+
/// is never aligned if cast to a type with a stricter alignment than the reference's
1390+
/// underlying allocation.
1391+
///
1392+
#[cfg_attr(bootstrap, doc = "```ignore")]
1393+
#[cfg_attr(not(bootstrap), doc = "```")]
1394+
/// #![feature(pointer_is_aligned)]
1395+
/// #![feature(const_pointer_is_aligned)]
1396+
///
1397+
/// const _: () = {
1398+
/// let data: i32 = 42;
1399+
/// let ptr: *const i32 = &data;
1400+
/// assert!(ptr.is_aligned());
1401+
///
1402+
/// // At runtime either `ptr1` or `ptr2` would be aligned,
1403+
/// // but at compiletime neither is aligned.
1404+
/// let ptr1: *const i64 = ptr.cast();
1405+
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1406+
/// assert!(!ptr1.is_aligned());
1407+
/// assert!(!ptr2.is_aligned());
1408+
/// };
1409+
/// ```
1410+
///
1411+
/// If a pointer is created from a fixed address, this function behaves the same during
1412+
/// runtime and compiletime.
1413+
///
1414+
#[cfg_attr(bootstrap, doc = "```ignore")]
1415+
#[cfg_attr(not(bootstrap), doc = "```")]
1416+
/// #![feature(pointer_is_aligned)]
1417+
/// #![feature(const_pointer_is_aligned)]
1418+
///
1419+
/// const _: () = {
1420+
/// let ptr = 40 as *const i32;
1421+
/// assert!(ptr.is_aligned());
1422+
///
1423+
/// // For pointers with a known address, runtime and
1424+
/// // compiletime behavior are identical.
1425+
/// let ptr1: *const i64 = ptr.cast();
1426+
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1427+
/// assert!(ptr1.is_aligned());
1428+
/// assert!(!ptr2.is_aligned());
1429+
/// };
1430+
/// ```
1431+
///
1432+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
13691433
#[must_use]
13701434
#[inline]
13711435
#[unstable(feature = "pointer_is_aligned", issue = "96284")]
@@ -1385,8 +1449,74 @@ impl<T: ?Sized> *const T {
13851449
/// # Panics
13861450
///
13871451
/// The function panics if `align` is not a power-of-two (this includes 0).
1388-
// #[cfg(not(bootstrap))] -- Calling this function in a const context from the bootstrap
1389-
// compiler will always return false.
1452+
///
1453+
/// # Examples
1454+
///
1455+
/// Basic usage:
1456+
/// ```
1457+
/// #![feature(pointer_is_aligned)]
1458+
/// #![feature(pointer_byte_offsets)]
1459+
///
1460+
/// let data: i32 = 42;
1461+
/// let ptr: *const i32 = &data;
1462+
///
1463+
/// assert!(ptr.is_aligned_to(1));
1464+
/// assert!(ptr.is_aligned_to(2));
1465+
/// assert!(ptr.is_aligned_to(4));
1466+
///
1467+
/// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2));
1468+
/// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4));
1469+
///
1470+
/// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8));
1471+
/// ```
1472+
///
1473+
/// # At compiletime
1474+
/// **Note: Alignment at compiletime is experimental and subject to change. See the
1475+
/// [tracking issue] for details.**
1476+
///
1477+
/// At compiletime, the compiler may not know where a value will end up in memory.
1478+
/// Calling this function on a pointer created from a reference at compiletime will only
1479+
/// return `true` if the pointer is guaranteed to be aligned. This means that the pointer
1480+
/// cannot be stricter aligned than the reference's underlying allocation.
1481+
///
1482+
#[cfg_attr(bootstrap, doc = "```ignore")]
1483+
#[cfg_attr(not(bootstrap), doc = "```")]
1484+
/// #![feature(pointer_is_aligned)]
1485+
/// #![feature(const_pointer_is_aligned)]
1486+
///
1487+
/// const _: () = {
1488+
/// let data: i32 = 42;
1489+
/// let ptr: *const i32 = &data;
1490+
///
1491+
/// assert!(ptr.is_aligned_to(1));
1492+
/// assert!(ptr.is_aligned_to(2));
1493+
/// assert!(ptr.is_aligned_to(4));
1494+
///
1495+
/// // At compiletime, we know for sure that the pointer isn't aligned to 8.
1496+
/// assert!(!ptr.is_aligned_to(8));
1497+
/// assert!(!ptr.wrapping_add(1).is_aligned_to(8));
1498+
/// };
1499+
/// ```
1500+
///
1501+
/// If a pointer is created from a fixed address, this function behaves the same during
1502+
/// runtime and compiletime.
1503+
///
1504+
#[cfg_attr(bootstrap, doc = "```ignore")]
1505+
#[cfg_attr(not(bootstrap), doc = "```")]
1506+
/// #![feature(pointer_is_aligned)]
1507+
/// #![feature(const_pointer_is_aligned)]
1508+
///
1509+
/// const _: () = {
1510+
/// let ptr = 40 as *const i32;
1511+
/// assert!(ptr.is_aligned_to(1));
1512+
/// assert!(ptr.is_aligned_to(2));
1513+
/// assert!(ptr.is_aligned_to(4));
1514+
/// assert!(ptr.is_aligned_to(8));
1515+
/// assert!(!ptr.is_aligned_to(16));
1516+
/// };
1517+
/// ```
1518+
///
1519+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
13901520
#[must_use]
13911521
#[inline]
13921522
#[unstable(feature = "pointer_is_aligned", issue = "96284")]

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

Lines changed: 134 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1632,8 +1632,72 @@ impl<T: ?Sized> *mut T {
16321632
}
16331633

16341634
/// Returns whether the pointer is properly aligned for `T`.
1635-
// #[cfg(not(bootstrap))] -- Calling this function in a const context from the bootstrap
1636-
// compiler will always return false.
1635+
///
1636+
/// # Examples
1637+
///
1638+
/// Basic usage:
1639+
/// ```
1640+
/// #![feature(pointer_is_aligned)]
1641+
/// #![feature(pointer_byte_offsets)]
1642+
///
1643+
/// let data: i32 = 42;
1644+
/// let ptr: *const i32 = &data;
1645+
///
1646+
/// assert!(ptr.is_aligned());
1647+
/// assert!(!ptr.wrapping_byte_add(1).is_aligned());
1648+
/// ```
1649+
///
1650+
/// # At compiletime
1651+
/// **Note: Alignment at compiletime is experimental and subject to change. See the
1652+
/// [tracking issue] for details.**
1653+
///
1654+
/// At compiletime, the compiler may not know where a value will end up in memory.
1655+
/// Calling this function on a pointer created from a reference at compiletime will only
1656+
/// return `true` if the pointer is guaranteed to be aligned. This means that the pointer
1657+
/// is never aligned if cast to a type with a stricter alignment than the reference's
1658+
/// underlying allocation.
1659+
///
1660+
#[cfg_attr(bootstrap, doc = "```ignore")]
1661+
#[cfg_attr(not(bootstrap), doc = "```")]
1662+
/// #![feature(pointer_is_aligned)]
1663+
/// #![feature(const_pointer_is_aligned)]
1664+
///
1665+
/// const _: () = {
1666+
/// let data: i32 = 42;
1667+
/// let ptr: *const i32 = &data;
1668+
/// assert!(ptr.is_aligned());
1669+
///
1670+
/// // At runtime either `ptr1` or `ptr2` would be aligned,
1671+
/// // but at compiletime neither is aligned.
1672+
/// let ptr1: *const i64 = ptr.cast();
1673+
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1674+
/// assert!(!ptr1.is_aligned());
1675+
/// assert!(!ptr2.is_aligned());
1676+
/// };
1677+
/// ```
1678+
///
1679+
/// If a pointer is created from a fixed address, this function behaves the same during
1680+
/// runtime and compiletime.
1681+
///
1682+
#[cfg_attr(bootstrap, doc = "```ignore")]
1683+
#[cfg_attr(not(bootstrap), doc = "```")]
1684+
/// #![feature(pointer_is_aligned)]
1685+
/// #![feature(const_pointer_is_aligned)]
1686+
///
1687+
/// const _: () = {
1688+
/// let ptr = 40 as *const i32;
1689+
/// assert!(ptr.is_aligned());
1690+
///
1691+
/// // For pointers with a known address, runtime and
1692+
/// // compiletime behavior are identical.
1693+
/// let ptr1: *const i64 = ptr.cast();
1694+
/// let ptr2: *const i64 = ptr.wrapping_add(1).cast();
1695+
/// assert!(ptr1.is_aligned());
1696+
/// assert!(!ptr2.is_aligned());
1697+
/// };
1698+
/// ```
1699+
///
1700+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
16371701
#[must_use]
16381702
#[inline]
16391703
#[unstable(feature = "pointer_is_aligned", issue = "96284")]
@@ -1653,8 +1717,74 @@ impl<T: ?Sized> *mut T {
16531717
/// # Panics
16541718
///
16551719
/// The function panics if `align` is not a power-of-two (this includes 0).
1656-
// #[cfg(not(bootstrap))] -- Calling this function in a const context from the bootstrap
1657-
// compiler will always return false.
1720+
///
1721+
/// # Examples
1722+
///
1723+
/// Basic usage:
1724+
/// ```
1725+
/// #![feature(pointer_is_aligned)]
1726+
/// #![feature(pointer_byte_offsets)]
1727+
///
1728+
/// let data: i32 = 42;
1729+
/// let ptr: *const i32 = &data;
1730+
///
1731+
/// assert!(ptr.is_aligned_to(1));
1732+
/// assert!(ptr.is_aligned_to(2));
1733+
/// assert!(ptr.is_aligned_to(4));
1734+
///
1735+
/// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2));
1736+
/// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4));
1737+
///
1738+
/// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8));
1739+
/// ```
1740+
///
1741+
/// # At compiletime
1742+
/// **Note: Alignment at compiletime is experimental and subject to change. See the
1743+
/// [tracking issue] for details.**
1744+
///
1745+
/// At compiletime, the compiler may not know where a value will end up in memory.
1746+
/// Calling this function on a pointer created from a reference at compiletime will only
1747+
/// return `true` if the pointer is guaranteed to be aligned. This means that the pointer
1748+
/// cannot be stricter aligned than the reference's underlying allocation.
1749+
///
1750+
#[cfg_attr(bootstrap, doc = "```ignore")]
1751+
#[cfg_attr(not(bootstrap), doc = "```")]
1752+
/// #![feature(pointer_is_aligned)]
1753+
/// #![feature(const_pointer_is_aligned)]
1754+
///
1755+
/// const _: () = {
1756+
/// let data: i32 = 42;
1757+
/// let ptr: *const i32 = &data;
1758+
///
1759+
/// assert!(ptr.is_aligned_to(1));
1760+
/// assert!(ptr.is_aligned_to(2));
1761+
/// assert!(ptr.is_aligned_to(4));
1762+
///
1763+
/// // At compiletime, we know for sure that the pointer isn't aligned to 8.
1764+
/// assert!(!ptr.is_aligned_to(8));
1765+
/// assert!(!ptr.wrapping_add(1).is_aligned_to(8));
1766+
/// };
1767+
/// ```
1768+
///
1769+
/// If a pointer is created from a fixed address, this function behaves the same during
1770+
/// runtime and compiletime.
1771+
///
1772+
#[cfg_attr(bootstrap, doc = "```ignore")]
1773+
#[cfg_attr(not(bootstrap), doc = "```")]
1774+
/// #![feature(pointer_is_aligned)]
1775+
/// #![feature(const_pointer_is_aligned)]
1776+
///
1777+
/// const _: () = {
1778+
/// let ptr = 40 as *const i32;
1779+
/// assert!(ptr.is_aligned_to(1));
1780+
/// assert!(ptr.is_aligned_to(2));
1781+
/// assert!(ptr.is_aligned_to(4));
1782+
/// assert!(ptr.is_aligned_to(8));
1783+
/// assert!(!ptr.is_aligned_to(16));
1784+
/// };
1785+
/// ```
1786+
///
1787+
/// [tracking issue]: https://github.com/rust-lang/rust/issues/comming-soon
16581788
#[must_use]
16591789
#[inline]
16601790
#[unstable(feature = "pointer_is_aligned", issue = "96284")]

0 commit comments

Comments
 (0)