iLab Neuromorphic Robotics Toolkit  0.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
nrt::Optional< T > Class Template Reference

#include <nrt/Core/Design/Optional.H>

template<class T>
class nrt::Optional< T >

A class for representing optional values.

This class is a container around some value which may or may not exist; it encapsulates optional data. Optional can wrap both reference and non reference data, and is by default set to be uninitialized upon creation.

This class provides similar functionality to boost::optional but supports r-value assignment and construction, unlike the boost version.

Optional can be used as a way to have functions indicate that they will not be returning a valid value. Consider:

Optional<double> sqrt( double n );
auto result = sqrt( -3.14 );
result.ifSet( [](double d){ std::cout << "Valid result!\n"; } ).otherwise( [](){ std::cout << "Invalid result!\n"; } );
// If we pass in a negative number here, we do not want to return a valid double.
// We can instead return an empty optional that can be checked using various means and properly ignored
// if invalid

Consider also the case of reference arguments to a function which may be considered optional. In C, these could be represented by a pointer to some type. C++ does not offer a way to have references be NULL, so there is no way to easily indicate that a parameter should not be calculated or not be used:

void myFunction( int required, Optional<double&> optionalDouble = OptionalEmpty )
{
if( optionalDouble )
optionalDouble = 3.14;
}
// note the use of OptionalEmpty to provide a default value for any Optional type indicating that
// it should be invalid
Warning
Accessing the value of an uninitialized Optional will result in undefined behavior. Make sure that it is initialized before attempting to read or write.

Also see: OptionalReference for details on reference instantiation and OptionalValue for value type instantiation.

Template Parameters
TThe type to make optional. Can be a reference.

Definition at line 86 of file Optional.H.

Inheritance diagram for nrt::Optional< T >:
nrt::OptionalBase< std::remove_reference< T >::type, std::is_reference< T >::value >

Public Member Functions

 Optional ()
 Default construction, will be marked invalid.
 
 Optional (OptionalNoneType const &)
 Construct from an OptionalNoneType, will be marked invalid.
 
 Optional (Optional const &other)
 Copy construction, will inherit the validity of the other Optional.
 
template<class U >
 Optional (Optional< U > const &other, typename std::enable_if<!std::is_reference< T >::value &&std::is_reference< U >::value &&std::is_same< typename std::remove_reference< U >::type, T >::value, bool >::type=false)
 Copy construct from a reference type assuming we are not a reference. More...
 
template<class U >
 Optional (Optional< U > const &other, typename std::enable_if< std::is_reference< T >::value &&!std::is_reference< U >::value &&std::is_same< typename std::remove_reference< T >::type, U >::value, bool >::type=false)
 Invalid copy constructor. More...
 
 Optional (Optional &&other)
 Move construction. More...
 
template<class U >
 Optional (Optional< U > &&other, typename std::enable_if<!std::is_reference< T >::value &&std::is_reference< U >::value &&std::is_same< typename std::remove_reference< U >::type, T >::value, bool >::type=false)
 Move construct from a reference type assuming we are not a reference. More...
 
template<class U >
 Optional (Optional< U > &&, typename std::enable_if< std::is_reference< T >::value &&!std::is_reference< U >::value &&std::is_same< typename std::remove_reference< T >::type, U >::value, bool >::type=false)
 Invalid move constructor. More...
 
 Optional (ArgumentTypeCopy otherT)
 Construct from our value type. More...
 
template<class U >
 Optional (U &&otherT, typename std::enable_if<!std::is_reference< T >::value &&std::is_same< U, typename std::remove_reference< T >::type >::value, bool >::type=false)
 Construct from from an r-value to our value type. More...
 
template<class U >
 Optional (U &&, typename std::enable_if< std::is_reference< T >::value &&std::is_same< U, typename std::remove_reference< T >::type >::value, bool >::type=false)
 Invalid construction from an r-value to our value type. More...
 
Optionaloperator= (Optional const &other)=default
 
OptionalifSet (std::function< void(ArgumentTypeCopy)> func)
 Apply a functor to the contents of this Optional if it is set. More...
 
Optional const & ifSet (std::function< void(ArgumentTypeCopy)> func) const
 Const version of ifSet.
 
void otherwise (std::function< void()> func) const
 Apply a functor to the contents of this Optional if it is NOT set. More...
 

Related Functions

(Note that these are not member functions.)

typedef int
nrt_optional_impl::OptionalNoneHelper::* 
OptionalNoneType
 A type used to indicate an empty optional. More...
 
OptionalNoneType const OptionalEmpty = static_cast<OptionalNoneType>( 0 )
 Provides a default value that can be used for Optional types to indicate that they are not in use. More...
 

