base class for all DICOM value representations storing a character string More...

Inheritance diagram for DcmByteString:

Public Member Functions
	DcmByteString (const DcmTag &tag, const Uint32 len=0)
	constructor.
	DcmByteString (const DcmByteString &old)
	copy constructor
virtual	~DcmByteString ()
	destructor
DcmByteString &	operator= (const DcmByteString &obj)
	assignment operator
virtual DcmObject *	clone () const
	clone method
virtual OFCondition	copyFrom (const DcmObject &rhs)
	Virtual object copying.
virtual DcmEVR	ident () const
	get element type identifier
virtual OFCondition	clear ()
	clear the currently stored value
virtual unsigned long	getVM ()
	get value multiplicity
Uint32	getRealLength ()
	get length of the stored value.
virtual Uint32	getLength (const E_TransferSyntax xfer=EXS_LittleEndianImplicit, const E_EncodingType enctype=EET_UndefinedLength)
	get DICOM length of the stored value.
virtual void	print (STD_NAMESPACE ostream &out, const size_t flags=0, const int level=0, const char pixelFileName=NULL, size_t pixelCounter=NULL)
	print element to a stream.
virtual OFCondition	write (DcmOutputStream &outStream, const E_TransferSyntax oxfer, const E_EncodingType enctype, DcmWriteCache *wcache)
	write data element to a stream
virtual OFCondition	writeSignatureFormat (DcmOutputStream &outStream, const E_TransferSyntax oxfer, const E_EncodingType enctype, DcmWriteCache *wcache)
	write data element to a stream as required for the creation of digital signatures
virtual OFCondition	getOFString (OFString &stringVal, const unsigned long pos, OFBool normalize=OFTrue)
	get a copy of a particular string component
virtual OFCondition	getOFStringArray (OFString &stringVal, OFBool normalize=OFTrue)
	get entire element value as a character string.
virtual OFCondition	getString (char *&stringVal)
	get a pointer to the current string value.
virtual OFCondition	getString (char *&stringVal, Uint32 &stringLen)
	get a pointer to the current string value.
virtual OFCondition	putString (const char *stringVal)
	set element value from the given character string.
virtual OFCondition	putString (const char *stringVal, const Uint32 stringLen)
	set element value from the given character string.
virtual OFCondition	verify (const OFBool autocorrect=OFFalse)
	check the currently stored string value.
virtual OFBool	containsExtendedCharacters (const OFBool checkAllStrings=OFFalse)
	check if this element contains non-ASCII characters.
virtual OFBool	isAffectedBySpecificCharacterSet () const
	check if this element is affected by SpecificCharacterSet
virtual OFBool	isEmpty (const OFBool normalize=OFTrue)
	check if this object is empty
Protected Types
enum	E_StringMode { DCM_MachineString, DCM_DicomString, DCM_UnknownString }
	internal type used to specify the current string representation More...
Protected Member Functions
virtual Uint8 *	newValueField ()
	create a new value field (string buffer) of the previously defined size (member variable 'Length').
virtual void	postLoadValue ()
	method is called after the element value has been loaded.
E_StringMode	getStringMode () const
	get current representation of the string value
virtual OFCondition	makeMachineByteString (const Uint32 length=0)
	convert currently stored string value to internal representation.
OFCondition	makeDicomByteString ()
	convert currently stored string value to DICOM representation.
OFCondition	getStringValue (OFString &stringVal)
	get a copy of the current string value.
Uint32	getMaxLength () const
	get the maximum number of characters for each string component
char	getPaddingChar () const
	get the end-of-string padding character
void	setPaddingChar (char c)
	set the end-of-string padding character
void	setMaxLength (Uint32 val)
	set the maximum number of characters for each string component
void	setNonSignificantChars (const OFString &characters)
	set non-significant characters used to determine whether the value is empty
Static Protected Member Functions
static OFCondition	checkStringValue (const OFString &value, const OFString &vm, const OFString &vr, const int vrID, const size_t maxLen=0)
	check whether given string value conforms to a certain VR and VM.
Private Attributes
char	paddingChar
	padding character used to adjust odd value length (e.g. a space)
Uint32	maxLength
	maximum number of characters for each string component
Uint32	realLength
	number of characters of the internal string representation
E_StringMode	fStringMode
	current representation of the string value
