DCMTK Version 3.7.0 OFFIS DICOM Toolkit

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

A class that implements the different kinds attribute matching. More...

## Classes
struct | Range
| Helper class for parsing value range pairs, as in date/time ranges. More...

## Public Member Functions
| DcmAttributeMatching ()
| Default construct an empty DcmAttributeMatching object.
| DcmAttributeMatching (const DcmVR vr)
| Construct an DcmAttributeMatching object that is appropriate for the given VR. More...
| operator OFBool () const
| Test whether this object may be used for matching, i.e. whether it is not empty. More...
OFBool | operator! () const
| Test whether this object cannot be used for matching, i.e. whether it is empty. More...
OFBool | operator() (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize) const
| Match the given query and candidate using the internally stored matching function. More...

## Static Public Member Functions
static OFBool | isDateQuery (const void *queryData, const size_t querySize)
| Check whether the given query data conforms to the VR DA. More...
static OFBool | isTimeQuery (const void *queryData, const size_t querySize)
| Check whether the given query data conforms to the VR TM. More...
static OFBool | isDateTimeQuery (const void *queryData, const size_t querySize)
| Check whether the given query data conforms to the VR DT. More...
static OFBool | singleValueMatching (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Match the query data and the candidate using Single Value Matching, as defined by the DICOM standard. More...
static OFBool | wildCardMatching (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Match the query and the candidate string using Wild Card Matching, as defined by the DICOM standard. More...
static OFBool | rangeMatchingDate (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Match the query date or date range and the candidate date. More...
static OFBool | rangeMatchingTime (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Match the query time or time range and the candidate time. More...
static OFBool | rangeMatchingDateTime (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Match the query date time or date time range and the candidate date time. More...
static OFBool | rangeMatchingDateTime (const void *dateQueryData, const size_t dateQuerySize, const void *timeQueryData, const size_t timeQuerySize, const void *dateCandidateData, const size_t dateCandidateSize, const void *timeCandidateData, const size_t timeCandidateSize)
| Match the query date and time or date and time range and the candidate date and time using combined datetime matching. More...
static OFBool | listOfUIDMatching (const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Match the query list of UIDs with the candidate UID. More...

## Static Private Member Functions
static OFBool | checkRangeQuery (OFBool(*check)(const char *, const size_t), const void *queryData, const size_t querySize)
| Helper function for generically implementing check functions operating on ranges. More...
template<typename T >
static OFBool | rangeMatchingTemplate (OFCondition(*parse)(const char *, const size_t, T &), const Range &query, const T &candidate)
| Helper template function for generically implementing range matching. More...
template<typename T >
static OFBool | rangeMatchingTemplate (OFCondition(*parse)(const char *, const size_t, T &), const void *queryData, const size_t querySize, const void *candidateData, const size_t candidateSize)
| Helper template function for generically implementing range matching. More...

## Private Attributes
OFBool(* | m_pMatch )(const void *, const size_t, const void *, const size_t)
| A pointer to one of the matching functions that is appropriate for the given VR.

## Detailed Description

A class that implements the different kinds attribute matching.

DcmAttributeMatching may either be used by directly calling the appropriate matching function, e.g. wildCardMatching() or by creating a DcmAttributeMatching object for a specific VR. In the latter case, DcmAttributeMatching will choose the appropriate matching function for the VR in its constructor and remember the result during its lifetime.

## Constructor & Destructor Documentation

## ◆ DcmAttributeMatching()

DcmAttributeMatching::DcmAttributeMatching | ( | const DcmVR | vr | ) |

Construct an DcmAttributeMatching object that is appropriate for the given VR.

Parameters

  vr | the DICOM Value Representation of the data that this object will be used on for matching.

## Member Function Documentation

## ◆ checkRangeQuery()

static OFBool DcmAttributeMatching::checkRangeQuery | ( | OFBool(*)(const char *, const size_t) | check,
|  | const void * | queryData,
|  | const size_t | querySize
| ) |  |
| static private

Helper function for generically implementing check functions operating on ranges.

Parameters

  check | a pointer to a function that checks a single value of the given query.
  queryData | a pointer to some data.
  querySize | the size (in bytes) of the data queryData refers to.

Returns
  logical AND of the results of the given check function applied to the beginning and the end of the range (as available).

## ◆ isDateQuery()

static OFBool DcmAttributeMatching::isDateQuery | ( | const void * | queryData,
|  | const size_t | querySize
| ) |  |
| static

Check whether the given query data conforms to the VR DA.

Parameters

  queryData | a pointer to some data.
  querySize | the size (in bytes) of the data queryData refers to.

Returns
  OFTrue if the query is a valid Date or Date Range, OFFalse otherwise.

## ◆ isDateTimeQuery()

static OFBool DcmAttributeMatching::isDateTimeQuery | ( | const void * | queryData,
|  | const size_t | querySize
| ) |  |
| static

Check whether the given query data conforms to the VR DT.

Parameters

  queryData | a pointer to some data.
  querySize | the size (in bytes) of the data queryData refers to.

Returns
  OFTrue if the query is a valid Date Time or Date Time Range, OFFalse otherwise.

## ◆ isTimeQuery()

static OFBool DcmAttributeMatching::isTimeQuery | ( | const void * | queryData,
|  | const size_t | querySize
| ) |  |
| static

Check whether the given query data conforms to the VR TM.

Parameters

  queryData | a pointer to some data.
  querySize | the size (in bytes) of the data queryData refers to.

Returns
  OFTrue if the query is a valid Time or Time Range, OFFalse otherwise.

## ◆ listOfUIDMatching()

static OFBool DcmAttributeMatching::listOfUIDMatching | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static

Match the query list of UIDs with the candidate UID.

Parameters

  queryData | a pointer to a character string that contains a backslash separated list of UIDs.
  querySize | the size (in bytes) of the string queryData refers to.
  candidateData | a pointer to a character string that contains an UID.
  candidateSize | the size (in bytes) of the string candidateData refers to.

Returns
  OFTrue if at least one of the UIDs from the query match the candidate, OFFalse otherwise.

If querySize equals zero, the result will be OFTrue, as appropriate for Universal Matching.

## ◆ operator OFBool()

DcmAttributeMatching::operator OFBool | ( |  | ) | const

Test whether this object may be used for matching, i.e. whether it is not empty.

Returns
  OFTrue if this object may be used for matching, OFFalse otherwise.

## ◆ operator!()

OFBool DcmAttributeMatching::operator! | ( |  | ) | const

Test whether this object cannot be used for matching, i.e. whether it is empty.

Returns
  OFTrue if this object cannot be used for matching, OFFalse otherwise.

## ◆ operator()()

OFBool DcmAttributeMatching::operator() | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  | const

Match the given query and candidate using the internally stored matching function.

Parameters

  queryData | a pointer some DICOM data that uses the same VR that was given during construction of this object.
  querySize | the size (in bytes) of the data queryData refers to.
  candidateData | a pointer to some DICOM data that used the same VR that was given during construction of this object.
  candidateSize | the size (in bytes) of the data candidateData refers to.

Returns
  compares the query data with the candidate data using the appropriate matching function for the given VR, returns OFTrue if they match, OFFalse if not or if an error occurred.

Precondition
  (*this) must have been constructed for a specific VR that matches the one of the query and candidate data, i.e. !(*this) must evaluate to OFFalse.

### Usage Example

DcmAttributeMatching match( EVR_DA );
match( "20160101-20181231", 17, "20170713", 8 ); // -> OFTrue
match = DcmAttributeMatching( EVR_TM );
match( "-12", 3, "11", 2 ) // -> OFTrue
DcmAttributeMatching( EVR_PN )( "M?ller", 6, "^Martin", 7 ) // -> OFFalse
DcmAttributeMatching
A class that implements the different kinds attribute matching.
Definition: dcmatch.h:41
DcmAttributeMatching::DcmAttributeMatching
DcmAttributeMatching()
Default construct an empty DcmAttributeMatching object.
EVR_TM
@ EVR_TM
time string
Definition: dcvr.h:198
EVR_DA
@ EVR_DA
date string
Definition: dcvr.h:135
EVR_PN
@ EVR_PN
person name
Definition: dcvr.h:177

## ◆ rangeMatchingDate()

static OFBool DcmAttributeMatching::rangeMatchingDate | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static

Match the query date or date range and the candidate date.

Parameters

  queryData | a pointer to a character string that contains a DICOM Date (DA) or a date range.
  querySize | the size (in bytes) of the string queryData refers to.
  candidateData | a pointer to a character string that contains a DICOM Date (DA).
  candidateSize | the size (in bytes) of the string candidateData refers to.

Returns
  OFTrue if the query and the candidate match, OFFalse otherwise.

If querySize equals zero, the result will be OFTrue, as appropriate for Universal Matching. Otherwise query will be converted to an OFDate or a range defined by two OFDates and candidate will be converted to an OFDate. It will then be tested whether the candidate date lies within the range given by the query or is equal to the queried date as appropriate. If the conversion to OFDate is unsuccessful for any of the dates, the result will be OFFalse.

## ◆ rangeMatchingDateTime() [1/2]

static OFBool DcmAttributeMatching::rangeMatchingDateTime | ( | const void * | dateQueryData,
|  | const size_t | dateQuerySize,
|  | const void * | timeQueryData,
|  | const size_t | timeQuerySize,
|  | const void * | dateCandidateData,
|  | const size_t | dateCandidateSize,
|  | const void * | timeCandidateData,
|  | const size_t | timeCandidateSize
| ) |  |
| static

Match the query date and time or date and time range and the candidate date and time using combined datetime matching.

Parameters

  dateQueryData | a pointer to a character string that contains a DICOM Date (DA) or a date range.
  dateQuerySize | the size (in bytes) of the string dateQueryData refers to.
  timeQueryData | a pointer to a character string that contains a DICOM Time (TM) or a time range.
  timeQuerySize | the size (in bytes) of the string timeQueryData refers to.
  dateCandidateData | a pointer to a character string that contains a DICOM Date (DA).
  dateCandidateSize | the size (in bytes) of the string dateCandidateData refers to.
  timeCandidateData | a pointer to a character string that contains a DICOM Time (TM).
  timeCandidateSize | the size (in bytes) of the string timeCandidateData refers to.

Returns
  OFTrue if the query and the candidate match, OFFalse otherwise.

If dateQuerySize and timeQuerySize equal zero, the result will be OFTrue, as appropriate for Universal Matching. Otherwise the query will be converted to an OFDateTime or a range defined by two OFDateTimes and candidate will be converted to an OFDateTime as defined by combined datetime matching. It will then be tested whether the candidate date time lies within the range given by the query or is equal to the queried date time as appropriate. If the conversion to OFDateTime is unsuccessful for any of the dates or times, the result will be OFFalse.

## ◆ rangeMatchingDateTime() [2/2]

static OFBool DcmAttributeMatching::rangeMatchingDateTime | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static

Match the query date time or date time range and the candidate date time.

Parameters

  queryData | a pointer to a character string that contains a DICOM Date Time (DT) or a date time range.
  querySize | the size (in bytes) of the string queryData refers to.
  candidateData | a pointer to a character string that contains a DICOM Date Time (DT).
  candidateSize | the size (in bytes) of the string candidateData refers to.

Returns
  OFTrue if the query and the candidate match, OFFalse otherwise.

If querySize equals zero, the result will be OFTrue, as appropriate for Universal Matching. Otherwise query will be converted to an OFDateTime or a range defined by two OFDateTimes and candidate will be converted to an OFDateTime. It will then be tested whether the candidate date time lies within the range given by the query or is equal to the queried date time as appropriate. If the conversion to OFDateTime is unsuccessful for any of the date times, the result will be OFFalse.

## ◆ rangeMatchingTemplate() [1/2]

template<typename T >

static OFBool DcmAttributeMatching::rangeMatchingTemplate | ( | OFCondition(*)(const char *, const size_t, T &) | parse,
|  | const Range & | query,
|  | const T & | candidate
| ) |  |
| static private

Helper template function for generically implementing range matching.

Template Parameters

  T | the type to parse the data int (e.g. OFDate), deduced automatically.

Parameters

  parse | a pointer to a function that parses a string as a T.
  query | the already separated (but not parsed) query.
  candidate | the already parsed candidate.

Returns
  OFTrue if parsing of the query was successful and candidate equals the query value or lies within the range defined by the query. OFFalse otherwise.

## ◆ rangeMatchingTemplate() [2/2]

template<typename T >

static OFBool DcmAttributeMatching::rangeMatchingTemplate | ( | OFCondition(*)(const char *, const size_t, T &) | parse,
|  | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static private

Helper template function for generically implementing range matching.

Template Parameters

  T | the type to parse the data int (e.g. OFDate), deduced automatically.

Parameters

  parse | a pointer to a function that parses a string as a T.
  queryData | a pointer to a character string that can be parsed as a T or a dash separated range of two Ts.
  querySize | the size (in bytes) of the string queryData refers to.
  candidateData | a pointer to a character string that can be parsed as a T for comparing it with the query.
  candidateSize | the size (in bytes) of the string candidateData refers to.

Returns
  OFTrue if parsing of the query and the candidate as a T was successful and the T value represented by candidateData equals the one from the query or lies within the range defined by the query. OFFalse otherwise.

## ◆ rangeMatchingTime()

static OFBool DcmAttributeMatching::rangeMatchingTime | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static

Match the query time or time range and the candidate time.

Parameters

  queryData | a pointer to a character string that contains a DICOM Time (TM) or a time range.
  querySize | the size (in bytes) of the string queryData refers to.
  candidateData | a pointer to a character string that contains a DICOM Time (TM).
  candidateSize | the size (in bytes) of the string candidateData refers to.

Returns
  OFTrue if the query and the candidate match, OFFalse otherwise.

If querySize equals zero, the result will be OFTrue, as appropriate for Universal Matching. Otherwise query will be converted to an OFTime or a range defined by two OFTimes and candidate will be converted to an OFTime. It will then be tested whether the candidate time lies within the range given by the query or is equal to the queried time as appropriate. If the conversion to OFTime is unsuccessful for any of the times, the result will be OFFalse.

## ◆ singleValueMatching()

static OFBool DcmAttributeMatching::singleValueMatching | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static

Match the query data and the candidate using Single Value Matching, as defined by the DICOM standard.

Parameters

  queryData | a pointer to some data.
  querySize | the size (in bytes) of the data queryData refers to.
  candidateData | a pointer to some data.
  candidateSize | the size (in bytes) of the data candidateData refers to.

Returns
  OFTrue if the query and the candidate match, OFFalse otherwise.

If querySize equals zero, the result will be OFTrue, as appropriate for Universal Matching. Otherwise the result will only be OFTrue if both data pieces have the same size are bitwise equal.

## ◆ wildCardMatching()

static OFBool DcmAttributeMatching::wildCardMatching | ( | const void * | queryData,
|  | const size_t | querySize,
|  | const void * | candidateData,
|  | const size_t | candidateSize
| ) |  |
| static

Match the query and the candidate string using Wild Card Matching, as defined by the DICOM standard.

Parameters

  queryData | a pointer to a character string potentially containing Wild Card characters.
  querySize | the size (in bytes) of the string queryData refers to.
  candidateData | a pointer to a character string.
  candidateSize | the size (in bytes) of the string candidateData refers to.

Returns
  OFTrue if the query and the candidate match, OFFalse otherwise.

If querySize equals zero, the result will be OFTrue, as appropriate for Universal Matching. If the query contains no Wild Card characters ('?' and '*') the result will be the same as if singleValueMatching() was called.

Note
  It is therefore not necessary to check for Wild Card characters and manually decided whether to use wildCardMatching() or singleValueMatching(), simply use wildCardMatching() if the query may potentially contain Wild Card characters.

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

- dcmdata/include/dcmtk/dcmdata/dcmatch.h

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