<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.3.10: http://docutils.sourceforge.net/" />
<title>Support for sequence in-place construction</title>
<meta name="author" content="Thorsten Ottosen" />
<meta name="date" content="2007-03-08" />
<style type="text/css">

/*
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005-09-25 17:49:54 +0200 (Sun, 25 Sep 2005) $
:Revision: $Revision: 3901 $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* "! important" is used here to override other ``margin-top`` and
   ``margin-bottom`` styles that are later in the stylesheet or 
   more specific.  See http://www.w3.org/TR/CSS1#the-cascade */
.first {
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin-left: 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left {
  clear: left }

img.align-right {
  clear: right }

img.borderless {
  border: 0 }

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font-family: serif ;
  font-size: 100% }

pre.line-block {
  font-family: serif ;
  font-size: 100% }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em ;
  background-color: #eeeeee }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid thin gray }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid thin black }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

tt.docutils {
  background-color: #eeeeee }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="support-for-sequence-in-place-construction">
<h1 class="title">Support for sequence in-place construction</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Thorsten Ottosen</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:thorsten.ottosen&#64;dezide.com">thorsten.ottosen&#64;dezide.com</a></td></tr>
<tr class="field"><th class="docinfo-name">organizations:</th><td class="field-body">Dezide Aps</td>
</tr>
<tr><th class="docinfo-name">Date:</th>
<td>2007-03-08</td></tr>
<tr class="field"><th class="docinfo-name">Number:</th><td class="field-body">WG21/N2212 and J16/07-0072</td>
</tr>
<tr class="field"><th class="docinfo-name">Working Group:</th><td class="field-body">Library</td>
</tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id2" name="id2">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference" href="#examples" id="id3" name="id3">2&nbsp;&nbsp;&nbsp;Examples</a></li>
<li><a class="reference" href="#design-rationale" id="id4" name="id4">3&nbsp;&nbsp;&nbsp;Design rationale</a></li>
<li><a class="reference" href="#wording" id="id5" name="id5">4&nbsp;&nbsp;&nbsp;Wording</a><ul class="auto-toc">
<li><a class="reference" href="#synopsis" id="id6" name="id6">4.1&nbsp;&nbsp;&nbsp;Synopsis</a></li>
<li><a class="reference" href="#specification" id="id7" name="id7">4.2&nbsp;&nbsp;&nbsp;Specification</a></li>
</ul>
</li>
<li><a class="reference" href="#acknowledgements" id="id8" name="id8">5&nbsp;&nbsp;&nbsp;Acknowledgements</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="introduction" name="introduction">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
<p>The lack of in-place construction in standard sequences
is normally not a big problem. However, for libraries that
tries to squeeze out the maximum efficiency of C++, it is a big
problem that standard sequences are overly encapsulated. Experts
needs to be able to write optimally efficient code.</p>
<p>The following type of libraries will benefit from this proposal:</p>
<ul class="simple">
<li>Serialization libraries (for example, <a class="reference" href="http://www.boost.org/libs/serialization/doc/index.html">Boost.Serialization</a> is an example)</li>
<li>Sockets (for example, <a class="reference" href="http://asio.sourceforge.net/boost-asio-proposal-0.3.6/libs/asio/doc/">Boost.Asio</a>  or the <a class="reference" href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2006/n2054.pdf">TR2 version</a> )</li>
<li>Message Passing Interfaces (for example, <a class="reference" href="http://www.generic-programming.org/~dgregor/boost.mpi/doc/">Boost.MPI</a> which uses Boost.Serialization internally)</li>
</ul>
<p>Even though move-semantics will help performance, it is still not
going to lead to optimal performance because construction followed
by move-construction is less efficient than construction alone.
Furthermore, some types are no more efficient to move than to copy,
and those types are not only builtin types.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id3" id="examples" name="examples">2&nbsp;&nbsp;&nbsp;Examples</a></h1>
<p>The following code demonstrates how one may exception-safely
fill a generic sequence with value from a serialization library:</p>
<pre class="literal-block">
template&lt; class Sequence, class Archive &gt;
void read( Sequence&amp; into, Archive&amp; from )
{
    int size;
    from &gt;&gt; size;
    into.uninitialized_grow( size );
    
    try
    {
        typename Sequence::iterator e = into.begin(); 
        for( int i = 0; i != size; ++i, ++e )
        {
            typedef typename Sequence::value_type T;
            //
            // Call placement new directly on 
            // uninitialized buffer
            //
            new( &amp;*e ) T( from );
        }
    }
    catch( ... ) 
    {
        into.uninitialized_shrink( size - i );
        throw;
    }
}
</pre>
<p>The following code demonstrates how one may 
trivially code the handy <tt class="docutils literal"><span class="pre">uninitialized_resize()</span></tt> function:</p>
<pre class="literal-block">
template&lt; class Sequence &gt;
void uninitialized_resize( Sequence&amp; seq, typename Sequence::size_type n )
{
    if( n &gt; seq.size() )
        seq.uninitialized_grow( n - seq.size() );
    else if( n &lt; seq.size() )
        seq.uninitialized_shrink( seq.size() - n );
    else
        ;
    assert( seq.size() == n );
}                   
</pre>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id4" id="design-rationale" name="design-rationale">3&nbsp;&nbsp;&nbsp;Design rationale</a></h1>
<p>One could imagine different ways to achieve the same. For example, 
to fill an <tt class="docutils literal"><span class="pre">std::vector&lt;T&gt;</span></tt> with uninitialized storage, we could add
the following member:</p>
<pre class="literal-block">
template &lt;class T, class A&gt;
class vector
{
   ...
   template &lt;class F&gt;  // F models functor(T* data, size_type n)
   vector(size_type n, F f);  // initialize vector with f(data(), n)
   ...
};
</pre>
<p>and then use it like:</p>
<pre class="literal-block">
struct dont_initialize
{
   template &lt;class T&gt;
   void operator()(T*, size_t) const {}
};

...

vector&lt;double&gt; v(1000, dont_initialize());
</pre>
<p>This has several drawbacks:</p>
<ol class="arabic simple">
<li>there are already too many constructors in the container interface.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="2">
<li>it is <em>harder and inconvenient</em> to add in-place construction because the functor needs access to
the data used for the in-place construction.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="3">
<li>it is overly <em>restrictive</em> to confine the uninitialized growth to construction.</li>
</ol>
<!--  -->
<ol class="arabic simple" start="4">
<li>it is <em>incomplete</em> since exception-safe code needs a special way to erase uninitialized elements too.</li>
</ol>
<p>Instead an approach similar to the existing <tt class="docutils literal"><span class="pre">insert()</span></tt> member functions has been pursued.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="wording" name="wording">4&nbsp;&nbsp;&nbsp;Wording</a></h1>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="synopsis" name="synopsis">4.1&nbsp;&nbsp;&nbsp;Synopsis</a></h2>
<p><em>Add the following members to the synopsis of the class templates</em> <tt class="docutils literal"><span class="pre">basic_string</span></tt>, <tt class="docutils literal"><span class="pre">list</span></tt> , <tt class="docutils literal"><span class="pre">deque</span></tt> <em>and</em> <tt class="docutils literal"><span class="pre">vector</span></tt>:</p>
<pre class="literal-block">
iterator uninitialized_grow( size_type n );
void     uninitialized_shrink( size_type n ); 
</pre>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id7" id="specification" name="specification">4.2&nbsp;&nbsp;&nbsp;Specification</a></h2>
<p><em>Add the following specification after the synopsis of the class templates</em> <tt class="docutils literal"><span class="pre">basic_string</span></tt>, <tt class="docutils literal"><span class="pre">list</span></tt> , <tt class="docutils literal"><span class="pre">deque</span></tt> <em>and</em> <tt class="docutils literal"><span class="pre">vector</span></tt>:</p>
<p><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">uninitialized_grow(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><em>Effects</em>: increases the container's size with <tt class="docutils literal"><span class="pre">n</span></tt> by growing the container with uninitialized objects at the end.</li>
<li><em>Returns</em>: an iterator <tt class="docutils literal"><span class="pre">r</span></tt> where <tt class="docutils literal"><span class="pre">&amp;*r</span></tt> points to the first of <tt class="docutils literal"><span class="pre">n</span></tt> subsequent regions of uninitialized memory 
in the range <tt class="docutils literal"><span class="pre">[r,r+n)</span></tt> that can each be used to construct objects of type <tt class="docutils literal"><span class="pre">value_type</span></tt> in.</li>
<li><em>Remarks</em>: if memory allocation fails, there are no effects.</li>
<li><em>Throws</em>: <tt class="docutils literal"><span class="pre">length_error</span></tt> if <tt class="docutils literal"><span class="pre">size()</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">&gt;</span> <span class="pre">max_size()</span></tt>.</li>
</ul>
<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">uninitialized_shrink(</span> <span class="pre">size_type</span> <span class="pre">n</span> <span class="pre">);</span></tt></p>
<ul class="simple">
<li><em>Effects</em>: decreases the container's size by <tt class="docutils literal"><span class="pre">n</span></tt> by removing the <tt class="docutils literal"><span class="pre">n</span></tt> last regions of uninitialized memory without calling any destructor.</li>
<li><em>Precondition</em>: at least <tt class="docutils literal"><span class="pre">n</span></tt> uninitialized objects exists at the end of the container.</li>
<li><em>Throws</em>: Nothing</li>
</ul>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="acknowledgements" name="acknowledgements">5&nbsp;&nbsp;&nbsp;Acknowledgements</a></h1>
<p>Many thanks to Christopher Kohlhoff and Matthias Troyer for their feedback.</p>
</div>
</div>
</body>
</html>
