Home Libraries Author Links

stm::smartptr::injective_ptr< T, Compare, Allocator, Policy > Class Template Reference
[SmartptrAids: Smart Pointer Aids]

Inheritance diagram for stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >:

Inheritance graph
[legend]

List of all members.


Detailed Description

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
class stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >

The class template injective_ptr is a smart pointer pointing to unique constant objects of element type T stored using a static repository.

The template parameter Compare shall define a strict weak ordering as described in (25.3). Then the uniqueness of objects in the repository means, that for each equivalence class of the equivalence relation defined by that strict weak ordering at most one representant is stored by the repository. Hence two injective_ptr<T, Compare, Allocator, Policy> instances pointing to equivalent objects are equal.

In contrast to other smart pointer designs the element type T is supplied to the injective_ptr<T, Compare, Allocator, Policy> constructors by value and not by a pointer to a user allocated value. The allocation is done by the implementation using the template argument Allocator and the template argument Compare to ensure that equivalent values are allocated only once. The value access requires one dereference operation but due to the constness of the objects stored in the repository, it is not possible to change the value of the element an injective_ptr points to.

If T supports boost::serialization, specializations of the class template injective_ptr<T, Compare, Allocator, Policy> supports it as well inclusive object T tracking. To define a typedef or to define a default initialized variable of injective_ptr<T, Compare, Allocator, Policy> type the element type T needs not be complete.

An injective_ptr<T, Compare, Allocator, Policy> object either points to an object of value type T in which case it is called dereferenceable, or not in which case it is called empty. The repository element associated with a dereferenceable injective_ptr<T, Compare, Allocator, Policy> instance is called the accessor of the element pointed to by the injective_ptr.

If the policy property multirange is false, the repository is not further structured and all accessors form one default range which is predefined in all cases.

Else each specialization of injective_ptr<T, Compare, Allocator, Policy> provides a maximum of std::numeric_limits<stm::dword>::max() different ranges each containing its own accessors. Also in this case the value access requires only one dereference operation wheras the management overhead in memory space and execution time during construction and destruction of injective_ptr<T, Compare, Allocator, Policy> objects is slightly greater than in the non-multirange case. Such a repository range is characterized by a value of rangeid_type returned by the methods make_range() and rangeid() may be stored and supplied as injective_ptr constructor argument. If none is specified, the predefined default range is used.

Because for any two injective_ptr<T, Compare, Allocator, Policy> instances ptr1 and ptr2, an equivalence of *ptr1 and *ptr2 under the equivalence relation induced by Compare implies that the accessor of this equivalent value is stored only once per range, the mathematical mapping

           injective_ptr<T, Compare, Allocator, Policy> --> range
is injective, hence the name injective_ptr. If the policy property surjective is true, that mapping is also surjective, hence bijective. This means that then accessors of elements no more associated with any injective_ptr<T, Compare, Allocator, true> instance are deleted and that elements no more accessed by any accessor are deallocated.

In all cases, it is guaranteed that equivalent objects of element type T are allocated only once even if they belong to different ranges.

Definition at line 254 of file smartptraids.hpp.


Public Types

typedef T element_type
 Provides the type of the template parameter T.
typedef
mapped_ptr_impl::rangeid_type 
rangeid_type
 Range ID type used as handle for the different repository ranges.
typedef Compare compare_type
 Provides the type of the template parameter Compare.
typedef Allocator allocator_type
 Provides the type of the template parameter Allocate.
typedef Policy policy_type
 Provides the type of the template parameter Policy.
typedef long refcount_type
 The type used for reference counts is long to be compatible with boost::shared_ptr.
typedef repository::range_type range_type
 The iterator range type range_type is a specialization of the class template boost::iterator_range and provides constant iterators with element_type as value type.

Public Member Functions

 injective_ptr ()
 Constructs an empty injective_ptr object for the default range.
 injective_ptr (rangeid_type rangeid)
 Constructs an empty injective_ptr object for the range of rangeid, which shall be rangeid_type() for the default range or be the result of a call of rangeid() or define_range().
 injective_ptr (const typename range_type::iterator &it)
 Constructs an injective_ptr object for the range of it pointing to the same value as it, if it is dereferenceable, else throws std::runtime_error.
 injective_ptr (const element_type &value, bool store=true)
 Constructs an injective_ptr object for the default range pointing to the unique object stored being equivalent to value under the equivalence relation induced by Compare.
 injective_ptr (const element_type &value, rangeid_type rangeid, bool store=true)
 Constructs an injective_ptr object for the range of rangeid pointing to the unique object stored being equivalent to value under the equivalence relation induced by Compare, where rangeid shall be rangeid_type() for the default range or be the result of a call of rangeid() or define_range().
 injective_ptr (const injective_ptr &other)
 Copy constructor.
