com.pixelmed.dicom

## Class TextAttribute

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

- Direct Known Subclasses:
    LongTextAttribute, ShortTextAttribute, UnlimitedTextAttribute

      public abstract class TextAttribute
      extends Attribute

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

- - ### Field Summary

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

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

      `valueLength, valueMultiplicity`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addValue(java.lang.String v)` Add a(nother) `String` value after any existing values of this attribute.
    `byte[]` | `getByteValues()` Get the values of this attribute as a byte array.
    `abstract int` | `getMaximumLengthOfEntireValue()`
    `long` | `getPaddedVL()` Get the value length of this attribute, accounting for the need for even-length padding.
    `java.lang.String[]` | `getStringValues(java.text.NumberFormat format)` Get the values of this attribute as strings.
    `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.
    `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

      `addValue, addValue, addValue, addValue, addValue, addValue, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrDefault, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrEmptyString, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDelimitedStringValuesOrNull, getDoubleValues, getDoubleValues, getDoubleValues, getElement, getFloatValues, getFloatValues, getFloatValues, getGroup, getIntegerValues, getIntegerValues, getIntegerValues, getLongValues, getLongValues, getLongValues, getOriginalStringValues, getShortValues, 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, toString, writeBase`

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

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

- - ### Field Detail

    - #### specificCharacterSet

          protected SpecificCharacterSet specificCharacterSet

  - ### Constructor Detail

    - #### TextAttribute

          protected TextAttribute(AttributeTag t)

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

      Parameters:
        `t` - the tag of the attribute

    - #### TextAttribute

          protected TextAttribute(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

    - #### TextAttribute

          protected TextAttribute(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 error in DICOM encoding

    - #### TextAttribute

          protected TextAttribute(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 error in DICOM encoding

  - ### Method Detail

    - #### getMaximumLengthOfEntireValue

          public abstract int getMaximumLengthOfEntireValue()

    - #### 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 by the host platform

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

    - #### 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:
        `DicomException` - if error in DICOM encoding
        `java.io.IOException` - if an I/O 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

      Description copied from class: `Attribute`

      Get the values of this attribute as a byte array.

      Overrides:
        `getByteValues` in class `Attribute`
      Returns:
        the values as an array of bytes
      Throws:
        `DicomException` - thrown if values are not available (such as not supported for this concrete attribute class)

    - #### getStringValues

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

      Description copied from class: `Attribute`

      Get the values of this attribute as strings.

      The strings may have been cleaned up into a canonical form, such as to remove padding as well as numbers formatted.

      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` - thrown if values are not available (such as not supported for this concrete attribute class)

    - #### 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` - thrown if value of this type is not valid for this concrete attribute class

    - #### 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` - thrown if not supported for concrete attribute class

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

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