Package 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
    Modifier and Type | Field | Description
    --- | --- | ---
    `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 | 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

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `allowRepairOfIncorrectLength()` |
    `protected boolean` | `allowRepairOfInvalidCharacterReplacement()` |
    `static java.lang.String` | `getCurrentTimeZone()` | Get a DICOM format `String` time zone representation of the current timezone.
    `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)` | Get a DICOM format DT `String` value from a Java `Date`.
    `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.
    `static java.lang.String` | `getTimeZone​(java.util.TimeZone javaTimeZone, java.util.Date javaDate)` | Get a DICOM format `String` time zone from a Java `TimeZone` on a particular Java `Date` .
    `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

      `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, 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 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` - if an I/O error occurs
        `DicomException` - if error in DICOM encoding

    - #### 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` - if an I/O error occurs
        `DicomException` - if error in DICOM encoding

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

      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` - if incorrectly encoded

    - #### 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` - if incorrectly encoded
        `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

    - #### getTimeZone

          public static java.lang.String getTimeZone​(java.util.TimeZone javaTimeZone,
                                                     java.util.Date javaDate)

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

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

      Parameters:
        `javaTimeZone` - the `TimeZone` time zone
        `javaDate` - the `Date` used to establish whether daylight savings is in effect or not
      Returns:
        a DICOM format `String` time zone representing the supplied time zone on the supplied date

    - #### getCurrentTimeZone

          public static java.lang.String getCurrentTimeZone()

      Get a DICOM format `String` time zone representation of the current timezone.

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

      Returns:
        a DICOM format `String` time zone representing the current time zone on the current date

    - #### 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` - if incorrectly encoded

    - #### 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` - if incorrectly encoded
        `DicomException` - if date attribute is missing or empty