Merge 2017-07 LWG Motion 36

Author: zygoloid

source/utilities.tex

@@ -9165,9 +9165,29 @@
 
   // \ref{util.smartptr.shared.create}, \tcode{shared_ptr} creation
   template<class T, class... Args>
-    shared_ptr<T> make_shared(Args&&... args);
+    shared_ptr<T> make_shared(Args&&... args); // \tcode{T} is not array
   template<class T, class A, class... Args>
-    shared_ptr<T> allocate_shared(const A& a, Args&&... args);
+    shared_ptr<T> allocate_shared(const A& a, Args&&... args); // \tcode{T} is not array
+
+  template<class T> shared_ptr<T> make_shared(size_t N); // \tcode{T} is \tcode{U[]}
+  template<class T, class A>
+    shared_ptr<T> allocate_shared(const A& a, size_t N); // \tcode{T} is \tcode{U[]}
+
+  template<class T> shared_ptr<T> make_shared(); // \tcode{T} is \tcode{U[N]}
+  template<class T, class A>
+    shared_ptr<T> allocate_shared(const A& a); // \tcode{T} is \tcode{U[N]}
+
+  template<class T>
+    shared_ptr<T> make_shared(size_t N, const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[]}
+  template<class T, class A>
+    shared_ptr<T> allocate_shared(const A& a, size_t N,
+                                  const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[]}
+
+  template<class T> shared_ptr<T>
+    make_shared(const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[N]}
+  template<class T, class A>
+    shared_ptr<T> allocate_shared(const A& a,
+                                  const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[N]}
 
   // \ref{util.smartptr.shared.cmp}, \tcode{shared_ptr} comparisons
   template<class T, class U>
@@ -9730,54 +9750,270 @@
 
 \rSec4[util.smartptr.shared.create]{\tcode{shared_ptr} creation}
 
+\pnum
+The common requirements that apply to
+all \tcode{make_shared} and \tcode{allocate_shared} overloads,
+unless specified otherwise, are described below.
+
+\indexlibrary{\idxcode{make_shared}}%
+\indexlibrary{\idxcode{allocate_shared}}%
+\begin{itemdecl}
+template<class T, ...>
+  shared_ptr<T> make_shared(\placeholder{args});
+template<class T, class A, ...>
+  shared_ptr<T> allocate_shared(const A& a, \placeholder{args});
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\requires \tcode{A} shall be an allocator~(\ref{allocator.requirements}).
+
+\pnum
+\effects Allocates memory for an object of type \tcode{T}
+(or \tcode{U[N]} when \tcode{T} is \tcode{U[]},
+where \tcode{N} is determined from \placeholder{args} as specified by the concrete overload).
+The object is initialized from \placeholder{args} as specified by the concrete overload.
+The \tcode{allocate_shared} templates use a copy of \tcode{a}
+(rebound for an unspecified \tcode{value_type}) to allocate memory.
+If an exception is thrown, the functions have no effect.
+
+\pnum
+\returns A \tcode{shared_ptr} instance that stores and owns the address of
+the newly constructed object.
+
+\pnum
+\postconditions \tcode{r.get() != 0 \&\& r.use_count() == 1},
+where \tcode{r} is the return value.
+
+\pnum
+\throws \tcode{bad_alloc}, or
+an exception thrown from \tcode{allocate} or from the initialization of the object.
+
+\pnum
+\remarks
+\begin{itemize}
+\item
+  Implementations should perform no more than one memory allocation.
+  \begin{note}
+  This provides efficiency equivalent to an intrusive smart pointer.
+  \end{note}
+\item
+  When an object of an array type \tcode{U} is specified to have
+  an initial value of \tcode{u} (of the same type),
+  this shall be interpreted to mean that
+  each array element of the object has as its initial value
+  the corresponding element from \tcode{u}.
+\item
+  When an object of an array type is specified to have
+  a default initial value,
+  this shall be interpreted to mean that each array element of the object
+  has a default initial value.
+\item
+  When a (sub)object of a non-array type \tcode{U} is specified to have
+  an initial value of \tcode{v}, or \tcode{U(l...)},
+  where \tcode{l...} is a list of constructor arguments,
+  \tcode{make_shared} shall initialize this (sub)object
+  via the expression \tcode{::new(pv) U(v)} or \tcode{::new(pv) U(l...)} respectively,
+  where \tcode{pv} has type \tcode{void*} and points to storage
+  suitable to hold an object of type \tcode{U}.
+\item
+  When a (sub)object of a non-array type \tcode{U} is specified to have
+  an initial value of \tcode{v}, or \tcode{U(l...)},
+  where \tcode{l...} is a list of constructor arguments,
+  \tcode{allocate_shared} shall initialize this (sub)object
+  via the expression
+  \begin{itemize}
+  \item \tcode{allocator_traits<A2>::construct(a2, pv, v)} or
+  \item \tcode{allocator_traits<A2>::construct(a2, pv, l...)}
+  \end{itemize}
+  respectively,
+  where \tcode{pv} points to storage
+  suitable to hold an object of type \tcode{U} and
+  \tcode{a2} of type \tcode{A2} is a rebound copy of
+  the allocator \tcode{a} passed to \tcode{allocate_shared}
+  such that its \tcode{value_type} is \tcode{U}.
+\item
+  When a (sub)object of non-array type \tcode{U} is specified to have
+  a default initial value,
+  \tcode{make_shared} shall initialize this (sub)object
+  via the expression \tcode{::new(pv) U()},
+  where \tcode{pv} has type \tcode{void*} and points to storage
+  suitable to hold an object of type \tcode{U}.
+\item
+  When a (sub)object of non-array type \tcode{U} is specified to have
+  a default initial value,
+  \tcode{allocate_shared} shall initialize this (sub)object
+  via the expression \tcode{allocator_traits<A2>::construct(a2, pv)},
+  where \tcode{pv} points to storage
+  suitable to hold an object of type \tcode{U} and
+  \tcode{a2} of type \tcode{A2} is a rebound copy of
+  the allocator \tcode{a} passed to \tcode{allocate_shared}
+  such that its \tcode{value_type} is \tcode{U}.
+\item
+  Array elements are initialized in ascending order of their addresses.
+\item
+  When the lifetime of the object managed by the return value ends, or
+  when the initialization of an array element throws an exception,
+  the initialized elements should be destroyed in the reverse order of their construction.
+\end{itemize}
+\begin{note}
+These functions will typically allocate more memory than \tcode{sizeof(T)} to
+allow for internal bookkeeping structures such as reference counts.
+\end{note}
+\end{itemdescr}
+
 \indexlibrary{\idxcode{make_shared}}%
 \indexlibrary{\idxcode{allocate_shared}}%
 \begin{itemdecl}
 template<class T, class... Args>
-  shared_ptr<T> make_shared(Args&&... args);
+  shared_ptr<T> make_shared(Args&&... args); // \tcode{T} is not array
 template<class T, class A, class... Args>
-  shared_ptr<T> allocate_shared(const A& a, Args&&... args);
+  shared_ptr<T> allocate_shared(const A& a, Args&&... args); // \tcode{T} is not array
 \end{itemdecl}
 
 \begin{itemdescr}
 \pnum
-\requires The expression \tcode{::new (pv) T(std::forward<Args>(args)...)},
-where \tcode{pv} has type \tcode{void*} and points to storage suitable
-to hold an object of type \tcode{T}, shall be well formed. \tcode{A} shall
-be an allocator~(\ref{allocator.requirements}). The copy constructor
-and destructor of \tcode{A} shall not throw exceptions.
+\returns A \tcode{shared_ptr} to an object of type \tcode{T}
+with an initial value \tcode{T(forward<Args>(args)...)}.
 
 \pnum
-\effects Allocates memory suitable for an object of type \tcode{T}
-and constructs an object in that memory via the placement
-\grammarterm{new-expression}
-\tcode{::new (pv) T(std::forward<Args>(args)...)}.
-The template \tcode{allocate_shared} uses a copy of \tcode{a} to
-allocate memory. If an exception is thrown, the functions have no effect.
+\remarks These overloads shall only participate in overload resolution
+when \tcode{T} is not an array type.
+The \tcode{shared_ptr} constructors called by these functions
+enable \tcode{shared_from_this}
+with the address of the newly constructed object of type \tcode{T}.
 
 \pnum
-\returns A \tcode{shared_ptr} instance that stores and owns
-the address of the newly constructed object of type \tcode{T}.
+\begin{example}
+\begin{codeblock}
+shared_ptr<int> p = make_shared<int>(); // \tcode{shared_ptr} to \tcode{int()}
+shared_ptr<vector<int>> q = make_shared<vector<int>>(16, 1);
+  // \tcode{shared_ptr} to vector of \tcode{16} elements with value \tcode{1}
+\end{codeblock}
+\end{example}
+\end{itemdescr}
 
+\indexlibrary{\idxcode{make_shared}}%
+\indexlibrary{\idxcode{allocate_shared}}%
+\begin{itemdecl}
+template<class T> shared_ptr<T> make_shared(size_t N); // \tcode{T} is \tcode{U[]}
+template<class T, class A>
+  shared_ptr<T> allocate_shared(const A& a, size_t N); // \tcode{T} is \tcode{U[]}
+\end{itemdecl}
+
+\begin{itemdescr}
 \pnum
-\postconditions \tcode{get() != 0 \&\& use_count() == 1}.
+\returns A \tcode{shared_ptr} to an object of type \tcode{U[N]}
+with a default initial value,
+where \tcode{U} is \tcode{remove_extent_t<T>}.
 
 \pnum
-\throws \tcode{bad_alloc}, or an exception thrown from
-\tcode{A::allocate} or from the constructor of \tcode{T}.
+\remarks These overloads shall only participate in overload resolution
+when \tcode{T} is of the form \tcode{U[]}.
 
 \pnum
-\remarks The \tcode{shared_ptr} constructor called by this function
-enables \tcode{shared_from_this} with the address
-of the newly constructed object of type \tcode{T}.
-Implementations should
-perform no more than one memory allocation. \begin{note} This provides
-efficiency equivalent to an intrusive smart pointer. \end{note}
+\begin{example}
+\begin{codeblock}
+shared_ptr<double[]> p = make_shared<double[]>(1024);
+  // \tcode{shared_ptr} to a value-initialized \tcode{double[1024]}
+shared_ptr<double[][2][2]> q = make_shared<double[][2][2]>(6);
+  // \tcode{shared_ptr} to a value-initialized \tcode{double[6][2][2]}
+\end{codeblock}
+\end{example}
+\end{itemdescr}
+
+\indexlibrary{\idxcode{make_shared}}%
+\indexlibrary{\idxcode{allocate_shared}}%
+\begin{itemdecl}
+template<class T> shared_ptr<T> make_shared(); // \tcode{T} is \tcode{U[N]}
+template<class T, class A>
+  shared_ptr<T> allocate_shared(const A& a); // \tcode{T} is \tcode{U[N]}
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\returns A \tcode{shared_ptr} to an object of type \tcode{T}
+with a default initial value.
+
+\pnum
+\remarks These overloads shall only participate in overload resolution
+when \tcode{T} is of the form \tcode{U[N]}.
 
 \pnum
-\begin{note} These functions will typically allocate more memory
-than \tcode{sizeof(T)} to allow for internal bookkeeping structures such
-as the reference counts. \end{note}
+\begin{example}
+\begin{codeblock}
+shared_ptr<double[1024]> p = make_shared<double[1024]>();
+  // \tcode{shared_ptr} to a value-initialized \tcode{double[1024]}
+shared_ptr<double[6][2][2]> q = make_shared<double[6][2][2]>();
+  // \tcode{shared_ptr} to a value-initialized \tcode{double[6][2][2]}
+\end{codeblock}
+\end{example}
+\end{itemdescr}
+
+\indexlibrary{\idxcode{make_shared}}%
+\indexlibrary{\idxcode{allocate_shared}}%
+\begin{itemdecl}
+template<class T>
+  shared_ptr<T> make_shared(size_t N, const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[]}
+template<class T, class A>
+  shared_ptr<T> allocate_shared(const A& a, size_t N,
+                                const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[]}
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\returns A \tcode{shared_ptr} to an object of type \tcode{U[N]},
+where \tcode{U} is \tcode{remove_extent_t<T>} and
+each array element has an initial value of \tcode{u}.
+
+\pnum
+\remarks These overloads shall only participate in overload resolution
+when \tcode{T} is of the form \tcode{U[]}.
+
+\pnum
+\begin{example}
+\begin{codeblock}
+shared_ptr<double[]> p = make_shared<double[]>(1024, 1.0);
+  // \tcode{shared_ptr} to a \tcode{double[1024]}, where each element is \tcode{1.0}
+shared_ptr<double[][2]> q = make_shared<double[][2]>(6, {1.0, 0.0});
+  // \tcode{shared_ptr} to a \tcode{double[6][2]}, where each \tcode{double[2]} element is \tcode{\{1.0, 0.0\}}
+shared_ptr<vector<int>[]> r = make_shared<vector<int>[]>(4, {1, 2});
+  // \tcode{shared_ptr} to a \tcode{vector<int>[4]}, where each vector has contents \tcode{\{1, 2\}}
+\end{codeblock}
+\end{example}
+\end{itemdescr}
+
+\indexlibrary{\idxcode{make_shared}}%
+\indexlibrary{\idxcode{allocate_shared}}%
+\begin{itemdecl}
+template<class T>
+  shared_ptr<T> make_shared(const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[N]}
+template<class T, class A>
+  shared_ptr<T> allocate_shared(const A& a,
+                                const remove_extent_t<T>& u); // \tcode{T} is \tcode{U[N]}
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\returns A \tcode{shared_ptr} to an object of type \tcode{T},
+where each array element of type \tcode{remove_extent_t<T>}
+has an initial value of \tcode{u}.
+
+\pnum
+\remarks These overloads shall only participate in overload resolution
+when \tcode{T} is of the form \tcode{U[N]}.
+
+\pnum
+\begin{example}
+\begin{codeblock}
+shared_ptr<double[1024]> p = make_shared<double[1024]>(1.0);
+  // \tcode{shared_ptr} to a \tcode{double[1024]}, where each element is \tcode{1.0}
+shared_ptr<double[6][2]> q = make_shared<double[6][2]>({1.0, 0.0});
+  // \tcode{shared_ptr} to a \tcode{double[6][2]}, where each double[2] element is \tcode{\{1.0, 0.0\}}
+shared_ptr<vector<int>[4]> r = make_shared<vector<int>[4]>({1, 2});
+  // \tcode{shared_ptr} to a \tcode{vector<int>[4]}, where each vector has contents \tcode{\{1, 2\}}
+\end{codeblock}
+\end{example}
 \end{itemdescr}
 
 \rSec4[util.smartptr.shared.cmp]{\tcode{shared_ptr} comparison}