DGtal 1.3.0
Searching...
No Matches
DGtal::Alias< 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 aliased. Therefore the user is reminded that the argument parameter is given to the function without any additional cost and may 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 Alias<T> is itself a light object (it holds only an enum and a pointer). More...

#include <DGtal/base/Alias.h>

## Public Member Functions

Alias (const Alias &other)=default

~Alias ()

Alias (const T &)=delete

Alias (const T *)=delete

Alias (T &t)

Alias (T *t)

Alias (const CowPtr< T > &)=delete

Alias (const CountedPtr< T > &t)

Alias (const CountedPtrOrPtr< T > &t)

Alias (T &&)=delete

operator T& () const

T * operator& () const

operator CountedPtrOrPtr< T > () 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

Aliasoperator= (const Alias &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::Alias< T >

Aim: This class encapsulates its parameter class so that to indicate to the user that the object/pointer will be only aliased. Therefore the user is reminded that the argument parameter is given to the function without any additional cost and may 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 Alias<T> is itself a light object (it holds only an enum and a pointer).

Description of template class 'Alias'

(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 type T& T* CountedPtr<T> CountedPtrOrPtr<T>
To: T& Shared. O(1) Shared. O(1)
To: T* Shared. O(1) Shared. O(1)
To: CountedPtrOrPtr<T> Shared. O(1) Shared. O(1) Shared. O(1), secure Shared. O(1), secure

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

For the last row (case where the programmer choose a CountedPtrOrPtr to hold the const alias), the user can thus enforce a secure 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 Alias<T> instead of T & or 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 T & or T * instead of Alias<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).
Template Parameters
 T is any type.
ConstAlias
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
// experienced developper, by looking at other parts of the code.
// Only aliasing, but for a long lifetime.
struct B1 {
B1( A & a ) // ambiguous, cost is O(1) here and lifetime of a should exceed constructor.
: myA( a ) {}
...
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.

// Aliasing for a long lifetime is visible.
struct B1_v2_1 {
B1_v2_1( Alias<A> a ) // not ambiguous, cost is O(1) here and lifetime of a should be long enough
: myA( a ) {}
...
A & myA;
};
// Aliasing for a long lifetime is visible.
struct B1_v2_2 {
B1_v2_2( Alias<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
...
A* myA;
};
// Aliasing for a long lifetime is visible.
struct B1_v2_3 {
B1_v2_3( Alias<A> a ) // not ambiguous, cost is O(1) here and lifetime of a should be long enough
: myA( a ) {}
...
CountedPtrOrPtr<A> myA;
};
...
A a1;
CountedPtr<A> cptr_a1( new A( a1 ) );
B1 ( a1 ); // not duplicated
B1_v2_1 ( a1 ); // not duplicated
B1_v2_2 ( a1 ); // not duplicated
B1_v2_3 ( a1 ); // not duplicated
B1_v2_3 ( cptr_a1 ); // not duplicated, even better the user choose a secure variant of alias.
Aim: This class encapsulates its parameter class so that to indicate to the user that the object/poin...
Definition: Alias.h:183
Note
The user should not use Alias<T> instead of T* for data members. It works in most cases, but there are some subtle differences between the two behaviors.
Alias have a default copy constructor, so as to let the user forward an Alias<T> parameter.

Definition at line 182 of file Alias.h.

## ◆ Parameter

template<typename T >
 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 189 of file Alias.h.

@ CONST_LEFT_VALUE_REF
Definition: Alias.h:189
@ COUNTED_PTR
Definition: Alias.h:190
@ RIGHT_VALUE_REF
Definition: Alias.h:190
@ CONST_PTR
Definition: Alias.h:189
@ COUNTED_PTR_OR_PTR
Definition: Alias.h:190
@ COUNTED_CONST_PTR_OR_CONST_PTR
Definition: Alias.h:191
@ LEFT_VALUE_REF
Definition: Alias.h:189

## ◆ Alias() [1/9]

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

Default copy constructor.

Parameters
 other the object to copy.

## ◆ ~Alias()

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

Destructor. Does nothing.

Definition at line 205 of file Alias.h.

205{}

## ◆ Alias() [2/9]

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

Constructor from const reference to an instance of T. Deleted.

Aliasing a const-ref is an error. Consider ConstAlias instead.

## ◆ Alias() [3/9]

template<typename T >
 DGtal::Alias< T >::Alias ( const T * )
delete

Constructor from const pointer to an instance of T. Deleted.

Aliasing a const-ptr is an error. Consider ConstAlias instead.

## ◆ Alias() [4/9]

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

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

Parameters
 t any reference to an object of type T.

Definition at line 226 of file Alias.h.

227 : myParam( LEFT_VALUE_REF ), myPtr( static_cast<const void*>( &t ) )
228 {}
const Parameter myParam
Characterizes the type of the input parameter at clone instanciation.
Definition: Alias.h:331
const void *const myPtr
Stores the address of the input parameter for further use.
Definition: Alias.h:333

## ◆ Alias() [5/9]

template<typename T >
 DGtal::Alias< T >::Alias ( T * t )
inline

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

Parameters
 t any pointer to an object of type T.

Definition at line 235 of file Alias.h.

236 : myParam( PTR ), myPtr( static_cast<const void*>( t ) ) {}

## ◆ Alias() [6/9]

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

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

Aliasing a const-cow ptr is an error. Consider ConstAlias instead.

## ◆ Alias() [7/9]

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

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

Parameters
 t a const-reference to any shared pointer to an object of type T.

Definition at line 250 of file Alias.h.

251 : myParam( COUNTED_PTR ), myPtr( static_cast<const void*>( &t ) )
252 {}

## ◆ Alias() [8/9]

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

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

Parameters
 t a const-reference to any shared or simple pointer to an object of type T.

Definition at line 259 of file Alias.h.

260 : myParam( COUNTED_PTR_OR_PTR ), myPtr( static_cast<const void*>( &t ) )
261 {}

## ◆ Alias() [9/9]

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

Constructor from right-reference value. Deleted.

Aliasing a rvalue ref has no meaning. Consider Clone instead.

## ◆ operator CountedPtrOrPtr< T >()

template<typename T >
 DGtal::Alias< T >::operator CountedPtrOrPtr< T > ( ) const
inline

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

• T& -> CountedPtrOrPtr<T> // shared
• T* -> CountedPtrOrPtr<T> // shared
• CountedPtr<T> -> CountedPtrOrPtr<T> // shared
• CountedPtrOrPtr<T> -> CountedPtrOrPtr<T> // shared

Definition at line 313 of file Alias.h.

314 {
315 switch( myParam ) {
316 case LEFT_VALUE_REF:
317 case PTR:
318 return CountedPtrOrPtr<T>( const_cast< T* >( static_cast< const T* >( myPtr ) ), false );
319 case COUNTED_PTR:
320 return CountedPtrOrPtr<T>( *( static_cast< const CountedPtr<T>* >( myPtr ) ) );
322 return CountedPtrOrPtr<T>( *( static_cast< const CountedPtrOrPtr<T>* >( myPtr ) ) );
323 default: ASSERT( false && "[Alias::operator CountedPtrOrPtr<T>() const] Invalid cast for given type. Consider passing a reference, a pointer or a CountedPtr as a parameter." );
324 return CountedPtrOrPtr<T>( 0 );
325 }
326 }

## ◆ operator T&()

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

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

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

Definition at line 276 of file Alias.h.

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

## ◆ operator&()

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

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

• T& -> T* // no duplication
• T* -> T* // no duplication

Definition at line 293 of file Alias.h.

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

## ◆ operator=()

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

Assignment.

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

## ◆ myParam

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

Characterizes the type of the input parameter at clone instanciation.

Definition at line 331 of file Alias.h.

## ◆ myPtr

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

Stores the address of the input parameter for further use.

Definition at line 333 of file Alias.h.

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