I am not able to understand one specific part of doc provided for the plusDays() method in ZonedDateTimeClass. Doc states:
Returns a copy of this ZonedDateTime with the specified number of days added.
This operates on the local time-line, adding days to the local date-time. This is then converted back to a ZonedDateTime, using the zone ID to obtain the offset.
When converting back to ZonedDateTime, if the local date-time is in an overlap, then the offset will be retained if possible, otherwise the earlier offset will be used. If in a gap, the local date-time will be adjusted forward by the length of the gap.
This instance is immutable and unaffected by this method call.
Params: days – the days to add, may be negative
Returns: a ZonedDateTime based on this date-time with the days added, not null
Throws: DateTimeException – if the result exceeds the supported date range
How I understand this: Assume we have ZonedDateTime object representing September 4, 2022 6 PM in America/New_York TimeZone. So this method will first convert it to LocalDateTime, that is, it will lose timezone information and just retain September 4, 2022 6 PM. It will add some number of days to it, let's say 7, so that the result is September 11, 2022 6 PM, and now it will convert it back to ZonedDateTime object by providing back the information related to timezone.
However, I am not able to understand the latter part of documentation, that is,
When converting back to ZonedDateTime, if the local date-time is in an overlap, then the offset will be retained if possible, otherwise the earlier offset will be used. If in a gap, the local date-time will be adjusted forward by the length of the gap.
What do they mean by local date-time is in an overlap? ...then the offset will be retained if possible, otherwise the earlier offset will be used. - what are these two different offsets? If in a gap... - what is this gap?
Can someone please help me understand this part of the doc?
Thank you in advance.