123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797 |
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0.1 Transitional//EN">
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>Boost.Flyweight Documentation - flyweight reference</title>
- <link rel="stylesheet" href="../style.css" type="text/css">
- <link rel="start" href="../index.html">
- <link rel="prev" href="index.html">
- <link rel="up" href="index.html">
- <link rel="next" href="key_value.html">
- </head>
- <body>
- <h1><img src="../../../../boost.png" alt="Boost logo" align=
- "middle" width="277" height="86">Boost.Flyweight
- <code>flyweight</code> reference</h1>
- <div class="prev_link"><a href="index.html"><img src="../prev.gif" alt="Boost.Flyweight reference" border="0"><br>
- Boost.Flyweight reference
- </a></div>
- <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
- Boost.Flyweight reference
- </a></div>
- <div class="next_link"><a href="key_value.html"><img src="../next.gif" alt="key-value flyweights" border="0"><br>
- Key-value flyweights
- </a></div><br clear="all" style="clear: all;">
- <hr>
- <h2>Contents</h2>
- <ul>
- <li><a href="#flyweight_fwd_synopsis">Header
- <code>"boost/flyweight/flyweight_fwd.hpp"</code> synopsis</a></li>
- <li><a href="#synopsis">Header
- <code>"boost/flyweight/flyweight.hpp"</code> synopsis</a>
- <ul>
- <li><a href="#flyweight">Class template <code>flyweight</code></a>
- <ul>
- <li><a href="#instantiation_types">Instantiation types</a></li>
- <li><a href="#static_init">Static data initialization</a></li>
- <li><a href="#constructors">Constructors, copy and assignment</a></li>
- <li><a href="#convertibility">Convertibility to the underlying types</a></li>
- <li><a href="#modifiers">Modifiers</a></li>
- <li><a href="#comparison">Comparison operators</a></li>
- <li><a href="#specialized">Specialized algorithms</a></li>
- <li><a href="#hash">Hash support</a></li>
- <li><a href="#config_macros">Configuration macros</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li><a href="#serialize_synopsis">Header
- <code>"boost/flyweight/serialize.hpp"</code> synopsis</a>
- <ul>
- <li><a href="#serialization">Serialization</a></li>
- </ul>
- </li>
- </ul>
- <h2>
- <a name="flyweight_fwd_synopsis">Header
- <a href="../../../../boost/flyweight/flyweight_fwd.hpp"><code>"boost/flyweight/flyweight_fwd.hpp"</code></a>
- synopsis</a>
- </h2>
- <blockquote><pre>
- <span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>functional</span><span class=special>/</span><span class=identifier>hash_fwd</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>></span>
- <span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>iosfwd</span><span class=special>></span>
- <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
-
- <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>Arg2</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>Arg3</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>Arg4</span><span class=special>=</span><b>implementation defined</b><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>Arg5</span><span class=special>=</span><b>implementation defined</b>
- <span class=special>></span>
- <span class=keyword>class</span> <span class=identifier>flyweight</span><span class=special>;</span>
- <span class=comment>// comparison:
- // <b>OP</b> is any of ==,<,!=,>,>=,<=</span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>T1</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg11</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg15</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>T2</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg21</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg25</span>
- <span class=special>></span>
- <span class=keyword>bool</span> <span class=keyword>operator</span> <span class=identifier><b><i>OP</i></b></span><span class=special>(</span>
- <span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T1</span><span class=special>,</span><span class=identifier>Arg11</span><span class=special>,...,</span><span class=identifier>Arg15</span><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span>
- <span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T2</span><span class=special>,</span><span class=identifier>Arg21</span><span class=special>,...,</span><span class=identifier>Arg25</span><span class=special>>&</span> <span class=identifier>y</span><span class=special>);</span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>T1</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg11</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg15</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>T2</span>
- <span class=special>></span>
- <span class=keyword>bool</span> <span class=keyword>operator</span> <span class=identifier><b><i>OP</i></b></span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T1</span><span class=special>,</span><span class=identifier>Arg11</span><span class=special>,...,</span><span class=identifier>Arg15</span><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>T2</span><span class=special>&</span> <span class=identifier>y</span><span class=special>);</span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>T1</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>T2</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg21</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg25</span>
- <span class=special>></span>
- <span class=keyword>bool</span> <span class=keyword>operator</span> <span class=identifier><b><i>OP</i></b></span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>T1</span><span class=special>&</span> <span class=identifier>x</span><span class=special>,</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T2</span><span class=special>,</span><span class=identifier>Arg21</span><span class=special>,...,</span><span class=identifier>Arg25</span><span class=special>>&</span> <span class=identifier>y</span><span class=special>);</span>
- <span class=comment>// specialized algorithms:</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span><span class=special>></span>
- <span class=keyword>inline</span> <span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span>
- <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>>&</span> <span class=identifier>x</span><span class=special>,</span><span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>>&</span> <span class=identifier>y</span><span class=special>);</span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>ElemType</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Traits</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span>
- <span class=special>></span>
- <span class=keyword>inline</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special><</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>>&</span> <span class=keyword>operator</span><span class=special><<(</span>
- <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special><</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>>&</span> <span class=identifier>out</span><span class=special>,</span>
- <span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>ElemType</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Traits</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span>
- <span class=special>></span>
- <span class=keyword>inline</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special><</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>>&</span> <span class=keyword>operator</span><span class=special>>>(</span>
- <span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_istream</span><span class=special><</span><span class=identifier>ElemType</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>>&</span> <span class=identifier>in</span><span class=special>,</span>
- <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
- <span class=keyword>using</span> <span class=identifier>flyweights</span><span class=special>::</span><span class=identifier>flyweight</span><span class=special>;</span>
- <span class=special>}</span> <span class=comment>// namespace boost</span>
- <span class=comment>// hash support:</span>
- <span class=keyword>namespace</span> <span class=identifier>std</span><span class=special>{</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>class</span> <span class=identifier>T</span><span class=special>></span> <span class=keyword>struct</span> <span class=identifier>hash</span><span class=special>;</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span><span class=special>></span>
- <span class=keyword>struct</span> <span class=identifier>hash</span><span class=special><</span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>></span> <span class=special>>;</span>
- <span class=special>}</span> <span class=comment>// namespace std</span>
- <span class=keyword>namespace</span> <span class=identifier>boost</span><span class=special>{</span>
- <span class=keyword>namespace</span> <span class=identifier>flyweights</span><span class=special>{</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,...,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span><span class=special>></span>
- <span class=keyword>inline</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>size_t</span> <span class=identifier>hash_value</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special><</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Arg1</span><span class=special>,...,</span><span class=identifier>Arg5</span><span class=special>>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=special>}</span> <span class=comment>// namespace boost::flyweights</span>
- <span class=special>}</span> <span class=comment>// namespace boost</span>
- </pre></blockquote>
- <p>
- <code>flyweight_fwd.hpp</code> forward declares the class template
- <a href="#flyweight"><code>flyweight</code></a> and its associated global functions and class template specializations.
- </p>
- <h2>
- <a name="synopsis">Header
- <a href="../../../../boost/flyweight/flyweight.hpp"><code>"boost/flyweight/flyweight.hpp"</code></a>
- synopsis</a>
- </h2>
- <h3><a name="flyweight">
- Class template <code>flyweight</code>
- </a></h3>
- <p>
- Objects of type <code>flyweight<...></code> provide access to immutable
- values of type <code>flyweight<...>::value_type</code>, with the following advantages over using
- plain <code>value_type</code> objects:
- <ul>
- <li>Flyweight objects with equivalent value share the same representation
- (the associated <code>value_type</code> object).
- </li>
- <li>The size of flyweights is typically that of a pointer, which is in general
- smaller than <code>sizeof(value_type)</code>.
- </li>
- </ul>
- So, if the level of redundancy (ratio of total objects to different values)
- is high enough, substituting a suitable instantiation of <code>flyweight</code>
- for <code>value_type</code> results in a reduction in memory usage.
- </p>
- <p>
- <code>flyweight</code> is parameterized according to some aspects:
- <ul>
- <li>Types <code>key_value</code> and <code>value_type</code>
- (possibly equal), where <code>key_type</code> serves as a
- key type to lookup and construct internal shared instances of
- objects of <code>value_type</code>.
- </li>
- <li>An optional <a href="tags.html#tag">tag</a> type meant to syntactically
- differentiate between otherwise identical instantiations.
- </li>
- <li>The <a href="factories.html#factory">factory class</a> used to store
- and retrieve the shared value objects.
- </li>
- <li>The type of <a href="holders.html#holder">holder</a> used to
- instantiate the flyweight factory and a mutex object, both of
- which are unique to each specialization of the <code>flyweight</code>
- class template.
- </li>
- <li>A <a href="locking.html#locking">locking policy</a> determining
- the synchronization mechanisms for internal access to shared resources.
- </li>
- <li>A <a href="tracking.html#tracking">tracking policy</a> which controls
- how values are treated when all their associated flyweight objects are
- destroyed.
- </li>
- </ul>
- These aspects impact the internal structure and behavior
- of the <code>flyweight</code> instantiation in the following manner:
- <ul>
- <li>Each instantation of <code>flyweight</code> internally owns
- a unique factory object and a unique synchronization
- <a href="locking.html#preliminary">mutex</a> object, both of which
- are created through the use of an associated holder type.
- </li>
- <li>The flyweight factory stores elements of an undisclosed type
- <code>Entry</code> that is implicitly convertible to
- <code>const key_type&</code> and also stores a subobject of
- <code>value_type</code>. Every flyweight object is associated
- to a <code>value_type</code> subobject of some <code>Entry</code>
- stored in the factory.
- </li>
- <li>The associated mutex object is used to protect all invocations
- to the insertion and deletion functions of the internal flyweight
- factory.
- </li>
- <li>Each flyweight object internally stores a value of some
- undisclosed type <code>Handle</code>. <code>Handle</code> and
- the <code>Entry</code> type referred to above are obtained
- from invocations to the associated tracking policy, in the
- manner described for this concept.
- </li>
- </ul>
- In what follows, we implicitly assume that <code>key_type</code> equivalence
- refers to the equivalence relationship induced by the factory class used.
- Also, two values of <code>value_type</code> are considered equivalent
- if they are constructed from equivalent keys, or are copies of
- objects constructed from equivalent keys.
- </p>
- <blockquote><pre>
- <span class=preprocessor>#include</span> <span class=special><</span><span class=identifier>initializer_list</span><span class=special>></span>
- <span class=keyword>template</span><span class=special><</span>
- <span class=keyword>typename</span> <span class=identifier>T</span><span class=special>,</span>
- <span class=keyword>typename</span> <span class=identifier>Arg1</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg2</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg3</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg4</span><span class=special>,</span><span class=keyword>typename</span> <span class=identifier>Arg5</span>
- <span class=special>></span>
- <span class=keyword>class</span> <span class=identifier>flyweight</span>
- <span class=special>{</span>
- <span class=keyword>public</span><span class=special>:</span>
- <span class=keyword>typedef</span> <span class=identifier><b>dependent on T</b></span> <span class=identifier>key_type</span><span class=special>;</span>
- <span class=keyword>typedef</span> <span class=identifier><b>dependent on T</b></span> <span class=identifier>value_type</span><span class=special>;</span>
- <span class=comment>// static data initialization:</span>
- <span class=keyword>static</span> <span class=keyword>bool</span> <span class=identifier>init</span><span class=special>();</span>
- <span class=keyword>class</span> <span class=identifier>initializer</span><span class=special>{</span><span class=keyword>public</span><span class=special>:</span><span class=identifier>initializer</span><span class=special>();</span><span class=special>};</span>
-
- <span class=comment>// construct/copy/destroy:</span>
-
- <span class=identifier>flyweight</span><span class=special>();</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span><span class=special>...</span> <span class=identifier>Args</span><span class=special>></span>
- <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>Args</span><span class=special>&&...</span> <span class=identifier>args</span><span class=special>);</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>V</span><span class=special>></span>
- <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>initializer_list</span><span class=special><</span><span class=identifier>V</span><span class=special>></span> <span class=identifier>list</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>flyweight</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>flyweight</span><span class=special>&&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=keyword>explicit</span> <span class=identifier>flyweight</span><span class=special>(</span><span class=identifier>value_type</span><span class=special>&&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=keyword>template</span><span class=special><</span><span class=keyword>typename</span> <span class=identifier>V</span><span class=special>></span>
- <span class=identifier>flyweight</span><span class=special>&</span> <span class=keyword>operator</span><span class=special>=(</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>initializer_list</span><span class=special><</span><span class=identifier>V</span><span class=special>></span> <span class=identifier>list</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>&</span> <span class=keyword>operator</span><span class=special>=(</span><span class=keyword>const</span> <span class=identifier>flyweight</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>&</span> <span class=keyword>operator</span><span class=special>=(</span><span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=identifier>flyweight</span><span class=special>&</span> <span class=keyword>operator</span><span class=special>=(</span><span class=identifier>value_type</span><span class=special>&&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=comment>// convertibility to underlying type:</span>
- <span class=keyword>const</span> <span class=identifier>key_type</span><span class=special>&</span> <span class=identifier>get_key</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
- <span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&</span> <span class=identifier>get</span><span class=special>()</span><span class=keyword>const</span><span class=special>;</span>
- <span class=keyword>operator</span> <span class=keyword>const</span> <span class=identifier>value_type</span><span class=special>&()</span><span class=keyword>const</span><span class=special>;</span>
- <span class=comment>// modifiers:</span>
- <span class=keyword>void</span> <span class=identifier>swap</span><span class=special>(</span><span class=identifier>flyweight</span><span class=special>&</span> <span class=identifier>x</span><span class=special>);</span>
- <span class=special>};</span>
- </pre></blockquote>
- <h4><a name="instantiation_types">Instantiation types</a></h4>
- <p>
- <code>T</code> can be either:
- <ul>
- <li>An arbitrary type,</li>
- <li>a type of the form
- <a href="key_value.html#key_value_construct"><code>key_value<Key,Value[,KeyFromValue]></code></a>.</li>
- </ul>
- In the first case, the nested types <code>key_type</code> and <code>value_type</code>
- are both equal to <code>T</code>. In the second case, <code>key_type</code>=<code>Key</code>,
- <code>value_type</code>=<code>Value</code>; we say then that the instantiation
- of <code>flyweight</code> is a <i>key-value</i> flyweight.
- <code>value_type</code> is the type of the values flyweight objects give access to,
- while value lookup is based on associated <code>key_type</code> values.
- <code>key_value</code> must be
- <a href="https://boost.org/sgi/stl/Assignable.html"><code>Assignable</code></a>
- and <code>value_type</code> must be constructible from <code>key_type</code>;
- additionally, <code>key_value</code> must
- conform to any extra requirements imposed by the type of factory used.
- For key-value flyweights, it is guaranteed that the creation or assignment of a flyweight
- object results in at most one construction (or copy construction in some
- particular cases) of an object
- of <code>value_type</code>, and this construction only occurs in the case that no
- equivalent value existed previously in the flyweight factory.
- </p>
- <p>
- The types <code>Arg1</code>, ... , <code>Arg5</code>, if provided, must be any
- of the following, in no particular order:
- <ul>
- <li>A <a href="tags.html#tag">tag</a>,</li>
- <li>a <a href="factories.html#factory">factory specifier</a>,</li>
- <li>a <a href="holders.html#holder">holder specifier</a>,</li>
- <li>a <a href="locking.html#locking">locking policy</a>,</li>
- <li>a <a href="tracking.html#tracking">tracking policy</a>.</li>
- </ul>
- No aspect can be specified twice. Each internal component of the
- <code>flyweight</code> instantiation is obtained through use of the
- corresponding specifier; for instance, the factory results from a
- certain (MPL) invocation of the given factory specifier, the internal
- mutex from the given locking policy, etc.
- The default configuration arguments are:
- <ul>
- <li>No tagging,</li>
- <li><a href="factories.html#hashed_factory"><code>hashed_factory<></code></a>,</li>
- <li><a href="holders.html#static_holder"><code>static_holder</code></a>,</li>
- <li><a href="locking.html#simple_locking"><code>simple_locking</code></a>,</li>
- <li><a href="tracking.html#refcounted"><code>refcounted</code></a> tracking policy.</li>
- </ul>
- </p>
- <h4><a name="static_init">Static data initialization</a></h4>
- <p>
- The static data internal to a given <code>flyweight</code> instantiation
- (factory instance, etc.) is constructed during the dynamic initialization
- phase of the program and always before the first program-wide use of the
- instantiated class. The following utilities can be
- used when more control about the moment of construction is required.
- </p>
- <code>static bool init();</code>
- <blockquote>
- <b>Effects:</b> After execution of this function the static data associated
- to the instantiation of <code>flyweight</code> is guaranteed to be
- constructed.<br>
- <b>Note:</b> Concurrent execution of this function is not thread safe.
- </blockquote>
- <code>initializer::initializer();</code>
- <blockquote>
- <b>Effects:</b> Executes <code>init()</code>.
- </blockquote>
- <h4><a name="constructors">Constructors, copy and assignment</a></h4>
- <code>flyweight();</code>
- <blockquote>
- <b>Effects:</b> Constructs a <code>flyweight</code> object with the value
- <code>value_type(key_type())</code>
- if <code>flyweight</code> is key-value
- or <code>value_type()</code>
- otherwise.
- </blockquote>
- <a name="fwd_ctor">
- <code>template<typename... Args><br>
- explicit flyweight(Args&&... args);</code></a>
- <blockquote>
- <b>Effects:</b> Constructs a <code>flyweight</code> object with the value
- <code>value_type(key_type(std::forward<Args>(args)...))</code>
- if <code>flyweight</code> is key-value
- or <code>value_type(std::forward<Args>(args)...)</code>
- otherwise.<br>
- <b>Note:</b> In compilers without variadic template support, the implementation
- replaces this constructor with a number of overloads accepting
- any combination of const/non-const lvalue/rvalue reference arguments
- up to a maximum number that
- can be globally <a href="#limit_num_ctor_args">configured</a> by the user.
- </blockquote>
- <code>template<typename V><br>
- flyweight(std::initializer_list<V> list);</code>
- <blockquote>
- <b>Effects:</b> Constructs a <code>flyweight</code> object with the value
- <code>value_type(key_type(list))</code> if <code>flyweight</code> is key-value
- or <code>value_type(list)</code> otherwise.<br>
- <b>Note:</b> The specialization for a particular <code>std::initializer_list<V'></code>
- of this member function template is not available unless
- <code>key_type</code> is constructible from
- <code>std::initializer_list<V'></code>.
- </blockquote>
- <code>flyweight(const flyweight& x);<br>
- flyweight(flyweight& x);<br>
- flyweight(const flyweight&& x);<br>
- flyweight(flyweight&& x);</code>
- <blockquote>
- <b>Effects:</b> Constructs a <code>flyweight</code> object associated to
- the same value as <code>x</code>.<br>
- <b>Exception safety:</b> <code>nothrow</code>.
- </blockquote>
- <code>explicit flyweight(const value_type& x);<br>
- explicit flyweight(value_type& x);<br>
- explicit flyweight(const value_type&& x);<br>
- explicit flyweight(value_type&& x);</code>
- <blockquote>
- <b>Requires:</b> If <code>flyweight</code> is key-value,
- <code>value_type</code> is
- <a href="https://boost.org/sgi/stl/Assignable.html"><code>Assignable</code></a>
- and the
- <a href="key_value.html#key_extractor"><code>Key Extractor</code></a>
- <code>KeyFromValue</code> must have been supplied as part of the
- <code>key_value<></code> construct.<br>
- <b>Effects:</b> Constructs a <code>flyweight</code> associated to a
- copy of <code>x</code> or with a <code>value_type</code> constructed
- from a key equivalent to that associated to <code>x</code>. For non-key-value
- flyweights, <code>x</code> is its own key; for key-value flyweights,
- the key is extracted through use of an object of type <code>KeyFromValue</code>.<br>
- </blockquote>
- <code>template<typename V><br>
- flyweight& operator=(std::initializer_list<V> list);</code>
- <blockquote>
- <b>Effects:</b> <code>*this=flyweight(list)</code>.<br>
- <b>Returns:</b> <code>*this</code>.<br>
- <b>Note:</b> The specialization for a particular <code>std::initializer_list<V'></code>
- of this member function template is not available unless
- <code>key_type</code> is constructible from
- <code>std::initializer_list<V'></code>.
- </blockquote>
- <code>flyweight& operator=(const flyweight& x);</code>
- <blockquote>
- <b>Effects:</b> Associates the <code>flyweight</code> object with the same value
- as <code>x</code>.<br>
- <b>Returns:</b> <code>*this</code>.<br>
- <b>Exception safety:</b> <code>nothrow</code>.
- </blockquote>
- <code>flyweight& operator=(const value_type& x);<br>
- flyweight& operator=(value_type&& x);</code>
- <blockquote>
- <b>Effects:</b> <code>*this=flyweight(x)</code> (first overload),
- <code>*this=flyweight(std::move(x))</code> (second overload).<br>
- <b>Returns:</b> <code>*this</code>.<br>
- </blockquote>
- <h4><a name="convertibility">Convertibility to the underlying types</a></h4>
- <code>const key_type& get_key()const;</code>
- <blockquote>
- <b>Returns:</b> A copy of the key used to construct the
- <code>value_type</code> associated to the <code>flyweight</code>
- object.<br>
- <b>Exception safety:</b> If <code>flyweight</code> is not key-value or
- if <code>KeyFromValue</code> was not provided, <code>nothrow</code>.
- </blockquote>
- <code>const value_type& get()const;<br>
- operator const value_type&()const;</code>
- <blockquote>
- <b>Returns:</b> The value associated to the <code>flyweight</code>
- object.<br>
- <b>Exception safety:</b> <code>nothrow</code>.
- </blockquote>
- <h4><a name="modifiers">Modifiers</a></h4>
- <code>void swap(flyweight& x);</code>
- <blockquote>
- <b>Effects:</b> Swaps the associations to <code>value_type</code>s each
- flyweight object has. No swapping of <code>key_type</code> or
- <code>value_type</code> objects is done.<br>
- <b>Exception safety:</b> <code>nothrow</code>.
- </blockquote>
- <h4><a name="comparison">Comparison operators</a></h4>
- <code>template<<br>
- typename T1,typename Arg11,...,typename Arg15,<br>
- typename T2,typename Arg21,...,typename Arg25<br>
- ><br>
- bool operator ==(<br>
- const flyweight<T1,Arg11,...,Arg15>& x,<br>
- const flyweight<T2,Arg21,...,Arg25>& y);</code>
- <blockquote>
- <b>Returns:</b> If <code>x</code> and <code>y</code> are of the same type, returns
- <code>true</code> if and only if they are associated to the same value; if
- <code>x</code> and <code>y</code> have different types, returns
- <code>x.get()==y.get()</code>.<br>
- <b>Exception safety:</b> If <code>x</code> and <code>y</code> are of the same type,
- <code>nothrow</code>.
- </blockquote>
- <code>template<<br>
- typename T1,typename Arg11,...,typename Arg15,<br>
- typename T2<br>
- ><br>
- bool operator ==(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y);</code>
- <blockquote>
- <b>Returns:</b> <code>x.get()==y</code>.
- </blockquote>
- <code>template<<br>
- typename T1,<br>
- typename T2,typename Arg21,...,typename Arg25<br>
- ><br>
- bool operator ==(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y);</code>
- <blockquote>
- <b>Returns:</b> <code>x==y.get()</code>.
- </blockquote>
- <code>template<<br>
- typename T1,typename Arg11,...,typename Arg15,<br>
- typename T2,typename Arg21,...,typename Arg25<br>
- ><br>
- bool operator <(<br>
- const flyweight<T1,Arg11,...,Arg15>& x,<br>
- const flyweight<T2,Arg21,...,Arg25>& y);</code>
- <blockquote>
- <b>Returns:</b> <code>x.get()<y.get()</code>.
- </blockquote>
- <code>template<<br>
- typename T1,typename Arg11,...,typename Arg15,<br>
- typename T2<br>
- ><br>
- bool operator <(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y);</code>
- <blockquote>
- <b>Returns:</b> <code>x.get()<y</code>.
- </blockquote>
- <code>template<<br>
- typename T1,<br>
- typename T2,typename Arg21,...,typename Arg25<br>
- ><br>
- bool operator <(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y);</code>
- <blockquote>
- <b>Returns:</b> <code>x<y.get()</code>.
- </blockquote>
- <code>template<<br>
- typename T1,typename Arg11,...,typename Arg15,<br>
- typename T2,typename Arg21,...,typename Arg25<br>
- ><br>
- bool operator <b><i>OP</i></b>(<br>
- const flyweight<T1,Arg11,...,Arg15>& x,<br>
- const flyweight<T2,Arg21,...,Arg25>& y);<br>
- template<<br>
- typename T1,typename Arg11,...,typename Arg15,<br>
- typename T2<br>
- ><br>
- bool operator <b><i>OP</i></b>(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y);</br>
- template<<br>
- typename T1,<br>
- typename T2,typename Arg21,...,typename Arg25<br>
- ><br>
- bool operator <b><i>OP</i></b>(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y);</code>
- <p>
- (<code><b><i>OP</i></b></code> is any of <code>!=</code>, <code>></code>,
- <code>>=</code>, <code><=</code>.)
- </p>
- <blockquote>
- <b>Returns:</b> <code>true</code> if and only if
- <blockquote>
- <code>!(x==y)</code> (<code><b><i>OP</i></b></code> is <code>!=</code>),<br>
- <code> y< x </code> (<code><b><i>OP</i></b></code> is <code>> </code>),<br>
- <code>!(x< y)</code> (<code><b><i>OP</i></b></code> is <code>>=</code>),<br>
- <code>!(y< x)</code> (<code><b><i>OP</i></b></code> is <code><=</code>).
- </blockquote>
- </blockquote>
- <h4><a name="specialized">Specialized algorithms</a></h4>
- <code>template<typename T,typename Arg1,...,typename Arg5><br>
- inline void swap(<br>
- flyweight<T,Arg1,...,Arg5>& x,flyweight<T,Arg1,...,Arg5>& y);</code>
- <blockquote>
- <b>Effects:</b> <code>x.swap(y)</code>.
- </blockquote>
- <code>template<<br>
- typename ElemType,typename Traits, <br>
- typename T,typename Arg1,...,typename Arg5<br>
- ><br>
- inline std::basic_ostream<ElemType,Traits>& operator<<(<br>
- std::basic_ostream<ElemType,Traits>& out,<br>
- const flyweight<T,Arg1,...,Arg5>& x);</code>
- <blockquote>
- <b>Effects:</b> <code>out<<x.get()</code>.<br>
- <b>Returns:</b> <code>out</code>.
- </blockquote>
- <code>template<<br>
- typename ElemType,typename Traits, <br>
- typename T,typename Arg1,...,typename Arg5<br>
- ><br>
- inline std::basic_ostream<ElemType,Traits>& operator>>(<br>
- std::basic_istream<ElemType,Traits>& in,<br>
- flyweight<T,Arg1,...,Arg5>& x);</code>
- <blockquote>
- <b>Requires:</b> If <code>flyweight</code> is key-value,
- <code>value_type</code> is
- <a href="https://boost.org/sgi/stl/Assignable.html"><code>Assignable</code></a>
- and the
- <a href="key_value.html#key_extractor"><code>Key Extractor</code></a>
- <code>KeyFromValue</code> must have been supplied as part of the
- <code>key_value<></code> construct.<br>
- <b>Effects:</b> Reads an object of type <code>value_type</code> from <code>in</code>
- and assigns it to <code>x</code>.<br>
- <b>Returns:</b> <code>in</code>.
- </blockquote>
- <h4><a name="hash">Hash support</a></h4>
- <p>
- Support is provided for hashing <code>flyweight</code>s both with <code>std::hash</code> and
- <a href="../../../../doc/html/hash.html"><code>boost::hash</code></a>. In either case, the calculation
- does not involve hashing the associated <code>value_type</code> objects themselves; so, it is
- immaterial whether <code>value_type</code> is hashable or not.
- The results given by <code>std::hash</code> and <code>boost::hash</code> for the same
- <code>flyweight</code> object will usually differ.<br />
- <b>Note:</b> Hash support can be <a href="#disable_hash_support">disabled</a> to solve
- clashes with code where this has already been defined by the user.
- </p>
- <code>namespace std{<br>
- template<typename T,typename Arg1,...,typename Arg5><br>
- struct hash<boost::flyweight<T,Arg1,...,Arg5> >;<br>
- }</code>
- <blockquote>
- This template specialization meets the requirements of class template <code>std::hash</code> in <b>[unord.hash]</b>.
- No exception is thrown when invoking instances of this specialization.
- </blockquote>
- <code>template<typename T,typename Arg1,...,typename Arg5><br>
- inline std::size_t hash_value(const flyweight<T,Arg1,...,Arg5>& x);</code>
- <blockquote>
- <b>Returns:</b> A hash value for <code>x</code> to be used by
- <a href="../../../../doc/html/hash/custom.html">Boost.Hash</a>.<br>
- <b>Exception safety:</b> <code>nothrow</code>.
- </blockquote>
- <h4><a name="config_macros">Configuration macros</a></h4>
- <a name="limit_num_ctor_args">
- <code>BOOST_FLYWEIGHT_LIMIT_PERFECT_FWD_ARGS</code></a>
- <blockquote>
- In compilers without variadic template support,
- globally define this macro to set the maximum number of
- arguments accepted by <code>flyweight</code>
- <a href="#fwd_ctor">forwarding constructor</a>, which by default
- is 5.
- </blockquote>
- <a name="disable_hash_support">
- <code>BOOST_FLYWEIGHT_DISABLE_HASH_SUPPORT</code></a>
- <blockquote>
- If defined, hash support is not provided. This can be useful to cope
- with legacy code where general <code>flyweight</code> hashing has already been
- defined by the user.
- </blockquote>
- <h2>
- <a name="serialize_synopsis">Header
- </a><a href="../../../../boost/flyweight/serialize.hpp"><code>"boost/flyweight/serialize.hpp"</code></a>
- synopsis
- </h2>
- <p>
- <code>serialize.hpp</code> includes the necessary functionality for interoperability
- of <code>flyweight</code> with
- <a href="../../../serialization/index.html">Boost.Serialization</a>.
- </p>
- <h3><a name="serialization">Serialization</a></h3>
- <p>
- <code>flyweight</code>s can be archived and retrieved by means of
- <a href="../../../serialization/index.html">Boost.Serialization</a>. Regular as well
- as XML archives are supported.
- Serialization is done in an efficient manner so that saving equivalent <code>flyweight</code>s
- result in their common <code>key_type</code> value being stored only once, regardless
- of whether <code>key_type</code> is
- <a href="../../../serialization/doc/traits.html#tracking">tracked</a> by
- Boost.Serialization or not.
- </p>
- Operation: saving of a <code>flyweight</code> object <code>x</code> to an
- output archive (XML archive) <code>ar</code>.
- <blockquote>
- <b>Requires:</b> <code>key_type</code> is serializable (XML-serializable).<br>
- <b>Effects:</b> The value <code>k=x.get_key()</code> is saved into <code>ar</code> as
- part of this operation or of a previous saving operation of a <code>flyweight</code>
- object with the same key.<br>
- <b>Exception safety:</b> Strong with respect to <code>x</code>. If an exception
- is thrown, <code>ar</code> may be left in an inconsistent state.
- </blockquote>
- Operation: loading of a <code>flyweight</code> <code>x'</code> from an
- input archive (XML archive) <code>ar</code>.
- <blockquote>
- <b>Requires:</b> <code>key_type</code> is serializable (XML-serializable).<br>
- <b>Effects:</b> <code>x'</code> is associated to a value constructed from a key
- equivalent to <code>k'</code>, a restored copy of the value <code>k</code>
- defined above.<br>
- <b>Exception safety:</b> Strong with respect to <code>x'</code>. If an exception
- is thrown, <code>ar</code> may be left in an inconsistent state.
- </blockquote>
- <hr>
- <div class="prev_link"><a href="index.html"><img src="../prev.gif" alt="Boost.Flyweight reference" border="0"><br>
- Boost.Flyweight reference
- </a></div>
- <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"><br>
- Boost.Flyweight reference
- </a></div>
- <div class="next_link"><a href="key_value.html"><img src="../next.gif" alt="key-value flyweights" border="0"><br>
- Key-value flyweights
- </a></div><br clear="all" style="clear: all;">
- <br>
- <p>Revised April 24th 2019</p>
- <p>© Copyright 2006-2019 Joaquín M López Muñoz.
- Distributed under the Boost Software
- License, Version 1.0. (See accompanying file <a href="../../../../LICENSE_1_0.txt">
- LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
- http://www.boost.org/LICENSE_1_0.txt</a>)
- </p>
- </body>
- </html>
|