DGtal  1.3.beta
Public Member Functions | Protected Types | Private Member Functions | Private Attributes
DGtal::ConstAlias< T > Class Template Reference

Aim: This class encapsulates its parameter class so that to indicate to the user that the object/pointer will be only const aliased (and hence left unchanged). Therefore the user is reminded that the argument parameter is given to the function without any additional cost and may not be modified, while he is aware that the lifetime of the argument parameter must be at least as long as the object itself. Note that an instance of ConstAlias<T> is itself a light object (it holds only an enum and a pointer). More...

#include <DGtal/base/ConstAlias.h>

Public Member Functions

 ConstAlias (const ConstAlias &other)=default
 
 ~ConstAlias ()
 
 ConstAlias (const T &t)
 
 ConstAlias (const T *ptrT)
 
 ConstAlias (const CowPtr< T > &)=delete
 
 ConstAlias (const CountedPtr< T > &shT)
 
 ConstAlias (const CountedPtrOrPtr< T > &shT)
 
 ConstAlias (const CountedConstPtrOrConstPtr< T > &shT)
 
 ConstAlias (T &&)=delete
 
 operator const T & () const
 
const T * operator& () const
 
 operator CountedConstPtrOrConstPtr< T > () const
 
const T * operator-> () const
 

Protected Types

enum  Parameter {
  CONST_LEFT_VALUE_REF, LEFT_VALUE_REF, PTR, CONST_PTR,
  COW_PTR, COUNTED_PTR, RIGHT_VALUE_REF, COUNTED_PTR_OR_PTR,
  COUNTED_CONST_PTR_OR_CONST_PTR
}
 Internal class that allows to distinguish the different types of parameters. More...
 

Private Member Functions

ConstAliasoperator= (const ConstAlias &other)
 

Private Attributes

const Parameter myParam
 Characterizes the type of the input parameter at clone instanciation. More...
 
const void *const myPtr
 Stores the address of the input parameter for further use. More...
 

Detailed Description

template<typename T>
class DGtal::ConstAlias< T >

Aim: This class encapsulates its parameter class so that to indicate to the user that the object/pointer will be only const aliased (and hence left unchanged). Therefore the user is reminded that the argument parameter is given to the function without any additional cost and may not be modified, while he is aware that the lifetime of the argument parameter must be at least as long as the object itself. Note that an instance of ConstAlias<T> is itself a light object (it holds only an enum and a pointer).

Description of template class 'ConstAlias'

(For a complete description, see Parameter passing, cloning and referencing).

It is used in methods or functions to encapsulate the parameter types. The following conversion from input parameter to data member or variable are possible:

Argument const T& const T* CountedPtr<T> CountedPtrOrPtr<T> CountedConstPtrOrConstPtr<T>
To: const T& Shared. O(1) Shared. O(1)
To: const T* Shared. O(1) Shared. O(1)
To: CountedConstPtrOrConstPtr<T> Shared. O(1) Shared. O(1) Shared. O(1), secure Shared. O(1), secure Shared. O(1), secure

Argument conversion to member is automatic except when converting to a pointer const T*: the address operator (operator&) must be used in this case.

For the last row (case where the programmer choose a CountedConstPtrOrConstPtr to hold the const alias), the user can thus enforce a secure const aliasing by handling a variant of CountedPtr as argument. In this case, even if the aliased object is destroyed in the caller context, it still exists in the callee context.

Note
The usage of ConstAlias<T> instead of const T & or const T * in parameters is recommended when the lifetime of the parameter must exceed the lifetime of the called method/function/constructor (often the case in constructor or init methods).
The usage of const T & or const T * instead of ConstAlias<T> is recommended when the lifetime of the parameter is not required to exceed the lifetime of the called method/function/constructor (often the case in standard methods, where the parameter is only used at some point, but not referenced after in some data member).
If the developer (not the user) wishes to enforce a secure const aliasing in all cases, he should probably clone the argument, hence use class Clone.
Template Parameters
Tis any type.
See also
Alias
Clone

It can be used as follows. Consider this simple example where class A is a big object.