injective_ptroperator= (const injective_ptr &other)
 Assigns the other injective_ptr to this injective_ptr and returns it.
injective_ptrassign (const element_type &value)
 Causes this injective_ptr to point to the unique object stored being equivalent to value under the equivalence relation induced by Compare retaining its range and returns this injective_ptr.
void reset ()
 Assigns the empty injective_ptr to this injective_ptr retaining its range.
void reset (const element_type &value)
 Causes this injective_ptr to point to the unique object stored being equivalent to value under the equivalence relation induced by Compare retaining its range.
void swap (injective_ptr &other)
 Exchanges the contents of this injective_ptr with that of the other.
 operator bool () const
 Returns true, if this injective_ptr is not empty, else false.
const element_typeoperator * () const
 Returns a constant reference to the element pointed to by this injective_ptr, if it is not be empty, else throws std::runtime_error.
const element_typeoperator-> () const
 Returns a constant pointer to the element pointed to by this injective_ptr, if it is not be empty, else throws std::runtime_error.
const element_typeget () const
 Returns a constant pointer to the element pointed to by this injective_ptr, if it is not empty, else the null pointer.
bool unique () const
 Returns true, if injective_ptr is surjective, this injective_ptr is dereferenceable and is the only one pointing to its element_type object, else false.
refcount_type use_count () const
 Returns -1, if this incective_ptr is empty, else for a surjective injective_ptr the number of injective_ptr objects, including this one, whose element value pointed to is equal to this one's, else 0.
const range_typerange () const
 Returns a constant reference to the range of this injective_ptr.
rangeid_type rangeid () const
 Returns the rangeid of the range of this injective_ptr.

Static Public Member Functions

static bool is_surjective ()
 Returns the value of the policy property surjective.
static bool is_multirange ()
 Returns the value of the policy property multirange.
static rangeid_type define_range ()
 Defines a new range and returns its range ID.
static void undefine_range (rangeid_type rangeid)
 Undefines the range of rangeid, if rangeid is not rangeid_type() which characterizes the default range and if the range is defined, else throws std::runtime_error.
static bool range_empty (rangeid_type rangeid)
 Returns true, if the range of rangeid is empty, else false.
static bool range_defined (rangeid_type rangeid)
 Returns true, if the range of rangeid is defined, else false.
static bool range_available (rangeid_type rangeid)
 Returns true, if the rangeid is available for definition, else false.

Friends

class boost::serialization::access
 Grant implementation access to boost::serialization.

Member Typedef Documentation

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef T stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::element_type

Provides the type of the template parameter T.

Definition at line 283 of file smartptraids.hpp.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef mapped_ptr_impl::rangeid_type stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::rangeid_type

Range ID type used as handle for the different repository ranges.

Its default constructor yields the handle of the predefined default range.

Definition at line 287 of file smartptraids.hpp.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef Compare stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::compare_type

Provides the type of the template parameter Compare.

Definition at line 290 of file smartptraids.hpp.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef Allocator stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::allocator_type

Provides the type of the template parameter Allocate.

Definition at line 293 of file smartptraids.hpp.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef Policy stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::policy_type

Provides the type of the template parameter Policy.

Definition at line 296 of file smartptraids.hpp.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef long stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::refcount_type

The type used for reference counts is long to be compatible with boost::shared_ptr.

Definition at line 300 of file smartptraids.hpp.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
typedef repository::range_type stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::range_type

The iterator range type range_type is a specialization of the class template boost::iterator_range and provides constant iterators with element_type as value type.

It represents an injective_ptr object's range. Although instances of range_type cannot be constructed with its public interface, they can be obtained by the method range() of injective_ptr.

Definition at line 308 of file smartptraids.hpp.


Constructor & Destructor Documentation

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::injective_ptr (  ) 

Constructs an empty injective_ptr object for the default range.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::injective_ptr ( rangeid_type  rangeid  ) 

Constructs an empty injective_ptr object for the range of rangeid, which shall be rangeid_type() for the default range or be the result of a call of rangeid() or define_range().

Throws std::runtime_error, if the range of rangeid is not defined.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::injective_ptr ( const typename range_type::iterator &  it  ) 

