com.pixelmed.dicom

## Class DateTimeAttribute

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

    public class DateTimeAttribute
    extends StringAttribute

A concrete class specializing `Attribute` for Date Time (DT) attributes.

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

See Also:
  `Attribute`, `AttributeFactory`, `AttributeList`

### Field Summary

Fields
`protected static int` `MAX_LENGTH_SINGLE_VALUE`

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

`specificCharacterSet`

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

`valueLength, valueMultiplicity`

### Constructor Summary

Constructors
Constructor and Description
`DateTimeAttribute(AttributeTag t)` Construct an (empty) attribute.
`DateTimeAttribute(AttributeTag t, long vl, DicomInputStream i)` Read an attribute from an input stream.
`DateTimeAttribute(AttributeTag t, java.lang.Long vl, DicomInputStream i)` Read an attribute from an input stream.

### Method Summary

Methods
`protected boolean` `allowRepairOfIncorrectLength()`
`protected boolean` `allowRepairOfInvalidCharacterReplacement()`
`static java.util.Date` `getDateFromFormattedString(AttributeList list, AttributeTag dateTag, AttributeTag timeTag)` Get a Java `Date` from a DICOM format DT `String` value.
`static java.util.Date` `getDateFromFormattedString(java.lang.String dateString)` Get a Java `Date` from a DICOM format DT `String` value.
`static java.lang.String` `getFormattedString(java.util.Date date)` Deprecated. use `getFormattedStringDefaultTimeZone()` instead
`static java.lang.String` `getFormattedString(java.util.Date date, java.util.TimeZone timezone)` Get a DICOM format DT `String` value from a Java `Date`.
`static java.lang.String` `getFormattedString(java.util.Date date, java.util.TimeZone timezone, boolean tzSuffix)` Get a DICOM format DT `String` value from a Java `Date`.
`static java.lang.String` `getFormattedStringDefaultTimeZone(java.util.Date date)` Get a DICOM format DT `String` value from a Java `Date`.
`static java.lang.String` `getFormattedStringUTC(java.util.Date date)` Get a DICOM format DT `String` value from a Java `Date`.
`int` `getMaximumLengthOfSingleValue()`
`static long` `getTimeInMilliSecondsSinceEpoch(AttributeList list, AttributeTag dateTag, AttributeTag timeTag)` Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by the combination of the DA and TM values of the specified pair of attributes.
`static long` `getTimeInMilliSecondsSinceEpoch(java.lang.String dateTime)` Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by the DT value.
`static java.util.TimeZone` `getTimeZone(java.lang.String dicomTimeZone)` Get a Java `TimeZone` from a DICOM format `String` time zone.
`byte[]` `getVR()` Get the value representation of this attribute (DT).
`boolean` `isCharacterInValueValid(int c)`

### Methods inherited from class com.pixelmed.dicom.StringAttribute

`addValue, addValue, addValue, addValue, addValue, addValue, addValue, areCharactersInValuesValid, areLengthsOfValuesValid, areValuesWellFormed, flushCachedCopies, getByteValues, getDoubleValues, getFloatValues, getIntegerValues, getInvalidCharacterReplacement, getLongValues, getOriginalStringValues, getPadByte, getPaddedVL, getShortValues, getSpecificCharacterSet, getStringValues, isValid, removeValues, repairValues, setSpecificCharacterSet, toString, translateByteArrayToString, translateStringToByteArray, write`

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

#### MAX_LENGTH_SINGLE_VALUE

    protected static final int MAX_LENGTH_SINGLE_VALUE

See Also:
  Constant Field Values

### Constructor Detail

#### DateTimeAttribute

    public DateTimeAttribute(AttributeTag t)

Construct an (empty) attribute.

Parameters:
  `t` - the tag of the attribute

#### DateTimeAttribute

    public DateTimeAttribute(AttributeTag t,
                     long vl,
                     DicomInputStream i)
                      throws java.io.IOException,
                             DicomException

Read an attribute from an input stream.

Parameters:
  `t` - the tag of the attribute
  `vl` - the value length of the attribute
  `i` - the input stream
Throws:
  `java.io.IOException`
  `DicomException`

#### DateTimeAttribute

    public DateTimeAttribute(AttributeTag t,
                     java.lang.Long vl,
                     DicomInputStream i)
                      throws java.io.IOException,
                             DicomException

Read an attribute from an input stream.

Parameters:
  `t` - the tag of the attribute
  `vl` - the value length of the attribute
  `i` - the input stream
Throws:
  `java.io.IOException`
  `DicomException`

### Method Detail

#### getMaximumLengthOfSingleValue

    public final int getMaximumLengthOfSingleValue()

Specified by:
  `getMaximumLengthOfSingleValue` in class `StringAttribute`

#### getVR

    public byte[] getVR()

Get the value representation of this attribute (DT).

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

#### allowRepairOfIncorrectLength

    protected final boolean allowRepairOfIncorrectLength()

Overrides:
  `allowRepairOfIncorrectLength` in class `StringAttribute`

#### allowRepairOfInvalidCharacterReplacement

    protected final boolean allowRepairOfInvalidCharacterReplacement()

Overrides:
  `allowRepairOfInvalidCharacterReplacement` in class `StringAttribute`

#### isCharacterInValueValid

    public final boolean isCharacterInValueValid(int c)
                                          throws DicomException

Overrides:
  `isCharacterInValueValid` in class `StringAttribute`
Throws:
  `DicomException`

#### getFormattedString

    public static java.lang.String getFormattedString(java.util.Date date,
                                      java.util.TimeZone timezone,
                                      boolean tzSuffix)

Get a DICOM format DT `String` value from a Java `Date`.

Will format the Date for the specified timezone.

Parameters:
  `date` - the Java `Date` to format
  `timezone` - the Java `TimeZone` to use
  `tzSuffix` - whether or not to append the time zone suffix
Returns:
  a DICOM formatted DT value

#### getFormattedString

    public static java.lang.String getFormattedString(java.util.Date date,
                                      java.util.TimeZone timezone)

Get a DICOM format DT `String` value from a Java `Date`.

Will format the Date for the specified timezone.

Will include the timezone suffix.

Parameters:
  `date` - the Java `Date` to format
  `timezone` - the Java `TimeZone` to use
Returns:
  a DICOM formatted DT value

#### getFormattedStringUTC

    public static java.lang.String getFormattedStringUTC(java.util.Date date)

Get a DICOM format DT `String` value from a Java `Date`.

Will format the Date for the UTC timezone, converting from whatever timezone is specified in the supplied `Date` if not UTC.

Parameters:
  `date` - the Java `Date` to format
Returns:
  a DICOM formatted DT value

#### getFormattedStringDefaultTimeZone

    public static java.lang.String getFormattedStringDefaultTimeZone(java.util.Date date)

Get a DICOM format DT `String` value from a Java `Date`.

Will format the Date for the default timezone, converting from whatever timezone is specified in the supplied `Date` if not the default.

Parameters:
  `date` - the Java `Date` to format
Returns:
  a DICOM formatted DT value

#### getFormattedString

    public static java.lang.String getFormattedString(java.util.Date date)

Deprecated. use `getFormattedStringDefaultTimeZone()` instead

Get a DICOM format DT `String` value from a Java `Date`.

Will format the Date for the default timezone, converting from whatever timezone is specified in the supplied `Date` if not the default.

Parameters:
  `date` - the Java `Date` to format
Returns:
  a DICOM formatted DT value

#### getDateFromFormattedString

    public static java.util.Date getDateFromFormattedString(java.lang.String dateString)
                                                     throws java.text.ParseException

Get a Java `Date` from a DICOM format DT `String` value.

Parameters:
  `dateString` - the date to parse
Returns:
  a Java `Date`
Throws:
  `java.text.ParseException`

#### getDateFromFormattedString

    public static java.util.Date getDateFromFormattedString(AttributeList list,
                                            AttributeTag dateTag,
                                            AttributeTag timeTag)
                                                     throws java.text.ParseException,
                                                            DicomException

Get a Java `Date` from a DICOM format DT `String` value.

Will use the TimezoneOffsetFromUTC if present in the AttributeList, else will assume UTC (not whatever the local time zone happens to be).

Parameters:
  `list` - the list containing the attributes
  `dateTag` - the tag of the DA attribute
  `timeTag` - the tag of the TM attribute
Returns:
  a Java `Date`
Throws:
  `java.text.ParseException`
  `DicomException` - if date attribute is missing or empty

#### getTimeZone

    public static java.util.TimeZone getTimeZone(java.lang.String dicomTimeZone)

Get a Java `TimeZone` from a DICOM format `String` time zone.

E.g. from +0500 or -0700, the last component of a DateTime attribute value, or the value of the DICOM attribute TimezoneOffsetFromUTC.

Parameters:
  `dicomTimeZone` - the `String` DICOM format time zone
Returns:
  a Java `TimeZone` representing the supplied time zone, or the GMT zone if it cannot be understood

#### getTimeInMilliSecondsSinceEpoch

    public static long getTimeInMilliSecondsSinceEpoch(java.lang.String dateTime)
                                                throws java.text.ParseException

Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by the DT value.

Parameters:
  `dateTime` - the string to parse
Returns:
  the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this date; may be a ludicrous value if string not formatted correctly
Throws:
  `java.text.ParseException`

#### getTimeInMilliSecondsSinceEpoch

    public static long getTimeInMilliSecondsSinceEpoch(AttributeList list,
                                       AttributeTag dateTag,
                                       AttributeTag timeTag)
                                                throws java.text.ParseException,
                                                       DicomException

Returns the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by the combination of the DA and TM values of the specified pair of attributes.

Will use the TimezoneOffsetFromUTC if present in the AttributeList, else will assume UTC (not whatever the local time zone happens to be).

Parameters:
  `list` - the list containing the attributes
  `dateTag` - the tag of the DA attribute
  `timeTag` - the tag of the TM attribute
Returns:
  the number of milliseconds since January 1, 1970, 00:00:00 GMT represented by this date
Throws:
  `java.text.ParseException`
  `DicomException` - if date attribute is missing or empty