Samsung Electronics logo

Samsung Web API: Time

© 2013 Samsung Electronics Co., Ltd. All rights reserved.

Introduction

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.

Table of Contents

Summary of Interfaces and Methods

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)

1. Type Definitions

1.1. TimeDurationUnit

TimeDuration unit (milliseconds, seconds, minutes, hours or days). 

  enum TimeDurationUnit { "MSECS", "SECS", "MINS", "HOURS", "DAYS" };

At least the following values must be supported:

  • MSECS - Indicates a duration in milliseconds
  • SECS - Indicates a duration in seconds
  • MINS - Indicates a duration in minutes
  • HOURS - Indicates a duration in hours
  • DAYS - Indicates a duration in days

2. Interfaces

2.1. TimeManagerObject

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.

2.2. TimeUtil

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:

  • Get the current date / time using getCurrentDateTime().
  • Get timezones using getLocalTimezone() and getAvailableTimezones().

METHODS

getCurrentDateTime

Returns the current date / time.

Signature
TZDate getCurrentDateTime();
Return value
TZDate Current TZDate object.
Exceptions
  • WebAPIException:

    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.

Code example
 var current_dt = webapis.time.getCurrentDateTime();
 console.log("current date / time is " + current_dt.toLocaleString());

getLocalTimezone

Returns identifier of the local system timezone.

Signature
DOMString getLocalTimezone();
Return value
Timezone Local timezone.
Exceptions
  • WebAPIException:

    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.

Code example
 console.log("The local time zone is " + webapis.time.getLocalTimezone());

getAvailableTimezones

Returns synchronously the identifiers of the timezones supported by the device.

Signature
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'.

Return value
Array of time zone identifiers.
Exceptions
  • WebAPIException:

    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.

Code example
 var tzids = webapis.time.getAvailableTimezones();
 console.log("The device supports " + tzids.length + " time zones.");

getDateFormat
Signature
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:

  • "d" = day number (1 to 31)
  • "D" = day name
  • "m" = month number (1 to 12)
  • "M" = month name
  • "y" = year

Examples of string formats include: "d/m/y", "y-d-m", "D, M d y".

Parameters
  • shortformat
    • Optional: Yes.
    • Nullable: Yes.
    • Type: boolean.
    • Description: Flag indicating if the user is interested in the short date format (23/10/2011) instead of a long date format ("Monday, October 23 2011"). By default, this attribute is set to false.
Return value
DOMString The date format according to the system's locale settings.
Exceptions
  • WebAPIException:

    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
Signature
DOMString getTimeFormat();

Returns the time format according to the system's locale settings.

These expressions may be used in the returned string:

  • "h" = hours (0 to 23 or 1 to 12 if AM/PM display)
  • "m" = minutes (0 to 59)
  • "s" = seconds (0 to 59)
  • "ap" = AM/PM display

Examples of string formats include: "h:m:s ap", "h:m:s".

Return value
DOMString The time format according to the system's locale settings.
Exceptions
  • WebAPIException:

    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.

Signature
boolean isLeapYear(long year);
Parameters
  • year
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Year to check.
Exceptions
  • WebAPIException:

    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.

Code example
 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.");

2.3. TZDate

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);
  };

METHODS

getDate

Returns the day of the month (from 1-31).

Signature
long getDate();

setDate

Sets the day of the month (from 1-31).

Signature
void setDate(long date);
Parameters
  • date
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Date to set.

getDay

Returns the day of the week (from 0-6).

Signature
long getDay();

getFullYear

Returns the year (four digits).

Signature
long getFullYear();

setFullYear

Sets the year (four digits).

Signature
void setFullYear(long year);
Parameters
  • year
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Year to set.

getHours

Returns the hour (0-23).

Signature
long getHours();

setHours

Sets the hour (0-23).

Signature
void setHours(long hours);
Parameters
  • hours
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Hours to set.

getMilliseconds

Returns the milliseconds (from 0-999).

Signature
long getMilliseconds();

setMilliseconds

Sets the milliseconds (from 0-999).

Signature
void setMilliseconds(long ms);
Parameters
  • ms
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Milliseconds to set.

getMinutes

Returns the minutes (from 0-59).

Signature
long getMinutes();

setMinutes

Sets the minutes (from 0-59).

Signature
void setMinutes(long minutes);
Parameters
  • minutes
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Minutes to set.

getMonth

Returns the month (from 0-11).

Signature
long getMonth();

setMonth

Sets the month (from 0-11).

Signature
void setMonth(long month);
Parameters
  • month
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Month to set.

getSeconds

Returns the seconds (from 0-59).

Signature
long getSeconds();

setSeconds

Sets the seconds (from 0-59).

Signature
void setSeconds(long seconds);
Parameters
  • seconds
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Seconds to set.

getUTCDate

Returns the day of the month, according to universal time (from 1-31).

Signature
long getUTCDate();

setUTCDate

Sets the day of the month, according to universal time (from 1-31).

Signature
void setUTCDate(long date);
Parameters
  • date
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Date to set.

getUTCDay

Returns the day of the week, according to universal time (from 0-6).

Signature
long getUTCDay();

getUTCFullYear

Returns the year, according to universal time (four digits).

Signature
long getUTCFullYear();

setUTCFullYear

Sets the year, according to universal time (four digits).

Signature
void setUTCFullYear(long year);
Parameters
  • year
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Year to set.

getUTCHours

Returns the hour, according to universal time (0-23).

Signature
long getUTCHours();

setUTCHours

Sets the hour, according to universal time (0-23).

Signature
void setUTCHours(long hours);
Parameters
  • hours
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Hours to set.

getUTCMilliseconds

Returns the milliseconds, according to universal time (from 0-999).

Signature
long getUTCMilliseconds();

setUTCMilliseconds

Sets the milliseconds, according to universal time (from 0-999).

Signature
void setUTCMilliseconds(long ms);
Parameters
  • ms
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Milliseconds to set.

getUTCMinutes

Returns the minutes, according to universal time (from 0-59).

Signature
long getUTCMinutes();

setUTCMinutes

Sets the minutes, according to universal time (from 0-59).

Signature
void setUTCMinutes(long minutes);
Parameters
  • minutes
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Minutes to set.

getUTCMonth

Returns the month, according to universal time (from 0-11).

Signature
long getUTCMonth();

setUTCMonth

Sets the month, according to universal time (from 0-11).

Signature
void setUTCMonth(long month);
Parameters
  • month
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Month to set.

getUTCSeconds

Returns the seconds, according to universal time (from 0-59).

Signature
long getUTCSeconds();

setUTCSeconds

Sets the seconds, according to universal time (from 0-59).

Signature
void setUTCSeconds(long seconds);
Parameters
  • seconds
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Seconds to set.

getTimezone

Returns timezone identifier.

Signature
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.

Signature
TZDate toTimezone(DOMString tzid);
Parameters
  • tzid
    • Optional: No.
    • Nullable: No.
    • Type: DOMString.
    • Description: Timezone identifier to set.
Return value
TZDate New TZDate in given Timezone.
Exceptions
  • WebAPIException:

    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.

Signature
TZDate toLocalTimezone();
Return value
TZDate The new TZDate in local Timezone.
Exceptions
  • WebAPIException:

    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).

Signature
TZDate toUTC();
Return value
TZDate Date/Time in UTC.
Exceptions
  • WebAPIException:

    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.

Signature
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:

  • Negative, if other is in the future
  • 0 if the two date / times are equal
  • Positive, if other is in the past
Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TZDate.
    • Description: Other Date/Time to compare to.
Return value
TimeDuration Duration in milliseconds between the two date / time objects (or in days for comparison between dates with no time component).
Exceptions
  • WebAPIException:

    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.

Signature
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.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TZDate.
    • Description: Other Date/Time to compare to.
Return value
boolean True if the 2 date/times are the same.
Exceptions
  • WebAPIException:

    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.

Signature
boolean earlierThan(TZDate other);

This method takes the timezones into consideration.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TZDate.
    • Description: Other Date/Time to compare to.
Return value
boolean True, if the Date/Time is earlier than the one passed in argument.
Exceptions
  • WebAPIException:

    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.

