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/scriptsfolder.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-windowsfolder.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-ingester.
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:
| Property | Type | Description |
|---|---|---|
tzName | Text | The timezone name |
stdAbbrev | Text | The Standard Time timezone abbreviation |
dstAbbrev | Text | The Daylight Savings Time abbreviation |
stdOffset | Number | The Standard Time UTC offset in seconds |
dstOffset | Number | The 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