DCMTK  Version 3.6.3
OFFIS DICOM Toolkit
Related Definitions | List of all members
OFoptional< T > Class Template Reference

The class template OFoptional manages an optional contained value, i.e. a value tagged with a state that reports its validity. More...

Related Definitions

Global types, methods and objects that are somehow related

OFnullpt_t OFnullopt
 A wildcard global constant to initialize an OFoptional object with disengaged state. More...
 
< unspecified > OFnullopt_t
 OFnullopt_t is the type of the global constant OFnullopt referring to a disengaged OFoptional object independent of the content type. More...
 

Detailed Description

template<typename T>
class OFoptional< T >

The class template OFoptional manages an optional contained value, i.e. a value tagged with a state that reports its validity.

A common use case for OFoptional is the return value of a function that may fail. OFoptional handles expensive to construct objects well and is more readable, as the intent is expressed explicitly. An OFoptional object which actually contains a value is called 'engaged', whereas an OFoptional object not containing a valid value is called 'disengaged'. The global constant 'OFnullopt' of type 'OFnullopt_t' may be used to explicitly mark an optional object as disengaged, for example to return a disengaged object from a function if an error occurred.

Template Parameters
Tthe type of the value to manage initialization state for. The type's destructor must be accessible by OFoptional<T>.
Note
There exists a sufficient specialization for reference types (T&) that behaves exactly like a pointer (T*) but allows OFoptional to be used in a generic context (when it's unknown if T is a reference or not).
See also
OFoptional_traits
OFdefault_optional_traits

OFoptional Syntax

OFoptional can be used like a pointer to the contained value, except OFoptional also manages the contained value's storage. Several operators have been overloaded to simplify the usage of OFoptional. Instead of looking at every overload's specification, it is more appropriate to describe the possible syntax in a general manner. Therefore we declare the following symbols that are used below to describe OFoptional's syntax and behavior:

SymbolDefinition
T
The content type to be used
t
An object of type T
o, lhs, rhs
An object of type OFoptional<T>
os
An STL compatible output stream
is
An STL compatible input stream
x
May be:
  • an object of type T
  • an object of type OFoptional<T>
  • OFnullopt

The following table describes possible operations on OFoptional and related objects:

ExpressionMeaning
os << o
Prints content of o to os. Prints nullopt if o is disengaged.
is >> o
Reads the content of o from is. If the content cannot be read from is, o becomes disengaged.
If o is disengaged before the expression is evaluated, the content of o is default constructed unless T is not default constructible or T's default constructor is not accessible by OFoptional<T>. If default construction is not possible, the expression has no effect (o remains disengaged).
Note
Detecting if T is default constructible within OFoptional<T> does not work correctly on all compilers. Especially all versions of Microsoft Visual Studio are impaired. For example a private default constructor of T might be detected as not accessible although OFoptional<T> was declared a friend of T. Specialize OFoptional_traits for a particular type T to override constructibility detection as required. See this example.
o == x, x == o
o != x, x != o
  • If x is an object of type T and o is engaged, x is compared to the content of o in the appropriate fashion. Otherwise o is considered inequal to x.
  • If x is another OFoptional object, the two objects are considered equal IFF both objects are disengaged or both objects are engaged and their contents are equal.
  • If x is OFnullopt, x and o are considered equal IFF o is disengaged.
o < x, x > o
o > x, x < o
o <= x, x >= o
o >= x, x <= o
  • If x is an object of type T, x is compared to the content of o if o is engaged. Otherwise o is considered less than x.
  • If x is another OFoptional object, the state of both objects is compared whereas disengaged is considered less than engaged. If both objects are engaged, their contents are compared to evaluate the expression.
  • If x is OFnullopt, o is considered equal to x if o is disengaged and greater than x otherwise.
OFoptional<T> o
OFoptional<T> o(x)
OFoptional<T> o(x0,...,xn)C++11
OFmake_optional(t)
Construct an OFoptional object. The content type T must be specified explicitly unless OFmake_optional is used, which deduces an appropriate type for T from the given parameter t.
If C++11 support is available, OFoptional can be move constructed from x, allowing the content to be moved into o instead of being copied. C++11 support also enables in-place construction of o, copying or moving the given arguments as appropriate to construct o's content in the most efficient way.
!o
Evaluates to OFTrue if o is disengaged, evaluates to OFFalse otherwise.
if(o), while(o), ...
When used in an appropriate context, o is evaluated to OFTrue if o is engaged and to OFFalse if o is disengaged.
If C++11 support is available, the conversion operator is marked as explicit, which prevents o to be interpreted as a boolean value in an inappropriate context. You should therefore use o with caution when C++11 support is unavailable, as o might be converted to a boolean value automatically where it shouldn't.
*o
o.value()
Access the content of o. The expression evaluates to a reference to o's content if o is engaged. Otherwise the results are undefined.
o.value_or(t)
Access the content of o. The expression evaluates to a copy of o's content if o is engaged. Otherwise a copy of t is returned.
If C++11 support is available, t may be moved instead of being copied, if possible.
o->
Access a member of o's content. Members of compound data-types can be accessed via this syntax if o is engaged. Otherwise the results are undefined.
o = x
o.emplace(x0,...,xn)C++11
Assign x to o. If x is another OFoptional object, the state is copied from x and the content is only assigned if x is engaged. If x is OFnullopt o simply becomes disengaged.
If C++11 support is available, OFoptional can be move assigned from x, allowing the content to be moved into o instead of being copied. C++11 support also enables in-place assignment of o via the member method emplace, copying or moving the given arguments as appropriate to assign o's content in the most efficient way.
o.swap(rhs)
OFswap(lhs, rhs)
Swap state and contents of two OFoptional objects.
  • Does nothing if both objects are disengaged.
  • Calls OFswap(*o, *rhs) resp. OFswap(*lhs, *rhs) if both objects are engaged.
  • Swaps the states if both objects' states differ and assigns the content of the engaged object to the previously disengaged object. If C++11 support is available, the content is moved from one object to the other. Otherwise the content is copied and afterwards destroyed in the now disengaged object.
Note
OFoptional is implemented based on the C++14 proposal for std::optional N3690, p. 503ff and is similar to Boost.Optional.

Usage example:

OFoptional<int> my_atoi( const char* str )
{
int result;
return parseValue( result, str ) ? OFoptional<int>( result ) : OFnullopt;
}
// Classical atoi, can't distinguish '0' from an error.
int i = atoi( "0" );
if( !i ) // ERROR
// Using OFoptional to distinguish '0' and parser error.
OFoptional<int> i = my_atoi( "0" );
if( !i ) // OK
{
// read optional value from standard input.
COUT << "Invalid value, please input a new value: ";
CIN >> i;
// if the user entered garbage, use 42 as default.
i = i.value_or( 42 );
}
// modify content of optional value and print the result.
*i += 3;
COUT << i << OFendl;

Related Definitions

◆ OFnullopt

template<typename T>
OFnullpt_t OFnullopt
related

A wildcard global constant to initialize an OFoptional object with disengaged state.

Example:

OFoptional<int> div( int lhs, int rhs )
{
return rhs ? OFmake_optional( lhs / rhs ) : OFnullopt;
}
See also
OFoptional

◆ OFnullopt_t()

template<typename T>
< unspecified > OFnullopt_t
related

OFnullopt_t is the type of the global constant OFnullopt referring to a disengaged OFoptional object independent of the content type.

OFnullopt_t may be used to improve the performance of overloaded methods, see example:

int add2( const OFoptional<int>& o )
{
return o ? *o + 2 : 2;
}
int add2( OFnullopt_t )
{
// Note: it's not required to check the state when OFnullopt is passed.
return 2;
}
The documentation for this class was generated from the following file:

Generated on Mon Feb 5 2018 for DCMTK Version 3.6.3 by Doxygen 1.8.14