Package com.pixelmed.dicom

# Class SequenceAttribute

java.lang.Object
com.pixelmed.dicom.Attribute
com.pixelmed.dicom.SequenceAttribute

public class SequenceAttribute extends Attribute

A concrete class specializing `Attribute` for Sequence (SQ) attributes.

Though an instance of this class may be created using its constructors, there is also a factory class, `AttributeFactory`.

See Also:
  - `SequenceItem`
  - `Attribute`
  - `AttributeFactory`
  - `AttributeList`

## Field Summary

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

`valueLength, valueMultiplicity`

## Constructor Summary

Constructors
Constructor
Description
`SequenceAttribute(AttributeTag t)`
Construct an (empty) attribute.

## Method Summary

Modifier and Type
Method
Description
`void`
`addItem(AttributeList item)`
Add an item to the sequence (after any existing items).
`void`
`addItem(AttributeList item, long byteOffset)`
Add an item to the sequence (after any existing items), keeping tracking of input byte offsets.
`void`
`addItem(SequenceItem item)`
Add an item to the sequence (after any existing items).
`static String[]`
`getArrayOfSingleStringValueOrDefaultOfNamedAttributeWithinSequenceItems(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, String dflt)`
Extract the string values of the specified attribute from within all the items of the specified sequence from within a list of attributes.
`static String[]`
`getArrayOfSingleStringValueOrDefaultOfNamedAttributeWithinSequenceItems(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, String dflt, NumberFormat format)`
Extract the string values of the specified attribute from within all the items of the specified sequence from within a list of attributes.
`static String[]`
`getArrayOfSingleStringValueOrEmptyStringOfNamedAttributeWithinSequenceItems(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag)`
Extract the string values of the specified attribute from within all the items of the specified sequence from within a list of attributes.
`static AttributeList`
`getAttributeListFromSelectedItemWithinSequence(SequenceAttribute sequenceAttribute, int index)`
Extract the AttributeList of the particular item in the sequence.
`static AttributeList`
`getAttributeListFromWithinSequenceWithSingleItem(AttributeList list, AttributeTag sequenceTag)`
Extract the AttributeList of the first item from a specified sequence from within a list of attributes.
`static AttributeList`
`getAttributeListFromWithinSequenceWithSingleItem(SequenceAttribute sequenceAttribute)`
Extract the AttributeList of the first item from a sequence.
`String`
`getDelimitedStringValuesOrDefault(String dflt, NumberFormat format)`
Get all the string values for all the items.
`SequenceItem`
`getItem(int index)`
Get particular item in the sequence.
`long`
`getLengthOfEntireEncodedAttribute(boolean explicit, boolean littleEndian)`
Get the length of the entire attribute when encoded, accounting for the characteristics of the Transfer Syntax and the need for even-length padding.
`static String`
`getMeaningOfCodedSequenceAttributeOrDefault(AttributeList list, AttributeTag sequenceTag, String dflt)`
Extract the code meaning attribute value from within the first item of the specified code sequence from within a list of attributes.
`static String`
`getMeaningOfCodedSequenceAttributeOrEmptyString(AttributeList list, AttributeTag sequenceTag)`
Extract the code meaning attribute value from within the first item of the specified code sequence from within a list of attributes.
`static Attribute`
`getNamedAttributeFromWithinSelectedItemWithinSequence(AttributeList list, AttributeTag sequenceTag, int index, AttributeTag namedTag)`
Extract the specified attribute from within the particular item of the specified sequence from within a list of attributes.
`static Attribute`
`getNamedAttributeFromWithinSelectedItemWithinSequence(SequenceAttribute sequenceAttribute, int index, AttributeTag namedTag)`
Extract the specified attribute from within the particular item in the sequence.
`static Attribute`
`getNamedAttributeFromWithinSequenceWithSingleItem(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag)`
Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.
`static Attribute`
`getNamedAttributeFromWithinSequenceWithSingleItem(SequenceAttribute sequenceAttribute, AttributeTag namedTag)`
Extract the specified attribute from the first item of the specified sequence.
`int`
`getNumberOfItems()`
Get the number of items in the sequence.
`static double`
`getSingleDoubleValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, double dflt)`
Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.
`static double`
`getSingleIntegerValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, int dflt)`
Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.
`static String`
`getSingleStringValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, String dflt)`
Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.
`static String`
`getSingleStringValueOfNamedAttributeFromWithinSequenceWithSingleItemOrEmptyString(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag)`
Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.
`byte[]`
`getVR()`
Get the value representation of this attribute (SQ).
`Iterator<SequenceItem>`
`iterator()`
Get an `Iterator` of the items in the sequence.
`void`
`remove(SequenceItem item)`
Remove an item from the sequence.
`void`
`removeValues()`
Remove any existing values, making the attribute empty (zero length).
`String`
`toString(DicomDictionary dictionary)`
Dump the contents of the attribute as a human-readable string.
`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, addValue, getByteValues, getByteValues, 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, getLengthOfBaseOfEncodedAttribute, getLengthOfEncodedValue, getLongValues, getLongValues, getLongValues, getOriginalStringValues, getPaddedVL, 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, getStringValues, getTag, getVL, getVM, getVRAsString, isValid, repairValues, 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`

