Loading...
Searching...
No Matches
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.
< unspecified > | OFnullopt_t
| OFnullopt_t is the type of the global constant `OFnullopt` referring to a disengaged OFoptional object independent of the content type.

## 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

  T | the 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:

Symbol | Definition
--- | ---
`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:

Expression | Meaning
--- | ---
`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;
OFoptional
The class template OFoptional manages an optional contained value, i.e. a value tagged with a state t...
Definition ofoption.h:486
OFoptional::OFnullopt
OFnullpt_t OFnullopt
A wildcard global constant to initialize an OFoptional object with disengaged state.
Definition ofoption.h:82

## 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;
}

References OFnullopt_t().

Referenced by OFnullopt_t().

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

- ofstd/include/dcmtk/ofstd/ofoption.h

Generated on for DCMTK Version 3.7.0 by Doxygen 1.15.0