datatools::handle< T > Class Template Reference

Templatized handle class that wraps a Boost shared pointer and behaves like a reference. More...

#include <bayeux/datatools/handle.h>

Public Types
typedef T	value_type
typedef value_type &	reference_type
typedef handle_predicate< T >	predicate_type

Public Member Functions
	handle (T *held_=nullptr)
	A constructor from a pointer to some on-the-fly allocated instance. More...
template<typename Q , typename = std::enable_if< std::is_same<const Q, T>::value && std::is_const<T>::value && !std::is_const<Q>::value>>
	handle (Q *held=nullptr)
	A constructor from a pointer to some on-the-fly allocated instance. More...
	handle (const boost::shared_ptr< T > &sp_)
	Constructor on a boost shared_ptr. More...
virtual	~handle ()
	Destructor. More...
bool	unique () const
	Check if the current handle holds an uniquely referenced object. More...
bool	has_data () const
	Return true if the internal shared pointer holds something. More...
	operator bool () const
	Return true if the internal shared pointer holds something. More...
void	swap (handle< T > &other_)
const T &	get () const
template<typename Q = T>
std::enable_if< std::is_same< Q, T >::value &&!std::is_const< Q >::value &&!std::is_const< T >::value, Q & >::type	grab ()
T *	operator-> ()
T const *	operator-> () const
T &	operator * ()
T const &	operator * () const
void	reset (T *elem_=nullptr)
	Reset the internal shared pointer with a new instance. More...
template<typename Q = T>
std::enable_if< std::is_same< Q, T >::value &&!std::is_const< Q >::value &&!std::is_const< T >::value, handle< const Q > >::type	to_const () const
	Return a handle instance that hosts the const instance. More...

Friends
class	boost::serialization::access

Detailed Description

template<typename T>
class datatools::handle< T >

Templatized handle class that wraps a Boost shared pointer and behaves like a reference.

A handle object is given the responsability to handle a class instance through its pointer using the shared pointer mechanism from Boost. The inner hidden pointer can be null, but accessors will throw exceptions if called when this is the case. The held instance must be initialized with the 'new' construction operator, or you can use the make_handle() free function.

Given handle and held type T (no additional qualifiers), an instance of handle<T> has the following access behaviour in different const contexts:

handle<T>: all members of handle and T accessible

const handle<T>: can only access const members of both

const handle<const T>: can only access const members of both

handle<const T>: can access all methods of handle, only const members of T

Access attempts outside these contexts will give a compile-time error.

The handle class is copyable and can be used within STL containers.

Example:

#include <datatools/handle.h>

{
  using namespace datatools;
  handle<int> h0;  // a default int is allocated
  h0.grab () = 999; // access the int and modify its value
  cout << "h0 = " << h0.get () << endl; // print it
  h0.reset (new int (0)); // discard the former int
                          // and allocate a new one
  handle<int> h1 (new int (1)); // create a new handle for another int
  {
    handle<int> h2 (h1); // another handle that shares the same int
                         // than the previous handle
    h2.grab () = 666;     //change the int value through this handle
  }
  cout << "h1 = " << h1.get () << endl; // print it through the
                                        // first handle

  auto h3 = make_handle<std::string>("foo"); // construction via make_handle

  cout << (*h3) << endl;      // access via dereference
  cout << h3->size() << endl; // access via dereference

  h3.reset();
  h3->size(); // Throws std::logic_error

};

See also

make_handle()

Member Typedef Documentation

predicate_type

template<typename T>

typedef handle_predicate<T> datatools::handle< T >::predicate_type

reference_type

template<typename T>

typedef value_type& datatools::handle< T >::reference_type

value_type

template<typename T>

typedef T datatools::handle< T >::value_type

Constructor & Destructor Documentation

handle() [1/3]

template<typename T>

datatools::handle< T >::handle ( T *  held_ = nullptr )

inline

A constructor from a pointer to some on-the-fly allocated instance.

This constructor is given a pointer to some dynamically allocated instance and pass it to the internal shared pointer.

Example:

datatools::handle<int> h(new int(3));

or

int * pi = new int(3);
datatools::handle<int> h(pi);

Warning

Never use such kind of mechanism to initialize a handle:

int i = 3;
datatools::handle<int> h(&i);

handle() [2/3]

template<typename T>

template<typename Q , typename = std::enable_if< std::is_same<const Q, T>::value && std::is_const<T>::value && !std::is_const<Q>::value>>

datatools::handle< T >::handle ( Q *  held = nullptr )

inline

A constructor from a pointer to some on-the-fly allocated instance.

This constructor is given a pointer to some dynamically allocated instance and pass it to the internal shared const pointer. This means that the handle does not allow to modify the element it handles.

Example:

datatools::handle<const int> h(new int(3));

handle() [3/3]

template<typename T>

datatools::handle< T >::handle ( const boost::shared_ptr< T > &  sp_ )

inline

Constructor on a boost shared_ptr.

~handle()

template<typename T>

virtual datatools::handle< T >::~handle ( )

inlinevirtual

Destructor.

Member Function Documentation

get()

template<typename T>

const T& datatools::handle< T >::get ( ) const

inline

Return a const reference to the hosted instance.

Exceptions

std::logic_error

when managed instance is null

grab()

template<typename T>

template<typename Q = T>

std::enable_if< std::is_same<Q, T>::value && !std::is_const<Q>::value && !std::is_const<T>::value, Q&>::type datatools::handle< T >::grab ( )

inline

Return a non-const reference to the hosted instance.

Exceptions

std::logic_error

when managed instance is null

has_data()

template<typename T>

bool datatools::handle< T >::has_data ( ) const

inline

Return true if the internal shared pointer holds something.

operator *() [1/2]

template<typename T>

T& datatools::handle< T >::operator * ( )

inline

Dereferences the stored pointer

Exceptions

std::logic_error

when managed instance is null

operator *() [2/2]

template<typename T>

T const& datatools::handle< T >::operator * ( ) const

inline

Dereferences the stored pointer in const context

Exceptions

std::logic_error

when managed instance is null

operator bool()

template<typename T>

datatools::handle< T >::operator bool ( ) const

inline

Return true if the internal shared pointer holds something.

operator->() [1/2]

template<typename T>

T* datatools::handle< T >::operator-> ( )

inline

Dereferences the stored pointer

Exceptions

std::logic_error

when managed instance is null

operator->() [2/2]

template<typename T>

T const* datatools::handle< T >::operator-> ( ) const

inline

Dereferences the stored pointer in const context

Exceptions

std::logic_error

when managed instance is null

reset()

template<typename T>

void datatools::handle< T >::reset ( T *  elem_ = nullptr )

inline

Reset the internal shared pointer with a new instance.

swap()

template<typename T>

void datatools::handle< T >::swap ( handle< T > &  other_ )

inline

to_const()

template<typename T>

template<typename Q = T>

std::enable_if< std::is_same<Q, T>::value && !std::is_const<Q>::value && !std::is_const<T>::value, handle<const Q> >::type datatools::handle< T >::to_const ( ) const

inline

Return a handle instance that hosts the const instance.

unique()

template<typename T>

bool datatools::handle< T >::unique ( ) const

inline

Check if the current handle holds an uniquely referenced object.

Friends And Related Function Documentation

boost::serialization::access

template<typename T>

friend class boost::serialization::access

friend

---

The documentation for this class was generated from the following file:

• bayeux/datatools/handle.h