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

    public abstract class StringAttribute
    extends Attribute

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

### Field Summary

Fields
`protected SpecificCharacterSet` `specificCharacterSet`

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

`valueLength, valueMultiplicity`

### Constructor Summary

Constructors
`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, java.lang.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, java.lang.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.

### Method Summary

Methods
`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.
`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.
`long[]` `getLongValues()` Get the values of this attribute as a long array.
`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.
`void` `removeValues()` Remove any existing values, making the attribute empty (zero length).
`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

`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, 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, 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

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

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

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