Constructs an injective_ptr object for the range of it pointing to the same value as it, if it is dereferenceable, else throws std::runtime_error.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::injective_ptr ( const element_type value,
bool  store = true 
)

Constructs an injective_ptr object for the default range pointing to the unique object stored being equivalent to value under the equivalence relation induced by Compare.

If store is false and such an object was not yet contained in the default range, its empty injective_ptr is constructed.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::injective_ptr ( const element_type value,
rangeid_type  rangeid,
bool  store = true 
)

Constructs an injective_ptr object for the range of rangeid pointing to the unique object stored being equivalent to value under the equivalence relation induced by Compare, where rangeid shall be rangeid_type() for the default range or be the result of a call of rangeid() or define_range().

If store is false and such an object was not yet contained in the range of rangeid, its empty injective_ptr is constructed. Throws std::runtime_error, if the range of rangeid is not defined.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::injective_ptr ( const injective_ptr< T, Compare, Allocator, Policy > &  other  ) 

Copy constructor.


Member Function Documentation

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
injective_ptr& stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::operator= ( const injective_ptr< T, Compare, Allocator, Policy > &  other  ) 

Assigns the other injective_ptr to this injective_ptr and returns it.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
injective_ptr& stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::assign ( const element_type value  ) 

Causes this injective_ptr to point to the unique object stored being equivalent to value under the equivalence relation induced by Compare retaining its range and returns this injective_ptr.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
void stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::reset (  ) 

Assigns the empty injective_ptr to this injective_ptr retaining its range.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
void stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::reset ( const element_type value  ) 

Causes this injective_ptr to point to the unique object stored being equivalent to value under the equivalence relation induced by Compare retaining its range.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
void stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::swap ( injective_ptr< T, Compare, Allocator, Policy > &  other  ) 

Exchanges the contents of this injective_ptr with that of the other.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::operator bool (  )  const

Returns true, if this injective_ptr is not empty, else false.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
const element_type& stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::operator * (  )  const

Returns a constant reference to the element pointed to by this injective_ptr, if it is not be empty, else throws std::runtime_error.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
const element_type* stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::operator-> (  )  const

Returns a constant pointer to the element pointed to by this injective_ptr, if it is not be empty, else throws std::runtime_error.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
const element_type* stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::get (  )  const

Returns a constant pointer to the element pointed to by this injective_ptr, if it is not empty, else the null pointer.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static bool stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::is_surjective (  )  [static]

Returns the value of the policy property surjective.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static bool stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::is_multirange (  )  [static]

Returns the value of the policy property multirange.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
bool stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::unique (  )  const

Returns true, if injective_ptr is surjective, this injective_ptr is dereferenceable and is the only one pointing to its element_type object, else false.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
refcount_type stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::use_count (  )  const

Returns -1, if this incective_ptr is empty, else for a surjective injective_ptr the number of injective_ptr objects, including this one, whose element value pointed to is equal to this one's, else 0.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
const range_type& stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::range (  )  const

Returns a constant reference to the range of this injective_ptr.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
rangeid_type stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::rangeid (  )  const

Returns the rangeid of the range of this injective_ptr.

Never throws.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static rangeid_type stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::define_range (  )  [static]

Defines a new range and returns its range ID.

Throws std::runtime_error, if the policy property multiranged is false or if the capacity of ranges is exhausted.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static void stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::undefine_range ( rangeid_type  rangeid  )  [static]

Undefines the range of rangeid, if rangeid is not rangeid_type() which characterizes the default range and if the range is defined, else throws std::runtime_error.

If the range was empty, it is marked as available for a new definition, else not. In that case all injective_ptr objects in the range of rangeid are invalidated.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static bool stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::range_empty ( rangeid_type  rangeid  )  [static]

Returns true, if the range of rangeid is empty, else false.

Throws std::runtime_error, if the range of rangeid is not defined.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static bool stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::range_defined ( rangeid_type  rangeid  )  [static]

Returns true, if the range of rangeid is defined, else false.

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
static bool stm::smartptr::injective_ptr< T, Compare, Allocator, Policy >::range_available ( rangeid_type  rangeid  )  [static]

Returns true, if the rangeid is available for definition, else false.


Friends And Related Function Documentation

template<class T, class Compare = std::less<T>, class Allocator = std::allocator<T>, class Policy = stm::smartptr::policy<>>
friend class boost::serialization::access [friend]

Grant implementation access to boost::serialization.

Definition at line 279 of file smartptraids.hpp.


© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).