## Constructor Details

### SequenceAttribute

public SequenceAttribute(AttributeTag t)

Construct an (empty) attribute.

Parameters:
  `t` - the tag of the attribute

## Method Details

### 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` -
Throws:
  `IOException`
  `DicomException`

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

### removeValues

public void removeValues()
Description copied from class: `Attribute`

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

Specified by:
  `removeValues` in class `Attribute`

### addItem

public void addItem(SequenceItem item)
Add an item to the sequence (after any existing items).

Parameters:
  `item` -

### addItem

public void addItem(AttributeList item)
Add an item to the sequence (after any existing items).

Parameters:
  `item` - the list of attributes that comprise the item

### addItem

public void addItem(AttributeList item, long byteOffset)
Add an item to the sequence (after any existing items), keeping tracking of input byte offsets.

Parameters:
  `item` - the list of attributes that comprise the item
  `byteOffset` - the byte offset in the input stream of the start of the item

### iterator

public Iterator<SequenceItem> iterator()
Get an `Iterator` of the items in the sequence.

Returns:
  a `Iterator` of items, each encoded as an `SequenceItem`

### getNumberOfItems

public int getNumberOfItems()
Get the number of items in the sequence.

Returns:
  the number of items

### getItem

public SequenceItem getItem(int index)
Get particular item in the sequence.

Parameters:
  `index` - which item to return, numbered from zero
Returns:
  a `SequenceItem`, null if no items or no such item

### remove

public void remove(SequenceItem item)
Remove an item from the sequence.

Parameters:
  `item` -

### getVR

public byte[] getVR()

Get the value representation of this attribute (SQ).

Overrides:
  `getVR` in class `Attribute`
Returns:
  'S','Q' in ASCII as a two byte array; see `ValueRepresentation`

### getLengthOfEntireEncodedAttribute

public long getLengthOfEntireEncodedAttribute(boolean explicit, boolean littleEndian) throws DicomException

Get the length of the entire attribute when encoded, accounting for the characteristics of the Transfer Syntax and the need for even-length padding.

Overrides:
  `getLengthOfEntireEncodedAttribute` in class `Attribute`
Parameters:
  `explicit` - true if the Transfer Syntax to be used for encoding is explicit VR
  `littleEndian` - true if the Transfer Syntax to be used for encoding is little endian
Returns:
  the length in bytes
Throws:
  `DicomException` - if the VL is too long to be written in Explicit VR Transfer Syntax

### getAttributeListFromWithinSequenceWithSingleItem

public static AttributeList getAttributeListFromWithinSequenceWithSingleItem(SequenceAttribute sequenceAttribute)

Extract the AttributeList of the first item from a sequence.

Parameters:
  `sequenceAttribute` - the sequence attribute that has one item (may be null in which case returns null)
Returns:
  the AttributeList if found else null

### getAttributeListFromSelectedItemWithinSequence

public static AttributeList getAttributeListFromSelectedItemWithinSequence(SequenceAttribute sequenceAttribute, int index)

Extract the AttributeList of the particular item in the sequence.

Parameters:
  `sequenceAttribute` - the sequence attribute that has one item (may be null in which case returns null)
  `index` - which item to return, numbered from zero
Returns:
  the AttributeList if found else null

### getNamedAttributeFromWithinSelectedItemWithinSequence

public static Attribute getNamedAttributeFromWithinSelectedItemWithinSequence(SequenceAttribute sequenceAttribute, int index, AttributeTag namedTag)

Extract the specified attribute from within the particular item in the sequence.

Parameters:
  `sequenceAttribute` - the sequence attribute that has one item (may be null in which case returns null)
  `index` - which item to return, numbered from zero
  `namedTag` - the tag of the attribute within the item of the sequence
Returns:
  the attribute if found else null

### getNamedAttributeFromWithinSelectedItemWithinSequence

public static Attribute getNamedAttributeFromWithinSelectedItemWithinSequence(AttributeList list, AttributeTag sequenceTag, int index, AttributeTag namedTag)

Extract the specified attribute from within the particular item of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `index` - which item to return, numbered from zero
  `namedTag` - the tag of the attribute within the item of the sequence
Returns:
  the attribute if found else null

### getAttributeListFromWithinSequenceWithSingleItem

public static AttributeList getAttributeListFromWithinSequenceWithSingleItem(AttributeList list, AttributeTag sequenceTag)

Extract the AttributeList of the first item from a specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
Returns:
  the AttributeList if found else null

