Time API Guide

Overview

The Tizen Time API supports the use of locale-specific calendar features by enabling your application to retrieve the current local time for a given date. Time API allows you to set a date and time for a particular time zone. It also facilitates converting one time zone to another. For a given date, you can perform calculations to convert local time to any date in the past, present, or future and also handle daylight saving time (DST) information. To use this API, add the required permissions to the config.xml file (see prerequisites section below). When the application is launched, a time object is instantiated automatically in the tizen object. The tizen.time object is an instance of the TimeUtil interface, which provides date, time, and time zone management features.

Figure below shows how the API objects are structured inside the application window.

 

 

Time object   

 

 

 

Time Object 

 

 

 

 

 

Prerequisites

The Time API has different levels of access to handle system and sensitive data. You can enable different permissions for the Time API in the config.xml file.

Get current date and time

The Time API provides the TimeUtil interface which allows you to work with current system date and current system time.

You can get and set the current system date and time.

  • Get Current Date and Time

    The TimeUtil.getCurrentDateTime method retrieves the current system date and time. This method returns a TZDate object.

    // Retrieves the current system date time and writes to console.
    var current_dt = tizen.time.getCurrentDateTime();
    console.log ("current date / time is " + current_dt.toLocaleString());
    In addition, you can use access functions like tizen.time.TZDate.getFullYear(), tizen.time.TZDate.getMonth(),.. to retrieve the information of individual fields year, month,etc .

Create and set new date and time

Create an instance of the Time interface by passing the date, time and time zone values to the new tizen.TZDate() method.

// Creates a time interface instance with the given values
var newDT = new tizen.TZDate(2012, 9, 22, 2, 25, 23, 200, );
console.log ("date / time is " + newDT.toLocaleString());
  • Set Current Date and Time

    You can use methods like tizen.time.TZDate.setFullYear(), tizen.time.TZDate.setMonth(), tizen.time.TZDate.setHours(), tizen.time.TZDate.setMinutes() .. to set the values for individual fields year, month, hours, minutes, etc .

    // Creates a time interface instance with the given values
    var newDT = new tizen.TZDate(2012, 9, 22, 2, 25, 23, 200, );
    newDT.setMonth(2); // Sets month as March

    The following table shows the parameter for the TZDate interface constructor.

    Parameter Format Example
    year YYYY (4-digit year) 2011
    month MM (2-digit month) 11
    day DD (2-digit day of month) 10
    hours hh (2 digits of hours) 3 (or 03)
    minutes mm (2 digits of minutes) 45
    seconds ss (2 digits of seconds) 4 (or 04)
    milliseconds (3 digits of milliseconds) 999
    timezone specific descriptor 1/specific descriptor
    2/specific descriptor n(string)
    America/Argentina/Buenos_Aires
    Other than the day parameter, which begins from 1, all parameters of the TZDate constructor begin from 0. This implies that, for the months of a year, the value for January is 0, for February, it is 1, and for December, it is 11. Therefore it may be convenient to add 1 to the returned value of tizen.time.TZDate.getMonth() method.

Get time zone information

  • Get Local time zone

    The TimeUtil.getLocalTimeZone method is used to get the local time zone. This method returns time zone as a string.

    // Sets the system date and time to Sep 22, 2012 and 01:32:46
    var newTZ = tizen.time.getLocalTimezone();
    console.log ("Local time zone is " + newTZ);
  • Get available time zones

    A list of available time zones can be obtained using the tizen.time.getAvailableTimezones() method.

    // Gets the list of available time zones and prints the number to console
    var tzList = tizen.time.getAvailableTimezones();
    console.log ("The device supports  " + tzList.length + "time zones");
  • Get time zone abbreviation

    The TZDate.getTimezoneAbbreviation() method determines the time zone abbreviation to be used at a particular date in the time zone.

    // Gets abbrevation of the time zone
    var current_dt = tizen.time.getCurrentDateTime();
    var tzAbbr = current_dt.getTimezoneAbbreviation();
    console.log ("Time zone abbrevation " + tzAbbr);

Check date and time formats

The TimeUtil interface provides methods for getting the format of the date and time.

  • Get Time Format

    You can get the system's local time format using the tizen.time.getTimeFormat() method. Returns a string. For example, you can get "h:m:s ap", where h denotes hours (0 to 23 or 1 to 12 if AM/PM display), m denotes minutes (0 to 59), s denotes seconds (0 to 59) and ap stands for AM/PM display format.

    // Gets the system's local time format and prints to console
    var timeFormat = tizen.time.getTimeFormat();
    console.log ("System's local time format " + timeFormat);
    Many time formats are supported in Tizen which include hh:mm:ss (for example, 16:08:27), and hh:mm:ss ap (for example, 04:08:27 PM)
  • Get Date Format

    You can get the system's local date format using the tizen.time.getDateFormat() method. Returns a string. For example, you can get string "d/m/y", where d stands for day, m stands for month and y denotes year.

    // Gets the system's local date format and prints to console
    var dateFormat = tizen.time.getDateFormat();
    console.log ("System's local date format " + dateFormat);
    Many date formats are supported in Tizen which include DD/MM/YYYY (for example, 23/10/1996), YYYY-DD-MM (for example, 1996-23-10), and hybrid formats (for example, Wednesday, October 23, 1996.)

