DCMTK  Version 3.6.4
OFFIS DICOM Toolkit
Related Definitions | List of all members
OFtuple< Types > Class Template Reference

A class template that implements generic tuples. More...

Related Definitions

Global types, methods and objects that are somehow related

const < unspecified > OFignore
 A literal used in conjunction with OFtie to ignore specific elements. More...
 
template<typename Tuple >
< metafunction > OFtuple_size
 A metafunction to determine the size of a tuple. More...
 
template<size_t Index, typename Tuple >
< metafunction > OFtuple_element
 A metafunction to determine the type of one element of a tuple. More...
 
template<typename... Types>
OFtuple< typename OFdecay< Types >::type... > OFmake_tuple (Types &&... args)
 Creates a tuple, automatically deducing the element types from the given arguments. More...
 
template<typename... Types>
OFtuple< Types &... > OFtie (Types &... args)
 Creates a tuple of references to the given arguments. More...
 
template<size_t Index, typename Tuple >
OFtuple_element< Index, Tuple >::type & OFget (Tuple &tuple)
 A function template to access an element of a tuple. More...
 
template<size_t Index, typename Tuple >
const OFtuple_element< Index, Tuple >::type & OFget (const Tuple &tuple)
 A function template to access an element of a tuple. More...
 

Detailed Description

template<typename... Types>
class OFtuple< Types >

A class template that implements generic tuples.

Template Parameters
Typesa sequence of element types that shall be contained in the tuple. An empty sequence is allowed.
NoteWhen C++11 support is not available, the number of elements OFtuple may contain is limited, currently up to 50 elements are supported.

Tuple Types

The term tuple type refers to the generic concept of tuples of elements, to be described as follows:

The following types provided by the DCMTK currently fulfill all the above requirements and may therefore be regarded as tuple types:

When C++11 support is enabled, OFtuple_size, OFtuple_element and OFget refer to the respective STL declarations and therefore std::array may then be regarded as a tuple type as well.

Defining own tuple types

It is possible to define one's own tuple types, which may then be modified by all operations that are defined on tuple types as well. To define a custom tuple type, you need to implement the above accession methods, which means to specialize OFtuple_size and OFtuple_element and overload OFget in appropriate ways.

Note
When C++11 support is enabled, you need to specialize and overload the respective STL definitions (e.g. std::get) instead!

OFtuple Syntax

As described in the previous section tuple types are queried and modified by the freestanding metafunctions and function templates OFtuple_size, OFtuple_element and OFget. Regarding OFtuple, two additional function templates are provided: OFmake_tuple and OFtie. Take a look at the Related Definitions section for their description.
However, some operations are defined on OFtuple objects themselves, these are described in this section. But first we need to declare the following symbols, which are used in that description:

SymbolDefinition
T0, T1, ..., Tn
U0, U1, ..., Un
The elements' types of two (possibly) different tuples
t0, t1, ..., tn
Objects of types T0, T1, ..., Tn respectively
u0, u1, ..., un
Objects of types U0, U1, ..., Un respectively
t, rhs
An object of type OFtuple<T0,T1,...,Tn>
u
An object of type OFtuple<U0,U1,...,Un>
t2
An object of type OFtuple<T0,T1>, a tuple with exactly two elements
p
An object of type OFPair<U0,U1>

The allowed syntax on OFtuple objects is described in the following table:

ExpressionMeaning
t == u, u == t
t != u, u != t
Compares the tuples t and u for equality / inequality.
You may compare tuples with different element types, as long as both elements at the same index are comparable (overload operator== rsp. operator!=).
  • Both tuples are considered equal IFF all pairs of elements that share the same index compare equal to one and another.
  • Both tuples are considered inequal IFF at least a pair of elements that share the same index compare inequal to one and another.
t < u, u > t
t > u, u < t
t <= u, u >= t
t >= u, u <= t
Tests if the tuples t and u are less / less or equal to each other.
You may compare tuples with different element types, as long as both elements at the same index are comparable (overload operator< rsp. operator<=).
  • Both tuples are considered less IFF for at least a pair of elements that share the same index the left hand side's tuple's element compares less to the other and all previously compared pairs of elements (elements with smaller indices) compared equal to one and another.
  • Both tuples are considered less or equal IFF for at least a pair of elements that share the same index the left hand side's tuple's element compares less to the other and all previously compared pairs of elements (elements with smaller indices) compared equal to one and another or all pairs of elements compare equal to one and another.
OFtuple<T0,T1,...,Tn> t
OFtuple<T0,T1,...,Tn> t( t0, t1, ..., tn )
OFtuple<T0,T1,...,Tn> t( u0, u1, ..., un )C++11
OFtuple<T0,T1> t2( p )
OFmake_tuple( t0, t1, ..., tn )
Constructs a tuple containing the supplied arguments as its elements (if any). The elements' types T0, T1, ..., Tn must be specified explicitly unless OFmake_tuple is used, which deduces appropriate types from the given parameters t0, t1, ..., tn.
If C++11 support is available, t may be move constructed from whatever arguments were supplied, possibly increasing the performance.
Note
You may still supply objects of different types than the respective elements even if C++11 support is not available. The arguments will then be copy constructed from the supplied objects first (and be copied again to initialized the elements inside the tuple).
t = rhs
t = u
t2 = p
Assigns the elements from another tuple type to the elements in the left hand side OFtuple object.
If C++11 support is available, the elements may be move assigned instead of being copied, possibly increasing the performance.
Note
You may directly assign an object of type OFPair to an OFtuple, but only if the tuple has exactly two elements.
t.swap( rhs )
OFswap( t, rhs )
Swaps the elements of two OFtuple objects with identical element types.
Effectively calls OFswap() on each pair of elements that share the same index. Note however that this is done sequentially, at no time requiring a whole copy of one the tuples to reside in the memory.

Usage Example:

// Include this file to use OFtuple
#include "dcmtk/ofstd/oftuple.h"
// A metatemplate for printing all elements of a tuple
// Note: This works on any tuple type, not just OFtuple
// based ones.
template<size_t Index>
struct printer
{
// First template-recurse to print the previous elements
// Then append the current one.
template<typename Tuple>
static void print( std::ostream& out, const Tuple& tuple )
{
printer<Index-1>::print( out, tuple );
out << ", " << OFget<Index-1>( tuple );
}
};
// Specialization to print the first element without a
// preceding ','.
template<>
struct printer<1>
{
template<typename Tuple>
static void print( std::ostream& out, const Tuple& tuple )
{
out << OFget<0>( tuple );
}
};
// Specialization so that printing empty tuples does
// not lead to an error.
template<>
struct printer<0>
{
static void print( ... ) {}
};
// A wrapper function template that applies
// OFtuple_size automatically, to ease printing tuples.
template<typename Tuple>
void printTuple( std::ostream& out, const Tuple& tuple )
{
printer<OFtuple_size<Tuple>::value>::print( out, tuple );
out << OFendl;
}
// Construct some tuples. Two OFtuple based ones and one
// OFPair based tuple.
OFtuple<OFString,size_t> t0( "Hello World", 42 ), t1;
OFPair<const char*,int> p( "Hello World", 42 );
// Compare the tuples and print them
if( t0 != t1 )
{
COUT << "The following tuples are inequal:" << OFendl;
COUT << " ";
printTuple( COUT, t0 );
COUT << " ";
printTuple( COUT, t1 );
}
// Assign the pair to the tuple
// Note: const char* gets auto-converted to OFString
// and int gets converted to size_t
// (probably with a warning, depending on your
// compiler and settings).
t1 = p;
// Compare the tuples and the pair
// Note: The pair needs to be converted to a tuple
// first, but comparing tuples with different element
// types goes well.
if( t0 == t1 && t0 == OFtuple<const char*,int>( p ) )
{
COUT << "The following tuples are equal:" << OFendl;
COUT << " ";
printTuple( COUT, t0 );
COUT << " ";
printTuple( COUT, t1 );
COUT << " ";
printTuple( COUT, p );
}
// Construct a tuple with some more elements and template-recursively print it
// Note: You don't need to declare the element types explicitly when using tuples this way.
printTuple( COUT, OFmake_tuple( "This", "is", "a", "tuple", "with", 7, "elements" ) );

Output:

The following tuples are inequal:
  Hello World, 42
  , 0
The following tuples are equal:
  Hello World, 42
  Hello World, 42
  Hello World, 42
This, is, a, tuple, with, 7, elements

Related Definitions

◆ OFget() [1/2]

template<size_t Index, typename Tuple >
OFtuple_element< Index, Tuple >::type & OFget ( Tuple &  tuple)
related

A function template to access an element of a tuple.

Template Parameters
Indexthe index of the element that should be accessed.
Tuplea tuple type, e.g. an instance of OFtuple. This parameter is deduced automatically.
Parameters
tuplea reference to the tuple to access an element of.
Precondition
Tuple is a tuple type, see Tuple Types for definition.
Index is a valid index , essentially: Index < OFtuple_size<Tuple>::value.
Returns
a reference to the tuple's element at the given index.

Usage Example:

OFget<0>( myTuple ) = "Hamish Alexander";
OFget<1>( myTuple ) = 23;
OFget<2>( myTuple ).push_back( 42 );

◆ OFget() [2/2]

template<size_t Index, typename Tuple >
const OFtuple_element< Index, Tuple >::type & OFget ( const Tuple &  tuple)
related

A function template to access an element of a tuple.

Template Parameters
Indexthe index of the element that should be accessed.
Tuplea tuple type, e.g. an instance of OFtuple. This parameter is deduced automatically.
Parameters
tuplea const reference to the tuple to access an element of.
Precondition
Tuple is a tuple type, see Tuple Types for definition.
Index is a valid index , essentially: Index < OFtuple_size<Tuple>::value.
Returns
a const reference to the tuple's element at the given index.

Usage Example:

const OFtuple<OFString,size_t,OFBool> myConstTuple( "Homer Simpson", 38, OFTrue );
if( OFget<0>( myConstTuple ) == "Homer Simpson" )
{
// OFget<1>( myConstTuple ) = 23; INVALID, myConstTuple is const!
OFBool isMale = OFget<2>( myConstTuple );
if( isMale )
COUT << OFget<0>( myConstTuple ) << ", age "
<< OFget<1>( myConstTuple ) << " is male." << OFendl;
}

Output:

Homer Simpson, age 38 is male.

◆ OFignore

template<typename... Types>
const<unspecified> OFignore
related

A literal used in conjunction with OFtie to ignore specific elements.

OFignore is a global constant that "tags" a specific tuple element which should be ignored. This means anything can be assigned to this element without any effect.

Usage Example:

PhoneBook pb;
PhoneBook::iterator it;
...
// We don't care if this was a new entry or an old one existed, we just want to update it
OFtie( it, OFignore ) = pb.insert( PhoneBook::value_type( OFmake_tuple( "Ringo", "John" ), "" );
updatePhonebookEntry( it );
...

◆ OFmake_tuple()

template<typename... Types>
OFtuple< typename OFdecay< Types >::type... > OFmake_tuple ( Types &&...  args)
related

Creates a tuple, automatically deducing the element types from the given arguments.

Parameters
argsa sequence of arguments. When no arguments are supplied, an object of type OFtuple<> is created.
NoteWhen C++11 support is not available, the number of elements OFtuple may contain is limited, currently up to 50 elements are supported.

OFcreate_tuple deduces the element types from the arguments by applying OFdecay to each parameter type.

Usage Example:

personIndex.push_back( OFmake_tuple( "Alexander", "Emily", 17 ) );
personIndex.push_back( OFmake_tuple( "Henke", "Michelle", 0 ) );

◆ OFtie()

template<typename... Types>
OFtuple< Types &... > OFtie ( Types &...  args)
related

Creates a tuple of references to the given arguments.

Parameters
argsa sequence of arguments. When no arguments are supplied, an object of type OFtuple<> is created.
NoteWhen C++11 support is not available, the number of elements OFtuple may contain is limited, currently up to 50 elements are supported.

OFtie is meant to link its arguments to an OFtuple object, to ease extracting the elements from a tuple.

Usage Example:

OFtuple<OFString,OFBool,unsigned,OFString> getAccount( const size_t accountId )
{
...
}
...
OFString name;
OFBool sex;
unsigned age;
OFString data;
OFtie( name, sex, age, data ) = getAccount( currentId );
See also
OFignore

◆ OFtuple_element

template<typename... Types>
template<size_t Index, typename Tuple >
<metafunction> OFtuple_element
related

A metafunction to determine the type of one element of a tuple.

Template Parameters
Indexthe index of the element its type should be determined.
Tuplea tuple type, e.g. an instance of OFtuple.
Precondition
Tuple is a tuple type, see Tuple Types for definition.
Index is a valid index , essentially: Index < OFtuple_size<Tuple>::value.
Returns
if the preconditions are met, OFtuple_element declares a member type alias type that yields the type of the element at the given index.

Usage Example:

typedef OFPair<OFString,size_t> MyPair;
MyPair pair( "Hello World", 42 );
MyTuple tuple( pair ); // Works, since both elements' types are the same as within MyPair.

◆ OFtuple_size

template<typename... Types>
template<typename Tuple >
<metafunction> OFtuple_size
related

A metafunction to determine the size of a tuple.

Template Parameters
Tuplea tuple type, e.g. an instance of OFtuple.
Precondition
Tuple is a tuple type, see Tuple Types for definition.
Returns
OFtuple_size is derived from an appropriate instance of OFintegral_constant if the preconditions are met. This means OFtuple_size declares a static member constant value set to the tuple's size.

Usage Example:

typedef OFPair<OFString,MyTuple> MyPair;
COUT << "OFtuple_size<MyTuple>::value: " << OFtuple_size<MyTuple>::value << OFendl;
COUT << "OFtuple_size<MyPair>::value: " << OFtuple_size<MyPair>::value << OFendl;

Output:

OFtuple_size<MyTuple>::value: 3
OFtuple_size<MyPair>::value: 2

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


Generated on Thu Nov 29 2018 for DCMTK Version 3.6.4 by Doxygen 1.8.14