### getNamedAttributeFromWithinSequenceWithSingleItem

public static Attribute getNamedAttributeFromWithinSequenceWithSingleItem(SequenceAttribute sequenceAttribute, AttributeTag namedTag)

Extract the specified attribute from the first item of the specified sequence.

Parameters:
  `sequenceAttribute` - the sequence attribute that has one item (may be null in which case returns null)
  `namedTag` - the tag of the attribute within the item of the sequence
Returns:
  the attribute if found else null

### getNamedAttributeFromWithinSequenceWithSingleItem

public static Attribute getNamedAttributeFromWithinSequenceWithSingleItem(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag)

Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
Returns:
  the attribute if found else null

### getSingleStringValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault

public static String getSingleStringValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, String dflt)

Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
  `dflt` - what to return if there is no such sequence attribute or it is empty or the attribute is not found
Returns:
  the attribute if found else the dflt

### getSingleStringValueOfNamedAttributeFromWithinSequenceWithSingleItemOrEmptyString

public static String getSingleStringValueOfNamedAttributeFromWithinSequenceWithSingleItemOrEmptyString(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag)

Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
Returns:
  the attribute if found else empty string

### getSingleIntegerValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault

public static double getSingleIntegerValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, int dflt)

Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
  `dflt` - what to return if there is no such sequence attribute or it is empty or the attribute is not found
Returns:
  the attribute if found else the dflt

### getSingleDoubleValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault

public static double getSingleDoubleValueOfNamedAttributeFromWithinSequenceWithSingleItemOrDefault(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, double dflt)

Extract the specified attribute from within the first item of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
  `dflt` - what to return if there is no such sequence attribute or it is empty or the attribute is not found
Returns:
  the attribute if found else the dflt

### getMeaningOfCodedSequenceAttributeOrDefault

public static String getMeaningOfCodedSequenceAttributeOrDefault(AttributeList list, AttributeTag sequenceTag, String dflt)

Extract the code meaning attribute value from within the first item of the specified code sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the code sequence (may not be null)
  `sequenceTag` - the tag of the code sequence attribute that has one item
  `dflt` - what to return if there is no such sequence attribute or it is empty or has no code meaning attribute
Returns:
  the code meaning if found else the dflt

### getMeaningOfCodedSequenceAttributeOrEmptyString

public static String getMeaningOfCodedSequenceAttributeOrEmptyString(AttributeList list, AttributeTag sequenceTag)

Extract the code meaning attribute value from within the first item of the specified code sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the code sequence (may not be null)
  `sequenceTag` - the tag of the code sequence attribute that has one item
Returns:
  the code meaning if found else empty string

### getDelimitedStringValuesOrDefault

public String getDelimitedStringValuesOrDefault(String dflt, NumberFormat format)

Get all the string values for all the items.

If there is no string value for an individual value or an exception trying to fetch it, the supplied default is returned for each Attribute.

A canonicalized (unpadded) form is returned for each Attribute value, not the original string.

Overrides:
  `getDelimitedStringValuesOrDefault` in class `Attribute`
Parameters:
  `dflt` - what to return if there are no (valid) string values
  `format` - the format to use for each numerical or decimal value (null if none)
Returns:
  the values as a delimited `String`

### getArrayOfSingleStringValueOrDefaultOfNamedAttributeWithinSequenceItems

public static String[] getArrayOfSingleStringValueOrDefaultOfNamedAttributeWithinSequenceItems(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, String dflt, NumberFormat format)

Extract the string values of the specified attribute from within all the items of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
  `dflt` - what to return if there is no (valid) string value
  `format` - the format to use for each numerical or decimal value (null if none)
Returns:
  an array of String with one element per Sequence item, zero length if no items or absent

### getArrayOfSingleStringValueOrDefaultOfNamedAttributeWithinSequenceItems

public static String[] getArrayOfSingleStringValueOrDefaultOfNamedAttributeWithinSequenceItems(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag, String dflt)

Extract the string values of the specified attribute from within all the items of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
  `dflt` - what to return if there is no (valid) string value
Returns:
  an array of String with one element per Sequence item, zero length if no items or absent

### getArrayOfSingleStringValueOrEmptyStringOfNamedAttributeWithinSequenceItems

public static String[] getArrayOfSingleStringValueOrEmptyStringOfNamedAttributeWithinSequenceItems(AttributeList list, AttributeTag sequenceTag, AttributeTag namedTag)

Extract the string values of the specified attribute from within all the items of the specified sequence from within a list of attributes.

Parameters:
  `list` - the list that contains the sequence (may not be null)
  `sequenceTag` - the tag of the sequence attribute that has one item
  `namedTag` - the tag of the attribute within the item of the sequence
Returns:
  an array of String with one element per Sequence item, zero length if no items or absent