DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
DcmPath Class Reference

Class representing a path of DICOM objects. More...

## Public Member Functions
| DcmPath ()
| Constructor, creates an empty search result.
| DcmPath (const OFList< DcmPathNode * > &currentPath)
| Constructor, creates a search result from a list of search nodes. More...
void | append (DcmPathNode *node)
| Appends a search node at the end of the search result path. More...
void | deleteBackNode ()
| Removes last path node from path. More...
| OFListIterator (DcmPathNode *) begin()
| Returns iterator pointing to first path component. More...
DcmPathNode * | back ()
| Returns last path component. More...
| OFListIterator (DcmPathNode *) end()
| Returns iterator pointing to last path component. More...
Uint32 | size () const
| Returns number of path components. More...
OFBool | empty () const
| Returns whether path is empty, ie does not contain any path nodes. More...
OFString | toString () const
| Returns a string representation of the path, e.g. "SourceImageSequence[0].ReferencedSOPInstanceUID". More...
OFBool | containsGroup (const Uint16 groupNo) const
| Returns whether the path contains tags of a given group. More...
OFBool | containsInvalidGroup () const
| Returns whether the path contains tags with invalid group numbers (groups 1, 3, 5, 7 and 0xFFFF are illegal in DICOM). More...
| ~DcmPath ()
| Destructor, cleans up memory of path nodes. More...

## Static Public Member Functions
static OFCondition | separatePathNodes (const OFString &path, OFList< OFString > &result)
| Returns a string representation of each path node separately. More...
static OFCondition | parseItemNoFromPath (OFString &path, Uint32 &itemNo, OFBool &wasWildcard)
| Helper function for findOrCreatePath(). More...
static OFCondition | parseTagFromPath (OFString &path, DcmTag &tag)
| Function that parses a tag from the beginning of a path string. More...

## Private Member Functions
| DcmPath (const DcmPath &rhs)
| Private undefined copy constructor. More...
DcmPath & | operator= (const DcmPath &arg)
| Private undefined assignment operator. More...

## Private Attributes
OFList< DcmPathNode * > | m_path
| Internal list representing the nodes in the path.

## Detailed Description

Class representing a path of DICOM objects.

A path is a "way" through a DICOM dataset, i.e. it starts e.g. with an item, followed by a sequence originally contained in this item. The sequence then could be followed by another item which is part of the sequence and so on. Thus the path should be well-formed, but if it is created manually (e.g. using append()) there is no corresponding checking.

## Constructor & Destructor Documentation

## ◆ DcmPath() [1/2]

DcmPath::DcmPath | ( | const OFList< DcmPathNode * > & | currentPath | ) |

Constructor, creates a search result from a list of search nodes.

Parameters

  currentPath | [in] The list of search nodes representing a "path" through a DICOM dataset

## ◆ ~DcmPath()

DcmPath::~DcmPath | ( |  | ) |

Destructor, cleans up memory of path nodes.

Does not delete the DcmObjects the nodes point to (this is also not done by the destructor of the path nodes, so the caller is responsible for freeing any related DICOM objects.

## ◆ DcmPath() [2/2]

DcmPath::DcmPath | ( | const DcmPath & | rhs | ) |
| private

Private undefined copy constructor.

Parameters

  rhs | Path to copy from

## Member Function Documentation

## ◆ append()

void DcmPath::append | ( | DcmPathNode * | node | ) |

Appends a search node at the end of the search result path.

It is not checked whether the resulting path is still valid.

Parameters

  node | [in] The node to append.

## ◆ back()

DcmPathNode* DcmPath::back | ( |  | ) |

Returns last path component.

Returns
  The last path component, NULL if none exists.

## ◆ containsGroup()

OFBool DcmPath::containsGroup | ( | const Uint16 | groupNo | ) | const

Returns whether the path contains tags of a given group.

Might be useful for looking after (unwanted) meta header tags etc.

Parameters

  groupNo | [in] The group number to look for

Returns
  OFTrue if group number is found in path, OFFalse otherwise

## ◆ containsInvalidGroup()

OFBool DcmPath::containsInvalidGroup | ( |  | ) | const

Returns whether the path contains tags with invalid group numbers (groups 1, 3, 5, 7 and 0xFFFF are illegal in DICOM).

Returns
  OFTrue if illegal group number is found in path, OFFalse otherwise

## ◆ deleteBackNode()

void DcmPath::deleteBackNode | ( |  | ) |

Removes last path node from path.

Also frees memory of path node but does not free memory of the underlying DICOM item or element.

Returns
  none

## ◆ empty()

OFBool DcmPath::empty | ( |  | ) | const

Returns whether path is empty, ie does not contain any path nodes.

Returns
  OFTrue, if path is empty, OFFalse otherwise

## ◆ OFListIterator() [1/2]

DcmPath::OFListIterator | ( | DcmPathNode * |  | ) |

Returns iterator pointing to first path component.

Returns
  Iterator to first path node.

## ◆ OFListIterator() [2/2]

DcmPath::OFListIterator | ( | DcmPathNode * |  | ) |

Returns iterator pointing to last path component.

Returns
  Iterator to last path node.

## ◆ operator=()

DcmPath& DcmPath::operator= | ( | const DcmPath & | arg | ) |
| private

Private undefined assignment operator.

Parameters

  arg | Path to copy from

Returns
  Reference to this object

## ◆ parseItemNoFromPath()

static OFCondition DcmPath::parseItemNoFromPath | ( | OFString & | path,
|  | Uint32 & | itemNo,
|  | OFBool & | wasWildcard
| ) |  |
| static

Helper function for findOrCreatePath().

Parses an item number from the beginning of the path string. The item number must be positive, starting with 0. The path must start like "[itemnumber]...".

Parameters

  path | [in/out] The path starting with the item number in square brackets, e.g. "[3]". The parsed item number and a potentially following "." are removed from the path
  itemNo | [out] The parsed item number. If a wildcard was parsed, this output parameter is not set at all.
  wasWildcard | [out] Is set to OFTrue, if wildcard was parsed (instead of concrete item number).

Returns
  EC_Normal, if concrete item number or wildcard was parsed

## ◆ parseTagFromPath()

static OFCondition DcmPath::parseTagFromPath | ( | OFString & | path,
|  | DcmTag & | tag
| ) |  |
| static

Function that parses a tag from the beginning of a path string.

The tag has to be either in numeric format, e.g. "(0010,0010)" or a dictionary name, e.g. "PatientName". If successful, the parsed tag is removed from the path string.

Parameters

  path | [in/out] The path string, starting with the attribute to parse
  tag | [out] The tag parsed

Returns
  EC_Normal if successful, error code otherwise

## ◆ separatePathNodes()

static OFCondition DcmPath::separatePathNodes | ( | const OFString & | path,
|  | OFList< OFString > & | result
| ) |  |
| static

Returns a string representation of each path node separately.

Tags are represented as numbers surrounded by braces "(gggg,eeee)", not dictionary names. Items are represented by a number or wildcard in square brackets, eg. "[12]" or "[*]".

Parameters

  path | The path to parse into different nodes
  result | [out] List containing the resulting strings

Returns
  none

## ◆ size()

Uint32 DcmPath::size | ( |  | ) | const

Returns number of path components.

Returns
  The number of path components

## ◆ toString()

OFString DcmPath::toString | ( |  | ) | const

Returns a string representation of the path, e.g. "SourceImageSequence[0].ReferencedSOPInstanceUID".

Returns
  String representing path

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

- dcmdata/include/dcmtk/dcmdata/dcpath.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1