Design and implementation of phase 02

[BuddhiWathsala]

• Subtask of Revamp the time APIs #1057
• Add leap seconds and time zone supports.

[BuddhiWathsala]

In the second phase, we can implement the following APIs according to the initial design. @daneshk FYI.

// Time zones

type Zone readonly & object {
  // if always at a fixed offset from Utc, then this
  // function returns it; otherwise nil
  function fixedOffset() returns ZoneOffset?;
  // this does not pay attention to timeZoneOffset nor dayOfWeek
  // it does pay attention to utc
  function utcFromCivil(Civil civilTime) returns Utc|Error;
  function utcToCivil(Utc utc) returns Civil;
};

final Zone systemZone = check loadSystemZone();

// Get a time zone from Ballerina's internal database
// of time zones.
// id is  of form "Continent/City"
function getZone(string id) returns Zone?;

[BuddhiWathsala]

The design phase 02 in this doc mentioned that,

  // this does not pay attention to timeZoneOffset nor dayOfWeek
  // it does pay attention to utc
  function utcFromCivil(Civil civilTime) returns Utc|Error;

Should this be rephrased as it does pay attention to time zone?.

And why we don't need to return an error from the getZone like we did in loadSystemZone. @jclark @daneshk

[daneshk]

The design phase 02 in this doc mentioned that,

  // this does not pay attention to timeZoneOffset nor dayOfWeek
  // it does pay attention to utc
  function utcFromCivil(Civil civilTime) returns Utc|Error;

Should this be rephrased as it does pay attention to time zone?.

Yes, It does pay attention to the time zone, not for the timeZoneOffset in the Civil record passed as input.

And why we don't need to return an error from the getZone like we did in loadSystemZone.

IMO, the getZone method is similar to maps where we have zone ids as keys and Zone as values. nonexistent entries should return nil rather than errors similar to maps. On the other hand, the loadSystemZone method should always return value unless there is a system error which is okay to return an error.