Merge 2018-11 LWG Motion 17

P1007R3 std::assume_aligned

Fixes #2423

Author: zygoloid

source/utilities.tex

@@ -6572,8 +6572,10 @@
   void undeclare_no_pointers(char* p, size_t n);
   pointer_safety get_pointer_safety() noexcept;
 
-  // \ref{ptr.align}, pointer alignment function
+  // \ref{ptr.align}, pointer alignment
   void* align(size_t alignment, size_t size, void*& ptr, size_t& space);
+  template<size_t N, class T>
+    [[nodiscard]] constexpr T* assume_aligned(T* ptr);
 
   // \ref{allocator.tag}, allocator argument tag
   struct allocator_arg_t { explicit allocator_arg_t() = default; };
@@ -7128,7 +7130,7 @@
 \end{itemdescr}
 
 
-\rSec2[ptr.align]{Align}
+\rSec2[ptr.align]{Pointer alignment}
 
 \indexlibrary{\idxcode{align}}%
 \begin{itemdecl}
@@ -7166,6 +7168,44 @@
 arguments for the same buffer.  \end{note}
 \end{itemdescr}
 
+\indexlibrary{\idxcode{assume_aligned}}%
+\begin{itemdecl}
+template<size_t N, class T>
+  [[nodiscard]] constexpr T* assume_aligned(T* ptr);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\mandates
+\tcode{N} is a power of two.
+
+\pnum
+\expects
+\tcode{ptr} points to an object \tcode{X} of
+a type similar\iref{conv.qual} to \tcode{T},
+where \tcode{X} has alignment \tcode{N}\iref{basic.align}.
+
+\pnum
+\returns
+\tcode{ptr}.
+
+\pnum
+\throws
+Nothing.
+
+\pnum
+\begin{note}
+The alignment assumption on an object \tcode{X}
+expressed by a call to \tcode{assume_aligned}
+may result in generation of more efficient code.
+It is up to the program to ensure that the assumption actually holds.
+The call does not cause the compiler to verify or enforce this.
+An implementation might only make the assumption
+for those operations on \tcode{X} that access \tcode{X}
+through the pointer returned by \tcode{assume_aligned}.
+\end{note}
+\end{itemdescr}
+
 \rSec2[allocator.tag]{Allocator argument tag}
 
 \indexlibrary{\idxcode{allocator_arg_t}}%