DateTime
The DateTime value type stores an absolute time and a timezone.
An absolute time is a concrete point in time, and is the same for everyone regardless of where they are in the world. For example, the moment man landed on the moon is an absolute time.
A civil time is the regular "year/month/day hours:min:seconds" method of representing a time, such as 2017/9/12 at 1:10pm. A civil time does not represent an unambiguous absolute time as it varies depending on where you are in the world.
A timezone describes how to convert an absolute time into a civil time and vice versa. For example, man landed on the moon 1969/07/20 at 4:18pm in the America/New_York timezone and 1969/07/21 at 6:18am in the Australia/Sydney timezone.
Internally a DateTime stores an absolute time and a specific timezone. When you access civil time properties, such as the hours or date properties, the timezone is used to convert the absolute time into a civil time. If you change the DateTime's timezone, using the toTimeZone() method, it will still refer to the same absolute time, but the civil time it returns will change.
Operators
Subtracting one DateTime from another returns the number of seconds between them.
var date1 = DateTime.time(7, 30, 0) var date2 = DateTime.time(8, 30, 0) Float seconds = date2 - date1 // 3600
You can use the subtraction operator to time how long something takes.
var startTime = DateTime.now() // Do some work System.log("Work took:", DateTime.now() - startTime)
Adding or subtracting a number from a DateTime adds or subtracts the specified number of seconds.
var date1 = DateTime.time(7, 30, 0) var date2 = date1 + 15 // 7:30:15
static function DateTime.now() → DateTime
static function DateTime.now(String timezone) → DateTime
static function DateTime.now(DateTime.TimeZone timezone) → DateTime
Returns the current date and time. If a timezone is not provided, the local timezone is used.
See DateTime.TimeZone for a description of the timezone format.
static function DateTime.time(Int hour, Int minute, Float second) → DateTime
static function DateTime.time(Int hour, Int minute, Float second, String timezone) → DateTime
static function DateTime.time(Int hour, Int minute, Float second, DateTime.TimeZone timezone) → DateTime
Returns the specified time, using the current date in the timezone provided. If a timezone is not specified, the local timezone is used.
See DateTime.TimeZone for a description of the timezone format.
function DateTime(Int year, Int month, Int date) → DateTime
function DateTime(Int year, Int month, Int date, String timezone) → DateTime
function DateTime(Int year, Int month, Int date, DateTime.TimeZone timezone) → DateTime
function DateTime(Int year, Int month, Int date, Int hour, Int minute, Float second) → DateTime
function DateTime(Int year, Int month, Int date, Int hour, Int minute, Float second, String timezone) → DateTime
function DateTime(Int year, Int month, Int date, Int hour, Int minute, Float second, DateTime.TimeZone timezone) → DateTime
Return a new DateTime for the specified civil date and time. If a timezone is not provided, the local timezone is used.
See DateTime.TimeZone for a description of the timezone format.
property Bool isValidread only
True if this is a valid date time, false otherwise. A DateTime is invalid if it has not been assigned a value. Modifying an invalid DateTime in any way will make it valid.
property Int dayOfWeekread only
property Int dayOfYearread only
The calendar year, month, date, day of the week and day of the year of the DateTime.
The year is the complete year value, such as 2016. The month ranges from 1-12, and the date from 1-31.
The dayOfWeek ranges from 0-6, with 0 corresponding to Sunday and 6 to Saturday. The dayOfYear ranges from 1-365 (or 1-366 on leap years).

The hour, minute, second and millisecond values of the DateTime.
Hour ranges from 0-23, minute from 0-59, second from 0-59 and millisecond 0-999.

property DateTime.TimeZone timeZoneread only
The DateTime's timezone. To change timezones, use the toTimeZone() method.
function toTimeZone(String timezone) → DateTime
function toTimeZone(DateTime.TimeZone timezone) → DateTime
Returns an equivalent DateTime in the specified timezone. If an invalid timezone is provided, the UTC timezone is used.
See DateTime.TimeZone for a description of the timezone format.
function format(String pattern) → String
Returns the formatted date string using the provided pattern.
The pattern string may contain any of the tokens shown below. Each matching token in the pattern is replaced with the corresponding date component value.
var date = DateTime(2017, 10, 9, 15, 13, 32); // 2017-10-09 at 3.13.32 PM System.log(date.format("YYYY-MM-DD 'at' h.mm.ss A"))
Characters in the pattern that do not form part of a token are left as is. However, as new tokens may be added in the future, it is safest to enclose these "pass through" characters in single quotes to ensure they are never treated as a pattern token.

function toISOString() → String
static function DateTime.parseISOString(String string) → DateTime
Create or parse an ISO 8061 date string from a DateTime. If the parsed data does not contain an understood ISO string, an invalid DateTime is returned.
var date = DateTime.parseISOString("1879-03-14T11:30:00+01:00") System.log(date.toISOString())
static function DateTime.fromUnixTime(Float seconds) → DateTime
Convert to and from Unix time.
Unix time, also known as POSIX time or UNIX Epoch time, is the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970, UTC, minus leap seconds.
DateTime values created from Unix time are in the UTC timezone by default. Use DateTime.toLocal() or DateTime.toTimeZone() to convert them to your local or target timezone.