Ticket #3472: initialized_documentation.patch

File initialized_documentation.patch, 4.3 KB (added by niels_dekker, 12 years ago)

documentation for boost::initialized<T>

  • value_init.htm

     
    3333                   
    3434<ul>
    3535          <li><a href="#val_init"><code>template class value_initialized&lt;T&gt;</code></a></li>
     36          <li><a href="#initialized"><code>template class initialized&lt;T&gt;</code></a></li>
    3637          <li><a href="#initialized_value"><code>initialized_value</code></a></li>
    3738                   
    3839</ul>
    … …  
    123124</pre>
    124125</p>
    125126<p>
     127The template <a href="#initialized"><code>initialized</code></a>
     128offers both value-initialization and direct-initialization.
     129It is especially useful as a data member type, allowing the very same object
     130to be either direct-initialized or value-initialized.
     131</p>
     132<p>
    126133The <code>const</code> object <a href="#initialized_value"><code>initialized_value</code></a>
    127134allows value-initializing a variable as follows:
    128135<pre>
    … …  
    340347                   
    341348<pre>value_initialized&lt;int&gt; x ;<br>get(x) = 1 ; // OK<br><br>value_initialized&lt;int const&gt; cx ;<br>get(x) = 1 ; // ERROR: Cannot modify a const object<br><br>value_initialized&lt;int&gt; const x_c ;<br>get(x_c) = 1 ; // ERROR: Cannot modify a const object<br><br>value_initialized&lt;int const&gt; const cx_c ;<br>get(cx_c) = 1 ; // ERROR: Cannot modify a const object<br></pre>
    342349
     350<h2><a name="initialized"><code>template class initialized&lt;T&gt;</code></a></h2>
     351                   
     352<pre>namespace boost {<br><br>template&lt;class T&gt;<br>class initialized<br>{
     353<br>  public :
     354<br>    initialized() : x() {}
     355<br>    explicit initialized(T const &amp; arg) : x(arg) {}
     356<br>    operator T const &amp;() const;
     357<br>    operator T&amp;();
     358<br>    T const &amp;data() const;
     359<br>    T&amp; data();
     360<br>    void swap( value_initialized&lt;T&gt;&amp; );
     361<br>
     362<br>  private :
     363<br>    <i>unspecified</i> x ;
     364<br>} ;
     365<br>
     366<br>template&lt;class T&gt;
     367<br>T const&amp; get ( initialized&lt;T&gt; const&amp; x );
     368<br>
     369<br>template&lt;class T&gt;
     370<br>T&amp; get ( initialized&lt;T&gt;&amp; x );
     371<br>
     372<br>} // namespace boost
     373<br></pre>
     374
     375The template class <code>boost::initialized&lt;T&gt;</code> supports both value-initialization
     376and direct-initialization, so its interface is a superset of the interface
     377of <code>value_initialized&lt;T&gt;</code>: Its default-constructor
     378value-initializes the wrapped object just like the default-constructor of
     379<code>value_initialized&lt;T&gt;</code>, but <code>boost::initialized&lt;T&gt;</code>
     380also offers an extra <code>explicit</code>
     381constructor, which direct-initializes the wrapped object by the specified value.
     382<p>
     383
     384<code>initialized&lt;T&gt;</code> is especially useful when the wrapped
     385object must be either value-initialized or direct-initialized, depending on
     386runtime conditions. For example, <code>initialized&lt;T&gt;</code> could
     387hold the value of a data member that may be value-initialized by some
     388constructors, and direct-initialized by others.
     389On the other hand, if it is known beforehand that the
     390object must <i>always</i> be value-initialized, <code>value_initialized&lt;T&gt;</code>
     391may be preferable. And if the object must always be
     392direct-initialized, none of the two wrappers really needs to be used.
     393</p>
     394 
     395
    343396<h2><a name="initialized_value"><code>initialized_value</code></a></h2>
    344397
    345398<pre>
    … …  
    399452<p>value_initialized was reimplemented by Fernando Cacciola and Niels Dekker
    400453for Boost release version 1.35 (2008), offering a workaround to various compiler issues.
    401454     </p>
     455<p><code>boost::initialized</code> was very much inspired by feedback from Edward Diener and
     456  Jeffrey Hellrung.
     457     </p>
    402458<p>initialized_value was written by Niels Dekker, and added to Boost release version 1.36 (2008).
    403459     </p>
    404460<p>Developed by <a href="mailto:fernando_cacciola@hotmail.com">Fernando Cacciola</a>,
    … …  
    407463     </p>
    408464                   
    409465<hr>         
    410 <p>Revised 03 October 2009</p>
     466<p>Revised 1 May 2010</p>
    411467                   
    412 <p>&copy; Copyright Fernando Cacciola, 2002, 2009.</p>
     468<p>&copy; Copyright Fernando Cacciola, 2002 - 2010.</p>
    413469                   
    414470<p>Distributed under the Boost Software License, Version 1.0. See
    415471<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>