const int N = 10000;
struct A { ...
int table[N];
};
// When looking at the signature of B1's constructor, there is an
// ambiguity on the role of parameter a and its life-time. Here
// a's lifetime should be longer than the construction. Generally
// the ambiguity is removed by adding comments or, for the
// experienced developper, by looking at other parts of the code.
// Only aliasing, but for a long lifetime.
struct B1 {
B1( const A & a ) // ambiguous, cost is O(1) here and lifetime of a should exceed constructor.
: myA( a ) {}
...
const A & myA;
};

Sometimes it is very important that the developper that uses the library is conscious that an object, say b, may require that an instance a given as parameter should have a lifetime longer than b itself (case for an instance of B1 above). Classes Clone, Alias, ConstAlias exist for these reasons. The class above may be rewritten as follows.

// ConstAliasing for a long lifetime is visible.
struct B1_v2_1 {
B1_v2_1( ConstAlias<A> a ) // not ambiguous, cost is O(1) here and lifetime of a should be long enough
: myA( a ) {}
...
const A & myA;
};
// ConstAliasing for a long lifetime is visible.
struct B1_v2_2 {
B1_v2_2( ConstAlias<A> a ) // not ambiguous, cost is O(1) here and lifetime of a should be long enough
: myA( &a ) {} // Note the use of the address operator because of the pointer member
...
const A* myA;
};
// ConstAliasing for a long lifetime is visible.
struct B1_v2_3 {
B1_v2_3( ConstAlias<A> a ) // not ambiguous, cost is O(1) here and lifetime of a should be long enough
: myA( a ) {}
...
CountedConstPtrOrConstPtr<A> myA;
};
...
A a1;
CountedPtr<A> counted_a1( new A( a1 ) );
B1 ( a1 ); // not duplicated
B1_v2_1 ( a1 ); // not duplicated
B1_v2_2 ( a1 ); // not duplicated
B1_v2_3 ( counted_a1 ); // not duplicated, even better the user choose a secure variant of const alias.
Note
The user should not use ConstAlias<T> instead of const T & for data members. It works in most cases, but there are some subtle differences between the two behaviors.
ConstAlias have a default copy constructor, so as to let the user forward an ConstAlias<T> parameter.
Examples
dec/exampleDECSurface.cpp.

Definition at line 186 of file ConstAlias.h.

Member Enumeration Documentation

◆ Parameter

template<typename T >
enum DGtal::ConstAlias::Parameter
protected

Internal class that allows to distinguish the different types of parameters.

Enumerator
CONST_LEFT_VALUE_REF 
LEFT_VALUE_REF 
PTR 
CONST_PTR 
COW_PTR 
COUNTED_PTR 
RIGHT_VALUE_REF 
COUNTED_PTR_OR_PTR 
COUNTED_CONST_PTR_OR_CONST_PTR 

Definition at line 193 of file ConstAlias.h.

Constructor & Destructor Documentation

◆ ConstAlias() [1/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const ConstAlias< T > &  other)
default

Default copy constructor.

Parameters
otherobject to copy.

◆ ~ConstAlias()

template<typename T >
DGtal::ConstAlias< T >::~ConstAlias ( )
inline

Destructor. Does nothing.

Definition at line 209 of file ConstAlias.h.

209 {}

◆ ConstAlias() [2/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const T &  t)
inline

Constructor from const reference to an instance of T. The object is pointed in 'this'.

Parameters
tany const reference to an object of type T.

Definition at line 216 of file ConstAlias.h.

217  : myParam( CONST_LEFT_VALUE_REF ), myPtr( static_cast<const void*>( &t ) ) {}

◆ ConstAlias() [3/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const T *  ptrT)
inline

Constructor from const pointer to an instance of T. The object is pointed in 'this'.

Parameters
ptrTany const pointer to an object of type T.

Definition at line 224 of file ConstAlias.h.

225  : myParam( CONST_PTR ), myPtr( static_cast<const void*>( ptrT ) ) {}

◆ ConstAlias() [4/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const CowPtr< T > &  )
delete

Constructor from a const reference to a copy-on-write pointer on T. Deleted.

Const-aliasing a copy-on-write pointer has no meaning. Consider Clone instead.

◆ ConstAlias() [5/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const CountedPtr< T > &  shT)
inline

Constructor from a const reference to a shared pointer on T. The object is pointed in 'this'.

Parameters
shTany const reference to a shared pointer to an object of type T.

