Add Support for Custom Time Duration Calculation

[DimuthuMadushan]

Purpose

Fixes: #6840

Examples

import ballerina/io;
import ballerina/time;

public function main() returns error? {
    time:Civil civil = check time:civilFromString("2025-04-13T17:35:30.120Z");
    civil = check time:civilAddDuration(civil, {years: 1, months: 3, days: 5, hours: 6, minutes: 9, seconds: 1});
    io:println("Civil value after adding duration: " + check time:civilToString(civil));

    time:TimeZone timeZone = check new("Asia/Colombo");
    civil = check time:civilFromString("2025-04-13T17:35:30.120-08:00[America/Los_Angeles]");
    civil = check timeZone.civilAddDuration(civil, {years: 1, months: 3, days: 5, hours: 6, minutes: 9, seconds: 1});
    io:println("Civil value after adding duration with zone: " + check time:civilToString(civil));
}

Output:

Civil value after adding duration: 2026-07-18T23:44:31.120Z
Civil value after adding duration with zone: 2026-07-19T13:14:31.120+05:30[Asia/Colombo]

Checklist

• Linked to an issue
• Updated the changelog
• Added tests
• Updated the spec
• Checked native-image compatibility

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.51%. Comparing base (016ed68) to head (70ce602).
Report is 3 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #521      +/-   ##
============================================
+ Coverage     92.36%   93.51%   +1.15%     
- Complexity       62       71       +9     
============================================
  Files            13       14       +1     
  Lines           406      478      +72     
  Branches         59       75      +16     
============================================
+ Hits            375      447      +72     
  Misses           23       23              
  Partials          8        8              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud