DCMTK: OFtuple< Types > Class Template Reference

DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
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.
template<typename Tuple>
< metafunction > | OFtuple_size
| A metafunction to determine the size of a tuple.
template<size_t Index, typename Tuple>
< metafunction > | OFtuple_element
| A metafunction to determine the type of one element of a tuple.
template<typename... Types>
OFtuple< typename OFdecay< Types >::type... > | OFmake_tuple (Types &&... args)
| Creates a tuple, automatically deducing the element types from the given arguments.
template<typename... Types>
OFtuple< Types &... > | OFtie (Types &... args)
| Creates a tuple of references to the given arguments.
template<size_t Index, typename Tuple>
OFtuple_element< Index, Tuple >::type & | OFget (Tuple &tuple)
| A function template to access an element of a tuple.
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.

## Detailed Description

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

A class template that implements generic tuples.

Template Parameters

  Types | a sequence of element types that shall be contained in the tuple. An empty sequence is allowed.
  | Note | When 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:

- A tuple type may contain a specific number of elements of arbitrary types.
- The metafunction OFtuple_size is specialized in an appropriate way to determine the number of elements a tuple type may contain.
- The metafunction OFtuple_element is specialized in an appropriate way to determine the type of one of the tuple's elements at the provided index.
- The function-template OFget is overloaded in appropriate ways to enable access to one of the tuple's elements at the provided index.

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

- any instance of OFtuple
- any instance of OFPair

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:

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

Expression | Meaning
--- | ---
`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" ) );
OFtuple::OFget
OFtuple_element< Index, Tuple >::type & OFget(Tuple &tuple)
A function template to access an element of a tuple.
OFtuple::OFmake_tuple
OFtuple< typename OFdecay< Types >::type... > OFmake_tuple(Types &&... args)
Creates a tuple, automatically deducing the element types from the given arguments.

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>

const OFtuple_element< Index, Tuple >::type & OFget | ( | const Tuple & | tuple | ) |
| related

A function template to access an element of a tuple.

Template Parameters

  Index | the index of the element that should be accessed.
  Tuple | a tuple type, e.g. an instance of OFtuple. This parameter is deduced automatically.

Parameters

  tuple | a 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;
}
OFtuple
A class template that implements generic tuples.
Definition oftuple.h:668

Output:

    Homer Simpson, age 38 is male.

References OFtuple_element.

## ◆ OFget() [2/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

  Index | the index of the element that should be accessed.
  Tuple | a tuple type, e.g. an instance of OFtuple. This parameter is deduced automatically.

Parameters

  tuple | a 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:

OFtuple<OFString,size_t,OFVector<int> > myTuple;
OFget<0>( myTuple ) = "Hamish Alexander";
OFget<1>( myTuple ) = 23;
OFget<2>( myTuple ).push_back( 42 );

References OFtuple_element.

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

typedef OFMap<OFtuple<OFString,OFstring>,OFString> PhoneBook;
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 );
...
OFMap
associative container class.
Definition ofmap.h:44
OFString
a simple string class that implements a subset of std::string.
Definition ofstring.h:76
OFString::insert
OFString & insert(size_t pos1, const OFString &str, size_t pos2=0, size_t n=OFString_npos)
Inserts at most n characters, starting at position pos2 of the input string str, into the current str...
OFtuple::OFignore
const < unspecified > OFignore
A literal used in conjunction with OFtie to ignore specific elements.
Definition oftuple.h:688

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

  args | a sequence of arguments. When no arguments are supplied, an object of type OFtuple<> is created.
  | Note | When 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:

OFVector<OFtuple<OFString,OFString,size_t> > personIndex;
personIndex.push_back( OFmake_tuple( "Alexander", "Emily", 17 ) );
personIndex.push_back( OFmake_tuple( "Henke", "Michelle", 0 ) );
OFVector
this is a resizable array.
Definition ofvector.h:45
OFVector::push_back
void push_back(const T &v)
insert an entry at the end of this object
Definition ofvector.h:292

## ◆ OFtie()

template<typename... Types>

OFtuple< Types &... > OFtie | ( | Types &... | args | ) |
| related

Creates a tuple of references to the given arguments.

Parameters

  args | a sequence of arguments. When no arguments are supplied, an object of type OFtuple<> is created.
  | Note | When 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 );
OFtuple::OFtie
OFtuple< Types &... > OFtie(Types &... args)
Creates a tuple of references to the given arguments.

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

  Index | the index of the element its type should be determined.
  Tuple | a 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;
typedef OFtuple<OFtuple_element<0,MyPair>::type,OFtuple_element<1,MyPair>::type> MyTuple;
MyPair pair( "Hello World", 42 );
MyTuple tuple( pair ); // Works, since both elements' types are the same as within MyPair.
OFPair
a pair - this implements parts of std::pair's interface.
Definition ofutil.h:323
OFtuple::OFtuple_element
< metafunction > OFtuple_element
A metafunction to determine the type of one element of a tuple.
Definition ofutil.h:540

Referenced by OFget(), and OFget().

## ◆ OFtuple_size

template<typename... Types>
template<typename Tuple>

<metafunction> OFtuple_size
| related

A metafunction to determine the size of a tuple.

Template Parameters

  Tuple | a 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 OFtuple<OFString,size_t,OFVector<int> > MyTuple;
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;
OFtuple::OFtuple_size
< metafunction > OFtuple_size
A metafunction to determine the size of a tuple.
Definition ofutil.h:518

Output:

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

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

- ofstd/include/dcmtk/ofstd/oftuple.h
- ofstd/include/dcmtk/ofstd/ofutil.h

Generated on for DCMTK Version 3.7.0 by Doxygen 1.16.1