© 2013 Samsung Electronics Co., Ltd. All rights reserved.
The Time API provides information regarding date / time and time zones.
The JavaScript Date object does not have full timezone support. Date objects allow only simple representations to denote a particular location's offset from Universal Coordinated Time (UTC). This is typically provided as a +/- offset from UTC-0 (also known as Greenwich Mean Time, or GMT) for example, +05:30 denotes that a location is 5 hours and 30 minutes ahead of UTC +00:00. The issue with this method is not getting the correct local time for a given date. The existing methods are sufficient for this purpose. The issue is correctly converting to and from local time and UTC for all points in time - in any of the past, present, and future - based on an initial time provided. This is important for defining relative dates, where a time in a given location may observe different UTC offsets, according to any Daylight Savings Rules (DST) in effect or any other changes that may occur to a location's time zone over time. Without the communication of the explicit time zone rules governing a given date and time, the ability to effectively calculate the offset of the local time to UTC or to any other time zone at any point in the past or future is lost.
This API can be used to get TZDate objects with full time zone support, convert them between timezones, retrieve available timezones.
For more information on the Time features, see Time Guide.
Interface | Method |
---|---|
TimeManagerObject | |
TimeUtil | TZDate getCurrentDateTime() DOMString getLocalTimezone() DOMString[] getAvailableTimezones() DOMString getDateFormat(boolean? shortformat) DOMString getTimeFormat() boolean isLeapYear(long year) |
TZDate | long getDate() void setDate(long date) long getDay() long getFullYear() void setFullYear(long year) long getHours() void setHours(long hours) long getMilliseconds() void setMilliseconds(long ms) long getMinutes() void setMinutes(long minutes) long getMonth() void setMonth(long month) long getSeconds() void setSeconds(long seconds) long getUTCDate() void setUTCDate(long date) long getUTCDay() long getUTCFullYear() void setUTCFullYear(long year) long getUTCHours() void setUTCHours(long hours) long getUTCMilliseconds() void setUTCMilliseconds(long ms) long getUTCMinutes() void setUTCMinutes(long minutes) long getUTCMonth() void setUTCMonth(long month) long getUTCSeconds() void setUTCSeconds(long seconds) DOMString getTimezone() TZDate toTimezone(DOMString tzid) TZDate toLocalTimezone() TZDate toUTC() TimeDuration difference(TZDate other) boolean equalsTo(TZDate other) boolean earlierThan(TZDate other) boolean laterThan(TZDate other) TZDate addDuration(TimeDuration duration) DOMString toLocaleDateString() DOMString toLocaleTimeString() DOMString toLocaleString() DOMString toDateString() DOMString toTimeString() DOMString toString() DOMString getTimezoneAbbreviation() long secondsFromUTC() boolean isDST() TZDate? getPreviousDSTTransition() TZDate? getNextDSTTransition() |
TimeDuration | TimeDuration difference(TimeDuration other) boolean equalsTo(TimeDuration other) boolean lessThan(TimeDuration other) boolean greaterThan(TimeDuration other) |
TimeDuration unit (milliseconds, seconds, minutes, hours or days).
enum TimeDurationUnit { "MSECS", "SECS", "MINS", "HOURS", "DAYS" };
At least the following values must be supported:
Defines what is instantiated in the webapis object.
[NoInterfaceObject] interface TimeManagerObject { readonly attribute TimeUtil time; };
WebAPIs implements TimeManagerObject;
There will be a webapis.time object that allows accessing the functionality of the Time API.
The TimeUtil class that provides access to the time API.
[NoInterfaceObject] interface TimeUtil { TZDate getCurrentDateTime() raises(WebAPIException); DOMString getLocalTimezone() raises(WebAPIException); DOMString[] getAvailableTimezones() raises(WebAPIException); DOMString getDateFormat(optional boolean? shortformat) raises(WebAPIException); DOMString getTimeFormat() raises(WebAPIException); boolean isLeapYear(long year) raises(WebAPIException); };
This interface offers methods to manage date / time as well as timezones such as:
getCurrentDateTime
Returns the current date / time.
TZDate getCurrentDateTime();
with error type UnknownError, if the call failed due to an unknown error.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
var current_dt = webapis.time.getCurrentDateTime(); console.log("current date / time is " + current_dt.toLocaleString());
getLocalTimezone
Returns identifier of the local system timezone.
DOMString getLocalTimezone();
with error type UnknownError, if the call failed due to an unknown error.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
console.log("The local time zone is " + webapis.time.getLocalTimezone());
getAvailableTimezones
Returns synchronously the identifiers of the timezones supported by the device.
DOMString[] getAvailableTimezones();
Zero or more slashes separate different components of a timezone identifier, with the most general descriptor first and the most specific one last. For example, 'Europe/Berlin', 'America/Argentina/Buenos_Aires'.
with error type UnknownError, if the call failed due to an unknown error.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
var tzids = webapis.time.getAvailableTimezones(); console.log("The device supports " + tzids.length + " time zones.");
getDateFormat
DOMString getDateFormat(optional boolean? shortformat);
Returns the date format according to the system's locale settings.
These expressions may be used in the returned string:
Examples of string formats include: "d/m/y", "y-d-m", "D, M d y".
with error type UnknownError, if the call failed due to an unknown error.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
getTimeFormat
DOMString getTimeFormat();
Returns the time format according to the system's locale settings.
These expressions may be used in the returned string:
Examples of string formats include: "h:m:s ap", "h:m:s".
with error type UnknownError, if the call failed due to an unknown error.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
isLeapYear
Returns true if the given year is a leap year.
boolean isLeapYear(long year);
with error type UnknownError, if the call failed due to an unknown error.
with error type InvalidValuesError, if any of the input parameters contain an invalid value.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
var current_dt = webapis.time.getCurrentDateTime(); var is_leap = webapis.time.isLeapYear(current_dt.getFullYear()); if (is_leap) console.log("This year is a leap year.");
The TZDate object represents information regarding a given date / time in a predefined timezone.
[Constructor(optional Date? datetime, optional DOMString? timezone), Constructor(long year, long month, long day, optional long? hours, optional long? minutes, optional long? seconds, optional long? milliseconds, optional DOMString? timezone)] interface TZDate { long getDate(); void setDate(long date); long getDay(); long getFullYear(); void setFullYear(long year); long getHours(); void setHours(long hours); long getMilliseconds(); void setMilliseconds(long ms); long getMinutes(); void setMinutes(long minutes); long getMonth(); void setMonth(long month); long getSeconds(); void setSeconds(long seconds); long getUTCDate(); void setUTCDate(long date); long getUTCDay(); long getUTCFullYear(); void setUTCFullYear(long year); long getUTCHours(); void setUTCHours(long hours); long getUTCMilliseconds(); void setUTCMilliseconds(long ms); long getUTCMinutes(); void setUTCMinutes(long minutes); long getUTCMonth(); void setUTCMonth(long month); long getUTCSeconds(); void setUTCSeconds(long seconds); DOMString getTimezone(); TZDate toTimezone(DOMString tzid) raises(WebAPIException); TZDate toLocalTimezone() raises(WebAPIException); TZDate toUTC() raises(WebAPIException); TimeDuration difference(TZDate other) raises(WebAPIException); boolean equalsTo(TZDate other) raises(WebAPIException); boolean earlierThan(TZDate other) raises(WebAPIException); boolean laterThan(TZDate other) raises(WebAPIException); TZDate addDuration(TimeDuration duration) raises(WebAPIException); DOMString toLocaleDateString(); DOMString toLocaleTimeString(); DOMString toLocaleString(); DOMString toDateString(); DOMString toTimeString(); DOMString toString(); DOMString getTimezoneAbbreviation() raises(WebAPIException); long secondsFromUTC() raises(WebAPIException); boolean isDST() raises(WebAPIException); TZDate? getPreviousDSTTransition() raises(WebAPIException); TZDate? getNextDSTTransition() raises(WebAPIException); };
getDate
Returns the day of the month (from 1-31).
long getDate();
setDate
Sets the day of the month (from 1-31).
void setDate(long date);
getDay
Returns the day of the week (from 0-6).
long getDay();
getFullYear
Returns the year (four digits).
long getFullYear();
setFullYear
Sets the year (four digits).
void setFullYear(long year);
getHours
Returns the hour (0-23).
long getHours();
setHours
Sets the hour (0-23).
void setHours(long hours);
getMilliseconds
Returns the milliseconds (from 0-999).
long getMilliseconds();
setMilliseconds
Sets the milliseconds (from 0-999).
void setMilliseconds(long ms);
getMinutes
Returns the minutes (from 0-59).
long getMinutes();
setMinutes
Sets the minutes (from 0-59).
void setMinutes(long minutes);
getMonth
Returns the month (from 0-11).
long getMonth();
setMonth
Sets the month (from 0-11).
void setMonth(long month);
getSeconds
Returns the seconds (from 0-59).
long getSeconds();
setSeconds
Sets the seconds (from 0-59).
void setSeconds(long seconds);
getUTCDate
Returns the day of the month, according to universal time (from 1-31).
long getUTCDate();
setUTCDate
Sets the day of the month, according to universal time (from 1-31).
void setUTCDate(long date);
getUTCDay
Returns the day of the week, according to universal time (from 0-6).
long getUTCDay();
getUTCFullYear
Returns the year, according to universal time (four digits).
long getUTCFullYear();
setUTCFullYear
Sets the year, according to universal time (four digits).
void setUTCFullYear(long year);
getUTCHours
Returns the hour, according to universal time (0-23).
long getUTCHours();
setUTCHours
Sets the hour, according to universal time (0-23).
void setUTCHours(long hours);
getUTCMilliseconds
Returns the milliseconds, according to universal time (from 0-999).
long getUTCMilliseconds();
setUTCMilliseconds
Sets the milliseconds, according to universal time (from 0-999).
void setUTCMilliseconds(long ms);
getUTCMinutes
Returns the minutes, according to universal time (from 0-59).
long getUTCMinutes();
setUTCMinutes
Sets the minutes, according to universal time (from 0-59).
void setUTCMinutes(long minutes);
getUTCMonth
Returns the month, according to universal time (from 0-11).
long getUTCMonth();
setUTCMonth
Sets the month, according to universal time (from 0-11).
void setUTCMonth(long month);
getUTCSeconds
Returns the seconds, according to universal time (from 0-59).
long getUTCSeconds();
setUTCSeconds
Sets the seconds, according to universal time (from 0-59).
void setUTCSeconds(long seconds);
getTimezone
Returns timezone identifier.
DOMString getTimezone();
Zero or more slashes separate different components, with the most general descriptor first and the most specific one last. For example, 'Europe/Berlin', 'America/Argentina/Buenos_Aires'.
This attribute uniquely identifies the timezone.
toTimezone
Returns a copy of the TZDate converted to a given time zone.
TZDate toTimezone(DOMString tzid);
with error type UnknownError, if the call failed due to an unknown error.
with error type InvalidValuesError, if the provided TZID is not recognized as a valid timezone identifier.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
toLocalTimezone
Returns a copy of the TZDate converted to the local time zone.
TZDate toLocalTimezone();
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
toUTC
Returns a copy of the TZDate converted to Coordinated Universal Time (UTC).
TZDate toUTC();
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
difference
Calculates the difference with another TZDate object.
TimeDuration difference(TZDate other);
Calculates the difference in time between this and other. This comparison method takes timezones into consideration for the comparison.
The TimeDuration that is returned is effectively this - other. The return value is a duration in milliseconds both TZDate objects have a time component, in days, otherwise. The result value will be:
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
equalsTo
Checks if the TZDate is equal to another.
boolean equalsTo(TZDate other);
This method takes the timezones into consideration and will return true if the two TZDate objects represent the same instant in different timezones.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
earlierThan
Checks if the TZDate is earlier than another.
boolean earlierThan(TZDate other);
This method takes the timezones into consideration.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
laterThan
Checks if the TZDate is later than another.
boolean laterThan(TZDate other);
This method takes the timezones into consideration.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
addDuration
Returns a new date by adding a duration to the current TZDate object.
TZDate addDuration(TimeDuration duration);
If the length of duration is negative, the new date / time will be earlier than it used to.
Note that calling this method does not alter the current object.
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
TZDate now = webapis.time.getCurrentDateTime(); TZDate in_one_week = now.addDuration(new webapis.TimeDuration(7, "DAYS"));
toLocaleDateString
Returns the date portion of a TZDate object as a string, using locale conventions.
DOMString toLocaleDateString();
toLocaleTimeString
Returns the time portion of a TZDate object as a string, using locale conventions.
DOMString toLocaleTimeString();
toLocaleString
Converts a TZDate object to a string, using locale conventions.
DOMString toLocaleString();
toDateString
Returns the date portion of a TZDate object as a string.
DOMString toDateString();
toTimeString
Returns the time portion of a TZDate object as a string.
DOMString toTimeString();
toString
Converts a TZDate object to a string.
DOMString toString();
getTimezoneAbbreviation
Determines the time zone abbreviation to be used at a particular date in the time zone.
DOMString getTimezoneAbbreviation();
For example, in Toronto this is currently "EST" during the winter months and "EDT" during the summer months when daylight savings time is in effect.
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
secondsFromUTC
Gets the number of seconds from Coordinated Universal Time (UTC) offset for the timezone.
long secondsFromUTC();
Returns the offset (in seconds) from UTC of the timezone, accounting for daylight savings if in effect in the timezone.
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
var offset = webapis.time.getCurrentDateTime().secondsFromUTC(); var myDate = new Date(); var exp_offset = myDate.getTimezoneOffset()*60; //offset is equals to exp_offset.
isDST
Indicates if Daylight Saving Time(DST) is active for this TZDate.
boolean isDST();
Indicates if daylight savings are in effect for the time zone and instant identified by the TZDate object.
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
getPreviousDSTTransition
Returns the date of the previous daylight saving time transition for the timezone.
TZDate? getPreviousDSTTransition();
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
getNextDSTTransition
Returns the date of the next daylight saving time transition for the timezone.
TZDate? getNextDSTTransition();
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
The TimeDuration object that contains the length and its associated time unit.
[Constructor(long long length, optional TimeDurationUnit? unit)] interface TimeDuration { attribute long long length; attribute TimeDurationUnit unit; TimeDuration difference(TimeDuration other) raises(WebAPIException); boolean equalsTo(TimeDuration other) raises(WebAPIException); boolean lessThan(TimeDuration other) raises(WebAPIException); boolean greaterThan(TimeDuration other) raises(WebAPIException); };
var now = webapis.time.getCurrentDateTime(); var tomorrow = now.addDuration(new webapis.TimeDuration(1, "DAYS")); // Becomes tomorrow, same time.
long long length
Duration length.
The unit of the duration length (milliseconds, seconds, minutes, hours, or days) is determined by the duration unit attribute.
TimeDurationUnit unit
Duration unit (milliseconds, seconds, minutes, hours, or days).
The default value is "MSECS" (milliseconds unit).
difference
Calculates the difference between two TimeDuration objects.
TimeDuration difference(TimeDuration other);
Calculates the difference in time between this and other. The TimeDuration that is returned is effectively first - other (that is: positive if the first parameter is larger).
The returned TimeDuration is the biggest possible unit without losing the precision.
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
// Compute event1.duration - event2.duration var diff = event1.duration.difference(event2.duration); if (diff.length > 0) console.log("event 1's duration is longer than event 2's"); else if (diff.length == 0) console.log("event 1's duration is as long as event 2's"); else console.log("event 1's duration is shorter than event 2's");
equalsTo
Checks if the TimeDuration is equal to another.
boolean equalsTo(TimeDuration other);
This method takes the units into consideration and will return true if the two TimeDuration objects represent the same duration in different units.
with error type UnknownError, if the call failed due to an unknown error.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
var d1 = new webapis.TimeDuration(60, "MINS"); // 60 minutes var d2 = new webapis.TimeDuration(1, "HOURS"); // 1 hour var ret = d1.equalsTo(d2); // Returns true
lessThan
Checks if the TimeDuration is lower than another.
boolean lessThan(TimeDuration other);
This method takes the units into consideration when doing the comparison.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
var d1 = new webapis.TimeDuration(1, "HOURS"); // 1 hour var d2 = new webapis.TimeDuration(120, "MINS"); // 120 minutes var ret = d1.lessThan(d2); // Returns true
greaterThan
Checks if the TimeDuration is greater than another.
boolean greaterThan(TimeDuration other);
This method takes the units into consideration when doing the comparison.
with error type NotSupportedError, if access to this functionality was denied by the implementation.
with error type SecurityError, if this functionality is not allowed.
with error type UnknownError, if the call failed due to an unknown error.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
var d1 = new webapis.TimeDuration(120, "MINS"); // 120 minutes var d2 = new webapis.TimeDuration(1, "HOURS"); // 1 hour var ret = d1.greaterThan(d2); // Returns true
module Time { enum TimeDurationUnit { "MSECS", "SECS", "MINS", "HOURS", "DAYS" }; [NoInterfaceObject] interface TimeManagerObject { readonly attribute TimeUtil time; }; WebAPIs implements TimeManagerObject; [NoInterfaceObject] interface TimeUtil { TZDate getCurrentDateTime() raises(WebAPIException); DOMString getLocalTimezone() raises(WebAPIException); DOMString[] getAvailableTimezones() raises(WebAPIException); DOMString getDateFormat(optional boolean? shortformat) raises(WebAPIException); DOMString getTimeFormat() raises(WebAPIException); boolean isLeapYear(long year) raises(WebAPIException); }; [Constructor(optional Date? datetime, optional DOMString? timezone), Constructor(long year, long month, long day, optional long? hours, optional long? minutes, optional long? seconds, optional long? milliseconds, optional DOMString? timezone)] interface TZDate { long getDate(); void setDate(long date); long getDay(); long getFullYear(); void setFullYear(long year); long getHours(); void setHours(long hours); long getMilliseconds(); void setMilliseconds(long ms); long getMinutes(); void setMinutes(long minutes); long getMonth(); void setMonth(long month); long getSeconds(); void setSeconds(long seconds); long getUTCDate(); void setUTCDate(long date); long getUTCDay(); long getUTCFullYear(); void setUTCFullYear(long year); long getUTCHours(); void setUTCHours(long hours); long getUTCMilliseconds(); void setUTCMilliseconds(long ms); long getUTCMinutes(); void setUTCMinutes(long minutes); long getUTCMonth(); void setUTCMonth(long month); long getUTCSeconds(); void setUTCSeconds(long seconds); DOMString getTimezone(); TZDate toTimezone(DOMString tzid) raises(WebAPIException); TZDate toLocalTimezone() raises(WebAPIException); TZDate toUTC() raises(WebAPIException); TimeDuration difference(TZDate other) raises(WebAPIException); boolean equalsTo(TZDate other) raises(WebAPIException); boolean earlierThan(TZDate other) raises(WebAPIException); boolean laterThan(TZDate other) raises(WebAPIException); TZDate addDuration(TimeDuration duration) raises(WebAPIException); DOMString toLocaleDateString(); DOMString toLocaleTimeString(); DOMString toLocaleString(); DOMString toDateString(); DOMString toTimeString(); DOMString toString(); DOMString getTimezoneAbbreviation() raises(WebAPIException); long secondsFromUTC() raises(WebAPIException); boolean isDST() raises(WebAPIException); TZDate? getPreviousDSTTransition() raises(WebAPIException); TZDate? getNextDSTTransition() raises(WebAPIException); }; [Constructor(long long length, optional TimeDurationUnit? unit)] interface TimeDuration { attribute long long length; attribute TimeDurationUnit unit; TimeDuration difference(TimeDuration other) raises(WebAPIException); boolean equalsTo(TimeDuration other) raises(WebAPIException); boolean lessThan(TimeDuration other) raises(WebAPIException); boolean greaterThan(TimeDuration other) raises(WebAPIException); }; };