Timestamp

A textual representation of a moment in time, with additional support handling invalid user inputs and for the special timestamp NOW. Allowing invalid user inputs to be stored in a Timestamp ensures that com.fwdekker.randomness.ui.JDateTimeField does not reset the input field after an invalid input has been written.

A Timestamp is similar in function to LocalDateTime: Both represent the notation of time rather than the moment in time itself, and neither supports timezones. The most important differences with LocalDateTime are that the Timestamp's value is not guaranteed to be valid, and that the Timestamp's value may be the special value NOW. Call doValidate to determine if (and why) the value is (in)valid.

The canonical format for the value is defined by FORMAT. However, values are interpreted quite liberally, so a value that deviates from FORMAT may still be valid. For example, a value of 5819 is equivalent to a value of 5819-01-01 00:00:00.000. This liberal interpretation is performed by DateParserUtils. The constructor of Timestamp proactively reformats the value into the FORMAT. Therefore, a Timestamp contains a valid value if and only if value matches the FORMAT after the constructor completes. The only exception is for the case-sensitive special value, which always refers to the current moment in time, is never re-formatted, and is always valid.

To represent a Timestamp which is guaranteed to be valid, use LocalDateTime instead.

Note that this class is not a data class. This is because the value field must be re-formatted in the constructor, but the field must also remain immutable. This requirement cannot be fulfilled with a data class.