/*

 *

 *  Copyright (C) 1994-2026, OFFIS e.V.

 *  All rights reserved.  See COPYRIGHT file for details.

 *

 *  This software and supporting documentation were developed by

 *

 *    OFFIS e.V.

 *    R&D Division Health

 *    Escherweg 2

 *    D-26121 Oldenburg, Germany

 *

 *

 *  Module:  dcmdata

 *

 *  Author:  Gerd Ehlers

 *

 *  Purpose: Interface of class DcmItem

 *

 */

#ifndef DCITEM_H

#define DCITEM_H

#include "dcmtk/config/osconfig.h"    /* make sure OS specific configuration is included first */

#include "dcmtk/ofstd/offile.h"       /* for offile_off_t */

#include "dcmtk/dcmdata/dctypes.h"

#include "dcmtk/dcmdata/dcobject.h"

#include "dcmtk/dcmdata/dclist.h"

#include "dcmtk/dcmdata/dcpcache.h"

// forward declarations

class DcmElement;

class DcmJsonFormat;

class DcmSequenceOfItems;

class DcmSpecificCharacterSet;

/** a class representing a list of DICOM elements in which each

 *  element has a different tag and elements are maintained in

 *  increasing order of tags. In particular, a sequence item.

 */

class DCMTK_DCMDATA_EXPORT DcmItem

  : public DcmObject

