Package com.pixelmed.dicom

## Class StringAttribute

- java.lang.Object
- - com.pixelmed.dicom.Attribute
  - - com.pixelmed.dicom.StringAttribute

- Direct Known Subclasses:
    `AgeStringAttribute`, `ApplicationEntityAttribute`, `CodeStringAttribute`, `DateAttribute`, `DateTimeAttribute`, `DecimalStringAttribute`, `IntegerStringAttribute`, `StringAttributeAffectedBySpecificCharacterSet`, `TimeAttribute`, `UniqueIdentifierAttribute`, `UniversalResourceAttribute`

      public abstract class StringAttribute
      extends Attribute

  An abstract class specializing `Attribute` for the family of string attributes.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected SpecificCharacterSet` | `specificCharacterSet` |

    - ### Fields inherited from class com.pixelmed.dicom.Attribute

      `valueLength, valueMultiplicity`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `StringAttribute​(AttributeTag t)` | Construct an (empty) attribute; called only by concrete sub-classes.
    `protected` | `StringAttribute​(AttributeTag t, long vl, DicomInputStream i)` | Read an attribute from an input stream; called only by concrete sub-classes.
    `protected` | `StringAttribute​(AttributeTag t, long vl, DicomInputStream i, SpecificCharacterSet specificCharacterSet)` | Read an attribute from an input stream; called only by concrete sub-classes.
    `protected` | `StringAttribute​(AttributeTag t, SpecificCharacterSet specificCharacterSet)` | Construct an (empty) attribute; called only by concrete sub-classes.
    `protected` | `StringAttribute​(AttributeTag t, java.lang.Long vl, DicomInputStream i)` | Read an attribute from an input stream; called only by concrete sub-classes.
    `protected` | `StringAttribute​(AttributeTag t, java.lang.Long vl, DicomInputStream i, SpecificCharacterSet specificCharacterSet)` | Read an attribute from an input stream; called only by concrete sub-classes.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addValue​(byte v)` | Add a(nother) byte value after any existing values of this attribute.
    `void` | `addValue​(double v)` | Add a(nother) double value after any existing values of this attribute.
    `void` | `addValue​(float v)` | Add a(nother) float value after any existing values of this attribute.
    `void` | `addValue​(int v)` | Add a(nother) int value after any existing values of this attribute.
    `void` | `addValue​(long v)` | Add a(nother) long value after any existing values of this attribute.
    `void` | `addValue​(short v)` | Add a(nother) short value after any existing values of this attribute.
    `void` | `addValue​(java.lang.String v)` | Add a(nother) `String` value after any existing values of this attribute.
    `protected boolean` | `allowRepairOfIncorrectLength()` |
    `protected boolean` | `allowRepairOfInvalidCharacterReplacement()` |
    `boolean` | `areCharactersInValuesValid()` |
    `boolean` | `areLengthsOfValuesValid()` |
    `boolean` | `areValuesWellFormed()` |
    `protected void` | `flushCachedCopies()` |
    `byte[]` | `getByteValues()` | Get the values of this attribute as a byte array.
    `double[]` | `getDoubleValues()` | Get the values of this attribute as a double array.
    `float[]` | `getFloatValues()` | Get the values of this attribute as a float array.
    `int[]` | `getIntegerValues()` | Get the values of this attribute as an int array.
    `protected char` | `getInvalidCharacterReplacement()` |
    `long[]` | `getLongValues()` | Get the values of this attribute as a long array.
    `abstract int` | `getMaximumLengthOfSingleValue()` |
    `java.lang.String[]` | `getOriginalStringValues()` | Get the values of this attribute as strings, the way they were originally inserted or read.
    `protected byte` | `getPadByte()` | Get the appropriate byte for padding a string to an even length.
    `long` | `getPaddedVL()` | Get the value length of this attribute, accounting for the need for even-length padding.
    `short[]` | `getShortValues()` | Get the values of this attribute as a short array.
    `SpecificCharacterSet` | `getSpecificCharacterSet()` | Get the specific character set for this attribute.
    `java.lang.String[]` | `getStringValues​(java.text.NumberFormat format)` | Get the values of this attribute as strings.
    `boolean` | `isCharacterInValueValid​(int c)` |
    `boolean` | `isValid()` | Do the values of this attribute comply with standard VR requirements? E.g., Are only valid characters are present (for string and text attributes) and length is within limits?
    `void` | `removeValues()` | Remove any existing values, making the attribute empty (zero length).
    `boolean` | `repairValues()` | Repair any existing values of this attribute to make them comply with standard VR requirements.
    `void` | `setSpecificCharacterSet​(SpecificCharacterSet specificCharacterSet)` | Set the specific character set for this attribute.
    `java.lang.String` | `toString​(DicomDictionary dictionary)` | Dump the contents of the attribute as a human-readable string.
    `protected java.lang.String` | `translateByteArrayToString​(byte[] bytes, int offset, int length)` | Decode a byte array into a string.
    `protected byte[]` | `translateStringToByteArray​(java.lang.String string)` | Encode a string into a byte array.
    `void` | `write​(DicomOutputStream o)` | Write the entire attribute (including values) to the output stream.

    - ### Methods inherited from class com.pixelmed.dicom.Attribute

      `getByteValues, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDoubleValues, getDoubleValues, getElement, getFloatValues, getFloatValues, getGroup, getIntegerValues, getIntegerValues, getLengthOfBaseOfEncodedAttribute, getLengthOfEncodedValue, getLengthOfEntireEncodedAttribute, getLongValues, getLongValues, getSingleDoubleValueOrDefault, getSingleDoubleValueOrDefault, getSingleDoubleValueOrDefault, getSingleFloatValueOrDefault, getSingleFloatValueOrDefault, getSingleFloatValueOrDefault, getSingleIntegerValueOrDefault, getSingleIntegerValueOrDefault, getSingleIntegerValueOrDefault, getSingleLongValueOrDefault, getSingleLongValueOrDefault, getSingleLongValueOrDefault, getSingleStringValueOrDefault, getSingleStringValueOrDefault, getSingleStringValueOrDefault, getSingleStringValueOrDefault, getSingleStringValueOrDefault, getSingleStringValueOrDefault, getSingleStringValueOrEmptyString, getSingleStringValueOrEmptyString, getSingleStringValueOrEmptyString, getSingleStringValueOrEmptyString, getSingleStringValueOrEmptyString, getSingleStringValueOrEmptyString, getSingleStringValueOrNull, getSingleStringValueOrNull, getSingleStringValueOrNull, getSingleStringValueOrNull, getSingleStringValueOrNull, getSingleStringValueOrNull, getStringValues, getStringValues, getStringValues, getStringValues, getStringValues, getTag, getVL, getVM, getVR, getVRAsString, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValues, setValues, setValues, setValues, setValues, setValues, setValues, toString, writeBase`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### specificCharacterSet

          protected SpecificCharacterSet specificCharacterSet

  - ### Constructor Detail

    - #### StringAttribute

          protected StringAttribute​(AttributeTag t)

      Construct an (empty) attribute; called only by concrete sub-classes.

      Parameters:
        `t` - the tag of the attribute

    - #### StringAttribute

          protected StringAttribute​(AttributeTag t,
                                    SpecificCharacterSet specificCharacterSet)

      Construct an (empty) attribute; called only by concrete sub-classes.

      Parameters:
        `t` - the tag of the attribute
        `specificCharacterSet` - the character set to be used for the text

    - #### StringAttribute

          protected StringAttribute​(AttributeTag t,
                                    long vl,
                                    DicomInputStream i)
                             throws java.io.IOException,
                                    DicomException

      Read an attribute from an input stream; called only by concrete sub-classes.

      Parameters:
        `t` - the tag of the attribute
        `vl` - the value length of the attribute
        `i` - the input stream
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `DicomException` - if a DICOM parsing error occurs

    - #### StringAttribute

          protected StringAttribute​(AttributeTag t,
                                    java.lang.Long vl,
                                    DicomInputStream i)
                             throws java.io.IOException,
                                    DicomException

      Read an attribute from an input stream; called only by concrete sub-classes.

      Parameters:
        `t` - the tag of the attribute
        `vl` - the value length of the attribute
        `i` - the input stream
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `DicomException` - if a DICOM parsing error occurs

    - #### StringAttribute

          protected StringAttribute​(AttributeTag t,
                                    long vl,
                                    DicomInputStream i,
                                    SpecificCharacterSet specificCharacterSet)
                             throws java.io.IOException,
                                    DicomException

      Read an attribute from an input stream; called only by concrete sub-classes.

      Parameters:
        `t` - the tag of the attribute
        `vl` - the value length of the attribute
        `i` - the input stream
        `specificCharacterSet` - the character set to be used for the text
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `DicomException` - if a DICOM parsing error occurs

    - #### StringAttribute

          protected StringAttribute​(AttributeTag t,
                                    java.lang.Long vl,
                                    DicomInputStream i,
                                    SpecificCharacterSet specificCharacterSet)
                             throws java.io.IOException,
                                    DicomException

      Read an attribute from an input stream; called only by concrete sub-classes.

      Parameters:
        `t` - the tag of the attribute
        `vl` - the value length of the attribute
        `i` - the input stream
        `specificCharacterSet` - the character set to be used for the text
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `DicomException` - if a DICOM parsing error occurs

  - ### Method Detail

    - #### getMaximumLengthOfSingleValue

          public abstract int getMaximumLengthOfSingleValue()

    - #### getSpecificCharacterSet

          public SpecificCharacterSet getSpecificCharacterSet()

      Get the specific character set for this attribute.

      Returns:
        the specific character set, or null if none

    - #### setSpecificCharacterSet

          public void setSpecificCharacterSet​(SpecificCharacterSet specificCharacterSet)

      Set the specific character set for this attribute.

      Parameters:
        `specificCharacterSet` - the specific character set, or null if none

    - #### flushCachedCopies

          protected void flushCachedCopies()

    - #### translateByteArrayToString

          protected java.lang.String translateByteArrayToString​(byte[] bytes,
                                                                int offset,
                                                                int length)

      Decode a byte array into a string.

      Parameters:
        `bytes` - the byte buffer in which the encoded string is located
        `offset` - the offset into the buffer
        `length` - the number of bytes to be decoded
      Returns:
        the string decoded according to the specified or default specific character set

    - #### translateStringToByteArray

          protected byte[] translateStringToByteArray​(java.lang.String string)
                                               throws java.io.UnsupportedEncodingException

      Encode a string into a byte array.

      Parameters:
        `string` - the string to be encoded
      Returns:
        the byte array encoded according to the specified or default specific character set
      Throws:
        `java.io.UnsupportedEncodingException` - if the encoding is not supported

    - #### getPaddedVL

          public long getPaddedVL()

      Description copied from class: `Attribute`

      Get the value length of this attribute, accounting for the need for even-length padding.

      Overrides:
        `getPaddedVL` in class `Attribute`
      Returns:
        the value length (padded to an even length)

    - #### getPadByte

          protected byte getPadByte()

      Get the appropriate byte for padding a string to an even length.

      Returns:
        the byte pad value appropriate to the VR

    - #### write

          public void write​(DicomOutputStream o)
                     throws DicomException,
                            java.io.IOException

      Description copied from class: `Attribute`

      Write the entire attribute (including values) to the output stream.

      Specified by:
        `write` in class `Attribute`
      Parameters:
        `o` - the output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `DicomException` - if a DICOM encoding error occurs

    - #### toString

          public java.lang.String toString​(DicomDictionary dictionary)

      Description copied from class: `Attribute`

      Dump the contents of the attribute as a human-readable string.

      No new line is appended.

      The result is of the form:

           (0xgggg,0xeeee) Name VR=<XX> VL=<0xnnnn> <...>

      For example:

           (0x0018,0x0020) ScanningSequence VR=<CS> VL=<0x2> <GR>

      Overrides:
        `toString` in class `Attribute`
      Parameters:
        `dictionary` - the dictionary to use to look up the name
      Returns:
        a single `String` value

    - #### getByteValues

          public byte[] getByteValues()
                               throws DicomException

      Get the values of this attribute as a byte array.

      Returns the originally read byte values, if read from a stream, otherwise converts the string to bytes and pads them.

      Overrides:
        `getByteValues` in class `Attribute`
      Returns:
        the values as an array of bytes
      Throws:
        `DicomException` - if a DICOM parsing error occurs

    - #### getStringValues

          public java.lang.String[] getStringValues​(java.text.NumberFormat format)
                                             throws DicomException

      Get the values of this attribute as strings.

      The strings are first cleaned up into a canonical form, to remove leading and trailing padding.

      Overrides:
        `getStringValues` in class `Attribute`
      Parameters:
        `format` - the format to use for each numerical or decimal value
      Returns:
        the values as an array of `String`
      Throws:
        `DicomException` - not thrown

    - #### getOriginalStringValues

          public java.lang.String[] getOriginalStringValues()
                                                     throws DicomException

      Get the values of this attribute as strings, the way they were originally inserted or read.

      Overrides:
        `getOriginalStringValues` in class `Attribute`
      Returns:
        the values as an array of `String`
      Throws:
        `DicomException` - not thrown

    - #### getShortValues

          public short[] getShortValues()
                                 throws DicomException

      Description copied from class: `Attribute`

      Get the values of this attribute as a short array.

      Overrides:
        `getShortValues` in class `Attribute`
      Returns:
        the values as an array of short
      Throws:
        `DicomException` - not thrown

    - #### getIntegerValues

          public int[] getIntegerValues()
                                 throws DicomException

      Description copied from class: `Attribute`

      Get the values of this attribute as an int array.

      Overrides:
        `getIntegerValues` in class `Attribute`
      Returns:
        the values as an array of int
      Throws:
        `DicomException` - not thrown

    - #### getLongValues

          public long[] getLongValues()
                               throws DicomException

      Description copied from class: `Attribute`

      Get the values of this attribute as a long array.

      Overrides:
        `getLongValues` in class `Attribute`
      Returns:
        the values as an array of long
      Throws:
        `DicomException` - not thrown

    - #### getFloatValues

          public float[] getFloatValues()
                                 throws DicomException

      Description copied from class: `Attribute`

      Get the values of this attribute as a float array.

      Overrides:
        `getFloatValues` in class `Attribute`
      Returns:
        the values as an array of float
      Throws:
        `DicomException` - not thrown

    - #### getDoubleValues

          public double[] getDoubleValues()
                                   throws DicomException

      Description copied from class: `Attribute`

      Get the values of this attribute as a double array.

      Overrides:
        `getDoubleValues` in class `Attribute`
      Returns:
        the values as an array of double
      Throws:
        `DicomException` - not thrown

    - #### addValue

          public void addValue​(java.lang.String v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) `String` value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - if unsupported encoding

    - #### addValue

          public void addValue​(byte v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) byte value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - not thrown

    - #### addValue

          public void addValue​(short v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) short value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - not thrown

    - #### addValue

          public void addValue​(int v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) int value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - not thrown

    - #### addValue

          public void addValue​(long v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) long value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - not thrown

    - #### addValue

          public void addValue​(float v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) float value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - not thrown

    - #### addValue

          public void addValue​(double v)
                        throws DicomException

      Description copied from class: `Attribute`
      Add a(nother) double value after any existing values of this attribute.
      Overrides:
        `addValue` in class `Attribute`
      Parameters:
        `v` - value to add
      Throws:
        `DicomException` - not thrown

    - #### removeValues

          public void removeValues()
                            throws DicomException

      Description copied from class: `Attribute`

      Remove any existing values, making the attribute empty (zero length).

      Specified by:
        `removeValues` in class `Attribute`
      Throws:
        `DicomException` - not thrown

    - #### areLengthsOfValuesValid

          public boolean areLengthsOfValuesValid()
                                          throws DicomException

      Throws:
        `DicomException`

    - #### isCharacterInValueValid

          public boolean isCharacterInValueValid​(int c)
                                          throws DicomException

      Throws:
        `DicomException`

    - #### areCharactersInValuesValid

          public boolean areCharactersInValuesValid()
                                             throws DicomException

      Throws:
        `DicomException`

    - #### areValuesWellFormed

          public boolean areValuesWellFormed()
                                      throws DicomException

      Throws:
        `DicomException`

    - #### isValid

          public boolean isValid()
                          throws DicomException

      Description copied from class: `Attribute`
      Do the values of this attribute comply with standard VR requirements? E.g., Are only valid characters are present (for string and text attributes) and length is within limits?
      Overrides:
        `isValid` in class `Attribute`
      Returns:
        true if valid, false if invalid or validation not supported for the attribute type
      Throws:
        `DicomException` - if error in DICOM value extraction

    - #### allowRepairOfIncorrectLength

          protected boolean allowRepairOfIncorrectLength()

    - #### allowRepairOfInvalidCharacterReplacement

          protected boolean allowRepairOfInvalidCharacterReplacement()

    - #### getInvalidCharacterReplacement

          protected char getInvalidCharacterReplacement()

    - #### repairValues

          public boolean repairValues()
                               throws DicomException

      Description copied from class: `Attribute`
      Repair any existing values of this attribute to make them comply with standard VR requirements. E.g., truncate them if they are too long. N.B., Not all types of attribute support repair.
      Overrides:
        `repairValues` in class `Attribute`
      Returns:
        true if successfully repaired or was already valid
      Throws:
        `DicomException` - if error in DICOM value extraction