Core Function Date

Date( <format>, <time> )

Description

Returns a string with the date and time formatted according to the format given. If no time is supplied defaults to the current time.

Parameters

format

The format string can consist of "*t" on its own to return an associative array containing:

sec (0 to 59)
min (0 to 59)
hour (0 to 23)
day (1 to 31)
month (1 to 12)
year (1900 onwards)
wday (Sunday is 1, Monday is 2 etc.)
yday (January 1st is 1, etc.)
isdst (true if Daylight Savings Time)

Or a literal strings, mixed with the following directives:

%A -- Full weekday name * -- Thursday
%a -- Abbreviated weekday name * -- Thu
%B -- Full month name * -- August
%b -- Abbreviated month name * -- Aug
%C -- Year divided by 100 and truncated to integer (00-99) -- 20
%c -- Date and time representation * -- Sun, 17 Aug 2014 16:07:02
%D -- Short MM/DD/YY date, equivalent to %m/%d/%y -- 08/23/01
%d -- Day of the month, zero-padded (01-31) -- 23
%E -- RFC1123 * -- Sun, 17 Aug 2014 15:49:28 GMT
%e -- Day of the month, space-padded ( 1-31)
%F -- Short YYYY-MM-DD date, equivalent to %Y-%m-%d -- 2001-08-23
%f -- Full Date Time * -- Sunday, 17 August 2014 15:52:07
%G -- ISO 8601 year (four digits)
%g -- ISO 8601 year (two digits)
%H -- Hour in 24h format (00-23) -- 14
%h -- Abbreviated month name * same as %b
%I -- Hour in 12h format (01-12) -- 02
%i -- Month & Day * -- August 17
%J -- Long date * -- Sunday, 17 August 2014
%j -- Day of the year (001-366) -- 235
%K -- Year & Month * -- 2014 August
%k -- Hour in 24h format, space-padded ( 7-23) -- 14
%L -- Short date * -- 08/17/2014
%l -- Hour in 12h format, space padded ( 1-12) -- 02
%M -- Minute (00-59) -- 55
%m -- Month as a decimal number (01-12) -- 08
%N -- 24-hour HH:MM time, equivalent to %H:%M -- 14:55
%n -- New-line character ('\n')
%O -- Long time * -- 15:46:35
%o -- Short time * -- 15:46
%p -- AM or PM designation (all uppercase) -- PM
%P -- am or pm designation (all lowercase) -- pm
%Q -- Milliseconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC
$R -- 24-hour clock time * -- 14:55
%r -- 12-hour clock time * -- 02:55:02 PM
%S -- Second (00-61) -- 02
%s -- Seconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC
%T -- ISO 8601 time format (HH:MM:SS), equivalent to %H:%M:%S -- 14:55:02
%t -- Horizontal-tab character ('\t')
%U -- Week number with the first Sunday as the first day of week one (00-53) -- 33
%u -- ISO 8601 weekday as number with Monday as 1 (1-7)
%V -- ISO 8601 week number
%v -- Date only, equivalent to %e-%b-%Y -- 8-Aug-2014
%W -- Week number with the first Monday as the first day of week one (00-53) -- 34
%w -- Weekday as a decimal number with Sunday as 0 (0-6) -- 4
%X -- Time representation * -- 14:55:02
%x -- Date representation * -- 08/23/01
%y -- Year, last two digits (00-99) -- 01
%Y -- Year -- 2001
%Z -- Timezone name or abbreviation * -- 2001
      If timezone cannot be determined, no characters
%Z -- ISO 8601 offset from UTC in timezone (1 minute=1, 1 hour=100)
      If timezone cannot be determined, no characters
%+ -- Full Date, equivalent to %a, %d %b %Y %H:%M:%S -- Sat, 16 Aug 2014 13:37:37
%: -- TimeSeparator * -- :
%/ -- DateSeparator * -- /
%% -- A literal percentage character ("%") -- %

Warning the specifiers marked with an asterisk (*) are locale-dependent.

If no time is provided for the second parameter the format may start with ! to indicate using UTC instead of the current time.

Regardless it will use the time as it is right now if you do not provide a time for it to use.

time

Optional; A time to use (time is provided in ticks).

If no time is supplied defaults to the current time (local machine time).

Return Value

Success: Returns a string containing the formatted time.

Failure: Returns NULL.

Remarks

None.

Example

Basic example

my $TimeStr = Date("Now it's %I:%M%p.");
say $TimeStr; // Now it's 05:19PM.

Another

my $TimeStr = Date("%A, %m %B %Y");
say $TimeStr; // Saturday, 08 August 2014

Creating an array

printr date("*t");   
// Array
// (
//     [sec] => 53
//     [min] => 20
//     [hour] => 16
//     [day] => 17
//     [month] => 8
//     [year] => 2014
//     [wday] => 0
//     [yday] => 229
//     [isdst] => true
// )

Create a List() of the from the associative array output but a special kind of List() that gets the values based on KEYS instead of INDEX

// Create the date array
$date = date("*t");
// Use @ to extract values from the array by KEY name
// instead of by index number like a normal List()
List (@$sec, @$min, @$hour, @$day, @$month, @$year, @$wday, @$yday, @$isdst) = $date;
say "Sec: $sec";
say "Min: $min";
say "Hour: $hour";
say "Day: $day";
say "Month: $month";
say "Year: $year";
say "WDay: $wday";
say "YDay: $yday";
say "IsDist: $isdst";
// Prints
// Sec: 19
// Min: 17
// Hour: 17
// Day: 19
// Month: 8
// Year: 2014
// WDay: 2
// YDay: 231
// IsDist: true