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
	)

staticprivate

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

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

staticprivate

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
	)

staticprivate

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

Classes

Public Member Functions

Static Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DcmAttributeMatching()

Member Function Documentation

◆ checkRangeQuery()

◆ isDateQuery()

◆ isDateTimeQuery()

◆ isTimeQuery()

◆ listOfUIDMatching()

◆ operator OFBool()

◆ operator!()

◆ operator()()

Usage Example

◆ rangeMatchingDate()

◆ rangeMatchingDateTime() [1/2]

◆ rangeMatchingDateTime() [2/2]

◆ rangeMatchingTemplate() [1/2]

◆ rangeMatchingTemplate() [2/2]

◆ rangeMatchingTime()

◆ singleValueMatching()

◆ wildCardMatching()