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

## Method Summary

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(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()`
`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.
`String[]`
`getStringValues(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.
`String`
`toString(DicomDictionary dictionary)`
Dump the contents of the attribute as a human-readable string.
`protected String`
`translateByteArrayToString(byte[] bytes, int offset, int length)`
Decode a byte array into a string.
`protected byte[]`
`translateStringToByteArray(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 Details

### specificCharacterSet

protected SpecificCharacterSet specificCharacterSet

## Constructor Details

### 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 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:
  `IOException` - if an I/O error occurs
  `DicomException` - if a DICOM parsing error occurs

### StringAttribute

protected StringAttribute(AttributeTag t, Long vl, DicomInputStream i) throws 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:
  `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 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:
  `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 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:
  `IOException` - if an I/O error occurs
  `DicomException` - if a DICOM parsing error occurs

## Method Details

### 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 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(String string) throws 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:
  `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, 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:
  `IOException` - if an I/O error occurs
  `DicomException` - if a DICOM encoding error occurs

### toString

public 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 String[] getStringValues(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 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(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