Constructor & Destructor Documentation

template<class T>
template<class U >
nrt::Optional< T >::Optional ( Optional< U > const &  other,
typename std::enable_if<!std::is_reference< T >::value &&std::is_reference< U >::value &&std::is_same< typename std::remove_reference< U >::type, T >::value, bool >::type  = false 
)

Copy construct from a reference type assuming we are not a reference.

This constructor only allows construction in the reference->value direction and requires that the types are identical.

Template Parameters
UThe type of the other Optional, which should be a T reference
Parameters
otherThe Optional that holds a reference of the same type
template<class T>
template<class U >
nrt::Optional< T >::Optional ( Optional< U > const &  other,
typename std::enable_if< std::is_reference< T >::value &&!std::is_reference< U >::value &&std::is_same< typename std::remove_reference< T >::type, U >::value, bool >::type  = false 
)

Invalid copy constructor.

This constructor will fail to compile since it represents creating a reference Optional from a non reference Optional of the same type. Static asserts will provide a more descriptive error

template<class T>
nrt::Optional< T >::Optional ( Optional< T > &&  other)

Move construction.

Move construction will always invalidate the moved Optional

template<class T>
template<class U >
nrt::Optional< T >::Optional ( Optional< U > &&  other,
typename std::enable_if<!std::is_reference< T >::value &&std::is_reference< U >::value &&std::is_same< typename std::remove_reference< U >::type, T >::value, bool >::type  = false 
)

Move construct from a reference type assuming we are not a reference.

This constructor only allows construction in the reference->value direction and requires that the types are identical.

Move construction will always invalidate the moved Optional.

Template Parameters
UThe type of the other Optional, which should be a T reference
Parameters
otherThe Optional that holds a reference of the same type. other will be invalidated after moving
template<class T>
template<class U >
nrt::Optional< T >::Optional ( Optional< U > &&  ,
typename std::enable_if< std::is_reference< T >::value &&!std::is_reference< U >::value &&std::is_same< typename std::remove_reference< T >::type, U >::value, bool >::type  = false 
)

Invalid move constructor.

This constructor will fail to compile since it represents creating a reference Optional from a non reference Optional of the same type. Static asserts will provide a more descriptive error

template<class T>
nrt::Optional< T >::Optional ( ArgumentTypeCopy  otherT)

Construct from our value type.

Parameters
otherTThe type of otherT depends upon whether this is a reference Optional or a value Optional. For references, the argument copy type will be a non const refernce. For values, the argument copy type will be a const reference.
template<class T>
template<class U >
nrt::Optional< T >::Optional ( U &&  otherT,
typename std::enable_if<!std::is_reference< T >::value &&std::is_same< U, typename std::remove_reference< T >::type >::value, bool >::type  = false 
)

Construct from from an r-value to our value type.

This constructor will only be available if we are not a reference Optional. References cannot be constructed from r-values.

Template Parameters
UThe type of the parameter, which should match our type T.
Parameters
otherTThe value to initialize with.
template<class T>
template<class U >
nrt::Optional< T >::Optional ( U &&  ,
typename std::enable_if< std::is_reference< T >::value &&std::is_same< U, typename std::remove_reference< T >::type >::value, bool >::type  = false 
)

Invalid construction from an r-value to our value type.

This constructor will fail to compile due to static assertions describing the reason for failure. This will only happen in the event that a reference Optional is initialized with a r-value to the value type

Member Function Documentation

template<class T>
Optional& nrt::Optional< T >::ifSet ( std::function< void(ArgumentTypeCopy)>  func)

Apply a functor to the contents of this Optional if it is set.

This, in conjunction with otherwise(), provides a clean interface to deal with Optional objects that may or may not actually contain values.

Optional<int> myOptional;
myOptional.ifSet( [](int x){ std::cout << "Had an int: " << x << std::endl; } ).otherwise( [](){ std::cout << "No value!" << std::endl; } );
template<class T>
void nrt::Optional< T >::otherwise ( std::function< void()>  func) const

Apply a functor to the contents of this Optional if it is NOT set.

This is intended to be used in conjunction with ifSet() to form an if/else pair over an Optional.

Friends And Related Function Documentation

template<class T>
typedef int nrt_optional_impl::OptionalNoneHelper::* OptionalNoneType
related

A type used to indicate an empty optional.

Definition at line 84 of file OptionalHelpers.H.

template<class T>
OptionalNoneType const OptionalEmpty = static_cast<OptionalNoneType>( 0 )
related

Provides a default value that can be used for Optional types to indicate that they are not in use.

Definition at line 88 of file OptionalHelpers.H.


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