Here is a basic example of how to use the Time::Piece module.

#!/usr/bin/perl
use strict;
use warnings;
use Time::Piece;
my $timepiece = Time::Piece->new();
print "$timepiece \n";

Which should return something like this.

Wed Jan 26 05:48:39 2022

Formatting the output

Here is an example of how to format the output using the built in mdy option.

#!/usr/bin/perl
use strict;
use warnings;
use Time::Piece;
my $timepiece = Time::Piece->new()->mdy;
print "$timepiece \n";

Which should produce a result in this format.

11-23-2021

Following are commonly used options.

Or strftime (string format time) can be used to format the output.

$timepiece = Time::Piece->new()->strftime("%m/%d/%Y");

Which should produce a result in this format in this example.

11/23/2021

Likewise, strptime can also be used to format the output. The date string being used (2021-04-16 in this example) must match the date format being used (%Y-%m-%d in this example).

$timepiece = Time::Piece->strptime("2022-11-23","%Y-%m-%d")->ymd('/');

However, this is a bit of an interesting animal, as strptime should return a result like this. Notice that although only the year, month and date were specified, the full datetime object is returned.

Thu Nov 11 00:00:00 2021

Often, the following is used to read the time.

$timepiece = Time::Piece->strptime("2021-11-23 05:48:12 -0500","%Y-%m-%d %H:%M:%S %z");

Which should now return the following.

Thu Nov 11 05:48:12 2021

However, almost always, you will use one of the built in options (such as mdy or ymd('/')) to reformat the output.

$timepiece = Time::Piece->strptime("2021-04-16 05:48:12 -0500","%Y-%m-%d %H:%M:%S %z")->mdy;

Or even back through strftime.

$timepiece = Time::Piece->strptime("2021-04-16 05:48:12 -0500","%Y-%m-%d %H:%M:%S %z")->strftime("%m/%d/%Y");

Compare Dates

Let's say you want to compare two different dates, to determine if one date is before or after another date. In this example, if the current date is before June 1st, then "before" will be printed. Else, "after" will be printed.

#!/usr/bin/perl
use strict;
use warnings;
use Time::Piece;

my $today = Time::Piece->new();
my $june  = Time::Piece->strptime("06/01/2022","%m/%d/%Y");

if ($today < $june) {
  print "$today is before $june \n";
}
else {
  print "$today is after $june \n";
}

Future / Past date time and epoch

Under the hood, the Time::Piece object contains an array of values which can be seen with Dumper.

use Data::Dumper;
use Time::Piece;
print Dumper $timepiece;

Which should return something like this.

$VAR1 = bless( [
                 34,         # seconds
                 51,         # minutes
                 23,         # hour
                 23,         # day of the month
                 10,         # month where 0 is January and 11 is December
                 '121',      # year
                 2,          # day of the week
                 326,        # day of the year
                 0,          # 0 means daylight savings is in effect, 1 means not in effect
                 1637733094, # epoch - number of seconds that have elapsed since 12/31/1969
                 1
               ], 'Time::Piece' );

Notice in this example that 1637733094 seconds that have elapsed since January 1st, 1970 (epoch). If you were to pass 1637733094 into the Time::Piece->new object, this would cause Time::Piece to return the date time as the number of seconds that have elapsed since 12/31/1969.

my $timepiece = Time::Piece->new('1637733094');

This is how you would go about setting a future or past date time. You would get the epoch of the future or past date time, and then use the epoch value in the Time::Piece->new object.

my $epoch = Time::Piece->strptime("2021-04-16 05:48:12 -0500","%Y-%m-%d %H:%M:%S %z")->epoch;
my $timepiece = Time::Piece->new($epoch);

Add or Substract days, weeks, months, years

The Time::Seconds module can be used to add or substract minutes, hours, days, weeks, months or years from a date time. Check out my article 

• ONE_HOUR
• ONE_MINUTE
• ONE_DAY
• ONE_WEEK
• ONE_MONTH
• ONE_FINANCIAL_MONTH
• ONE_YEAR
• LEAP_YEAR
• NON_LEAP_YEAR

Check out my article Add or subtract time using Time::Piece and Time::Seconds for more details on this.

#!/usr/bin/perl
use strict;
use warnings;
use Time::Piece;
use Time::Seconds;

my $timepiece = Time::Piece->new;
my $one_month_forward   = ($timepiece + ONE_MONTH);
my $two_months_forward  = ($timepiece + ONE_MONTH * 2);
my $one_month_backward  = ($timepiece - ONE_MONTH);
my $two_months_backward = ($timepiece - ONE_MONTH * 2);
my $one_day_forward     = ($timepiece + ONE_DAY);
my $one_days_backward   = ($timepiece - ONE_DAY);
my $two_days_backward   = ($timepiece - ONE_DAY * 2);

Optionally, here is how you could use ->ymd() to format the result.

#!/usr/bin/perl
use strict;
use warnings;
use Time::Piece;
use Time::Seconds;

my $timepiece = Time::Piece->new;
my $one_month_forward = ($timepiece + ONE_MONTH)->ymd();