NAME

T - Stands for Time

This module mostly a handy wrapper around DateTime module.

SYNOPSIS

use T;

my $dt  =  T::new '2024-01-02 03:04:05';
my $now =  T::now;
my $day =  T::tday $now;
my $ymd =  T::fymd $now, '@';  # 2024@01@02

my $secs =  T::steady;

DESCRIPTION

T is a small helper module around DateTime. It normalizes dates into the local time zone and applies a Postgres-friendly formatter.

Please note, all DateTime objects are in 'local' timezone. It is differ in compare to DateTime where new() and now() functions return objects with 'float' and UTC timezones correspondigly. See DateTime for details.

All functions could be called without parameters, in this case they fallback to T::new.

FUNCTIONS

new

my $dt =  T::new;                          # Defaults to T::now.
my $dt =  T::new $dt;                      # Does nothing. Return as is.
my $dt =  T::new 1737936005;               # DateTime from epoch.
my $dt =  T::new '2024-01-02 03:04:05';    # Parse string.
my $dt =  T::new $value;

Parse $value into a DateTime object. All objects assigned 'DateTime::Format::Pg' formatter and local timezone. Parsing is done via 'DateTime::Format::Pg'.

• No arguments: return "now".

• False value: return undef.

• DateTime object: return it unchanged.

• Integer: treat as unix epoch seconds.

• String: parse using DateTime::Format::Pg.

tday

my $dt =  T::tday $value;       # 2025-03-07 05:34 -> 2025-03-07 00:00

Return $value truncated to the beginning of the day.

tmonth

my $dt =  T::tmonth $value;     # 2025-03-07 -> 2025-03-01

Return $value truncated to the beginning of the month.

tyear

my $dt =  T::tyear $value;      # 2025-03-07 -> 2025-01-01

Return $value truncated to the beginning of the year.

hnow

my $dt =  T::hnow;

High-resolution current time. See DateTime::HiRes for details.

now

my $dt =  T::now;

Current time. Synonym for DateTime::now but additionally assigned local timezone.

today

my $dt =  T::today;

Current date (start of the day). Alias to DateTime->today.

tmrw

my $dt =  T::tmrw $value;

Return "tomorrow" ($value truncated to day, plus one day).

nday

my $dt =  T::nday $value, $days;

Add $days days using "next" semantics.

nmonth

my $dt =  T::nmonth $value, $months;

Add $months months using "next" semantics.

nyear

my $dt =  T::nyear $value, $years;

Add $years years using "next" semantics.

next

my $dt =  T::next $value, days   => 1;
my $dt =  T::next $value, months => 1;
my $dt =  T::next $value, years  => 1;

Clone $value and add time using DateTime->add. It uses end_of_month => 'limit' to handle shorter months.

See DateTime->add for details.

first_day

my $dt =  T::first_day $value;                 # 2027-05-15    -> 2027-05-01
my $dt =  T::first_day $value, $months_ahead;  # 2027-05-15, 3 -> 2027-08-01

Return the first day of the month for $value. If $months_ahead is provided, move forward by that many months.

steady

my $seconds =  T::steady;

Return a monotonic timestamp in seconds when available, otherwise "time" in Time::HiRes.

fmt

my $str =  T::fmt $format;
my $str =  T::fmt $format, $value;

Format a date using strftime. $value is passed through "new". See "strftime" in DateTime for details. https://metacpan.org/pod/DateTime#strftime-Patterns

fymd

my $str =  T::fymd;
my $str =  T::fymd $value;
my $str =  T::fymd $value, $sep;

Format as YYYsepMsepDD.

fmdy

my $str =  T::fmdy;
my $str =  T::fmdy $value;
my $str =  T::fmdy $value, $sep;

Format as MsepDsepYYYY.

fdmy

my $str =  T::fdmy;
my $str =  T::fdmy $value;
my $str =  T::fdmy $value, $sep;

Format as DsepMsepYYYY.

fd

my $str =  T::fd;
my $str =  T::fd $value;

Format as YYYY-MM-DD. fd stands for 'format date'.

ft

my $str =  T::ft;
my $str =  T::ft $value;

Format as HH:MM:SS. ft stands for 'format time'.

ftm

my $str =  T::ftm;
my $str =  T::ftm $value;

Format as HH:MM:SS.NNNNNN. ftm stands for 'format time micro'.

fsm

my $str =  T::fsm;
my $str =  T::fsm $value;

Format as SS.NNNNNN. fsm stands for 'format seconds with microseconds'.

fdtm

my $str =  T::fdtm;
my $str =  T::fdtm $value;

Format as YYYY-MM-DD HH:MM:SS.NNNNNN. fdtm stands for 'format date time with microseconds'.

diff

my $days =  T::diff $dt1, $dt2;

Return the day delta between two DateTime objects. See "delta_days" in DateTime for details.

SEE ALSO

DateTime, DateTime::Format::Pg, A, C, I, L, M, S, T, U.

cpanm App::Ground

perl -MCPAN -e shell
install App::Ground