Signature
boolean laterThan(TZDate other);

This method takes the timezones into consideration.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TZDate.
    • Description: Other Date/Time to compare to.
Return value
boolean True, if the Date/Time is later than the one passed in argument.
Exceptions
  • WebAPIException:

    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.

Signature
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.

Parameters
  • duration
    • Optional: No.
    • Nullable: No.
    • Type: TimeDuration.
    • Description: TimeDuration to add.
Exceptions
  • WebAPIException:

    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.

Code example
 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.

Signature
DOMString toLocaleDateString();
Return value
DOMString Date portion of the TZDate object as a string, using locale conventions.

toLocaleTimeString

Returns the time portion of a TZDate object as a string, using locale conventions.

Signature
DOMString toLocaleTimeString();
Return value
DOMString Time portion of the TZDate object as a string, using locale conventions.

toLocaleString

Converts a TZDate object to a string, using locale conventions.

Signature
DOMString toLocaleString();
Return value
DOMString String representation of the TZDate object, using locale conventions.

toDateString

Returns the date portion of a TZDate object as a string.

Signature
DOMString toDateString();
Return value
DOMString Date portion of the TZDate object as a string.

toTimeString

Returns the time portion of a TZDate object as a string.

Signature
DOMString toTimeString();
Return value
DOMString Time portion of the TZDate object as a string.

toString

Converts a TZDate object to a string.

Signature
DOMString toString();
Return value
DOMString String representation of the TZDate object.

getTimezoneAbbreviation

Determines the time zone abbreviation to be used at a particular date in the time zone.

Signature
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.

Return value
DOMString Abbreviation of the time zone (such as "EST").
Exceptions
  • WebAPIException:

    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.

Signature
long secondsFromUTC();

Returns the offset (in seconds) from UTC of the timezone, accounting for daylight savings if in effect in the timezone.

Return value
long Offset from UTC in seconds.
Exceptions
  • WebAPIException:

    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.

Code example
 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.

Signature
boolean isDST();

Indicates if daylight savings are in effect for the time zone and instant identified by the TZDate object.

Return value
boolean Flag indicating if daylight saving are in effect.
Exceptions
  • WebAPIException:

    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.

Signature
TZDate? getPreviousDSTTransition();
Return value
TZDate The date of the previous daylight saving transition (before the instant identified by the TZDate).
Exceptions
  • WebAPIException:

    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.

Signature
TZDate? getNextDSTTransition();
Return value
TZDate The date of the next daylight saving transition (after the instant identified by the TZDate).
Exceptions
  • WebAPIException:

    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.

2.4. TimeDuration

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);
  };
Code example
 var now = webapis.time.getCurrentDateTime();
 var tomorrow = now.addDuration(new webapis.TimeDuration(1, "DAYS")); // Becomes tomorrow, same time.

ATTRIBUTES

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).

METHODS

difference

Calculates the difference between two TimeDuration objects.

Signature
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.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TimeDuration.
    • Description: Other TimeDuration object to compare to.
Return value
New TimeDuration object corresponding to the result of this - other.
Exceptions
  • WebAPIException:

    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.

Code example
 // 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.

Signature
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.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TimeDuration.
    • Description: Other TimeDuration object to compare to.
Return value
boolean True if the two TimeDuration object represent the same duration.
Exceptions
  • WebAPIException:

    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.

Code example
 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.

Signature
boolean lessThan(TimeDuration other);

This method takes the units into consideration when doing the comparison.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TimeDuration.
    • Description: Other TimeDuration object to compare to.
Return value
boolean True if the TimeDuration is less than other.
Exceptions
  • WebAPIException:

    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.

Code example
 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.

Signature
boolean greaterThan(TimeDuration other);

This method takes the units into consideration when doing the comparison.

Parameters
  • other
    • Optional: No.
    • Nullable: No.
    • Type: TimeDuration.
    • Description: Other TimeDuration object to compare to.
Return value
boolean True if the TimeDuration is greater than other.
Exceptions
  • WebAPIException:

    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.

Code example
 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

3. Full WebIDL 

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);
  };
};