DcmCharString: add some support for multi-byte characters

- add DcmCharString::getVM() and getOFString(), which handle multi-byte charsets
- DcmByteString::containsExtendedCharacters():
  add check for ESCAPE characters (only allowed in code extensions)
- removed obsolete DcmCharString::containsExtendedCharacters()

Author: jriesmeier

.github/workflows/cmake-win.yml

@@ -33,7 +33,7 @@ jobs:
 
       # Uncompress support libraries into directory c:\dcmtk_support\libs.
       # We rename the original directory to libs so that the rest of the script
-      # can use the ame path even if the support library package is updated
+      # can use the same path even if the support library package is updated
       # in the future in the download task above.
       - name: Uncompress Support libraries
         shell: pwsh

dcmdata/include/dcmtk/dcmdata/dcbytstr.h

@@ -274,20 +274,19 @@ class DCMTK_DCMDATA_EXPORT DcmByteString: public DcmElement
      */
     virtual OFCondition verify(const OFBool autocorrect = OFFalse);
 
-    /** 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.
+    /** check if this element contains non-ASCII characters.
+     *  This works by checking for any byte values above 127, which works for any
+     *  single-byte code and for single-value multi-byte codes, and for ESC characters,
+     *  which will mean that a code extension is used.
      *  @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, i.e. none of the derived VR classes.
+     *    UC and UT.
      *  @return true if element contains non-ASCII characters, false otherwise
      */
     virtual OFBool containsExtendedCharacters(const OFBool checkAllStrings = OFFalse);
 
     /** check if this element is affected by SpecificCharacterSet
-     *  @return always returns false since none of the derived VR classes is affected by
+     *  @return returns false, overwritten by derived VR classes that are affected by
      *    the SpecificCharacterSet (0008,0005) element
      */
     virtual OFBool isAffectedBySpecificCharacterSet() const;
@@ -379,6 +378,11 @@ class DCMTK_DCMDATA_EXPORT DcmByteString: public DcmElement
      */
     virtual OFCondition makeMachineByteString(const Uint32 length = 0);
 
+    /** check if the VR supports more than one value.
+     * @return OFTrue
+     */
+    virtual OFBool supportsMultiValue() const { return OFTrue; };
+
     /** 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).
@@ -420,11 +424,10 @@ class DCMTK_DCMDATA_EXPORT DcmByteString: public DcmElement
 
     /* --- static helper functions --- */
 
-    /** check if a given character string 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.
+    /** check if this element contains non-ASCII characters.
+     *  This works by checking for any byte values above 127, which works for any
+     *  single-byte code and for single-value multi-byte codes, and for ESC characters,
+     *  which will mean that a code extension is used.
      *  @param stringVal character string to be checked
      *  @param stringLen length of the string (number of characters without the trailing
      *    NULL byte)

dcmdata/include/dcmtk/dcmdata/dcchrstr.h

@@ -107,15 +107,21 @@ class DCMTK_DCMDATA_EXPORT DcmCharString
      */
     virtual OFCondition verify(const OFBool autocorrect = OFFalse);
 
-    /** 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.
-     *  @param checkAllStrings not used in this class
-     *  @return true if element contains non-ASCII characters, false otherwise
+    /** get value multiplicity
+     *  @return number of string components (separated by a backslash)
      */
-    virtual OFBool containsExtendedCharacters(const OFBool checkAllStrings = OFFalse);
+    virtual unsigned long getVM();
+
+    /** get a copy of a particular string component
+     *  @param stringVal variable in which the result value is stored
+     *  @param pos index of the value in case of multi-valued elements (0..vm-1)
+     *  @param normalize not used since string normalization depends on value representation
+     *  @return status, EC_Normal if successful, an error code otherwise
+     */
+    virtual OFCondition getOFString(OFString &stringVal,
+                                    const unsigned long pos,
+                                    OFBool normalize = OFTrue);
+
 
     /** check if this element is affected by SpecificCharacterSet
      *  @return always returns true since all derived VR classes are affected by the
@@ -169,6 +175,16 @@ class DCMTK_DCMDATA_EXPORT DcmCharString
      */
     virtual const OFString& getDelimiterChars() const;
 
+private:
+
+  /** helper method to get VM or component indexes from the value, considering the character encoding
+   *  @param pos index of the component, or -1 if only the VM is needed
+   *  @param start receives a pointer to the component with index "pos", if pos is >= 0
+   *  @param end a pointer to the  component end, if pos is >= 0
+   *  @param vm receives the VM of the value if pos is -1
+   *  @return status, EC_Normal if successful, EC_IllegalParameter if pos is invalid
+   */
+  OFCondition getIndexOfPosition(long pos, const char*& start, const char*& end, unsigned long& vm);
 };
 
 

dcmdata/include/dcmtk/dcmdata/dcitem.h

@@ -317,11 +317,10 @@ class DCMTK_DCMDATA_EXPORT DcmItem
      */
     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.
+    /** check if this element contains non-ASCII characters.
+     *  This works by checking for any byte values above 127, which works for any
+     *  single-byte code and for single-value multi-byte codes, and for ESC characters,
+     *  which will mean that a code extension is used.
      *  @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.

dcmdata/include/dcmtk/dcmdata/dcsequen.h

@@ -313,11 +313,10 @@ class DCMTK_DCMDATA_EXPORT DcmSequenceOfItems : public DcmElement
      */
     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.
