Time Format plug-in parse functions

The Time Format plug-in parse functions parse the value contained by the timeDate parameter according to the format you specify in the format parameter. Each function returns the resulting value as a float of seconds since the epoch.

float parse(string format, string timeDate)
float parseTime(string format, string timeDate)

float parseUTC(string format, string timeDate)
float parseTimeUTC(string format, string timeDate)

float parseWithTimeZone(string format, string timeDate, string tzName)
float parseTimeWithTimeZone(string format, string timeDate, string tzName)

format	String that specifies the format of the value in the timeDate parameter. For details about what you can specify here, see Format specification for the Time Format plug-in functions.
timeDate	String that contains the time you want to parse.
name	String that specifies the name of a time zone.

Note: Release 4.1 added the parse(), parseUTC(), and parseWithTimeZone() functions to be consistent with the format(), formatUTC(), and formatWithTimeZone() functions. Previously, the Time Format plug-in provided only parseTime(), parseTimeUTC(), and parseTimeWithTimeZone(). The corresponding parse functions (for example, parse() and parseTime()) return the same results. There are no plans to deprecate the older functions.

The parse() and parseTime() functions parse the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting it as a date and time in the local timezone. Each function returns the resulting value as a float of seconds since the epoch.

The parseUTC() and parseTimeUTC() functions parse the value contained by the timeDate parameter according to the format you specify in the format parameter. Each function interprets the timeDate as a UTC date and time. The returned value is a float of seconds since the epoch.

The parseWithTimeZone() and parseTimeWithTimeZone() functions parse the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting it as a date and time in the local timezone. The returned value is a float of seconds since the epoch.

If the timeDate parameter specifies only a time, the date is assumed to be 1 January 1970 in the appropriate timezone. If the timeDate parameter specifies only a date, the time is assumed to be the midnight that starts that day in the appropriate timezone. Adding them together as seconds gives the right result.

Each function returns NaN if it cannot parse the specified string.

If timeDate string specifies a time zone, and there is a matching z, Z, v, or V in the format string, the time zone specified in the timeDate string takes precedence over any other ways of specifying the time zone. For example, when you call the parseUTC() or parseWithTimeZone() function, and you specify a time zone or offset in the timeDate string, the time zone or offset specification in the timeDate string overrides the time zone you specify as a parameter to the parseWithTimeZone() function and the normal interpretation of times and dates as UTC by the parseUTC() function.

Parsing behavior is undefined if the format string includes duplicate elements such as "MM yyyy MMMM", has missing elements such as "MM", or it includes potentially contradictory elements and is given contradictory input, for example, "Tuesday 3 January 1970" (it was actually a Saturday).

Dates before 1970 are represented by negative numbers.

timeFormat.parseWithTimeZone("DD.MM.YY Z", "01.01.70 +0900", "UTC");
timeFormat.parseUTC("DD.MM.YY Z", "01.01.70 +0900");

In the first example, the +0900 specification in the timeDate string overrides the UTC specification for the time zone name parameter. In the second example, the +0900 specification in the timeDate string overrides the UTC specified by calling the parseUTC() function.