formatTime()

Returns the time in a particular format.

Synopsis

string formatTime( string format, time t [, string milliFormat] );

Parameters

Parameter Description
format

Output format (without milliseconds) or in HTTP or ISO format.

If you specify the

"HTTP" format, the function returns the time in HTTP format and the milliseconds (string milliFormat) are ignored (see RFC 2616).

Example output: "Thu, 01 Jan 1970 00:00:00 GMT"

if you specify the

"ISO" format, it produces a dateTime string in ISO-8601 format.

Example output: "1969-12-31T17:00:00.000-07:00"
t time
milliFormat Output format for the milliseconds

Return value

The function returns the new time format as a string or in the event of errors an empty string.

Error

With incorrect variable types or invalid arguments

Description

The function formatTime() returns the time t given as time in a format defined by the arguments format and milliFormat. The string format contains the formatting with an accuracy of seconds. The parameters available for this are those of the function strftime() of the ANSI C standard:

Parameters Meaning
%a Abbreviated name of the weekday
%A full name of the weekday
%b Abbreviated name of the month
%B Full name of the month
%c Local representation of date and time
%d Day in the month (01 - 31)
%H Hour (00 - 23)
%I Hour (00 -12)
%j Day in the year (001 - 366)
%m Month (01 - 12)
%M Minute (00 - 59)
%p

Local equivalent of AM (morning) or PM (afternoon)

The parameter %p was implemented for use in English speaking countries.
%S Second (00 - 59)
%U Week in the year (Sunday is the first day of the week) (00 - 53)
%V ISO 8601 week number of the year (01–53, first week has at least 4 days in the new year)
%w Weekday (0-6, Sunday is 0!)
%W Week in the year (Monday is the first day of the week) (00-53)
%x Local representation of the date
%X Local representation of the time
%y Year without the century (00 - 99)
%Y Year with the century
%Z Name of the time zone if it exists
%% %

The format fprintf() is used in the optional string milliFormat to specify milliseconds. The corresponding output will be appended to the expression generated by the first format specification.

Tip:
To generate a UTC timestamp suitable for dpQuery() with PostgreSQL, use the ISO format and append "Z": 
string sTimerange = formatTime("ISO", t);
sTimerange = sTimerange + "Z";
For queries that require UTC timestamps (without local time zone offset), consider using formatTimeUTC() instead.

Example

The following example outputs the week in the year, date and time in the local time (localTime) and UTC time (utcTime).

main()
{
  time t1;
  string localTime;
  string utcTime;
  setTime(t1,2010,6,1,15);
  localTime = formatTime("%W; %c", t1, " ms: %04d");
  utcTime = formatTimeUTC("%W; %c", t1, " ms: %04d");
  DebugN("Local: ", localTime);
  //Output: ["Local: "]["22; 6/1/2010 3:00:00 PM ms: 0000"]
  DebugN("UTC: ", utcTime);
  //Output: ["UTC: "]["22; 6/1/2010 1:00:00 PM ms: 0000"]
}

The following example produces a dateTime string in ISO format.

main()
{
  string dt1;
  dt1 = formatTime("ISO", makeTime(2014, 6, 30, 18, 30, 3,
  7));
  DebugN("format time in ISO format:", dt1); 
}

Assignment

Time function

Availability

CTRL