NAME

Moment - class that represents the moment in time

VERSION

version 1.3.0

SYNOPSIS

Moment is a Perl library. With this library you can create object that represent some moment in time.

The library works with date and time in the UTC timezone. The purpose of not supporting other timezones is to force good practice in working with time. The best way to manage time in program is to store and to work with time in UTC.

There are 4 ways you can create new object with the new() constructor:

my $some_moment = Moment->new(
    # dt format is 'YYYY-MM-DD hh:mm:ss'
    dt => '2014-11-27 03:31:23',
);

my $other_moment = Moment->new(
    year => 2014,
    month => 1,
    day => 3,

    hour => 4,
    minute => 2,
    second => 10,
);

my $one_more_moment = Moment->new(
    # Unix time (a.k.a. POSIX time or Epoch time)
    timestamp => 1000000000,
);

my $moment_from_iso_string = Moment->new(
    # ISO 8601
    iso_string => '2015-11-07T10:51:22Z',
);

You can also use now() constructor to create object that points to the current moment in time:

my $now = Moment->now();

When you have an object you can you use methods from it.

Here are the methods to get the values that was used in constructor:

#'2014-11-27 03:31:23'
my $dt = $moment->get_dt();
my $d = $moment->get_d();
my $t = $moment->get_t();

my $year = $moment->get_year();
my $month = $moment->get_month();
my $day = $moment->get_day();
my $hour = $moment->get_hour();
my $minute = $moment->get_minute();
my $second = $moment->get_second();

# Unix time (a.k.a. POSIX time or Epoch time)
my $number = $moment->get_timestamp();

# ISO 8601
my $iso_string => $moment->get_iso_string();

You can find out what is the day of week of the moment that is stored in the object. You can get scalar with the weekday name:

# 'monday', 'tuesday' and others
my $string = $moment->get_weekday_name();

Or you can get weekday number (specifying what weekday should be number one):

my $number = $moment->get_weekday_number( first_day => 'monday' );

Or you can test if the weekday of the moment is some specified weekday:

$moment->is_monday();
$moment->is_tuesday();
$moment->is_wednesday();
$moment->is_thursday();
$moment->is_friday();
$moment->is_saturday();
$moment->is_sunday();

You can test if the year of the moment is leap with the method:

$moment->is_leap_year();

If you have 2 Moment objects you can compare them with the cmp() method. The method cmp() works exaclty as cmp builtin keyword and returns -1, 0, or 1:

my $result = $moment_1->cmp($moment_2);

The Moment object is immutable. You can't change it after it is created. But you can create new objects with the methods plus(), minus() and get_month_start(), get_month_end():

my $in_one_day = $moment->plus( day => 1 );
my $ten_seconds_before = $moment->minus( second => 10 );

# create object with the moment '2014-11-01 00:00:00'
my $moment = Moment->new(dt => '2014-11-27 03:31:23')->get_month_start();

# create object with the moment '2014-11-30 23:59:59'
my $moment = Moment->new(dt => '2014-11-27 03:31:23')->get_month_end();

DESCRIPTION

Features and limitations of this library:

Library is as simple as possible
Class represents only UTC time, no timezone info
Object orentied design
Object can't be changed after creation
The precise is one seond
Working with dates in the period from '1800-01-01 00:00:00' to '2199-12-31 23:59:59'
Dies in case of any errors
No dependencies, but perl and its core modules
Plays well with Data::Printer
Using SemVer for version numbers

METHODS

new()

Constructor. Creates new Moment object that points to the specified moment of time. Can be used in 4 different ways:

my $some_moment = Moment->new(
    # dt format is 'YYYY-MM-DD hh:mm:ss'
    dt => '2014-11-27 03:31:23',
);

my $other_moment = Moment->new(
    year => 2014,
    month => 1,
    day => 3,

    hour => 4,
    minute => 2,
    second => 10,
);

my $one_more_moment = Moment->new(
    # Unix time (a.k.a. POSIX time or Epoch time)
    timestamp => 1000000000,
);

my $moment_from_iso_string = Moment->new(
    # ISO 8601
    iso_string => '2015-11-07T10:51:22Z',
);

Dies in case of errors.

now()

Constructor. Creates new Moment object that points to the current moment of time.

my $current_moment = Moment->now();

get_timestamp()

Returns the timestamp of the moment stored in the object.

The timestamp is also known as Unix time, POSIX time, Epoch time.

This is the number of seconds passed from '1970-01-01 00:00:00'.

This number can be negative.

say Moment->new( dt => '1970-01-01 00:00:00' )->get_timestamp(); # 0
say Moment->new( dt => '2000-01-01 00:00:00' )->get_timestamp(); # 946684800
say Moment->new( dt => '1960-01-01 00:00:00' )->get_timestamp(); # -315619200

The value that return this method is in the range [-5_364_662_400, 7_258_118_399].

get_dt()

Returns the scalar with date and time of the moment stored in the object. The data in scalar is in format 'YYYY-MM-DD hh:mm:ss'.

say Moment->now()->get_dt(); # 2014-12-07 11:50:57

The value that return this method is in the range ['1800-01-01 00:00:00', '2199-12-31 23:59:59'].

get_iso_string()

Returns the scalar with date and time of the moment stored in the object. The data in scalar is in ISO 8601 format 'YYYY-MM-DDThh:mm:ssZ'.

say Moment->now()->get_iso_string(); # 2014-12-07T11:50:57Z

The value that return this method is in the range ['1800-01-01T00:00:00Z', '2199-12-31T23:59:59Z'].

get_d()

Returns the scalar with date of the moment stored in the object. The data in scalar is in format 'YYYY-MM-DD'.

say Moment->now()->get_d(); # 2014-12-07

The value that return this method is in the range ['1800-01-01', '2199-12-31'].

get_t()

Returns the scalar with time of the moment stored in the object. The data in scalar is in format 'hh:mm:ss'.

say Moment->now()->get_t(); # 11:50:57

The value that return this method is in the range ['00:00:00', '23:59:59'].

get_year()

Returns the scalar with year of the moment stored in the object.

say Moment->now()->get_year(); # 2014

The value that return this method is in the range [1800, 2199].

get_month()

Returns the scalar with number of month of the moment stored in the object.

say Moment->now()->get_month(); # 12

The value that return this method is in the range [1, 12].

Method return '9', not '09'.

get_day()

Returns the scalar with number of day since the beginning of mongth of the moment stored in the object.

say Moment->now()->get_day(); # 7

The value that return this method is in the range [1, MAX_DAY]. Where the MAX_DAY depend on the month:

1 => 31,
2 => 28, # 29 on leap years
3 => 31,
4 => 30,
5 => 31,
6 => 30,
7 => 31,
8 => 31,
9 => 30,
10 => 31,
11 => 30,
12 => 31,

Method return '7', not '07'.

get_hour()

Returns the scalar with hour of the moment stored in the object.

say Moment->now()->get_hour(); # 11

The value that return this method is in the range [0, 23].

Method return '9', not '09'.

get_minute()

Returns the scalar with minute of the moment stored in the object.

say Moment->now()->get_minute(); # 50

The value that return this method is in the range [0, 59].

Method return '9', not '09'.

get_second()

Returns the scalar with second of the moment stored in the object.

say Moment->now()->get_second(); # 57

The value that return this method is in the range [0, 59].

Method return '9', not '09'.

get_weekday_name()

Return scalar with the weekday name. Here is the full list of strings that this method can return: 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'.

say Moment->now()->get_weekday_name(); # sunday

get_weekday_number()

my $number = $moment->get_weekday_number( first_day => 'monday' );

Returns scalar with weekday number.

The value that return this method is in the range [1, 7].

You must specify value for the first_day parameter. It should be one of: 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'.

my $m = Moment->new( dt => '2015-04-27 00:00:00');  # monday

$m->get_weekday_number( first_day => 'monday' ); # 1
$m->get_weekday_number( first_day => 'sunday' ); # 2

is_monday()

Returns true value is the weekday of the moment is monday. Otherwise returns false value.

is_tuesday()

Returns true value is the weekday of the moment is tuesday. Otherwise returns false value.

is_wednesday()

Returns true value is the weekday of the moment is wednesday. Otherwise returns false value.

is_thursday()

Returns true value is the weekday of the moment is thursday. Otherwise returns false value.

is_friday()

Returns true value is the weekday of the moment is friday. Otherwise returns false value.

is_saturday()

Returns true value is the weekday of the moment is saturday. Otherwise returns false value.

is_sunday()

Returns true value is the weekday of the moment is sunday. Otherwise returns false value.

is_leap_year()

Returns true value is the year of the moment is leap. Otherwise returns false value.

cmp()

Method to compare 2 object. It works exactly as perl builtin 'cmp' keyword.

my $result = $moment_1->cmp($moment_2);

It returns -1, 0, or 1 depending on whether the $moment_1 is stringwise less than, equal to, or greater than the $moment_2

say Moment->new(dt=>'1970-01-01 00:00:00')->cmp( Moment->new(dt=>'2000-01-01 00:00') ); # -1
say Moment->new(dt=>'2000-01-01 00:00:00')->cmp( Moment->new(dt=>'2000-01-01 00:00') ); # 0
say Moment->new(dt=>'2010-01-01 00:00:00')->cmp( Moment->new(dt=>'2000-01-01 00:00') ); # 1

plus()

Method plus() returns new object that differ from the original to the specified time. The class of the new object is the same as the class of the variable on which you run method.

my $new_moment = $moment->plus(
    day => 1,
    hour => 2,
    minute => 3,
    second => 4,
);

You can also use negative numbers.

my $two_hours_ago = $moment->plus( hour => -2 );

Here is an example:

say Moment->new(dt=>'2010-01-01 00:00:00')
    ->plus( day => 1, hour => 2, minute => 3, second => 4 )
    ->get_dt()
    ;
# 2010-01-02 02:03:04

minus()

Method minus() returns new object that differ from the original to the specified time. The class of the new object is the same as the class of the variable on which you run method.

my $new_moment = $moment->minus(
    day => 1,
    hour => 2,
    minute => 3,
    second => 4,
);

You can also use negative numbers.

my $two_hours_behind = $moment->minus( hour => -2 );

Here is an example:

say Moment->new(dt=>'2010-01-01 00:00:00')
    ->minus( day => 1, hour => 2, minute => 3, second => 4 )
    ->get_dt()
    ;
# 2009-12-30 21:56:56

get_month_start()

Method get_month_start() returns new object that points to the moment the month starts. The class of the new object is the same as the class of the variable on which you run method.

# 2014-12-01 00:00:00
say Moment->new(dt=>'2014-12-07 11:50:57')->get_month_start()->get_dt();

The time of the new object is always '00:00:00'.

get_month_end()

Method get_month_end() returns new object that points to the moment the month end. The class of the new object is the same as the class of the variable on which you run method.

# 2014-12-31 23:59:59
say Moment->new(dt=>'2014-12-07 11:50:57')->get_month_end()->get_dt();

The time of the new object is always '23:59:59'.

SAMPLE USAGE

Find the last day of the current month (for december 2014 it is 31):

my $day = Moment->now()->get_month_end()->get_day();

Loop for every day in month:

my $start = Moment->now()->get_month_start();
my $end = $start->get_month_end();

my $current = $start;
while ( $current->cmp($end) == -1 ) {
    say $current->get_day();
    $current = $current->plus( day => 1 );
}

Find out the weekday name for given date (for 2014-01-01 is is wednesday):

my $weekday = Moment->new( dt => '2014-01-01 00:00:00' )->get_weekday_name();

Find out how many seconds in one day (the answer is 86400):

my $moment = Moment->now();
my $seconds_in_a_day = $moment->get_timestamp() - $moment->minus( day => 1 )->get_timestamp();

FAQ

Q: Why there is no parameters 'month' and 'year' in plus() and minus() methods?

A: It is easy to add or substidude second, minute, hour or day from some date. But month and year are different. The number of days in month and year differ from one to anoter. Because of that some touth questions appear. For example what should we get if we add 1 year to the date 2000-02-29? To make this library as simple as possible, I've desided not to implement this feature.

Q: How does this library works with leap seconds?

A: It does not. This library knows nothing about leap seconds.

Q: How should I handle timezones with this module?

A: The best practice to work with time is to work witn time in UTC timezone. This means converting all inputs to UTC timezone and converting it to the desired timezones on output.

You must find out the offset from the UTC timezone and use plus() or minus() methods to create object with UTC time.

For example, if you have time '2014-12-20 18:51:20 +0300' you should create Moment object with the code:

my $m = Moment->new( dt => '2014-12-20 18:51:20' )->minus( hour => 3 );

And if you need to output the time in some special timezone you shlould to the same thing:

say $m->plus( hour => 5, minute => 30 )->get_dt();

Q: Why there are no methods to find out the week number?

A: There are several ways to define what is the first week in year. To make this library as simple as possible, I've desided not to implement this feature.

Q: How to serialize this object and deserialize it?

A: There are 3 ways. To use timestamp as the serialised string, to use ISO string, or to use dt. Timestamp, ISO string or dt contaings all the needed data to recreate the object with the exact same state.

Serialize timestamp:

my $serialized_timestamp = $moment->get_timestamp();

Restore timestamp:

my $restored_moment = Moment->new( timestamp => $serialized_timestamp );

Serialize ISO string:

my $serialized_iso_string = $moment->get_iso_string();

Restore ISO string:

my $restored_moment = Moment->new( iso_string => $serialized_iso_string );

Serialize dt:

my $serialized_dt = $moment->get_dt();

Restore dt:

my $restored_moment = Moment->new( dt => $serialized_dt );

Q: I need my own output format.

A: This is simple. Just write your own class using Moment as the parent and implement method that you need.

Q: Why there is a limitation that this module work only with dates in the range from '1800-01-01 00:00:00' to '2199-12-31 23:59:59'?

A: One of the main ideas behind this libraray is simplicity. Adding this limitations makes the creation and testing of this library simplier. And this limits are enouth for real life problems.

SOURCE CODE

The source code for this library is hosted on GitHub https://github.com/bessarabov/Moment

BUGS

Please report any bugs or feature requests in GitHub Issues https://github.com/bessarabov/Moment/issues

AUTHOR

Ivan Bessarabov <ivan@bessarabov.ru>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install Moment, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Moment

CPAN shell

perl -MCPAN -e shell
install Moment

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

new()

now()

get_timestamp()

get_dt()

get_iso_string()

get_d()

get_t()

get_year()

get_month()

get_day()

get_hour()

get_minute()

get_second()

get_weekday_name()

get_weekday_number()

is_monday()

is_tuesday()

is_wednesday()

is_thursday()

is_friday()

is_saturday()

is_sunday()

is_leap_year()

cmp()

plus()

minus()

get_month_start()

get_month_end()

SAMPLE USAGE

FAQ

SEE ALSO

SOURCE CODE

BUGS

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions