Date API - Documentation | www.HtmlElements.com

DateTime API

Overview

The DateTime object represents an object that can store, display, and process date and time information. DateTime has a high precision, up to 1 yoctosecond (10-24 seconds).

To instantiate a DateTime object, the user has to include the following files to the head of the page:

  • smart.element.js - the base class;
  • smart.date.js - the JS file containing the class DateTime.

Initialization

A DateTime object can be instantiated by calling the DateTime class constructor with different arguments, depending on the user's preference. The available options are listed below:

  • No arguments - the current date and time are stored in the object (equivalent to the standard new Date() construction): 
    const newDateTime = new Smart.Utilities.DateTime();
  • One argument 'today' - the current date and time are stored in the object (equivalent to the standard new Date() construction): 
    const newDateTime = new Smart.Utilities.DateTime('today');
    A second argument can optionally be passed to denote the time zone.
  • One argument 'todayDate' - the current date is stored in the object (but not the current time): 
    const newDateTime = new Smart.Utilities.DateTime('todayDate');
    A second argument can optionally be passed to denote the time zone.
  • One argument of type Date - an equivalent DateTime object is created: 
    const newDateTime = new Smart.Utilities.DateTime(new Date(2013, 2, 1, 2, 30, 15));
    A second argument can optionally be passed to denote the time zone.
  • One string argument representing a date. The string should be in a format recognized by the Date.parse() method: 
    const newDateTime = new Smart.Utilities.DateTime('2018-12-17T03:24:00');
    A second argument can optionally be passed to denote the time zone.
  • More than two arguments, each one representing a time part. These are:
    • year
    • month - unlike in standard Date objects, when initializing a DateTime object, 1 means January, 2 - February, 3 - March, etc.
    • day
    • hour (optional)
    • minute (optional)
    • second (optional)
    • millisecond (optional)
    • microsecond (optional)
    • nanosecond (optional)
    • picosecond (optional)
    • femtosecond (optional)
    • attosecond (optional)
    • zeptosecond (optional)
    • yoctosecond (optional)
    const newDateTime = new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11);

Formatting Date and Time

The DateTime class provides a method called toString that returns a string with the stored date and time information formatted based on a format string. There are a number of built-in format strings that are listed below:

  • d - short date pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('d');
// Result is "3/12/1920"
  • D - long date pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('D');
// Result is "Friday, March 12, 1920"
  • t - short time pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('t');
// Result is "8:34 AM"
  • T - long time pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('T');
// Result is "8:34:21 AM"
  • f - long date, short time pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('f');
// Result is "Friday, March 12, 1920 8:34 AM"
  • F - long date, long time pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('F');
// Result is "Friday, March 12, 1920 8:34:21 AM"
  • M - month/day pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('M');
// Result is "March 12"
  • Y - month/year pattern 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('Y');
// Result is "1920 March"
  • FP - full precision (from year to yoctosecond) 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('FP');
// Result is "1920-03-12 08:34:21:089:019:800:002:333:018:045:011"
  • FT - full precision time (from hour to yoctosecond) 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('FT');
// Result is "08:34:21:089:019:800:002:333:018:045:011"
  • PP - processor precision (from year to picosecond) 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('PP');
// Result is "1920-03-12 08:34:21:089:019:800:002"
  • PT - processor precision time (from hour to picosecond) 
    new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('PT');
// Result is "08:34:21:089:019:800:002"

A custom format string can also be applied. The custom format string can be constructed using the following sub-strings:

  • ddd - day of the week, as a three-letter abbreviation
  • dddd - day of the week, using the full name
  • d - day of month, without leading zero for single-digit days
  • dd - day of month, with leading zero for single-digit days
  • MMM - month, as a three-letter abbreviation
  • MMMM - month, using the full name
  • M - month, as digits, with no leading zero for single-digit months
  • MM - month, as digits, with leading zero for single-digit months
  • y - year, as two digits, but with no leading zero for years less than 10
  • yy - year, as two digits, with leading zero for years less than 10
  • yyyy - year represented by four full digits
  • h - hours with no leading zero for single-digit hours, using 12-hour clock
  • hh - hours with leading zero for single-digit hours, using 12-hour clock
  • H - hours with no leading zero for single-digit hours, using 24-hour clock
  • HH - hours with leading zero for single-digit hours, using 24-hour clock
  • m - minutes with no leading zero for single-digit minutes
  • mm - minutes with leading zero for single-digit minutes
  • s - seconds with no leading zero for single-digit seconds
  • ss - seconds with leading zero for single-digit seconds
  • t - one character am/pm indicator ('a' or 'p')
  • tt - multicharacter am/pm indicator
  • f - deciseconds
  • ff - centiseconds
  • fff - milliseconds
  • u - microseconds with no leading zero for single-digit microseconds.
  • uu - microseconds with leading zero for single-digit microseconds.
  • n - nanoseconds with no leading zero for single-digit nanoseconds.
  • nn - nanoseconds with leading zero for single-digit nanoseconds.
  • p - picoseconds with no leading zero for single-digit picoseconds.
  • pp - picoseconds with leading zero for single-digit picoseconds.
  • e - femtoseconds with no leading zero for single-digit femtoseconds.
  • ee - femtoseconds with leading zero for single-digit femtoseconds.
  • a - attoseconds with no leading zero for single-digit attoseconds.
  • aa - attoseconds with leading zero for single-digit attoseconds.
  • x - zeptoseconds with no leading zero for single-digit zeptoseconds.
  • xx - zeptoseconds with leading zero for single-digit zeptoseconds.
  • o - yoctoseconds with no leading zero for single-digit yoctoseconds.
  • oo - yoctoseconds with leading zero for single-digit yoctoseconds.
  • z - time zone offset, no leading zero
  • zz - time zone offset with leading zero
  • zzz - time zone offset with leading zero

Here is an example of applying custom format strings:

new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('dd-MMM-yy HH:mm:ss.fff');
// Result is "12-Mar-20 08:34:21.089"
new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11).toString('dddd-MMMM-yyyy');
// Result is "Friday-March-1920"

Methods

Along with toString, the DateTime class provides the following methods:

Formatting Methods

  • toDateString - equivalent to the standard Date method of the same name. Returns the date portion of a DateTime object in human readable form in American English.
  • toLocaleDateString - equivalent to the standard Date method of the same name. Returns a string with a language sensitive representation of the date portion of the date.
  • toLocaleString - equivalent to the standard Date method of the same name. Returns a string with a language sensitive representation of the date.
  • toLocaleTimeString - equivalent to the standard Date method of the same name. Returns a string with a language sensitive representation of the time portion of the date.

To set the locale required for these methods, set the calendar.locale field of the DateTime object.

const newDateTime = new Smart.Utilities.DateTime(2013, 3, 1, 2, 30, 15);
newDateTime.calendar.locale = 'de';
newDateTime.toDateString();
// Result is "Fri Mar 01 2013"
newDateTime.toLocaleDateString();
// Result is "1.3.2013"
newDateTime.toLocaleString();
// Result is "1.3.2013, 02:30:15"
newDateTime.toLocaleTimeString();
// Result is "02:30:15"

Methods for Getting Time Parts

The following methods can be used to get the value of a particular time part of the DateTime object:

  • year
  • month
  • day
  • hour
  • minute
  • second
  • millisecond
  • microsecond
  • nanosecond
  • picosecond
  • femtosecond
  • attosecond
  • zeptosecond
  • yoctosecond
const newDateTime = new Smart.Utilities.DateTime(1920, 3, 12, 8, 34, 21, 89, 19, 800, 2, 333, 18, 45, 11);
const years = newDateTime.year();
// years is "1920"
const hours = newDateTime.hour();
// hours is "8"
const microseconds = newDateTime.microsecond();
// microseconds is "19"
const yoctoseconds = newDateTime.yoctosecond();
// yoctoseconds is "11"

Methods for Incrementing/Decrementing Time Parts

The following methods can be used to increment/decrement the value of a time part of the DateTime object:

  • addYears(value, createNew)
  • addMonths(value, createNew)
  • addDays(value, createNew)
  • addHours(value, createNew)
  • addMinutes(value, createNew)
  • addSeconds(value, createNew)
  • addDeciseconds(value, createNew)
  • addCentiseconds(value, createNew)
  • addMilliseconds(value, createNew)
  • addMicroseconds(value, createNew)
  • addNanoseconds(value, createNew)
  • addPicoseconds(value, createNew)
  • addFemtoseconds(value, createNew)
  • addAttoseconds(value, createNew)
  • addZeptoseconds(value, createNew)
  • addYoctoseconds(value, createNew)

The value parameter denotes the amount to increment (if positive) or decrement (if negative) the time part with. The createNew parameter determines if the DateTime object will be modified or a new one will be returned.

const newDateTime = new Smart.Utilities.DateTime(2013, 3, 1, 2, 30, 15);
const years = newDateTime.year();
// years is "1920"
const hours = newDateTime.hour();
// hours is "8"
const microseconds = newDateTime.microsecond();
// microseconds is "19"
const yoctoseconds = newDateTime.yoctosecond();
// yoctoseconds is "11"

Other Methods

There are several additional methods part of the DateTime object:

  • clone - clones a DateTime object.
  • clearTime - returns a new DateTime object with the same date, but with hour-yoctosecond time parts set to 0.
  • compare - compares two DateTime objects. Returns 1 if the first date is later than the second one, -1 if the second date is later than the first one, and 0 if dates are equal. All time parts (year-yoctosecond) are compared by this method.
  • toDate - returns an equivalent JavaScript Date object. Retains precision up to milliseconds. An optional parameter denoting a time zone can be passed.
const newDateTime = new Smart.Utilities.DateTime(2013, 3, 1, 2, 30, 15);
const secondDateTime = newDateTime.clone();
// secondDateTime represents "3/1/2013, 2:30:15 AM"
const thirdDateTime = newDateTime.clearTime();
// secondDateTime represents "3/1/2013, 12:00:00 AM"
const comparison1 = newDateTime.compare(secondDateTime);
// secondDateTime is 0
const comparison2 = newDateTime.compare(thirdDateTime);
// secondDateTime is 1
const date = newDateTime.toDate();
// secondDateTime represents "3/1/2013, 2:30:15 AM"