boost-react-native-bundle

<!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"> Boost.Flyweight reference </a></div> <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"> Boost.Flyweight reference </a></div> <div class="next_link"><a href="key_value.html"><img src="../next.gif" alt="key-value flyweights" border="0"> Key-value flyweights </a></div> <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="#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> #include <iosfwd> namespace boost{ namespace flyweights{ template< typename T, typename Arg1=implementation defined, typename Arg2=implementation defined, typename Arg3=implementation defined, typename Arg4=implementation defined, typename Arg5=implementation defined > class flyweight; // comparison: // OP is any of ==,<,!=,>,>=,<= template< typename T1,typename Arg11,...,typename Arg15, typename T2,typename Arg21,...,typename Arg25 > bool operator OP( const flyweight<T1,Arg11,...,Arg15>& x, const flyweight<T2,Arg21,...,Arg25>& y); template< typename T1,typename Arg11,...,typename Arg15, typename T2 > bool operator OP(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y); template< typename T1, typename T2,typename Arg21,...,typename Arg25 > bool operator OP(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y); // specialized algorithms: template<typename T,typename Arg1,...,typename Arg5> inline void swap( flyweight<T,Arg1,...,Arg5>& x,flyweight<T,Arg1,...,Arg5>& y); template< typename ElemType,typename Traits, typename T,typename Arg1,...,typename Arg5 > inline std::basic_ostream<ElemType,Traits>& operator<<( std::basic_ostream<ElemType,Traits>& out, const flyweight<T,Arg1,...,Arg5>& x); template< typename ElemType,typename Traits, typename T,typename Arg1,...,typename Arg5 > inline std::basic_ostream<ElemType,Traits>& operator>>( std::basic_istream<ElemType,Traits>& in, flyweight<T,Arg1,...,Arg5>& x); } // namespace boost::flyweights using flyweights::flyweight; } // namespace boost </pre></blockquote> <code>flyweight_fwd.hpp</code> forward declares the class template <a href="#flyweight"><code>flyweight</code></a> and its associated global functions. <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> 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. <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. <blockquote><pre> #include <initializer_list> template< typename T, typename Arg1,typename Arg2,typename Arg3,typename Arg4,typename Arg5 > class flyweight { public: typedef dependent on T key_type; typedef dependent on T value_type; // static data initialization: static bool init(); class initializer{public:initializer();}; // construct/copy/destroy: flyweight(); template<typename... Args> explicit flyweight(Args&&... args); template<typename V> flyweight(std::initializer_list<V> list); flyweight(const flyweight& x); flyweight(flyweight& x); flyweight(const flyweight&& x); flyweight(flyweight&& x); explicit flyweight(const value_type& x); explicit flyweight(value_type& x); explicit flyweight(const value_type&& x); explicit flyweight(value_type&& x); template<typename V> flyweight& operator=(std::initializer_list<V> list); flyweight& operator=(const flyweight& x); flyweight& operator=(const value_type& x); flyweight& operator=(value_type&& x); // convertibility to underlying type: const key_type& get_key()const; const value_type& get()const; operator const value_type&()const; // modifiers: void swap(flyweight& x); }; </pre></blockquote> <h4><a name="instantiation_types">Instantiation types</a></h4> <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 key-value 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="http://www.sgi.com/tech/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. 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> <h4><a name="static_init">Static data initialization</a></h4> 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. <code>static bool init();</code> <blockquote> Effects: After execution of this function the static data associated to the instantiation of <code>flyweight</code> is guaranteed to be constructed. Note: Concurrent execution of this function is not thread safe. </blockquote> <code>initializer::initializer();</code> <blockquote> Effects: Executes <code>init()</code>. </blockquote> <h4><a name="constructors">Constructors, copy and assignment</a></h4> <code>flyweight();</code> <blockquote> Effects: 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> explicit flyweight(Args&&... args);</code></a> <blockquote> Effects: 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. Note: 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> flyweight(std::initializer_list<V> list);</code> <blockquote> Effects: 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. Note: 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); flyweight(flyweight& x); flyweight(const flyweight&& x); flyweight(flyweight&& x);</code> <blockquote> Effects: Constructs a <code>flyweight</code> object associated to the same value as <code>x</code>. Exception safety: <code>nothrow</code>. </blockquote> <code>explicit flyweight(const value_type& x); explicit flyweight(value_type& x); explicit flyweight(const value_type&& x); explicit flyweight(value_type&& x);</code> <blockquote> Requires: If <code>flyweight</code> is key-value, <code>value_type</code> is <a href="http://www.sgi.com/tech/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. Effects: 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>. </blockquote> <code>template<typename V> flyweight& operator=(std::initializer_list<V> list);</code> <blockquote> Effects: <code>*this=flyweight(list)</code>. Returns: <code>*this</code>. Note: 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> Effects: Associates the <code>flyweight</code> object with the same value as <code>x</code>. Returns: <code>*this</code>. Exception safety: <code>nothrow</code>. </blockquote> <code>flyweight& operator=(const value_type& x); flyweight& operator=(value_type&& x);</code> <blockquote> Effects: <code>*this=flyweight(x)</code> (first overload), <code>*this=flyweight(std::move(x))</code> (second overload). Returns: <code>*this</code>. </blockquote> <h4><a name="convertibility">Convertibility to the underlying types</a></h4> <code>const key_type& get_key()const;</code> <blockquote> Return: A copy of the key used to construct the <code>value_type</code> associated to the <code>flyweight</code> object. Exception safety: 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; operator const value_type&()const;</code> <blockquote> Return: The value associated to the <code>flyweight</code> object. Exception safety: <code>nothrow</code>. </blockquote> <h4><a name="modifiers">Modifiers</a></h4> <code>void swap(flyweight& x);</code> <blockquote> Effects: 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. Exception safety: <code>nothrow</code>. </blockquote> <h4><a name="comparison">Comparison operators</a></h4> <code>template<   typename T1,typename Arg11,...,typename Arg15,   typename T2,typename Arg21,...,typename Arg25 > bool operator ==(   const flyweight<T1,Arg11,...,Arg15>& x,   const flyweight<T2,Arg21,...,Arg25>& y);</code> <blockquote> Returns: 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>. Exception safety: If <code>x</code> and <code>y</code> are of the same type, <code>nothrow</code>. </blockquote> <code>template<   typename T1,typename Arg11,...,typename Arg15,   typename T2 > bool operator ==(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y);</code> <blockquote> Returns: <code>x.get()==y</code>. </blockquote> <code>template<   typename T1,   typename T2,typename Arg21,...,typename Arg25 > bool operator ==(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y);</code> <blockquote> Returns: <code>x==y.get()</code>. </blockquote> <code>template<   typename T1,typename Arg11,...,typename Arg15,   typename T2,typename Arg21,...,typename Arg25 > bool operator <(   const flyweight<T1,Arg11,...,Arg15>& x,   const flyweight<T2,Arg21,...,Arg25>& y);</code> <blockquote> Returns: <code>x.get()<y.get()</code>. </blockquote> <code>template<   typename T1,typename Arg11,...,typename Arg15,   typename T2 > bool operator <(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y);</code> <blockquote> Returns: <code>x.get()<y</code>. </blockquote> <code>template<   typename T1,   typename T2,typename Arg21,...,typename Arg25 > bool operator <(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y);</code> <blockquote> Returns: <code>x<y.get()</code>. </blockquote> <code>template<   typename T1,typename Arg11,...,typename Arg15,   typename T2,typename Arg21,...,typename Arg25 > bool operator OP(   const flyweight<T1,Arg11,...,Arg15>& x,   const flyweight<T2,Arg21,...,Arg25>& y); template<   typename T1,typename Arg11,...,typename Arg15,   typename T2 > bool operator OP(const flyweight<T1,Arg11,...,Arg15>& x,const T2& y); template<   typename T1,   typename T2,typename Arg21,...,typename Arg25 > bool operator OP(const T1& x,const flyweight<T2,Arg21,...,Arg25>& y);</code> (<code>OP</code> is any of <code>!=</code>, <code>></code>, <code>>=</code>, <code><=</code>.) <blockquote> Returns: <code>true</code> if and only if <blockquote> <code>!(x==y)</code> (<code>OP</code> is <code>!=</code>), <code>  y< x </code> (<code>OP</code> is <code>> </code>), <code>!(x< y)</code> (<code>OP</code> is <code>>=</code>), <code>!(y< x)</code> (<code>OP</code> is <code><=</code>). </blockquote> </blockquote> <h4><a name="specialized">Specialized algorithms</a></h4> <code>template<typename T,typename Arg1,...,typename Arg5> inline void swap(   flyweight<T,Arg1,...,Arg5>& x,flyweight<T,Arg1,...,Arg5>& y);</code> <blockquote> Effects: <code>x.swap(y)</code>. </blockquote> <code>template<   typename ElemType,typename Traits,   typename T,typename Arg1,...,typename Arg5 > inline std::basic_ostream<ElemType,Traits>& operator<<(   std::basic_ostream<ElemType,Traits>& out,   const flyweight<T,Arg1,...,Arg5>& x);</code> <blockquote> Effects: <code>out<<x.get()</code>. Returns: <code>out</code>. </blockquote> <code>template<   typename ElemType,typename Traits,   typename T,typename Arg1,...,typename Arg5 > inline std::basic_ostream<ElemType,Traits>& operator>>(   std::basic_istream<ElemType,Traits>& in,   flyweight<T,Arg1,...,Arg5>& x);</code> <blockquote> Requires: If <code>flyweight</code> is key-value, <code>value_type</code> is <a href="http://www.sgi.com/tech/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. Effects: Reads an object of type <code>value_type</code> from <code>in</code> and assigns it to <code>x</code>. Returns: <code>in</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> Effects: 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> <h2> <a name="serialize_synopsis">Header </a><a href="../../../../boost/flyweight/serialize.hpp"><code>"boost/flyweight/serialize.hpp"</code></a> synopsis </h2> <code>serialize.hpp</code> includes the necessary functionality for interoperability of <code>flyweight</code> with <a href="../../../serialization/index.html">Boost.Serialization</a>. <h3><a name="serialization">Serialization</a></h3> <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. Operation: saving of a <code>flyweight</code> object <code>x</code> to an output archive (XML archive) <code>ar</code>. <blockquote> Requires: <code>key_type</code> is serializable (XML-serializable). Effects: 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. Exception safety: 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> Requires: <code>key_type</code> is serializable (XML-serializable). Effects: <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. Exception safety: 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"> Boost.Flyweight reference </a></div> <div class="up_link"><a href="index.html"><img src="../up.gif" alt="Boost.Flyweight reference" border="0"> Boost.Flyweight reference </a></div> <div class="next_link"><a href="key_value.html"><img src="../next.gif" alt="key-value flyweights" border="0"> Key-value flyweights </a></div> Revised September 3rd 2014 © Copyright 2006-2014 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>) </body> </html>