+    /** check if this element contains non-ASCII characters.
+     *  This works by checking for any byte values above 127, which works for any
+     *  single-byte code and for single-value multi-byte codes, and for ESC characters,
+     *  which will mean that a code extension is used.
      *  @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.

dcmdata/include/dcmtk/dcmdata/dcvrlt.h

@@ -114,13 +114,6 @@ class DCMTK_DCMDATA_EXPORT DcmLongText
     virtual OFCondition checkValue(const OFString &vm = "",
                                    const OFBool oldFormat = OFFalse);
 
-    /** get the value multiplicity.
-     *  Since the backslash "\" is not regarded as a separator the value
-     *  multiplicity is always 1.
-     *  @return value multiplicity of the currently stored value
-     */
-    virtual unsigned long getVM();
-
     /** get a copy of a particular string component
      *  @param stringVal variable in which the result value is stored
      *  @param pos index of the value in case of multi-valued elements (0..vm-1)
@@ -151,6 +144,14 @@ class DCMTK_DCMDATA_EXPORT DcmLongText
      */
     static OFCondition checkStringValue(const OFString &value,
                                         const OFString &charset = "");
+
+  protected:
+    /** check if the VR supports more than one value.
+     *  Since the backslash "\" is not regarded as a separator,
+     *  multiple values cannot be encoded.
+     *  @return OFFalse
+     */
+    virtual OFBool supportsMultiValue() const { return OFFalse; };
 };
 
 

dcmdata/include/dcmtk/dcmdata/dcvrst.h

@@ -115,13 +115,6 @@ class DCMTK_DCMDATA_EXPORT DcmShortText
     virtual OFCondition checkValue(const OFString &vm = "",
                                    const OFBool oldFormat = OFFalse);
 
-    /** get the value multiplicity.
-     *  Since the backslash "\" is not regarded as a separator the value
-     *  multiplicity is always 1.
-     *  @return value multiplicity of the currently stored value
-     */
-    virtual unsigned long getVM();
-
     /** get a copy of a particular string component
      *  @param stringVal variable in which the result value is stored
      *  @param pos index of the value in case of multi-valued elements (0..vm-1)
@@ -152,6 +145,13 @@ class DCMTK_DCMDATA_EXPORT DcmShortText
      */
     static OFCondition checkStringValue(const OFString &value,
                                         const OFString &charset = "");
+protected:
+  /** check if the VR supports more than one value.
+   *  Since the backslash "\" is not regarded as a separator,
+   *  multiple values cannot be encoded.
+   *  @return OFFalse
+   */
+  virtual OFBool supportsMultiValue() const { return OFFalse; };
 };
 
 

dcmdata/include/dcmtk/dcmdata/dcvrut.h

@@ -117,13 +117,6 @@ class DCMTK_DCMDATA_EXPORT DcmUnlimitedText
     virtual OFCondition checkValue(const OFString &vm = "",
                                    const OFBool oldFormat = OFFalse);
 
-    /** get the value multiplicity.
-     *  Since the backslash "\" is not regarded as a separator the value
-     *  multiplicity is always 1.
-     *  @return value multiplicity of the currently stored value
-     */
-    virtual unsigned long getVM();
-
     /** get a copy of a particular string component
      *  @param stringVal variable in which the result value is stored
      *  @param pos index of the value in case of multi-valued elements (0..vm-1)
@@ -154,6 +147,13 @@ class DCMTK_DCMDATA_EXPORT DcmUnlimitedText
      */
     static OFCondition checkStringValue(const OFString &value,
                                         const OFString &charset = "");
+protected:
+  /** check if the VR supports more than one value.
+   *  Since the backslash "\" is not regarded as a separator,
+   *  multiple values cannot be encoded.
+   *  @return OFFalse
+   */
+  virtual OFBool supportsMultiValue() const { return OFFalse; };
 };
 
 

dcmdata/libsrc/dcbytstr.cc

@@ -766,7 +766,7 @@ OFBool DcmByteString::containsExtendedCharacters(const OFBool checkAllStrings)
     OFBool result = OFFalse;
     /* only check if parameter is true since derived VRs are not affected
        by the attribute SpecificCharacterSet (0008,0005) */
-    if (checkAllStrings)
+    if (checkAllStrings || isAffectedBySpecificCharacterSet())
     {
         char *str = NULL;
         Uint32 len = 0;
@@ -872,10 +872,10 @@ OFBool DcmByteString::containsExtendedCharacters(const char *stringVal,
 {
     if (stringVal != NULL)
     {
-        for (size_t i = stringLen; i != 0; --i)
+        for (size_t i = stringLen; i != 0; --i, ++stringVal)
         {
-            /* check for 8 bit characters */
-            if (OFstatic_cast(unsigned char, *stringVal++) > 127)
+            /* check for 8 bit and Escape characters */
+            if (*stringVal & 0x80 || *stringVal == 0x1b)
                 return OFTrue;
         }
     }