{

  public:

    // be friend with "greater than" and "less than" operators that are defined

    // outside of this class

    friend OFBool operator< (const DcmItem& lhs, const DcmItem& rhs);

    friend OFBool operator> (const DcmItem& lhs, const DcmItem& rhs);

    friend OFBool operator<=(const DcmItem& lhs, const DcmItem& rhs);

    friend OFBool operator>=(const DcmItem& lhs, const DcmItem& rhs);

    /** default constructor

     */

    DcmItem();

    /** constructor.

     *  Create new item from given tag and length.

     *  @param tag DICOM tag for the new element

     *  @param len value length for the new element

     */

    DcmItem(const DcmTag &tag,

            const Uint32 len = 0);

    /** copy constructor

     *  @param old item to be copied

     */

    DcmItem(const DcmItem &old);

    /** assignment operator. Private creator cache is not copied

     *  as it is also the case for clone().

     *  @param obj the item to be copied

     *  @return Reference to this object after assignment

     */

    DcmItem &operator=(const DcmItem &obj);

    /** comparison operator that compares the value of this object

     *  with a given object of the same type. The tag of the element is also

     *  considered as the first component that is compared, followed by the

     *  object types (VR, i.e. DCMTK'S EVR) and the comparison of all value

     *  components of the object, preferably in the order declared in the

     *  object (if applicable). For item values that means that all elements

     *  within the items are compared to each other in ascending tag order.

     *  This may be an expensive operation.

     *  @param  rhs the right hand side of the comparison

     *  @return 0 if the object values are equal.

     *          -1 if this element has fewer components than the rhs element.

     *          Also -1 if the value of the first component that does not match

     *          is lower in this object than in rhs. Also returned if rhs

     *          cannot be casted to this object type or both objects are of

     *          different VR (i.e. the DcmEVR returned by the element's ident()

     *          call are different).

     *          1 if either this element has more components than the rhs

     *          element, or if the first component that does not match is

     *          greater in this object than in rhs object.

     */

    virtual int compare(const DcmItem& rhs) const;

    /** destructor

     */

    virtual ~DcmItem();

    /** clone method

     *  @return deep copy of this object

     */

    virtual DcmObject *clone() const

    {

      return new DcmItem(*this);

    }

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

     *  @param rhs - [in] The instance to copy from. Has to be of the same

     *                class type as "this" object

     *  @return EC_Normal if copying was successful, error otherwise

     */

    virtual OFCondition copyFrom(const DcmObject& rhs);

    /** get type identifier

     *  @return type identifier of this class (EVR_item)

     */

    virtual DcmEVR ident() const;

    /** get value multiplicity

     *  @return always returns 1 (according to the DICOM standard)

     */

    virtual unsigned long getVM();

    /** get number of values (elements) stored in this item.

     *  The result is the same as card() unless overwritten in a derived class.

     *  @return number of elements in this item

     */

    virtual unsigned long getNumberOfValues();

    /** get cardinality of this item

     *  @return number of elements in this item

     */

    virtual unsigned long card() const;

    /** check if this element is a leaf node in a dataset tree.

     *  All subclasses of DcmElement except for DcmSequenceOfItems

     *  are leaf nodes, while DcmSequenceOfItems, DcmItem, DcmDataset etc.

     *  are not.

     *  @return true if leaf node, false otherwise.

     */

    virtual OFBool isLeaf() const { return OFFalse; }

    /** check if this item is nested in a sequence of items, i.e.\ not a

     *  top-level or stand-alone item/dataset

     *  @return true if this item is nested, false otherwise

     */

    virtual OFBool isNested() const;

    /** print all elements of the item to a stream

     *  @param out output stream

     *  @param flags optional flag used to customize the output (see DCMTypes::PF_xxx)

     *  @param level current level of nested items. Used for indentation.

     *  @param pixelFileName not used

     *  @param pixelCounter not used

     */

    virtual void print(STD_NAMESPACE ostream &out,

                       const size_t flags = 0,

                       const int level = 0,

                       const char *pixelFileName = NULL,

                       size_t *pixelCounter = NULL);

    /** @copydoc DcmObject::calcElementLength()

     */

    virtual Uint32 calcElementLength(const E_TransferSyntax xfer,

                                     const E_EncodingType enctype);

    /** calculate the value length (without attribute tag, VR and length field)

     *  of this DICOM element when encoded with the given transfer syntax and

     *  the given encoding type for sequences.

     *  If length encoding is set to be explicit and the item content is larger

     *  than the available 32-bit length field, then undefined length is

     *  returned. If "dcmWriteOversizedSeqsAndItemsUndefined" is disabled,

     *  also the internal DcmObject errorFlag is set to

     *  EC_SeqOrItemContentOverflow.

     *  @param xfer transfer syntax for length calculation

     *  @param enctype sequence encoding type for length calculation

     *  @return value length of DICOM element

     */

    virtual Uint32 getLength(const E_TransferSyntax xfer = EXS_LittleEndianImplicit,

                             const E_EncodingType enctype = EET_UndefinedLength);

    /** initialize the transfer state of this object. This method must be called

     *  before this object is written to a stream or read (parsed) from a stream.

     */

    virtual void transferInit();

    /** finalize the transfer state of this object. This method must be called

     *  when reading/writing this object from/to a stream has been completed.

     */

    virtual void transferEnd();

    /** get parent item of this object, i.e.\ the item/dataset in which the

     *  surrounding sequence element is stored.

     *  @return pointer to the parent item of this object (might be NULL)

     */

    virtual DcmItem *getParentItem();

    /** check if this DICOM object can be encoded in the given transfer syntax.

     *  @param newXfer transfer syntax in which the DICOM object is to be encoded

     *  @param oldXfer transfer syntax in which the DICOM object was read or created.

     *  @return true if object can be encoded in desired transfer syntax, false otherwise.

     */

    virtual OFBool canWriteXfer(const E_TransferSyntax newXfer,

                                const E_TransferSyntax oldXfer);

    /** This function reads the information of all attributes which

     *  are captured in the input stream and captures this information

     *  in elementList. Each attribute is represented as an element

     *  in this list. If not all information for an attribute could be

     *  read from the stream, the function returns EC_StreamNotifyClient.

     *  @param inStream      The stream which contains the information.

     *  @param ixfer         The transfer syntax which was used to encode

     *                       the information in inStream.

     *  @param glenc         Encoding type for group length; specifies

     *                       what will be done with group length tags.

     *  @param maxReadLength Maximum read length for reading an attribute value.

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition read(DcmInputStream &inStream,

                             const E_TransferSyntax ixfer,

                             const E_GrpLenEncoding glenc = EGL_noChange,

                             const Uint32 maxReadLength = DCM_MaxReadLength);

    /** This function reads the information of all attributes which

     *  are captured in the input stream and captures this information

     *  in elementList, up to the attribute tag stopParsingAtElement.

     *  Each attribute is represented as an element

     *  in this list. If not all information for an attribute could be

     *  read from the stream, the function returns EC_StreamNotifyClient.

     *  @param inStream      The stream which contains the information.

     *  @param ixfer         The transfer syntax which was used to encode

     *                       the information in inStream.

     *  @param glenc         Encoding type for group length; specifies

     *                       what will be done with group length tags.

     *  @param maxReadLength Maximum read length for reading an attribute value.

     *  @param stopParsingAtElement parsing of the input stream is stopped when

     *                       this tag key or any higher tag is encountered.

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition readUntilTag(DcmInputStream &inStream,

                                     const E_TransferSyntax ixfer,

                                     const E_GrpLenEncoding glenc = EGL_noChange,

                                     const Uint32 maxReadLength = DCM_MaxReadLength,

                                     const DcmTagKey &stopParsingAtElement = DCM_UndefinedTagKey);

    /** write object to a stream

     *  @param outStream DICOM output stream

     *  @param oxfer output transfer syntax

     *  @param enctype encoding types (undefined or explicit length)

     *  @param wcache pointer to write cache object, may be NULL

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition write(DcmOutputStream &outStream,

                              const E_TransferSyntax oxfer,

                              const E_EncodingType enctype,

                              DcmWriteCache *wcache);

    /** write object in XML format

     *  @param out output stream to which the XML document is written

     *  @param flags optional flag used to customize the output (see DCMTypes::XF_xxx)

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition writeXML(STD_NAMESPACE ostream &out,

                                 const size_t flags = 0);

    /** write object in JSON format

     *  @param out output stream to which the JSON document is written

     *  @param format used to format and customize the output

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition writeJson(STD_NAMESPACE ostream &out,

                                  DcmJsonFormat &format);

    /** write object in JSON format and control whether the output

     *  is encapsulated in braces

     *  @param out output stream to which the JSON document is written

     *  @param format used to format and customize the output

     *  @param printBraces true if output should be encapsulated in braces

     *  @param printNewline true if a newline should be printed after a closing brace

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition writeJsonExt(STD_NAMESPACE ostream &out,

                                  DcmJsonFormat &format,

                                  OFBool printBraces,

                                  OFBool printNewline);

    /** special write method for creation of digital signatures

     *  @param outStream DICOM output stream

     *  @param oxfer output transfer syntax

     *  @param enctype encoding types (undefined or explicit length)

     *  @param wcache pointer to write cache object, may be NULL

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition writeSignatureFormat(DcmOutputStream &outStream,

                                             const E_TransferSyntax oxfer,

                                             const E_EncodingType enctype,

                                             DcmWriteCache *wcache);

    /** returns true if the object contains an element with Unknown VR at any nesting level

     *  @return true if the object contains an element with Unknown VR, false otherwise

     */

    virtual OFBool containsUnknownVR() const;

    /** check if this object contains non-ASCII characters at any nesting level. 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.

     *  @param checkAllStrings if true, also check elements with string values not affected

     *    by SpecificCharacterSet (0008,0005). By default, only check PN, LO, LT, SH, ST,

     *    UC and UT.

     *  @return true if object contains non-ASCII characters, false otherwise

     */

    virtual OFBool containsExtendedCharacters(const OFBool checkAllStrings = OFFalse);

    /** check if this object is affected by SpecificCharacterSet at any nesting level.

     *  In detail, it is checked whether this object contains any data elements that

     *  according to their VR are affected by the SpecificCharacterSet (0008,0005)

     *  element. This is true for the following VRs: PN, LO, LT, SH, ST, UC and UT

     *  @return true if object is affected by SpecificCharacterSet, false otherwise

     */

    virtual OFBool isAffectedBySpecificCharacterSet() const;

    /** mode specifying whether the SpecificCharacterSet (0008,0005) element should be

     *  checked by convertCharacterSet() or not, i.e.\ whether this element might be

     *  present on this dataset-level. This method is reimplemented in derived classes.

     *  @return always returns OFFalse, i.e.\ SpecificCharacterSet should not be checked

     */

    virtual OFBool checkForSpecificCharacterSet() const { return OFFalse; }

    /** convert all element values that are contained in this item and that are affected

     *  by SpecificCharacterSet from the given source character set to the given

     *  destination character set. The defined terms for a particular character set can

     *  be found in the DICOM standard, e.g. "ISO_IR 100" for ISO 8859-1 (Latin 1) or

     *  "ISO_IR 192" for Unicode in UTF-8. An empty string denotes the default character

     *  repertoire, which is ASCII (7-bit). If multiple values are given for 'fromCharset'

     *  (separated by a backslash) code extension techniques are used and escape sequences

     *  may be encountered in the source string to switch between the specified character

     *  sets.

     *  @note The conversion code does not perform a thorough validation of the strings to

     *    be converted. For example, characters that are permitted in the source character

     *    set but forbidden in DICOM (such as byte positions 0x80-0x9F in ISO_IR 100) may

     *    be converted without warning or error.

     *  @param fromCharset name of the source character set(s) used for the conversion

     *  @param toCharset name of the destination character set used for the conversion.

     *    Only a single value is permitted (i.e. no code extensions).

     *  @param flags optional flag used to customize the conversion (see DCMTypes::CF_xxx)

     *  @param updateCharset if OFTrue, the SpecificCharacterSet (0008,0005) element is

     *    updated, i.e.\ the current value is either replaced or a new element is inserted

     *    or the existing element is deleted. If OFFalse the SpecificCharacterSet element

     *    remains unchanged.

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition convertCharacterSet(const OFString &fromCharset,

                                            const OFString &toCharset,

                                            const size_t flags = 0,

                                            const OFBool updateCharset = OFFalse);

    /** convert all element values that are contained in this item and that are affected

     *  by SpecificCharacterSet to the given destination character set. If not disabled,

     *  the source character set is determined automatically from the value of the

     *  SpecificCharacterSet (0008,0005) element. The defined terms for the destination

     *  character set can be found in the DICOM standard, e.g. "ISO_IR 100" for ISO 8859-1

     *  (Latin 1) or "ISO_IR 192" for Unicode in UTF-8. An empty string denotes the

     *  default character repertoire, which is ASCII (7-bit).

     *  @note The conversion code does not perform a thorough validation of the strings to

     *    be converted. For example, characters that are permitted in the source character

     *    set but forbidden in DICOM (such as byte positions 0x80-0x9F in ISO_IR 100) may

     *    be converted without warning or error.

     *  @param toCharset name of the destination character set used for the conversion.

     *    Only a single value is permitted (i.e. no code extensions).

     *  @param flags optional flag used to customize the conversion (see DCMTypes::CF_xxx)

     *  @param ignoreCharset if OFTrue, the value of SpecificCharacterSet is ignored,

     *    otherwise the element value is updated. Also see checkForSpecificCharacterSet().

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition convertCharacterSet(const OFString &toCharset,

                                            const size_t flags = 0,

                                            const OFBool ignoreCharset = OFFalse);

    /** convert all element values that are contained in this item and that are affected

     *  by SpecificCharacterSet from the currently selected source character set to the

     *  currently selected destination character set.

     *  @note The conversion code does not perform a thorough validation of the strings to

     *    be converted. For example, characters that are permitted in the source character

     *    set but forbidden in DICOM (such as byte positions 0x80-0x9F in ISO_IR 100) may

     *    be converted without warning or error.

     *  @param converter character set converter to be used to convert the element values

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition convertCharacterSet(DcmSpecificCharacterSet &converter);

    /** convert all element values that are contained in this item and that are affected

     *  by SpecificCharacterSet to UTF-8 (Unicode). The value of the SpecificCharacterSet

     *  (0008,0005) element is updated, set or deleted automatically if needed. The

     *  transliteration mode is disabled, i.e. the conversion flags are explicitly set to

     *  0 - see convertCharacterSet().

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition convertToUTF8();

    /** update the SpecificCharacterSet (0008,0005) element depending on the given

     *  parameters. The current value of this element is either replaced or a new

     *  element is inserted or the existing element is deleted.

     *  @note This method is called by convertCharacterSet() and convertToUTF8() when

     *    needed, so there is usually no reason to call it directly.

     *  @param status error status of previous operations (might also be updated)

     *  @param converter character set converter used to convert element values

     */

    virtual void updateSpecificCharacterSet(OFCondition &status,

                                            const DcmSpecificCharacterSet &converter);

    /** insert a new element into the list of elements maintained by this item.

     *  The list of elements is always kept in ascending tag order.

     *  @param elem element to be inserted, must not be contained in this or

     *    any other item.  Will be deleted upon destruction of this item object.

     *  @param replaceOld if true, this element replaces any other element with

     *    the same tag which may already be contained in the item.  If false,

     *    insert fails if another element with the same tag is already present.

     *  @param checkInsertOrder if true, a warning message is sent to the console

     *    if the element is not inserted at the end of the list.  This is used

     *    in the read() method to detect datasets with out-of-order elements.

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition insert(DcmElement *elem,

                               OFBool replaceOld = OFFalse,

                               OFBool checkInsertOrder = OFFalse);

    /** access an element from the item. This method returns a pointer to one

     *  of the elements in the item, and not a copy.

     *  @param num index number of element, must be < card()

     *  @return pointer to element if found, NULL if num >= card()

     */

    virtual DcmElement *getElement(const unsigned long num);

    /** this method enables a stack based, depth-first traversal of a complete

     *  hierarchical DICOM dataset (that is, classes derived from DcmItem or

     *  DcmSequenceOfItems). With each call of this method, the next object

     *  in the tree is located and marked on the stack.

     *  @param stack "cursor" for current position in the dataset. The stack

     *    will contain a pointer to each dataset, sequence, item and element

     *    from the main dataset down to the current element, and is updated

     *    upon each call to this method. An empty stack is equivalent to a stack

     *    containing a pointer to this object only.

     *  @param intoSub if true, the nextObject method will perform a hierarchical

     *    search through the dataset (depth-first), if false, only the current

     *    container object will be traversed (e.g., all elements of an item

     *    or all items of a sequence).

     *  @return EC_Normal if value length is correct, an error code otherwise

     */

    virtual OFCondition nextObject(DcmStack &stack,

                                   const OFBool intoSub);

    /** this method is only used in container classes,

     *  that is, DcmItem and DcmSequenceOfItems. It returns a pointer to the

     *  next object in the list AFTER the given object. If the caller passes NULL,

     *  a pointer to the first object in the list is returned. If the given object

     *  is not found, the given object is the last one in the list or the list is

     *  empty, NULL is returned.

     *  @param obj pointer to one object in the container; we are looking for the

     *    next entry after this one. NULL if looking for the first entry.

     *  @return pointer to next object in container or NULL if not found

     */

    virtual DcmObject *nextInContainer(const DcmObject *obj);

    /** remove element from list. If found, the element is not deleted but

     *  returned to the caller who is responsible for further management of the

     *  DcmElement object.

     *  @param num index number of element, must be < card()

     *  @return pointer to DcmElement if found, NULL otherwise

     */

    virtual DcmElement *remove(const unsigned long num);

    /** remove element from list. If found, the element is not deleted but

     *  returned to the caller who is responsible for further management of the

     *  DcmElement object.

     *  @param elem pointer to element (as type DcmObject *) to be removed from list

     *  @return pointer to element (as type DcmElement *) if found, NULL otherwise

     */

    virtual DcmElement *remove(DcmObject *elem);

    /** remove element from list. If found, the element is not deleted but

     *  returned to the caller who is responsible for further management of the

     *  DcmElement object.

     *  @param tag attribute tag of element to be removed

     *  @return pointer to DcmElement if found, NULL otherwise

     */

    virtual DcmElement *remove(const DcmTagKey &tag);

    /** check if this item is empty

     *  @param normalize not used for this class

     *  @return true if item is empty, i.e.\ has no elements, false otherwise

     */

    virtual OFBool isEmpty(const OFBool normalize = OFTrue);

    /** clear (remove) all attributes from item and delete them from memory.

     *  @return EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition clear();

    /** check the currently stored element value

     *  @param autocorrect correct value length if OFTrue

     *  @return status, EC_Normal if value length is correct, an error code otherwise

     */

    virtual OFCondition verify(const OFBool autocorrect = OFFalse );

    /** a complex, stack-based, hierarchical search method. It allows for a search

     *  for a DICOM object with a given attribute within a given container,

     *  hierarchically, from a starting position identified through a cursor stack.

     *  @param xtag the DICOM attribute tag we are searching for

     *  @param resultStack Depending on the search mode (see below), this parameter

     *     either serves as an input and output parameter, or as an output parameter

     *     only (the latter being the default). When used as an input parameter,

     *     the cursor stack defines the start position for the search within a

     *     hierarchical DICOM dataset. Upon successful return, the stack contains

     *     the position of the element found, in the form of a pointer to each dataset,

     *     sequence, item and element from the main dataset down to the found element.

     *  @param mode search mode, controls how the search stack is handled.

     *     In the default mode, ESM_fromHere, the stack is ignored on input, and

     *     the search starts in the object for which this method is called.

     *     In the other modes, the stack is used both as an input and an output

     *     parameter and defines the starting point for the search.

     *  @param searchIntoSub if true, the search will be performed hierarchically descending

     *    into the sequences and items of the dataset. If false, only the current container

     *    (sequence or item) will be traversed.

     *  @return EC_Normal if found, EC_TagNotFound if not found, an error code is something

     *    went wrong.

     */

    virtual OFCondition search(const DcmTagKey &xtag,              // in

                               DcmStack &resultStack,              // inout

                               E_SearchMode mode = ESM_fromHere,   // in

                               OFBool searchIntoSub = OFTrue );    // in

    /** this method loads all attribute values maintained by this object and

     *  all sub-objects (in case of a container such as DcmDataset) into memory.

     *  After a call to this method, the file from which a dataset was read may safely

     *  be deleted or replaced. For large files, this method may obviously allocate large

     *  amounts of memory.

     *  @return EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition loadAllDataIntoMemory();

    /** iterate over all elements and remove those element values from memory which exceed

     *  a given length and which can be loaded from file when needed again. For all other

     *  elements, nothing is done.

     *  @param maxLength maximum length (number of bytes) allowed without removing the value

     */

    virtual void compactElements(const Uint32 maxLength);

    /** This function takes care of group length and padding elements

     *  in the current element list according to what is specified in

     *  glenc and padenc. If required, this function does the following

     *  two things:

     *    a) it calculates the group length of all groups which are

     *       contained in this item and sets the calculated values

     *       in the corresponding group length elements and

     *    b) it inserts a corresponding padding element (or, in case

     *       of sequences: padding elements) with a corresponding correct

     *       size into the element list.

     *  @param glenc          Encoding type for group length; specifies what shall

     *                        be done with group length tags.

     *  @param padenc         Encoding type for padding; specifies what shall be

     *                        done with padding tags.

     *  @param xfer           The transfer syntax that shall be used.

     *  @param enctype        Encoding type for sequences; specifies how sequences

     *                        will be handled.

     *  @param padlen         The length up to which the dataset shall be padded,

     *                        if padding is desired.

     *  @param subPadlen      For sequences (i.e. sub elements), the length up to

     *                        which item shall be padded, if padding is desired.

     *  @param instanceLength Number of extra bytes added to the item/dataset

     *                        length used when computing the padding; this

     *                        parameter is for instance used to pass the length

     *                        of the file meta header from the DcmFileFormat to

     *                        the DcmDataset object.

     *  @return status, EC_Normal if successful, an error code otherwise

     */

    virtual OFCondition computeGroupLengthAndPadding(const E_GrpLenEncoding glenc,

                                                     const E_PaddingEncoding padenc = EPD_noChange,

                                                     const E_TransferSyntax xfer = EXS_Unknown,

                                                     const E_EncodingType enctype = EET_ExplicitLength,

                                                     const Uint32 padlen = 0,

                                                     const Uint32 subPadlen = 0,

                                                     Uint32 instanceLength = 0);

    /** check if an element with the given attribute tag exists in the dataset

     *  @param key tag key to be searched

     *  @param searchIntoSub if true, do hierarchical search within sequences,

     *    if false only search through this dataset

     *  @return true if tag found, false otherwise

     */

    OFBool tagExists(const DcmTagKey &key,

                     OFBool searchIntoSub = OFFalse);

    /** check if an element with the given attribute tag exists in the dataset

     *  and has a non-empty value

     *  @param key tag key to be searched

     *  @param searchIntoSub if true, do hierarchical search within sequences,

     *    if false only search through this dataset

     *  @return true if tag found and element non-empty, false otherwise

     */

    OFBool tagExistsWithValue(const DcmTagKey &key,

                              OFBool searchIntoSub = OFFalse);

    /* --- findAndGet functions: find an element and get it or the value, respectively --- */

    /** find element and get a pointer to it (or copy it).

     *  The result variable 'element' is automatically set to NULL if an error occurs.

     *  @note Applicable to all DICOM value representations (VR).

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param element variable in which the reference to (or copy of) the element is stored

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @param createCopy create a copy of the element if true, return a reference otherwise

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetElement(const DcmTagKey &tagKey,

                                  DcmElement *&element,

                                  const OFBool searchIntoSub = OFFalse,

                                  const OFBool createCopy = OFFalse);

    /** find all elements matching a particular tag and return references to them on a stack.

     *  This functions always performs a deep search (i.e. searches into sequence of items).

     *  @note Applicable to all DICOM value representations (VR).

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param resultStack stack where references to the elements are stored (added to).

     *    If no element is found, the stack is not modified (e.g. cleared).

     *  @return EC_Normal if at least one matching tag is found, an error code otherwise.

     */

    OFCondition findAndGetElements(const DcmTagKey &tagKey,

                                   DcmStack &resultStack);

    /** find element and get value as a reference to a C string. NB: The string is not copied!

     *  Since the getString() routine is called internally the resulting string reference represents

     *  the (possibly multi-valued) value as stored in the dataset, i.e. no normalization is performed.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: AE, AS, CS, DA, DS, DT, IS, LO, LT, PN, SH, ST, TM,

     *    UC, UI, UR, UT.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored (might be NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetString(const DcmTagKey &tagKey,

                                 const char *&value,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a reference to a C string. NB: The string is not copied!

     *  Since the getString() routine is called internally the resulting string reference represents

     *  the (possibly multi-valued) value as stored in the dataset, i.e. no normalization is performed.

     *  The result variable 'value' is automatically set to NULL and 'length' is set to 0 if an error

     *  occurs.

     *  Please note that since the length is returned separately, the string value can contain more

     *  than one NULL byte.

     *  @note Applicable to the following VRs: AE, AS, CS, DA, DS, DT, IS, LO, LT, PN, SH, ST, TM,

     *    UC, UI, UR, UT.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored (might be NULL)

     *  @param length length of the string (number of characters without the trailing NULL byte)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetString(const DcmTagKey &tagKey,

                                 const char *&value,

                                 Uint32 &length,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a C++ string (only one component).

     *  Since the getOFString() routine is called internally the resulting string is normalized, i.e.

     *  leading and/or trailing spaces are removed according to the associated value representation,

     *  or the element value is converted to a character string (for non-string VRs) - see documentation

     *  in the corresponding header file.

     *  In contrast to the above and below function only the specified component (see parameter 'pos')

     *  is returned. The result variable 'value' is automatically set to an empty string if an error

     *  occurs.

     *  @note Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD,

     *    OF, OL, OV, OW, PN, SH, SL, SS, ST, SV, TM, UC, UI, UL, UR, US, UT, UV.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetOFString(const DcmTagKey &tagKey,

                                   OFString &value,

                                   const unsigned long pos = 0,

                                   const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a C++ string (all components).

     *  Since the getOFStringArray() routine is called internally the resulting string is normalized,

     *  i.e. leading and/or trailing spaces are removed according to the associated value representation

     *  or the element values are converted to character strings (for non-string VRs) - see documentation

     *  in the corresponding header file.

     *  The result variable 'value' is automatically set to an empty string if an error occurs.

     *  @note Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB, OD,

     *    OF, OL, OV, OW, PN, SH, SL, SS, ST, SV, TM, UC, UI, UL, UR, US, UT, UV.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetOFStringArray(const DcmTagKey &tagKey,

                                        OFString &value,

                                        const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an unsigned 8-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: OB.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint8(const DcmTagKey &tagKey,

                                Uint8 &value,

                                const unsigned long pos = 0,

                                const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of unsigned 8-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: OB.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint8Array(const DcmTagKey &tagKey,

                                     const Uint8 *&value,

                                     unsigned long *count = NULL,

                                     const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an unsigned 16-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: OW, US.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint16(const DcmTagKey &tagKey,

                                 Uint16 &value,

                                 const unsigned long pos = 0,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of unsigned 16-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: AT, OW, US.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint16Array(const DcmTagKey &tagKey,

                                      const Uint16 *&value,

                                      unsigned long *count = NULL,

                                      const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a signed 16-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: SS.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetSint16(const DcmTagKey &tagKey,

                                 Sint16 &value,

                                 const unsigned long pos = 0,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of signed 16-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: SS.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetSint16Array(const DcmTagKey &tagKey,

                                      const Sint16 *&value,

                                      unsigned long *count = NULL,

                                      const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an unsigned 32-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: OL, UL.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint32(const DcmTagKey &tagKey,

                                 Uint32 &value,

                                 const unsigned long pos = 0,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of unsigned 32-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: OL, UL.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint32Array(const DcmTagKey &tagKey,

                                      const Uint32 *&value,

                                      unsigned long *count = NULL,

                                      const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a signed 32-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: IS, SL.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetSint32(const DcmTagKey &tagKey,

                                 Sint32 &value,

                                 const unsigned long pos = 0,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of signed 32-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: SL.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetSint32Array(const DcmTagKey &tagKey,

                                      const Sint32 *&value,

                                      unsigned long *count = NULL,

                                      const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an unsigned 64-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: OV, UV.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint64(const DcmTagKey &tagKey,

                                 Uint64 &value,

                                 const unsigned long pos = 0,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of unsigned 64-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: OV, UV.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetUint64Array(const DcmTagKey &tagKey,

                                      const Uint64 *&value,

                                      unsigned long *count = NULL,

                                      const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a signed 64-bit integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: SV.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetSint64(const DcmTagKey &tagKey,

                                 Sint64 &value,

                                 const unsigned long pos = 0,

                                 const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of signed 64-bit integers.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: SV.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetSint64Array(const DcmTagKey &tagKey,

                                      const Sint64 *&value,

                                      unsigned long *count = NULL,

                                      const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a (signed) long integer.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: IS, OL, SL, SS, UL, US.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetLongInt(const DcmTagKey &tagKey,

                                  long int &value,

                                  const unsigned long pos = 0,

                                  const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a 32-bit floating point.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: FL, OF.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetFloat32(const DcmTagKey &tagKey,

                                  Float32 &value,

                                  const unsigned long pos = 0,

                                  const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of 32-bit floating point values.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: FL, OF.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetFloat32Array(const DcmTagKey &tagKey,

                                       const Float32 *&value,

                                       unsigned long *count = NULL,

                                       const OFBool searchIntoSub = OFFalse);

    /** find element and get value as a 64-bit floating point.

     *  The result variable 'value' is automatically set to zero if an error occurs.

     *  @note Applicable to the following VRs: DS, FD, OD.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the element value is stored

     *  @param pos index of the value in case of multi-valued elements (0..vm-1)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetFloat64(const DcmTagKey &tagKey,

                                  Float64 &value,

                                  const unsigned long pos = 0,

                                  const OFBool searchIntoSub = OFFalse);

    /** find element and get value as an array of 64-bit floating point values.

     *  The result variable 'value' is automatically set to NULL if an error occurs.

     *  @note Applicable to the following VRs: FD, OD.

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param value variable in which the reference to the element value is stored

     *  @param count stores number of items in the result array (if not NULL)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndGetFloat64Array(const DcmTagKey &tagKey,

                                       const Float64 *&value,

                                       unsigned long *count = NULL,

                                       const OFBool searchIntoSub = OFFalse);

    /** looks up and returns a given sequence.

     *  The result variable 'sequence' is automatically set to NULL if an error occurs

     *  (e.g. if 'seqTagKey' does not refer to a sequence attribute).

     *  @note Applicable to the following VRs: SQ, (pixelSQ).

     *  @param seqTagKey DICOM tag specifying the sequence attribute to be searched for

     *  @param sequence variable in which the reference to (or copy of) the sequence is stored

     *  @param searchIntoSub flag indicating whether to search into sub-sequences or not

     *  @param createCopy create a copy of the sequence if true, return a reference otherwise

     *  @return EC_Normal upon success, an error otherwise.

     */

    OFCondition findAndGetSequence(const DcmTagKey &seqTagKey,

                                   DcmSequenceOfItems *&sequence,

                                   const OFBool searchIntoSub = OFFalse,

                                   const OFBool createCopy = OFFalse);

    /** looks up and returns a given sequence item, if it exists. Otherwise sets 'item'

     *  to NULL and returns EC_TagNotFound (specified sequence does not exist) or

     *  EC_IllegalParameter (specified item does not exist). Only the top-most level of

     *  the dataset/item is examined (i.e. no deep-search is performed).

     *  Please note that an instance of the DcmPixelItem class cannot be retrieved.

     *  @note Applicable to the following VRs: SQ, (pixelSQ).

     *  @param seqTagKey DICOM tag specifying the sequence attribute to be searched for

     *  @param item variable in which the reference to (or copy of) the item is stored

     *  @param itemNum number of the item to be searched for (0..n-1, -1 for last)

     *  @param createCopy create a copy of the item if true, return a reference otherwise

     *  @return EC_Normal upon success, an error otherwise.

     */

    OFCondition findAndGetSequenceItem(const DcmTagKey &seqTagKey,

                                       DcmItem *&item,

                                       const signed long itemNum = 0,

                                       const OFBool createCopy = OFFalse);

    /* --- findOrCreate functions: find an element or create a new one --- */

    /** looks up the given sequence in the current dataset and returns the given item.

     *  If either the sequence or the item do not exist, they are created. If necessary,

     *  multiple empty items are inserted. Only the top-most level of the dataset/item

     *  is examined (i.e. no deep-search is performed).

     *  Please note that an instance of the DcmPixelItem class cannot be retrieved or

     *  created.

     *  @note Applicable to the following VRs: SQ, (pixelSQ).

     *  @param seqTag DICOM tag specifying the sequence attribute to be searched for

     *    (or to be created)

     *  @param item variable in which the reference to the sequence item is stored

     *  @param itemNum number of the item to be searched for (0..n-1, -1 for last,

     *    -2 for append new)

     *  @return EC_Normal upon success, an error otherwise.

     */

    OFCondition findOrCreateSequenceItem(const DcmTag &seqTag,

                                         DcmItem *&item,

                                         const signed long itemNum = 0);

    /* --- findAndXXX functions: find an element and do something with it --- */

    /** find element, create a copy and insert it into the given destination dataset.

     *  This functions never performs a deep search (i.e. does not search into sequence

     *  of items). Empty elements are also copied. However, if the given tag is not

     *  found in the current dataset, EC_TagNotFound is returned and the destination

     *  dataset remains unchanged.

     *  @note Applicable to all DICOM value representations (VR).

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param destItem destination dataset to which the copied element is inserted

     *  @param replaceOld flag indicating whether to replace an existing element or not

     *  @return EC_Normal upon success, an error code otherwise

     */

    OFCondition findAndInsertCopyOfElement(const DcmTagKey &tagKey,

                                           DcmItem *destItem,

                                           const OFBool replaceOld = OFTrue);

    /** find element, remove it from the dataset and free the associated memory.

     *  @note Applicable to all DICOM value representations (VR).

     *  @param tagKey DICOM tag specifying the attribute to be searched for

     *  @param allOccurrences flag indicating whether to delete all occurrences of the

     *    attribute tag or the first one only (implies 'searchIntoSub' to be true)

     *  @param searchIntoSub flag indicating whether to search into sequences or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition findAndDeleteElement(const DcmTagKey &tagKey,

                                     const OFBool allOccurrences = OFFalse,

                                     const OFBool searchIntoSub = OFFalse);

    /** looks up the given sequence in the current dataset and deletes the given item.

     *  @note Applicable to the following VRs: SQ, (pixelSQ).

     *  @param seqTagKey DICOM tag specifying the sequence attribute to be searched for

     *  @param itemNum number of the item to be deleted (0..n-1, -1 for last)

     *  @return EC_Normal upon success, an error otherwise.

     */

    OFCondition findAndDeleteSequenceItem(const DcmTagKey &seqTagKey,

                                          const signed long itemNum);

    /* --- putAndInsert functions: put value and insert new element --- */

    /** create a new element, put specified value to it and insert the element into the dataset/item.

     *  @note Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB,

     *    OD, OF, OL, OV, OW, PN, SH, SL, SS, ST, SV, TM, UC, UI, UL, UR, US, UT, UV.

     *  @param tag DICOM tag specifying the attribute to be created

     *  @param value string value to be set for the new element (might be empty or NULL).  The format

     *    of the string value is specified by the putString() method of the corresponding VR class.

     *  @param replaceOld flag indicating whether to replace an existing element or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition putAndInsertString(const DcmTag &tag,

                                   const char *value,

                                   const OFBool replaceOld = OFTrue);

    /** create a new element, put specified value to it and insert the element into the dataset/item.

     *  Please note that since the length of the string has to be specified explicitly, the string

     *  can contain more than one NULL byte.

     *  @note Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB,

     *    OD, OF, OL, OV, OW, PN, SH, SL, SS, ST, SV, TM, UC, UI, UL, UR, US, UT, UV.

     *  @param tag DICOM tag specifying the attribute to be created

     *  @param value string value to be set for the new element (might be empty or NULL).  The format

     *    of the string value is specified by the putString() method of the corresponding VR class.

     *  @param length length of the string (number of characters without the trailing NULL byte)

     *  @param replaceOld flag indicating whether to replace an existing element or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition putAndInsertString(const DcmTag &tag,

                                   const char *value,

                                   const Uint32 length,

                                   const OFBool replaceOld = OFTrue);

    /** create a new element, put specified value to it and insert the element into the dataset/item.

     *  @note Applicable to the following VRs: AE, AS, AT, CS, DA, DS, DT, FL, FD, IS, LO, LT, OB,

     *    OD, OF, OL, OV, OW, PN, SH, SL, SS, ST, SV, TM, UC, UI, UL, UR, US, UT, UV.

     *  @param tag DICOM tag specifying the attribute to be created

     *  @param value string value to be set for the new element (might be empty).  The format of the

     *    string value is specified by the putOFStringArray() method of the corresponding VR class.

     *  @param replaceOld flag indicating whether to replace an existing element or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition putAndInsertOFStringArray(const DcmTag &tag,

                                          const OFString &value,

                                          const OFBool replaceOld = OFTrue);

    /** create a new element, put specified value to it and insert the element into the dataset/item.

     *  @note Applicable to the following VRs: OB, ox (polymorph OB/OW), px (pixel data).

     *  @param tag DICOM tag specifying the attribute to be created

     *  @param value value to be set for the new element (might be NULL)

     *  @param count number of values (= bytes in this case) to be copied from 'value'

     *  @param replaceOld flag indicating whether to replace an existing element or not

     *  @return EC_Normal upon success, an error code otherwise.

     */

    OFCondition putAndInsertUint8Array(const DcmTag &tag,

                                       const Uint8 *value,

                                       const unsigned long count,

                                       const OFBool replaceOld = OFTrue);

    /** create a new element, put specified value to it and insert the element into the dataset/item.

     *  @note Applicable to the following VRs: US, xs (US or SS).

     *  @param tag DICOM tag specifying the attribute to be created