OFString	nonSignificantChars
	non-significant characters used to determine whether the value is empty

Detailed Description

base class for all DICOM value representations storing a character string

Member Enumeration Documentation

enum DcmByteString::E_StringMode [protected]

internal type used to specify the current string representation

Enumerator:

DCM_MachineString	string has internal representation (no padding)
DCM_DicomString	string has DICOM representation (even length)
DCM_UnknownString	string has unknown representation (maybe multiple padding chars?)

Constructor & Destructor Documentation

DcmByteString::DcmByteString	(	const DcmTag &	tag,
		const Uint32	len = `0`
	)

constructor.

Create new element from given tag and length.

Parameters:

tag	DICOM tag for the new element
len	value length for the new element

DcmByteString::DcmByteString ( const DcmByteString & old )

copy constructor

Parameters:

old	element to be copied

Member Function Documentation

static OFCondition DcmByteString::checkStringValue	(	const OFString &	value,
		const OFString &	vm,
		const OFString &	vr,
		const int	vrID,
		const size_t	maxLen = `0`
	)		`[static, protected]`

check whether given string value conforms to a certain VR and VM.

Parameters:

value	string value to be checked (possibly multi-valued)
vm	value multiplicity (according to the data dictionary) to be checked for. (See DcmElement::checkVM() for a list of valid values; "" for no check.)
vr	two-character identifier of the VR to be checked (lower case)
vrID	expected numeric identifier of the VR
maxLen	maximum number of characters allowed for a single value (0 = no check)

Returns:: status of the check, EC_Normal if value is correct, an error code otherwise

virtual OFCondition DcmByteString::clear ( ) [virtual]

clear the currently stored value

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

virtual DcmObject* DcmByteString::clone ( ) const [inline, virtual]

clone method

Returns:: deep copy of this object

Implements DcmObject.

Reimplemented in DcmCharString, DcmDecimalString, DcmTime, DcmApplicationEntity, DcmAgeString, DcmCodeString, DcmDate, DcmDateTime, DcmLongString, DcmPersonName, DcmShortString, DcmIntegerString, DcmShortText, DcmUniqueIdentifier, DcmUnlimitedText, and DcmLongText.

virtual OFBool DcmByteString::containsExtendedCharacters ( const OFBool checkAllStrings = OFFalse ) [virtual]

check if this element contains non-ASCII characters.

Please note that this check is pretty simple and only works for single-byte character sets that do include the 7-bit ASCII codes, e.g. for the ISO 8859 family. In other words: All character codes below 128 are considered to be ASCII codes and all others are considered to be non-ASCII.

Parameters:

checkAllStrings if true, also check elements with string values not affected by SpecificCharacterSet (0008,0005), default: only check PN, LO, LT, SH, ST, UT

Returns:: true if element contains non-ASCII characters, false otherwise

Reimplemented from DcmObject.

Reimplemented in DcmCharString.

virtual OFCondition DcmByteString::copyFrom ( const DcmObject & rhs ) [virtual]

Virtual object copying.

This method can be used for DcmObject and derived classes to get a deep copy of an object. Internally the assignment operator is called if the given DcmObject parameter is of the same type as "this" object instance. If not, an error is returned. This function permits copying an object by value in a virtual way which therefore is different to just calling the assignment operator of DcmElement which could result in slicing the object.

Parameters:

rhs	- [in] The instance to copy from. Has to be of the same class type as "this" object

Returns:: EC_Normal if copying was successful, error otherwise

Reimplemented from DcmElement.

Reimplemented in DcmCharString, DcmDecimalString, DcmTime, DcmApplicationEntity, DcmAgeString, DcmCodeString, DcmDate, DcmDateTime, DcmLongString, DcmPersonName, DcmShortString, DcmIntegerString, DcmShortText, DcmUniqueIdentifier, DcmUnlimitedText, and DcmLongText.

virtual Uint32 DcmByteString::getLength	(	const E_TransferSyntax	xfer = `EXS_LittleEndianImplicit`,
		const E_EncodingType	enctype = `EET_UndefinedLength`
	)		`[virtual]`

get DICOM length of the stored value.

The string value is padded if required. Therefore, the returned length always has an even value.

Parameters:

xfer	not used
enctype	not used

Returns:: number of characters stored in DICOM representation

Reimplemented from DcmElement.

Uint32 DcmByteString::getMaxLength ( ) const [inline, protected]

get the maximum number of characters for each string component

Returns:: maximum number of characters for each string component

virtual OFCondition DcmByteString::getOFString	(	OFString &	stringVal,
		const unsigned long	pos,
		OFBool	normalize = `OFTrue`
	)		`[virtual]`

get a copy of a particular string component

Parameters:

stringVal	variable in which the result value is stored
pos	index of the value in case of multi-valued elements (0..vm-1)
normalize	not used since string normalization depends on value representation

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

Reimplemented in DcmDecimalString, DcmUniqueIdentifier, DcmUnlimitedText, DcmIntegerString, DcmShortText, DcmLongText, DcmTime, DcmApplicationEntity, DcmCodeString, DcmDate, DcmDateTime, DcmLongString, DcmPersonName, and DcmShortString.

virtual OFCondition DcmByteString::getOFStringArray	(	OFString &	stringVal,
		OFBool	normalize = `OFTrue`
	)		`[virtual]`

get entire element value as a character string.

In case of VM > 1 the individual values are separated by a backslash ('\').

Parameters:

stringVal	variable in which the result value is stored
normalize	normalize each element value prior to concatenation

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

Reimplemented in DcmUnlimitedText, DcmShortText, and DcmLongText.

char DcmByteString::getPaddingChar ( ) const [inline, protected]

get the end-of-string padding character

Returns:: end-of-string padding character

Uint32 DcmByteString::getRealLength ( )

get length of the stored value.

Trailing spaces (padding characters) are ignored for the "real" length.

Returns:: number of characters stored for the string value

virtual OFCondition DcmByteString::getString ( char *& stringVal ) [virtual]

get a pointer to the current string value.

This includes all string components and separators. NB: This method does not copy the stored value.

Parameters:

stringVal reference to the pointer variable

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

virtual OFCondition DcmByteString::getString	(	char *&	stringVal,
		Uint32 &	stringLen
	)		`[virtual]`

get a pointer to the current string value.

This includes all string components and separators. Since the length is returned separately, the string value can contain more than one NULL byte. NB: This method does not copy the stored value.

Parameters:

stringVal	reference to the pointer variable
stringLen	length of the string (number of characters without the trailing NULL byte)

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

E_StringMode DcmByteString::getStringMode ( ) const [inline, protected]

get current representation of the string value

Returns:: current representation of the string value

OFCondition DcmByteString::getStringValue ( OFString & stringVal ) [protected]

get a copy of the current string value.

This includes all string components and separators.

Parameters:

stringVal variable in which the result is stored

Returns:: status, EC_Normal if successful, an error code otherwise

virtual unsigned long DcmByteString::getVM ( ) [virtual]

get value multiplicity

Returns:: number of string components (separated by a backslash)

Implements DcmObject.

Reimplemented in DcmUnlimitedText, DcmShortText, and DcmLongText.

virtual DcmEVR DcmByteString::ident ( ) const [virtual]

get element type identifier

Returns:: type identifier of this class (EVR_UNKNOWN)

Implements DcmObject.

Reimplemented in DcmUnlimitedText, DcmDecimalString, DcmTime, DcmApplicationEntity, DcmAgeString, DcmCodeString, DcmDate, DcmDateTime, DcmLongString, DcmPersonName, DcmShortString, DcmIntegerString, DcmShortText, DcmUniqueIdentifier, and DcmLongText.

virtual OFBool DcmByteString::isAffectedBySpecificCharacterSet ( ) const [virtual]

check if this element is affected by SpecificCharacterSet

Returns:: always returns false since none of the derived VR classes is affected by the SpecificCharacterSet (0008,0005) element

Reimplemented from DcmObject.

Reimplemented in DcmCharString.

virtual OFBool DcmByteString::isEmpty ( const OFBool normalize = OFTrue ) [virtual]

check if this object is empty

Parameters:

normalize normalize value before checking (ignore non-significant characters)

Returns:: true if object is empty, i.e. has no value, false otherwise

Reimplemented from DcmObject.

OFCondition DcmByteString::makeDicomByteString ( ) [protected]

convert currently stored string value to DICOM representation.

It removes trailing spaces apart from a possibly required single padding character (in case of odd string length).

Returns:: status, EC_Normal if successful, an error code otherwise

virtual OFCondition DcmByteString::makeMachineByteString ( const Uint32 length = 0 ) [protected, virtual]

convert currently stored string value to internal representation.

It removes any trailing space character and recomputes the string length.

Parameters:

length number of characters of the string value (optional)

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented in DcmUniqueIdentifier.

virtual Uint8* DcmByteString::newValueField ( ) [protected, virtual]

create a new value field (string buffer) of the previously defined size (member variable 'Length').

Also handles odd value length by allocating extra space for the padding character. This method is used by derived classes only.

Returns:: pointer to the newly created value field

Reimplemented from DcmElement.

DcmByteString& DcmByteString::operator= ( const DcmByteString & obj )

assignment operator

Parameters:

obj	element to be assigned/copied

Returns:: reference to this object

virtual void DcmByteString::postLoadValue ( ) [protected, virtual]

method is called after the element value has been loaded.

Can be used to correct the value before it is used for the first time.

Reimplemented from DcmElement.

virtual void DcmByteString::print	(	STD_NAMESPACE ostream &	out,
		const size_t	flags = `0`,
		const int	level = `0`,
		const char *	pixelFileName = `NULL`,
		size_t *	pixelCounter = `NULL`
	)		`[virtual]`

print element to a stream.

The output format of the value is a backslash separated sequence of string components (if any).

Parameters:

out	output stream
flags	optional flag used to customize the output (see DCMTypes::PF_xxx)
level	current level of nested items. Used for indentation.
pixelFileName	not used
pixelCounter	not used

Implements DcmObject.

Reimplemented in DcmUniqueIdentifier.

virtual OFCondition DcmByteString::putString ( const char * stringVal ) [virtual]

set element value from the given character string.

The length of the given string is determined automatically by searching for the first NULL byte.

Parameters:

stringVal input character string (possibly multi-valued)

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

Reimplemented in DcmUniqueIdentifier.

virtual OFCondition DcmByteString::putString	(	const char *	stringVal,
		const Uint32	stringLen
	)		`[virtual]`

set element value from the given character string.

The length of the string has to be specified explicitly. The string can, therefore, also contain more than one NULL byte.

Parameters:

stringVal	input character string (possibly multi-valued)
stringLen	length of the string (number of characters without the trailing NULL byte)

Returns:: status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

Reimplemented in DcmUniqueIdentifier.

void DcmByteString::setMaxLength ( Uint32 val ) [inline, protected]

set the maximum number of characters for each string component

Parameters:

val	maximum number of characters for each string component

void DcmByteString::setNonSignificantChars ( const OFString & characters ) [inline, protected]

set non-significant characters used to determine whether the value is empty

Parameters:

characters non-significant characters used to determine whether the value is empty

void DcmByteString::setPaddingChar ( char c ) [inline, protected]

set the end-of-string padding character

Parameters:

c	end-of-string padding character

virtual OFCondition DcmByteString::verify ( const OFBool autocorrect = OFFalse ) [virtual]

check the currently stored string value.

Checks every string component for the maximum length specified for the particular value representation.

Parameters:

autocorrect correct value and value component length if OFTrue

Returns:: status, EC_Normal if value length is correct, an error code otherwise

Implements DcmObject.

Reimplemented in DcmCharString.

virtual OFCondition DcmByteString::write	(	DcmOutputStream &	outStream,
		const E_TransferSyntax	oxfer,
		const E_EncodingType	enctype,
		DcmWriteCache *	wcache
	)		`[virtual]`

write data element to a stream

Parameters:

outStream	output stream
oxfer	transfer syntax used to write the data
enctype	flag, specifying the encoding with undefined or explicit length
wcache	pointer to write cache object, may be NULL

Reimplemented from DcmElement.

virtual OFCondition DcmByteString::writeSignatureFormat	(	DcmOutputStream &	outStream,
		const E_TransferSyntax	oxfer,
		const E_EncodingType	enctype,
		DcmWriteCache *	wcache
	)		`[virtual]`

write data element to a stream as required for the creation of digital signatures

Parameters:

outStream	output stream
oxfer	transfer syntax used to write the data
enctype	flag, specifying the encoding with undefined or explicit length
wcache	pointer to write cache object, may be NULL

Reimplemented from DcmElement.

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

dcmdata/include/dcmtk/dcmdata/dcbytstr.h

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation