DateTimeStatic

About

This singleton class provides “static” utility functions for working with instances of DateTime. You call these functions via the DateTime() method. For example, to call the .now() function:

var $now : cs.js.DateTime
$now:=DateTime.now()

Local timezone

When the singleton instance of this class is created, the current local timezone abbreviation and name (e.g. "PST" and "America/Los_Angeles") are read from the system. If that is successful, a process named "$refreshTimezone" is started which refreshes the timezone information every minute. This ensures the timezone information is always up to date, even during Daylight Savings Time transitions or when you move to a different timezone on a laptop.

NOTE

If you are using a laptop and want DateTime instances to use the timezone of the current location, be sure to configure your system to set the timezone automatically.

i18n

.getCustomFormat()

.getCustomFormat(name: Text { ; locale : Text }): Text

Each locale has a map of custom formats for use with DateTime.format(). Use this function if you want to examine the value of a custom format.

If locale is passed, it should be an IANA locale name, which will be resolved. If locale is not passed or is empty, the current locale is used.

If name exists in the custom formats for the resolved locale, it is returned. If it does not exist, an empty string is returned.


.setCustomFormat()

.setCustomFormat(name : Text; format : Text { ; locale : Text }) : Boolean

Each locale has a map of custom formats for use with DateTime.format(). Use this function if you want to set the value of a custom format. An existing format with the given name will be overwritten.

If locale is passed, it should be an IANA locale name, which will be resolved. If locale is not passed or is empty, the current locale is used.

If name or format is empty, or if name is the same as a DateTime formatting token or a standard DateTime localized format, false is returned. Otherwise if the format is successfully set, true is returned.

Timezones

.getSystemTimezone()

.getSystemTimezone() : Text

This function does the following:

  • On macOS, attempts to read the local timezone abbreviation and name by executing a shell script in the component’s Resources/scripts folder.

  • On Windows, attempts to read the local timezone abbreviation and name by executing a packaged python+script executable in the component’s Resources/scripts/getTimezone-windows folder.

  • If either of those fail, "" is returned.

  • If any of the above attempts succeeds, the abbreviation and name, separated by |, are returned.

Ordinarily you would have no need to call this function. It is called for you when the singleton instance of DateTimeStatic is created, and by the $refreshTimezone process started by the DateTimeStatic constructor.

TIP

If you will only use and deploy to macOS, you can safely delete the Resources/scripts/getTimezone-windows folder, which will greatly reduce the size of the component.


.getTimezone()

.getTimezone() : Text

Returns the current local timezone abbreviation and name separated by |.


.getTimezoneAbbrev()

.getTimezoneAbbrev() : Text

Returns the current local timezone abbreviation.


.getTimezoneName()

.getTimezoneName() : Text

Returns the current local timezone name.


.getTimezoneNames()

.getTimezoneNames() : Collection

Returns a collection with all of the possible timezone names in sorted order. This would be useful, for example, if you want to allow the user to select from a menu or list of timezone names.


.getTimezoneOffset()

getTimezoneOffset(timezone : Text) : Integer

Returns the UTC offset for the given timezone, which should be an IANA timezone abbreviation and name, separated by |.

If the abbreviation or name is missing or empty, it defaults to the current local value.

If the abbreviation or name is invalid, or if they result in an ambiguous UTC offset, -1 is returned.

Examples

$offset:=DateTime.getTimezoneOffset("PDT|America/Los_Angeles")
// => -25200

$offset:=DateTime.getTimezoneOffset("PPT|America/Los_Angeles")
// => -1 (invalid)

// CET is unique within Europe, this works
$offset:=DateTime.getTimezoneOffset("CET|Europe")
// => 3600

.getUTCOffset()

.getUTCOffset(date : Date; time : Time { ; isUTC : Boolean }) : Integer

Returns the UTC offset to the local timezone (as determined by the system) at the moment represented by date and time.

If isUTC is true, date and time are considered to be UTC, and the offset to local time is still returned.


.loadTzdata()

.loadTzdata() : Boolean

Loads the file js.component.4dbase/Resources/tzdata.json into memory. tzdata.json should be in the form created by the tzdata-ingesteropen in new window.

If the file is successfully loaded, true is returned.

If the file cannot be found or if the file is malformed, a SystemError is thrown and false is returned.

NOTE

This function is called for you when the singleton instance of DateTimeStatic is created. You should only ever need to call this function if you have replaced tzdata.json with a newer version without restarting the host db.


.timezoneRefreshInterval

.timezoneRefreshInterval : Integer
.timezoneRefreshInterval := interval : Integer

The interval, in seconds, at which the local timezone is refreshed. The default is 15 seconds.

As a setter, if interval is less than 1, it is set to 1.


.tzdata

.tzdata : Collection

A collection containing the timezone data loaded by .loadTzdata(). Each element of the collection is an object with the following properties:

PropertyTypeDescription
tzNameTextThe timezone name
stdAbbrevTextThe Standard Time timezone abbreviation
dstAbbrevTextThe Daylight Savings Time abbreviation
stdOffsetNumberThe Standard Time UTC offset in seconds
dstOffsetNumberThe Daylight Savings Time UTC offset in seconds

For timezones that do not observe Daylight Savings Time, dstAbbrev will be empty and dstOffset will be the same as stdOffset.

This property is null if .loadTzdata() fails — in which case almost all DateTime functionality will fail! If it is not null, it should be considered read-only.

NOTE

tzdata.json only represents the current state of timezones around the world. It does not contain any data about Daylight Savings Time transitions, which is why you must correctly specify the timezone abbreviation and name for a given date and time when specifying timezones.

Utilities

.add()

.add(sourceDate : Date; sourceTime : Time; amounts : Object) : Object

Returns an object with sourceDate and sourceTime adjusted by the given amounts. amounts is an object which may have one or more of the following numeric properties, with missing properties treated as zero:

.years .months .weeks .days .time .hours .minutes .seconds

If .time is present, .hours, .minutes, and .seconds are ignored. Overflows or underflows adjust the next highest unit accordingly. For example:

$date:=!2022-08-27!
$time:=?22:58:00?

$amounts:=New object(\
 "years"; 1; \
 "months"; 1; \
 "days"; 1; \
 "hours"; 1; \
 "minutes"; 2; \
 "seconds"; 27\
 )

$result:=DateTime.add($date; $time; $amounts)
// $result => { date: !2023-09-29!, time: ?00:00:27? }

.factorSeconds()

.factorSeconds(seconds : Integer) : Object

Returns an object which factors a number of seconds into the numeric properties .hours, .minutes and .seconds. ``


.formatUTCOffset()

.formatUTCOffset(offset: Integer { ; separator: Boolean }) : Text

Returns offset (in seconds) in standard ISO format. If separator is true, : is placed between the hours and minutes.

Examples

$offset:=DateTime.formatUTCOffset(-(?08:00:00?)+0)
// => "-0800"

$offset:=DateTime.formatUTCOffset(-(?08:00:00?)+0; True)
// => "-08:00"

$offset:=DateTime.formatUTCOffset(0)
// => "+0000"

.makeTime()

.makeTime(hours : Integer { ; minutes : Integer { ; seconds : Integer }}) : Object

Creates a Time from the constituent values and returns an object with two properties:

  • .time : The calculated time in seconds, clipped to a 24 hour range
  • .days : The number of days that overflowed or underflowed

Omitted values default to zero.

Examples

// In these examples, $result.time is seconds, but I'm displaying
// time to make it easier to see what's going on.

$result:=DateTime.makeTime(1; 2)
// => { time: ?01:02:00?, days: 0 }

$result:=DateTime.makeTime(27; 127; 127)
// => { time: ?05:09:07?, days: 1 }

$result:=DateTime.makeTime(1; -127; 127)
// => { time: ?22:55:07?, days: -1 }

$result:=DateTime.makeTime(1; -127; -127)
// => { time: ?22:50:53?, days: -1 }

.now()

.now({ "*" }) : cs.js.DateTime

A convenience function for creating a DateTime at the current local date/time. If "*" is passed, the date and time are retrieved from Server.


.subtract()

.subtract(sourceDate : Date; sourceTime : Time; amounts : Object) : Object

This is the same as .add(), but subtracts values instead of adding.


.utc()

.utc() : cs.js.DateTime
.utc(input : Text) : cs.js.DateTime
.utc(date : Date { ; time : Time { ; ms : Integer }}) : cs.js.DateTime

Creates a DateTime where the input parameters are considered to be UTC rather than local time. For more information on the parameters, see the DateTime constructor.

Although the input parameters are considered UTC, the created DateTime is in local mode.

NOTE

If the first parameter is not a string or a Date, an invalid DateTime is returned.

Example

// Local time on 2022-08-28 is UTC-0700
$dt:=DateTime.utc(!2022-08-28!; ?03:00:00?)
$date:=$dt.utc.date  // 2022-08-28
$time:=$dt.utc.time  // 03:00:00
$date:=$dt.date      // 2022-08-27
$time:=$dt.time      // 20:00:00
Last Updated:
Contributors: Aparajita