Check for leap year

A leap year is a year containing one extra day in order to keep the calendar year synchronized with the astronomical or seasonal year. In each leap year, the month of February has 29 days instead of 28.

If you are creating a calendar-based application or accepting a birth date on an application form, you must validate user input for a leap year date value. For example, 29/02/2011 is invalid user input.

The TimeUtil.isLeapYear method is used to check whether the given year is a leap year. This method takes the year input in the YYYY format.

en.time.getCurrentDateTime();
var is_leap = tizen.time.isLeapYear(current_dt.getFullYear());
if (is_leap)
   console.log("This year is a leap year.");
In JavaScript, the Date object does not have a mechanism to check for a leap year. So, you must perform mathematical calculations to achieve this. By using the Tizen TZDate object, you only need to call the isLeapYear method to check for a leap year.

Time conversion

The Time API’s TimeDuration interface provides methods to convert time to local or specified time zone and to UTC standard time.

var now = tizen.time.getCurrentDateTime();
var newtz = now.toTimezone();
var str = newtz.getTimezone();
console.log("Converted time zone " + str);
newtz = date.toLocalTimezone();
str = newtz.getTimezone();
console.log("Local time zone " + str);
var tzUTC = newtz.toUTC();
console.log("UTC standard time " + tzUTC.toLocaleString());

Calculate difference in time

The Time API’s TimeDuration interface provides the difference method to calculate the difference between two date or time events without having to bother about the difference in the event units. TimeDuration.difference method accepts another TimeDuration object and performs a (this object – parameter object) operation, and returns a TimeDuration object.

// Compute event1.duration - event2.duration
var diff = event1.duration.difference(event2.duration);
if (diff.length > 0)
   console.log("Event1 is longer than Event2");
else if (diff.length = 0)
   console.log("Event1 is as long as Event2");
else
   console.log("Event1 is shorter than Event2");
The unit of the returned TimeDuration object is equivalent to the largest possible unit amongst the source parameter units while making sure that precision is not lost in the result. This implies that if, for example, when the comparison is made between "1 hour" and "20 minutes", the result of the difference are displayed as 40 minutes, not 0.67 hour. Although the hour unit is bigger than the minute unit, the result is more precise if presented in minutes.

Check whether daylight saving time enabled

Daylight saving time, also known as Summer time is used to make better use of daylight

The TzDate.isDST method is used to check if DST has been enabled for the current time zone

var current_dt = tizen.time.getCurrentDateTime();
var is_DST = current_dt.isDST;
if (is_DST)
   console.log("Day light saving is enabled");
  • Get previous DST transition

    Returns the date of the previous daylight saving time transition for the timezone.

    var now = tizen.time.getCurrentDateTime();
    var tzDT = now.getPreviousDSTTransition();
  • Get Next DST transition

    Returns the date of the next daylight saving time transition for the timezone.

    var now = tizen.time.getCurrentDateTime();
    var tzDT = now.getNextDSTTransition();
DST (or summer time) is the practice of clocks being advanced temporarily by a fixed time during the summer to take advantage of more daylight. Typically, this temporary adjustment is one hour. For example, one hour shift ahead in time will cause the last moment of 20:59 to jump to 22:00 instead of 21:00. In this case, the day will have 23 hours. In another scenario, one hour shift back in time will cause the day to have 25 hours

Change time duration

You can use the tizen.time.TZDate.addDuration() method to add the specified number of seconds to the current time or the specified number of days to the current date; the duration is of type TimeDuration.

// a journey in time
var now = tizen.time.getCurrentDateTime();
var newDT = now.addDuration(new tizen.TimeDuration(5, "DAYS"));

Compare time

There are three methods for convenient time comparison: tizen.time.TZDate.equalsTo(), tizen.time.TZDate.earlierThan() and tizen.time.TZDate.laterThan(). Each of them should be applied to a TZDateobject and each of them returns a boolean value.

if(newDT.equalsTo(myGetCurrentDateTime.currentDT) == false) {
    // changed
    if(newDT.earlierThan(myGetCurrentDateTime.currentDT) == true ) {
        // earlier - time has stepped back!
    }
    if(newDT.laterThan(myGetCurrentDateTime.currentDT) == true ) {
        // later - time has elapsed.
    }
} else {
    // the same time!
}
File attachments: