A class to store attribute values for DICOM metadata. More...

#include <vtkDICOMValue.h>

Public Member Functions
	vtkDICOMValue (vtkDICOMVR vr, double v)
	Construct a new value from the data that is provided. More...

	vtkDICOMValue (vtkDICOMVR vr, const std::string &v)

	vtkDICOMValue (vtkDICOMVR vr, vtkDICOMTag v)

	vtkDICOMValue (vtkDICOMVR vr, const vtkDICOMItem &v)

	vtkDICOMValue (vtkDICOMVR vr, const char *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const unsigned char *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const short *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const unsigned short *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const int *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const unsigned int *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const long long *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const unsigned long long *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const float *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const double *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const vtkDICOMTag *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, const vtkDICOMItem *data, size_t count)

	vtkDICOMValue (vtkDICOMVR vr, vtkDICOMCharacterSet cs, const std::string &v)
	Construct a string value with a specific character set. More...

	vtkDICOMValue (vtkDICOMVR vr, vtkDICOMCharacterSet cs, const char *data, size_t l)

	vtkDICOMValue (vtkDICOMVR vr)
	Create an empty value.

	vtkDICOMValue (const vtkDICOMValue &v)
	Copy constructor.

	vtkDICOMValue (vtkDICOMTag v)
	Construct from a tag.

	vtkDICOMValue (const vtkDICOMItem &v)
	Construct from an item.

	vtkDICOMValue (const vtkDICOMSequence &v)
	Construct from a sequence.

	vtkDICOMValue ()
	Default constructor, constructs an invalid value.

	~vtkDICOMValue ()
	Destructor releases the internal data array.

void	Clear ()
	Clear the value, the result is an invalid value.

bool	IsValid () const
	Check whether this value is valid, i.e. contains data.

vtkDICOMVR	GetVR () const
	Get the VR, the representation of the data values.

unsigned int	GetVL () const
	Get the VL, the length of the data in bytes (will always be even).

vtkDICOMCharacterSet	GetCharacterSet () const
	Get the character set for a text value. More...

size_t	GetNumberOfValues () const
	Get the value multiplicity. More...

void	GetValues (std::string *vb, size_t n, size_t i=0) const
	Copy "n" values into vb, starting at value "i". More...

void	GetValues (unsigned char *vb, size_t n, size_t i=0) const

void	GetValues (short *vb, size_t n, size_t i=0) const

void	GetValues (unsigned short *vb, size_t n, size_t i=0) const

void	GetValues (int *vb, size_t n, size_t i=0) const

void	GetValues (unsigned int *vb, size_t n, size_t i=0) const

void	GetValues (long long *vb, size_t n, size_t i=0) const

void	GetValues (unsigned long long *vb, size_t n, size_t i=0) const

void	GetValues (float *vb, size_t n, size_t i=0) const

void	GetValues (double *vb, size_t n, size_t i=0) const

void	GetValues (vtkDICOMTag *vb, size_t n, size_t i=0) const

std::string	GetUTF8String (size_t i) const
	Get one scalar, string, tag or item from the value. More...

std::string	GetString (size_t i) const

unsigned char	GetUnsignedChar (size_t i) const

short	GetShort (size_t i) const

unsigned short	GetUnsignedShort (size_t i) const

int	GetInt (size_t i) const

unsigned int	GetUnsignedInt (size_t i) const

long long	GetInt64 (size_t i) const

unsigned long long	GetUnsignedInt64 (size_t i) const

float	GetFloat (size_t i) const

double	GetDouble (size_t i) const

vtkDICOMTag	GetTag (size_t i) const

const vtkDICOMItem &	GetItem (size_t i) const

std::string	AsUTF8String () const
	Get the value as a scalar, string, tag, or item. More...

std::string	AsString () const

unsigned char	AsUnsignedChar () const

short	AsShort () const

unsigned short	AsUnsignedShort () const

int	AsInt () const

unsigned int	AsUnsignedInt () const

long long	AsInt64 () const

unsigned long long	AsUnsignedInt64 () const

float	AsFloat () const

double	AsDouble () const

vtkDICOMTag	AsTag () const

const vtkDICOMItem &	AsItem () const

const char *	GetCharData () const
	Get a pointer to the internal data array. More...

const unsigned char *	GetUnsignedCharData () const

const short *	GetShortData () const

const unsigned short *	GetUnsignedShortData () const

const int *	GetIntData () const

const unsigned int *	GetUnsignedIntData () const

const long long *	GetInt64Data () const

const unsigned long long *	GetUnsignedInt64Data () const

const float *	GetFloatData () const

const double *	GetDoubleData () const

const vtkDICOMTag *	GetTagData () const

const vtkDICOMItem *	GetSequenceData () const

const vtkDICOMValue *	GetMultiplexData () const

char *	AllocateCharData (vtkDICOMVR vr, size_t vn)
	Allocate space within a value object. More...

char *	AllocateCharData (vtkDICOMVR vr, vtkDICOMCharacterSet cs, size_t vn)

unsigned char *	AllocateUnsignedCharData (vtkDICOMVR vr, size_t vn)

short *	AllocateShortData (vtkDICOMVR vr, size_t vn)

unsigned short *	AllocateUnsignedShortData (vtkDICOMVR vr, size_t vn)

int *	AllocateIntData (vtkDICOMVR vr, size_t vn)

unsigned int *	AllocateUnsignedIntData (vtkDICOMVR vr, size_t vn)

long long *	AllocateInt64Data (vtkDICOMVR vr, size_t vn)

unsigned long long *	AllocateUnsignedInt64Data (vtkDICOMVR vr, size_t vn)

float *	AllocateFloatData (vtkDICOMVR vr, size_t vn)

double *	AllocateDoubleData (vtkDICOMVR vr, size_t vn)

vtkDICOMTag *	AllocateTagData (vtkDICOMVR vr, size_t vn)

vtkDICOMItem *	AllocateSequenceData (vtkDICOMVR vr, size_t vn)

vtkDICOMValue *	AllocateMultiplexData (vtkDICOMVR vr, size_t vn)

void	ComputeNumberOfValuesForCharData ()
	Compute the number of backslash-separated string values. More...

unsigned char *	ReallocateUnsignedCharData (size_t vn)
	Reallocate data of type OB or UN. More...

void	AppendValueToUTF8String (std::string &str, size_t i) const
	Append value "i" to the supplied UTF8 string.

void	AppendValueToSafeUTF8String (std::string &str, size_t i) const
	Append value "i" to the supplied UTF8 string for safe printing.

void	AppendValueToString (std::string &str, size_t i) const
	Append value "i" to the supplied string. More...

bool	Matches (const vtkDICOMValue &value) const
	Check if the value matches the specified find query value. More...

bool	Matches (const std::string &v) const
	Check if the value is equal to the specified string. More...

bool	Matches (double v) const
	Check if the value is the specified numeric value. More...

vtkDICOMValue &	operator= (const vtkDICOMValue &o)
	Override assignment operator for reference counting.

vtkDICOMValue &	operator= (const vtkDICOMSequence &o)
	Assign a value from a sequence object.

bool	operator== (const vtkDICOMValue &o) const
	Equality requires that all elements of the value are equal.

bool	operator!= (const vtkDICOMValue &o) const

Static Public Member Functions
static vtkDICOMValue	FromUTF8String (vtkDICOMVR vr, vtkDICOMCharacterSet cs, const std::string &v)
	Create a value from a UTF8-encoded string. More...

Friends
class	vtkDICOMSequence

class	vtkDICOMValueFriendMetaData

Detailed Description

A class to store attribute values for DICOM metadata.

The vtkDICOMValue class is a container for any values that can be stored in a DICOM data element. Like std::string, it is implemented as a pointer to a reference-counted internal data object. To keep it lightweight, in terms of size, it has no virtual methods.

Constructor & Destructor Documentation

◆ vtkDICOMValue() [1/2]

vtkDICOMValue::vtkDICOMValue	(	vtkDICOMVR	vr,
		double	v
	)

Construct a new value from the data that is provided.

The data will be copied into the value, with conversion if necessary. If the data cannot be converted into the type required by the VR, then the resulting value will be invalid.

For these VRs, always use these types:

OB (other byte) or UN (unknown), use unsigned char.
OW, use either unsigned short or signed short.
AT, use an array of vtkDICOMTag values.
SQ, use an array of vtkDICOMItem values.

◆ vtkDICOMValue() [2/2]

vtkDICOMValue::vtkDICOMValue	(	vtkDICOMVR	vr,
		vtkDICOMCharacterSet	cs,
		const std::string &	v
	)

Construct a string value with a specific character set.

This will set the character set that will be used to interpret the data inside the string value. The character set parameter will be ignored unless the the VR is PN, SH, LO, ST, LT, or UT, since all other VRs are restricted to ASCII.

Member Function Documentation

◆ AllocateCharData()

char* vtkDICOMValue::AllocateCharData	(	vtkDICOMVR	vr,
		size_t	vn
	)

Allocate space within a value object.

Allocate an array of the specified size (number of elements) within the value object. This method will not do any checks to ensure that the data type matches the VR. It is meant to be an efficient way for the parser to allocate a value so that the value's contents can be read in directly from a file.

◆ AppendValueToString()

void vtkDICOMValue::AppendValueToString	(	std::string &	str,
		size_t	i
	)		const

Append value "i" to the supplied string.

This will convert the value to human-readable format. Be cautious when using this method for an element with VR equal to ST, LT, or UT, because the resulting string might be very long, and might contain special (i.e. non-printable) characters.

◆ AsUTF8String()

std::string vtkDICOMValue::AsUTF8String ( ) const

Get the value as a scalar, string, tag, or item.

The value is converted to the desired type, if possible, and returned. Otherwise the return value is zero (or an empty string). Conversion to string always produces an empty string for values of type UN, SQ, OB, OW, and OF. Trailing spaces are always removed from strings. Leading spaces are removed unless the VR is ST, LT, or UT.

◆ ComputeNumberOfValuesForCharData()

void vtkDICOMValue::ComputeNumberOfValuesForCharData ( )

Compute the number of backslash-separated string values.

After calling AllocateCharData and writing text into the allocated space, this must be called to set the NumberOfValues according to the number of backslash-separated string values that are present.

◆ FromUTF8String()

static vtkDICOMValue vtkDICOMValue::FromUTF8String	(	vtkDICOMVR	vr,
		vtkDICOMCharacterSet	cs,
		const std::string &	v
	)

static

Create a value from a UTF8-encoded string.

This will convert a UTF-8 string to the target encoding and store the result in a new value. If the target encoding is ISO 2022, then escape codes will be added before and after delimiters as necessary (the delimiters are 'backslash' for multi-valued VRs, and '^', '=' for PN).

◆ GetCharacterSet()

vtkDICOMCharacterSet vtkDICOMValue::GetCharacterSet ( ) const

inline

Get the character set for a text value.

String values are stored with their original encoding, as given by the SpecificCharacterSet attribute of the data set that they belong to. This only applies to VRs of PN, SH, LO, ST, LT, and UT. All other string values are always stored as plain ASCII with no control characters.

◆ GetCharData()

const char* vtkDICOMValue::GetCharData ( ) const

Get a pointer to the internal data array.

GetCharData will return a null-terminated string if VR is AE, AS, CS, DA, DS, DT, IS, LO, LT, PN, SH, ST, TM, UI, UT, with a possible trailing space if the VR is not UI (UID). The other methods will return a valid pointer if the the requested pointer type matches the VR. To compute the size of the array, divide VL by the size of the requested type. Do not use NumberOfValues as the array size, because for many VRs the array size is much larger than the NumberOfValues, in fact for OB, OF, UT, and many other VRs the entire array counts as a single value, according to the DICOM standard. Returns NULL if the requested pointer type does not match the VR.

◆ GetNumberOfValues()

size_t vtkDICOMValue::GetNumberOfValues ( ) const

inline

Get the value multiplicity.

The number of values has different interpretations for for different VRs:

for backslash-delimited text (AE, AS, CS, DA, DS, DT, IS, LO, PN, SH, UI) it is the number of backslash-separated values.
for other text (LT, ST, UT) the number of values is always 1.
for binary numerical data (FL, FD, SS, US, SL, UL, OF, OW, OB) the number of binary values will be returned.
for UN, the number of bytes will be returned.
for attribute tags (VR is AT) the number of tags will be returned.
for sequences (SQ) the number of items in the sequence, excluding any delimiters, will be returned.

◆ GetUTF8String()

std::string vtkDICOMValue::GetUTF8String ( size_t i ) const

Get one scalar, string, tag or item from the value.

Convert the i'th value to the desired type, if possible, and return it. If the value is invalid, or conversion is not possible, or the index is out of range, then the return value will be zero (or an empty string). Trailing spaces are always removed from strings. Leading spaces are removed unless the VR is ST, LT, or UT.

◆ GetValues()

void vtkDICOMValue::GetValues	(	std::string *	vb,
		size_t	n,
		size_t	i = `0`
	)		const

Copy "n" values into vb, starting at value "i".

Get one or more values, doing conversion from the stored type to the requested type. If the VR is IS or DS (integer string or decimal string) then conversion from text to a numerical value will be performed.

◆ Matches() [1/3]

bool vtkDICOMValue::Matches ( const std::string & v ) const

Check if the value is equal to the specified string.

Note that matches to an empty string will always succeed due to the universal matching rule. To check if a value is empty, you should instead check to see if its VL is zero. Padding spaces will automatically be stripped before the comparison is done. The character set of the string is assumed to be the same as the character set of the value that is being matched. This method can be used to match numerical values in addition to text values.

◆ Matches() [2/3]

bool vtkDICOMValue::Matches ( const vtkDICOMValue & value ) const

Check if the value matches the specified find query value.

This method is used during "find" requests, according to the rules of DICOM Part 4 C.2.2.2 Attribute Matching. The standard wildcards "*" and "?" are supported, as well as numeric ranges (for times and dates) through the use of two values separated by "-". Matches are case sensitive, except when the VR is PN. If the value has multiplicity, then the match will succeed if any of the values match.

◆ Matches() [3/3]

bool vtkDICOMValue::Matches ( double v ) const

Check if the value is the specified numeric value.

This will return true only if the value has a numeric representation (e.g. has a VR of IS, DS, US, UL, SS, SL, FL, FD) and is equal to the specified number. If the value multiplicity is greater than one, then the match is true if at least one value matches.

◆ ReallocateUnsignedCharData()

unsigned char* vtkDICOMValue::ReallocateUnsignedCharData ( size_t vn )

Reallocate data of type OB or UN.

Values of type OB or UN can hold encapsulated data. When building these values, it is useful to be able to extend the internal data as needed. After this method is called, the NumberOfValues will be vn, and the VL will be 0xffffffff.

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

vtkDICOMValue.h

Public Member Functions

Static Public Member Functions

Friends