/ 
Module-Generic-v0.37.3
River stage two • 17 direct dependents • 20 total dependents
/ Module::Generic::DateTime

NAME

Module::Generic::DateTime - A DateTime wrapper for enhanced features

SYNOPSIS

use Module::Generic::DateTime;

my $dt = DateTime->new;
my $gdt = Module::Generic::DateTime->new( $dt );
# or directly will instantiate a default DateTime value based on DateTime->now
my $gdt = Module::Generic::DateTime->new;

# Now you can do operations that are not normally possible with DateTime
# Compare a dt object with a unix timestamp
if( $gdt > time() )
{
    # do something
}
elsif( $gdt < '2020-03-01 07:12:10+0900' )
{
    # do something
}
# and of course, comparison with other dt works as before
elsif( $gdt >= $dt )
{
    # do something
}

# Remove 10 seconds from time object
$gdt -= 10;
# Add 5 seconds and get a new object
my $dt2 = $gdt + 5;

# Get the difference as an interval between two objects
my $interval = $dt1 - $dt2;
# DateTime::Duration are represented by Module::Generic::DateTime::Interval
# and extra manipulations are possible
# Add 7 seconds
$int += 7;
# Change the days
$int->days( 5 );
# or using lvalue
$int->days = 5;
# or multiply everything (years, months, weeks, days, hours, minutes, seconds and nanoseconds) in the interval by 2
$int *= 2
# Multiply one interval by another:
my $new_interval = $int1 * $int2;
# or multiply with assignment
$int1 *= $int2;
# Then add the interval to the datetime object
$dt += $int;

VERSION

v0.5.0

DESCRIPTION

Module::Generic::DateTime is a thin wrapper around DateTime to provide additional features as exemplified above.

It also enables the DateTime object to be thawed and frozen and converted to JSON with the respective methods STORABLE_freeze, STORABLE_thaw, TO_JSON

All other method calls not in this API are passed to DateTime using AUTOLOAD with the added benefit that, if a method called triggers a fatal exception, it is caught using Nice::Try try-catch block and an error is set and return is returned instead.

CONSTRUCTOR

new

Provided with an optional DateTime object and this returns a new instance of Module::Generic::DateTime.

If no DateTime object was provided, this will instantiate one implicitly and set the formatter to stringify it to an iso8601 string, such as: 2022-03-08T14:22:10+0000. By default the instantiated DateTime object use the default time zone, which is GMT. You can change the time zone afterward using "set_time_zone" in DateTime:

$dt->set_time_zone( 'Asia/Tokyo' );

from_epoch

my $d = Module::Generic::DateTime->from_epoch( epoch => $unix_timestamp );

Instantiate a new Module::Generic::DateTime using the DateTime method from_epoch. Any parameters are passed through to "from_epoch" in DateTime

If a DateTime error occurs, it will be caught and an error will be set and undef will be returned.

now

my $d = Module::Generic::DateTime->now;

Instantiate a new Module::Generic::DateTime using the DateTime method now. Any parameters are passed through to "now" in DateTime

If a DateTime error occurs, it will be caught and an error will be set and undef will be returned.

METHODS

as_string

This is an alias to "stringify"

datetime

Sets or gets the underlying DateTime object.

op

This method is called to overload the following operations:

  • "" stringification

  • bool

  • > greater than

  • => greater or equal than

  • < lower than

  • <= lower or equal than

  • == euqal

  • != not equal

  • - minus

  • + plus

op_minus_plus

This methods handles cases of overloading for minus and plus

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

Additionally, upon loading Module::Generic::DateTime, it will ensure the following DateTime modules also have a FREEZE and THAW subroutines if not defined already: DateTime, DateTime::TimeZone, DateTime::TimeZone::OffsetOnly, DateTime::Locale::FromData, DateTime::Locale::Base

SEE ALSO

Module::Generic, Module::Generic::DateTime::Interval, DateTime, DateTime::Format::Strptime, DatetTime::TimeZone

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2000-2024 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.