DCMTK
Version 3.6.2
OFFIS DICOM Toolkit
|
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... | |
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.
T | the type of the value to manage initialization state for. The type's destructor must be accessible by OFoptional<T>. |
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:
|
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).
|
o == x, x == o |
|
o < x, x > o |
|
OFoptional<T> o | 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 | 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 | 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) | Swap state and contents of two OFoptional objects.
|
|
related |
A wildcard global constant to initialize an OFoptional object with disengaged state.
Example:
|
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: