DcmByteString Class Reference

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

Inheritance diagram for DcmByteString:

DcmElement DcmObject DcmAgeString DcmApplicationEntity DcmCharString DcmCodeString DcmDate DcmDateTime DcmDecimalString DcmIntegerString DcmTime DcmUniqueIdentifier List of all members.

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 getString (char *&stringVal)
 get a pointer to the current string value.
virtual OFCondition putString (const char *stringVal)
 set element value from the given character string
virtual OFCondition putOFStringArray (const OFString &stringVal)
 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 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.
virtual OFCondition makeMachineByteString ()
 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.
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 Types

enum  E_StringMode { DCM_MachineString, DCM_DicomString, DCM_UnknownString }
 internal type used to specify the current string representation More...

Private Attributes

char paddingChar
 padding character used to adjust odd value length (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

Definition at line 42 of file dcbytstr.h.

Member Enumeration Documentation

enum DcmByteString::E_StringMode [private]

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

Definition at line 46 of file dcbytstr.h.

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

Referenced by clone().

DcmByteString::DcmByteString ( const DcmByteString &  old  ) 

copy constructor

Parameters:
old element to be copied

Member Function Documentation

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

assignment operator

Parameters:
obj element to be assigned/copied
Returns:
reference to this object

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

clone method

Returns:
deep copy of this object

Implements DcmObject.

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

Definition at line 85 of file dcbytstr.h.

References DcmByteString().

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, DcmApplicationEntity, DcmAgeString, DcmCodeString, DcmDate, DcmDecimalString, DcmDateTime, DcmIntegerString, DcmLongString, DcmLongText, DcmPersonName, DcmShortString, DcmShortText, DcmTime, DcmUniqueIdentifier, and DcmUnlimitedText.

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

get element type identifier

Returns:
type identifier of this class (EVR_UNKNOWN)

Implements DcmObject.

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

virtual OFCondition DcmByteString::clear (  )  [virtual]

clear the currently stored value

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

Reimplemented from DcmElement.

Referenced by DVPSStoredPrint::clearInstanceUID().

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

get value multiplicity

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

Implements DcmObject.

Reimplemented in DcmLongText, DcmShortText, and DcmUnlimitedText.

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 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.

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::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.

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 DcmApplicationEntity, DcmCodeString, DcmDate, DcmDecimalString, DcmDateTime, DcmIntegerString, DcmLongString, DcmLongText, DcmPersonName, DcmShortString, DcmShortText, DcmTime, and DcmUnlimitedText.

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::putString ( const char *  stringVal  )  [virtual]

set element value from the given character string

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::putOFStringArray ( const OFString &  stringVal  )  [virtual]

set element value from the given character string.

Parameters:
stringVal input character string (possibly multi-valued)
Returns:
status, EC_Normal if successful, an error code otherwise

Reimplemented from DcmElement.

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.

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

check if this element contains non-ASCII characters

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 OFBool DcmByteString::isAffectedBySpecificCharacterSet (  )  const [virtual]

check if this element is affected by SpecificCharacterSet

Returns:
always returns false

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.

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.

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 OFCondition DcmByteString::makeMachineByteString (  )  [protected, virtual]

convert currently stored string value to internal representation.

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

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

Reimplemented in DcmUniqueIdentifier.

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

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

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

set the end-of-string padding character

Parameters:
c end-of-string padding character

Definition at line 267 of file dcbytstr.h.

References paddingChar.

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

Definition at line 272 of file dcbytstr.h.

References maxLength.

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

Definition at line 277 of file dcbytstr.h.

References nonSignificantChars.

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. (valid values: "1", "1-2", "1-3", "1-8", "1-99", "1-n", "2", "2-n", "2-2n", "3", "3-n", "3-3n", "4", "6", "9", "16", "32" or "" 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

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

Generated on 6 Jan 2011 for OFFIS DCMTK Version 3.6.0 by Doxygen 1.5.1