I am trying to ensure that calling toString() on my ZonedDateTime Object will comply with ISO-8601 format.
The documentation for the toString() method states:
…The output is compatible with ISO-8601 if the offset and ID are the same
Does this mean that there exists a situation where calling zdt.getOffset() will return something different than zdt.getZone().getRules().getOffset(zdt.toInstant()) ?
This doesn’t seem to make sense.
Can someone provide an example in which the offset and ID are not the same (ie: where toString() does not comply with ISO-8601) so that I can better understand the description in the documentation.
Best Answer
The example in the documentation is 2007-12-03T10:15:30+01:00[Europe/Paris]. This happens not to be ISO compliant since ISO-8601 does not include the [Europe/Paris] part. This was added by the java.time developers in a compromise between getting as close to the standard as reasonable and still provding the time zone information in an unambiguous way.
So the real question may in fact be the opposite: if ZonedDateTime.toString() includes the time zone information that ISO does not include, when is the result fully ISO compliant? What does “if the offset and ID are the same” mean? Here we have to remember that ZoneOffset is a subclass of ZoneID and may be used as a zone ID in ZonedDateTime. In this case the offset and the ID are the same. Otherwise they are not. For a specific example, ZonedDateTime.now(ZoneOffset.ofHours(+2)).toString() may produce 2017-04-26T15:04:59.828+02:00. This is fully ISO compatible because the zone is given as just +02:00, which is the same as the offset. Also ZonedDateTime.now(ZoneOffset.UTC).toString() gives something in the format 2017-04-26T13:04:59.828Z. Since Z counts as an offset, this is compatible too.
I think that in most cases it won’t be very useful. If your zone is just an offset, you would usually prefer to use OffsetDateTime over ZonedDateTime, and if so, of course you don’t care whether ZonedDateTime.toString() is ISO compatible or not
Date Reference Util Function
fun Long.toInstant(): Instant {
return Instant.ofEpochMilli(this)
}
fun Instant.toCurrentZonedDateTime(zoneId: ZoneId = ZoneId.systemDefault()): ZonedDateTime {
return ZonedDateTime.ofInstant(this, zoneId)
}
fun Instant.toSgZonedDateTime(): ZonedDateTime {
return ZonedDateTime.ofInstant(this, ZoneId.of(("Asia/Singapore")))
}
fun Instant.toUTCDateTime(): ZonedDateTime {
return this.toCurrentZonedDateTime(zoneId = ZoneOffset.UTC)
}
fun ZonedDateTime.toStandardISO8601(): String {
return this.withZoneSameInstant(ZoneOffset.UTC).toString()
}
fun ZonedDateTime.toSingaporeStandardISO8601IgnoreUTCZoneId(): String {
return ZonedDateTime.of(this.toLocalDateTime(), ZoneId.of("Asia/Singapore")).toStandardISO8601()
}
fun ZonedDateTime.toSingaporeZoneDateTime(): ZonedDateTime {
return this.withZoneSameInstant(ZoneId.of("Asia/Singapore"))
}
fun String?.parseStandardISO8601(formatter: DateTimeFormatter = DateTimeFormatter.ISO_OFFSET_DATE_TIME): ZonedDateTime? {
if (this == null) return null
return try {
ZonedDateTime.parse(this, formatter)
} catch (e: Exception) {
null
}