[Time] Add support add/subtract specified amount of year, month, date from the given time

[daneshk]

Description: In the current time module, we only support adding/subtracting seconds from the given time in UTC. This is because we don't support advanced cases like leap seconds, daylight saving, etc in the module. If we need to support adding/subtracting specific no of year, month, and date, we need to consider those scenarios as well.

This task is to check the possibility of supporting it in the time module.

Refer: https://github.com/wso2-enterprise/internal-support-ballerina/issues/743

[daneshk]

Extracted from the Ballerina time module specification,

Nominal duration

A specification of a duration in terms of a variety of units (e.g. months, years) which can be resolved to a definite duration only relative to a particular timestamp.

Apart from seconds, the units are

• minutes
• hours
• days
• weeks
• months
• years

Note that all of these other than seconds are affected by leap seconds.

If you ignore leap seconds, all except months and years can be resolved into a definite number of seconds independent of a timestamp.

We can represent this as a record with optional fields (or with fields defaulting to 0).

Arithmetic using nominal durations and broken-down date-time has several cases that are poorly defined e.g.

• January 31st + 1 month
• February 29th (on a leap year) + 1 month
• In local time, 23.5 hours before clocks go forward + 1 day (i.e. at which will be skipped over by moving clocks forward)

There's an algorithm in XML Schema Part 2 we can use https://www.w3.org/TR/xmlschema-2/#adding-durations-to-dateTimes

[daneshk]

In practice, handling leap seconds is often done by relying on systems or services (like NTP servers) that are designed to manage leap seconds. Most applications simply ignore leap seconds because their occurrence is so infrequent and they typically have a negligible impact on most time calculations.

Leap Seconds in Java:

• Unix Time Basis: Java’s java.time API is based on the Unix time system, which typically counts time in seconds since the Unix epoch (1970-01-01T00:00:00Z). Unix time does not account for leap seconds; it assumes a consistent 86400 seconds per day.
• No Direct Leap Second Support: Since Java's Instant, LocalDateTime, ZonedDateTime, and other classes in java.time are built on top of this system, they do not recognize or handle leap seconds. Instead, they assume that every minute has exactly 60 seconds, even during a leap second.
• Ignoring Leap Seconds: When a leap second occurs (e.g., 2015-06-30T23:59:60Z), Java’s Instant and related classes will not represent that extra second. Instead, they will move from 23:59:59 directly to 00:00:00 of the next day.
• Continuous Time Flow: Java treats time as flowing continuously without accounting for the occasional extra second that a leap second introduces. This is generally acceptable for most applications, but it can lead to slight inaccuracies in environments where exact timekeeping is critical.

Leap Seconds in Golang:

• Unix Time Basis: Go’s time.Time type is based on the Unix time system, which counts time in seconds since the Unix epoch (1970-01-01T00:00:00Z). Unix time does not include leap seconds and assumes that every day has exactly 86400 seconds.
• Ignoring Leap Seconds: Go does not recognize or handle the extra second during a leap second event. If a leap second occurs, Go's time functions will skip directly from 23:59:59 to 00:00:00 of the next day, just like in Java.

Python's Time Libraries:

• Unix Time Basis: Python's datetime module and the time functions in the time module are based on Unix time, which does not include leap seconds. Unix time assumes that each day has exactly 86400 seconds.
• No Native Leap Second Handling: Python’s datetime and time modules do not recognize or represent the 23:59:60 leap second. If a leap second occurs, Python will skip directly from 23:59:59 to 00:00:00 of the next day.

[daneshk]

When adding a duration to a specific timestamp while considering Daylight Saving Time (DST), you need to account for potential DST transitions that may cause the local time to shift forward or backward. Here we need timezone-aware timestamps

Using timezone-aware objects (like ZonedDateTime in Java or datetime with pytz/zoneinfo in Python) ensures that any DST-related shifts are accurately reflected in the final timestamp.

[daneshk]

The proposed design contains APIs to cater to the following scenarios,

• Time zone agnostic calculation. The operation is purely mathematical. For example, adding one hour adds one hour to the current time without considering whether that hour crosses a DST boundary.

• Time zone aware calculation(Handles Daylight Saving Time (DST)).

• The Time duration record definition,

  # The time duration record, used to pass the datetime value, needs to be added or subtracted from the civil time.
  # Fields can be negative. The negative value will be subtracted from the civil time.
  # if any of the three fields are > 0, then all must be >= 0
  # if any of the three fields are < 0, then all must be <= 0
  type Duration record {|
  int years?;
  int months?;
  int weeks?;
  int days?;
  int hours?;
  int minutes?;
  Seconds seconds?;
  |};

• The module-level method which is time-zone agnostic.

  # Adds the given datetime duration to the given civil time. This is a time zone-agnostic calculation
  #
  # + civil - The civil time to which the duration should be added
  # + deltaTime - The time duration to be added
  public isolated function civilAddDuration(Civil civil, Duration dateTime) returns Civil;

Sample code:

time:Civil civil = check time:civilFromString("2021-04-12T23:20:50.520Z");
time:Duration duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6};
time:Civil newCivil = time:civilAddDuration(civil, duration);

• The time zone aware calculation needs a new API inside the Zone object like below.

public type Zone readonly & object {

    # If always at a fixed offset from Utc, then this function returns it; otherwise nil.
    #
    # + return - The fixed zone offset or nil
    public isolated function fixedOffset() returns ZoneOffset?;

    # Converts a given `Civil` value to an `Utc` timestamp based on the time zone value.
    #
    # + civil - `Civil` time
    # + return - The corresponding `Utc` value or an error if `civil.timeAbbrev` is missing
    public isolated function utcFromCivil(Civil civil) returns Utc|Error;

    # Converts a given `Utc` timestamp to a `Civil` value based on the time zone value.
    #
    # + utc - `Utc` timestamp
    # + return - The corresponding `Civil` value
    public isolated function utcToCivil(Utc utc) returns Civil;

    # Adds the given datetime duration to the given civil time.  This is a time zone-aware calculation
    # + civil - The civil time to which the duration should be added
    # + deltaTime - The datetime duration to be added
    public isolated function civilAddDuration(Civil civil, Duration dateTime) returns Civil;
};

Sample code

time:TimeZone timeZone = check new("Asia/Colombo");
time:Civil localTime = check timeZone.utcToCivil(time:utcNow());
time:Duration duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6};
time:Civil newCivil = timeZone.civilAddDuration(localTime, duration);

[daneshk]

@jclark @sameerajayasoma, could you please review the proposed API to add duration for the civil record? The requirement is to add/subtract a DateTime (provided by the user) from the current date and get the modified date. We only provide the utcAddSeconds[1] API that works with seconds.

1. https://central.ballerina.io/ballerina/time/latest#utcAddSeconds