P2846R6 reserve_hint: Eagerly reserving memory for not-quite-sized lazy ranges

Author: burblebee

source/containers.tex

@@ -1403,14 +1403,23 @@
 from \tcode{*ranges::begin(rg)}.
 For \tcode{vector},
 if \tcode{R} models
-neither \tcode{ranges::\libconcept{sized_range}} nor \tcode{ranges::\libconcept{forward_range}},
+\tcode{ranges::\libconcept{approximately_sized_range}}
+but not \tcode{ranges::\libconcept{sized_range}} or models
+\tcode{ranges::\libconcept{input_range}}
+but not \tcode{ranges::\libconcept{forward_range}},
 \tcode{T} is also \oldconcept{MoveInsertable} into \tcode{X}.
 
 \pnum
 \effects
 Constructs a sequence container equal to the range \tcode{rg}.
 Each iterator in the range \tcode{rg} is dereferenced exactly once.
 
+\pnum
+\recommended
+If \tcode{R} models \tcode{ranges::\libconcept{approximately_sized_range}} and
+\tcode{ranges::distance(\linebreak{}rg) <= ranges::reserve_hint(rg)} is \tcode{true},
+an implementation should not perform any reallocation.
+
 \pnum
 \ensures
 \tcode{distance(begin(), end()) == ranges::distance(rg)} is \tcode{true}.
@@ -1761,7 +1770,10 @@
 from \tcode{*ranges::begin(rg)}.
 For \tcode{vector},
 if \tcode{R} models
-neither \tcode{ranges::\libconcept{sized_range}} nor \tcode{ranges::\libconcept{forward_range}},
+\tcode{ranges::\libconcept{approximately_sized_range}}
+but not \tcode{ranges::\libconcept{sized_range}} or models
+\tcode{ranges::\libconcept{input_range}}
+but not \tcode{ranges::\libconcept{forward_range}},
 \tcode{T} is also \oldconcept{MoveInsertable} into \tcode{X}.
 \tcode{rg} and \tcode{a} do not overlap.
 
@@ -1773,6 +1785,12 @@
 For \tcode{vector} and \tcode{deque},
 also invalidates the past-the-end iterator.
 Each iterator in the range \tcode{rg} is dereferenced exactly once.
+
+\pnum
+\recommended
+If \tcode{R} models \tcode{ranges::\libconcept{approximately_sized_range}} and
+\tcode{ranges::distance(\linebreak{}rg) <= ranges::reserve_hint(rg)} is \tcode{true},
+an implementation should not perform any reallocation.
 \end{itemdescr}
 
 \begin{itemdecl}
@@ -8908,9 +8926,18 @@
 Initializes exactly $N$ elements
 from the results of dereferencing successive iterators of \tcode{rg},
 where $N$ is \tcode{ranges::distance(rg)}.
-Performs no reallocations if \tcode{R} models
-\tcode{ranges::\libconcept{forward_range}} or \tcode{ranges::\libconcept{sized_range}};
-otherwise, performs order $\log N$ reallocations and
+
+\pnum
+Performs no reallocations if:
+\begin{itemize}
+\item
+\tcode{R} models \tcode{ranges::\libconcept{approximately_sized_range}}, and
+\tcode{ranges::distance(rg) <= ranges::re\-serve_hint(rg)} is \tcode{true}, or
+\item
+\tcode{R} models \tcode{ranges::\libconcept{forward_range}} and
+\tcode{R} does not model \tcode{ranges::approximately_sized_range}.
+\end{itemize}
+Otherwise, performs order $\log N$ reallocations and
 order $N$ calls to the copy or move constructor of \tcode{T}.
 \end{itemdescr}
 
@@ -9161,6 +9188,21 @@
 is \tcode{true}, there are no effects.
 Otherwise, if an exception is thrown by the move constructor of a non-\oldconcept{CopyInsertable}
 \tcode{T}, the effects are unspecified.
+
+\pnum
+For the declarations taking a range \tcode{R},
+performs at most one reallocation if:
+\begin{itemize}
+\item
+\tcode{R} models \tcode{ranges::\libconcept{approximately_sized_range}} and
+\tcode{ranges::distance(rg) <= ranges::re\-serve_hint(rg)} is \tcode{true}, or
+\item
+\tcode{R} models \tcode{ranges::\libconcept{forward_range}} and
+\tcode{R} does not model \tcode{ranges::\libconcept{approximately_sized_range}}.
+\end{itemize}
+For the declarations taking a pair of \tcode{InputIterator},
+performs at most one reallocation if
+\tcode{InputItera\-tor} models \oldconcept{ForwardIterator}.
 \end{itemdescr}
 
 \indexlibrarymember{erase}{vector}%