Definition at line 241 of file ConstAlias.h.

242  : myParam( COUNTED_PTR ), myPtr( static_cast<const void*>( &shT ) ) {}

◆ ConstAlias() [6/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const CountedPtrOrPtr< T > &  shT)
inline

Constructor from a const reference to a shared or simple const pointer on T. The object is pointed in 'this'.

Parameters
shTany const reference to a shared or simple const pointer to an object of type T.

Definition at line 249 of file ConstAlias.h.

250  : myParam( COUNTED_PTR_OR_PTR ), myPtr( static_cast<const void*>( &shT ) ) {}

◆ ConstAlias() [7/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( const CountedConstPtrOrConstPtr< T > &  shT)
inline

Constructor from a const reference to a shared or simple const pointer on T. The object is pointed in 'this'.

Parameters
shTany const reference to a shared or simple const pointer to an object of type T.

Definition at line 257 of file ConstAlias.h.

258  : myParam( COUNTED_CONST_PTR_OR_CONST_PTR ), myPtr( static_cast<const void*>( &shT ) ) {}

◆ ConstAlias() [8/8]

template<typename T >
DGtal::ConstAlias< T >::ConstAlias ( T &&  )
delete

Constructor from right-reference value. Delete.

Const-aliasing a rvalue ref has no meaning. Consider Clone instead.

Member Function Documentation

◆ operator const T &()

template<typename T >
DGtal::ConstAlias< T >::operator const T & ( ) const
inline

Cast operator to a T const-reference. The object is never duplicated. Allowed input parameters are:

  • const A & -> const A & // no duplication
  • const A* -> const A & // no duplication, exception if null

Definition at line 273 of file ConstAlias.h.

274  {
275  switch( myParam ) {
277  case CONST_PTR:
278  return *( static_cast< const T* >( myPtr ) );
279  default: ASSERT( false && "[ConstAlias::operator const T&() const] Invalid cast for given type. Consider passing a const left-value reference or a const pointer as a parameter." );
280  return *( static_cast< const T* >( myPtr ) );
281  }
282  }

References DGtal::ConstAlias< T >::CONST_LEFT_VALUE_REF, DGtal::ConstAlias< T >::CONST_PTR, DGtal::ConstAlias< T >::myParam, and DGtal::ConstAlias< T >::myPtr.

◆ operator CountedConstPtrOrConstPtr< T >()

template<typename T >
DGtal::ConstAlias< T >::operator CountedConstPtrOrConstPtr< T > ( ) const
inline

Cast operator to a shared or simple const pointer. The object is never duplicated. Allowed input parameters are:

Definition at line 311 of file ConstAlias.h.

312  {
313  switch( myParam ) {
315  case CONST_PTR:
316  return CountedConstPtrOrConstPtr<T>( static_cast< const T* >( myPtr ), false );
317  case COUNTED_PTR:
318  return CountedConstPtrOrConstPtr<T>( *( static_cast< const CountedPtr<T>* >( myPtr ) ) );
319  case COUNTED_PTR_OR_PTR:
320  return CountedConstPtrOrConstPtr<T>( *( static_cast< const CountedPtrOrPtr<T>* >( myPtr ) ) );
322  return CountedConstPtrOrConstPtr<T>( *( static_cast< const CountedPtrOrPtr<T>* >( myPtr ) ) );
323  default: ASSERT( false && "[ConstAlias::operator CowPtr<T>() const] Invalid cast for given type. Consider passing a CountedPtr or a CowPtr as a parameter." );
324  return CountedConstPtrOrConstPtr<T>( 0, false );
325  }
326  }

References DGtal::ConstAlias< T >::CONST_LEFT_VALUE_REF, DGtal::ConstAlias< T >::CONST_PTR, DGtal::ConstAlias< T >::COUNTED_CONST_PTR_OR_CONST_PTR, DGtal::ConstAlias< T >::COUNTED_PTR, DGtal::ConstAlias< T >::COUNTED_PTR_OR_PTR, DGtal::ConstAlias< T >::myParam, and DGtal::ConstAlias< T >::myPtr.

◆ operator&()

template<typename T >
const T* DGtal::ConstAlias< T >::operator& ( ) const
inline

Cast operator to a T const-pointer. The object is never duplicated. Allowed input parameters are:

  • const A & -> const A* // no duplication
  • const A* -> const A* // no duplication

Definition at line 290 of file ConstAlias.h.

291  {
292  switch( myParam ) {
294  case CONST_PTR:
295  return static_cast< const T* >( myPtr );
296  default: ASSERT( false && "[const T* ConstAlias::operator&() const] Invalid address operator for given type. Consider passing a const left-value reference or a const pointer as a parameter." );
297  return static_cast< const T* >( myPtr );
298  }
299  }

References DGtal::ConstAlias< T >::CONST_LEFT_VALUE_REF, DGtal::ConstAlias< T >::CONST_PTR, DGtal::ConstAlias< T >::myParam, and DGtal::ConstAlias< T >::myPtr.

◆ operator->()

template<typename T >
const T* DGtal::ConstAlias< T >::operator-> ( ) const
inline

Definition at line 328 of file ConstAlias.h.

329  {
330  switch( myParam ) {
332  case CONST_PTR:
333  return static_cast< const T* >( myPtr );
334  case COUNTED_PTR:
335  return ( static_cast< const CountedPtr<T>* >( myPtr ) )->operator->();
336  case COUNTED_PTR_OR_PTR:
337  return ( static_cast< const CountedPtrOrPtr<T>* >( myPtr ) )->operator->();
339  return ( static_cast< const CountedConstPtrOrConstPtr<T>* >( myPtr ) )->operator->();
340  default: ASSERT( false && "[ConstAlias::operator->() const] Invalid cast for given type. Consider passing a CountedPtr or a CowPtr as a parameter." );
341  return 0;
342  }
343  }

References DGtal::ConstAlias< T >::CONST_LEFT_VALUE_REF, DGtal::ConstAlias< T >::CONST_PTR, DGtal::ConstAlias< T >::COUNTED_CONST_PTR_OR_CONST_PTR, DGtal::ConstAlias< T >::COUNTED_PTR, DGtal::ConstAlias< T >::COUNTED_PTR_OR_PTR, DGtal::ConstAlias< T >::myParam, and DGtal::ConstAlias< T >::myPtr.

◆ operator=()

template<typename T >
ConstAlias& DGtal::ConstAlias< T >::operator= ( const ConstAlias< T > &  other)
private

Assignment.

Parameters
otherthe object to copy.
Returns
a reference on 'this'. Forbidden (otherwise the user might be tempted to use it as a member).

Field Documentation

◆ myParam

template<typename T >
const Parameter DGtal::ConstAlias< T >::myParam
private

◆ myPtr

template<typename T >
const void* const DGtal::ConstAlias< T >::myPtr
private

The documentation for this class was generated from the following file:
DGtal::ConstAlias::CONST_PTR
@ CONST_PTR
Definition: ConstAlias.h:193
DGtal::ConstAlias::myPtr
const void *const myPtr
Stores the address of the input parameter for further use.
Definition: ConstAlias.h:350
DGtal::ConstAlias::COUNTED_PTR
@ COUNTED_PTR
Definition: ConstAlias.h:194
DGtal::ConstAlias::COUNTED_PTR_OR_PTR
@ COUNTED_PTR_OR_PTR
Definition: ConstAlias.h:194
DGtal::ConstAlias::CONST_LEFT_VALUE_REF
@ CONST_LEFT_VALUE_REF
Definition: ConstAlias.h:193
DGtal::ConstAlias::PTR
@ PTR
Definition: ConstAlias.h:193
DGtal::ConstAlias::LEFT_VALUE_REF
@ LEFT_VALUE_REF
Definition: ConstAlias.h:193
DGtal::ConstAlias::myParam
const Parameter myParam
Characterizes the type of the input parameter at clone instanciation.
Definition: ConstAlias.h:348
DGtal::ConstAlias::RIGHT_VALUE_REF
@ RIGHT_VALUE_REF
Definition: ConstAlias.h:194
DGtal::ConstAlias::COUNTED_CONST_PTR_OR_CONST_PTR
@ COUNTED_CONST_PTR_OR_CONST_PTR
Definition: ConstAlias.h:195
DGtal::ConstAlias::COW_PTR
@ COW_PTR
Definition: ConstAlias.h:194