NAME

Time::C - Convenient time manipulation.

VERSION

version 0.009

SYNOPSIS

use Time::C;

my $t = Time::C->from_string('2016-09-23T04:28:30Z');

# 2016-01-01T04:28:30Z
$t->month = $t->day = 1;

# 2016-01-01T00:00:00Z
$t->hour = $t->minute = $t->second = 0;

# 2016-02-04T00:00:00Z
$t->month += 1; $t->day += 3;

# 2016-03-03T00:00:00Z
$t->day += 28;

# print all days of the week (2016-02-29T00:00:00Z to 2016-03-06T00:00:00Z)
$t->day_of_week = 1;
do { say $t } while ($t->day_of_week++ < 7);

DESCRIPTION

Makes manipulating time structures more convenient. Internally uses Time::Moment, Time::Piece and Time::Zone::Olson.

CONSTRUCTORS

new

my $t = Time::C->new();
my $t = Time::C->new($year);
my $t = Time::C->new($year, $month);
my $t = Time::C->new($year, $month, $day);
my $t = Time::C->new($year, $month, $day, $hour);
my $t = Time::C->new($year, $month, $day, $hour, $minute);
my $t = Time::C->new($year, $month, $day, $hour, $minute, $second);
my $t = Time::C->new($year, $month, $day, $hour, $minute, $second, $tz);

Creates a Time::C object for the specified time, or the current time if no $year is specified.

$year: This is the year. If not specified, new() will call now_utc(). The year is 1-based and starts with year 1 corresponding to 1 AD. Legal values are in the range 1-9999.
$month: This is the month. If not specified it defaults to 1. The month is 1-based and starts with month 1 corresponding to January. Legal values are in the range 1-12.
$day: This is the day of the month. If not specified it defaults to 1. The day is 1-based and starts with day 1 being the first day of the month. Legal values are in the range 1-31.
$hour: This is the hour. If not specified it defaults to 0. The hour is 0-based and starts with hour 0 corresponding to midnight. Legal values are in the range 0-23.
$minute: This is the minute. If not specified it defaults to 0. The minute is 0-based and starts with minute 0 being the first minute of the hour. Legal values are in the range 0-59.
$second: This is the second. If not specified it defaults to 0. The second is 0-based and starts with second 0 being the first second of the minute. Legal values are in the range 0-59.
$tz: This is the timezone specification such as Europe/Stockholm or UTC. If not specified it defaults to UTC.

localtime

my $t = Time::C->localtime($epoch);
my $t = Time::C->localtime($epoch, $tz);

Creates a Time::C object for the specified $epoch and optional $tz.

$epoch: This is the time in seconds since the system epoch, usually 1970-01-01T00:00:00Z.
$tz: This is the timezone specification, such as Europe/Stockholm or UTC. If not specified defaults to the timezone specified in $ENV{TZ}, or UTC if that is unspecified.

gmtime

my $t = Time::C->gmtime($epoch);

Creates a Time::C object for the specified $epoch. The timezone will be UTC.

$epoch: This is the time in seconds since the system epoch, usually 1970-01-01T00:00:00Z.

now

my $t = Time::C->now();
my $t = Time::C->now($tz);

Creates a Time::C object for the current epoch in the timezone specified in $tz or $ENV{TZ} or UTC if the first two are unspecified.

$tz: This is the timezone specification, such as Europe/Stockholm or UTC. If not specified defaults to the timezone specified in $ENV{TZ}, or UTC if that is unspecified.

now_utc

my $t = Time::C->now_utc();

Creates a Time::C object for the current epoch in UTC.

from_string

my $t = Time::C->from_string($str);
my $t = Time::C->from_string($str, $format);
my $t = Time::C->from_string($str, $format, $expected_tz);

Creates a Time::C object for the specified $str, using the optional $format to parse it, and the optional $expected_tz to set an unambigous timezone, if it matches the offset the parsing operation gave.

$str: This is the string that will be parsed by either "strptime" in Time::Piece or "from_string" in Time::Moment.
$format: This is the format that "strptime" in Time::Piece will be given, by default it is undef. If it is not defined, "from_string" in Time::Moment will be used instead.
$expected_tz: If the parsed time contains a zone or offset that parses, and the offset matches the $expected_tz offset, $expected_tz will be set as the timezone. If it doesn't match, a generic timezone matching the offset will be set, such as UTC for an offset of 0. This variable will also default to UTC.

ACCESSORS

These accessors will work as LVALUEs, meaning you can assign to them to change the time being represented.

Note that an assignment expression will return the computed value rather than the assigned value. This means that in the expression my $wday = $t->day_of_week = 8; the value assigned to $wday will be 1 because the value returned from the day_of_week assignment wraps around after 7, and in fact starts the subsequent week. Similarly in the expression my $mday = $t->month(2)->day_of_month = 30; the value assigned to $mday will be either 1 or 2 depending on if it's a leap year or not, and the month will have changed to 3.

epoch

my $epoch = $t->epoch;
$t->epoch = $epoch;
$t->epoch += 3600;
$t->epoch++;
$t->epoch--;

$t = $t->epoch($new_epoch);

Returns or sets the epoch, i.e. the number of seconds since 1970-01-01T00:00:00Z.

If the form $t->epoch($new_epoch) is used, it likewise changes the epoch but returns the entire object.

tz

my $tz = $t->tz;
$t->tz = $tz;

$t = $t->tz($new_tz);

Returns or sets the timezone. If the timezone can't be recognised it dies.

If the form $t->tz($new_tz) is used, it likewise changes the timezone but returns the entire object.

offset

my $offset = $t->offset;
$t->offset = $offset;
$t->offset += 60;

$t = $t->offset($new_offset);

Returns or sets the current offset in minutes. If the offset is set, it tries to find a generic Etc/GMT+X or +XX:XX timezone that matches the offset and updates the tz to this. If it fails, it dies with an error.

If the form $t->offset($new_offset) is used, it likewise sets the timezone from $new_offset but returns the entire object.

tm

my $tm = $t->tm;
$t->tm = $tm;

$t = $t->tm($new_tm);

Returns a Time::Moment object for the current epoch and offset. On setting, it changes the current epoch.

If the form $t->tm($new_tm) is used, it likewise changes the current epoch but returns the entire object.

string

my $str = $t->string;
my $str = $t->string($format);
$t->string = $str;
$t->string($format) = $str;

$t = $t->string($format, $new_str);

Renders the current time to a string using the optional strftime $format. If the $format is not given it defaults to undef. When setting this value, it tries to parse the string using "strptime" in Time::Piece with the $format or "from_string" in Time::Moment if no $format was given or strptime fails. If the detected offset matches the current tz, that is kept, otherwise it will get changed to a generic tz in the form of Etc/GMT+X or +XX:XX.

If the form $t->string($format, $new_str) is used, it likewise updates the epoch and timezone but returns the entire object.

year

my $year = $t->year;
$t->year = $year;
$t->year += 10;
$t->year++;
$t->year--;

$t = $t->year($new_year);

Returns or sets the current year, updating the epoch accordingly.

If the form $t->year($new_year) is used, it likewise sets the current year but returns the entire object.

The year is 1-based where the year 1 corresponds to 1 AD. Legal values are in the range 1-9999.

quarter

my $quarter = $t->quarter;
$t->quarter = $quarter;
$t->quarter += 4;
$t->quarter++;
$t->quarter--;

$t = $t->quarter($new_quarter);

Returns or sets the current quarter of the year, updating the epoch accordingly.

If the form $t->quarter($new_quarter) is used, it likewise sets the current quarter but returns the entire object.

The quarter is 1-based where quarter 1 is the first three months of the year. Legal values are in the range 1-4.

month

my $month = $t->month;
$t->month = $month;
$t->month += 12;
$t->month++;
$t->month--;

$t = $t->month($new_month);

Returns or sets the current month of the year, updating the epoch accordingly.

If the form $t->month($new_month) is used, it likewise sets the month but returns the entire object.

The month is 1-based where month 1 is January. Legal values are in the range 1-12.

week

my $week = $t->week;
$t->week = $week;
$t->week += 4;
$t->week++;
$t->week--;

$t = $t->week($new_week);

Returns or sets the current week or the year, updating the epoch accordingly.

If the form $t->week($new_week) is used, it likewise sets the current week but returns the entire object.

The week is 1-based where week 1 is the first week of the year according to ISO 8601. The first week may actually have some days in the previous year, and the last week may have some days in the subsequent year. Legal values are in the range 1-53.

day

my $day = $t->day;
$t->day = $day;
$t->day += 31;
$t->day++;
$t->day--;

$t = $t->day($new_day);

Returns or sets the current day of the month, updating the epoch accordingly.

If the form $t->day($new_day) is used, it likewise sets the current day of the month but returns the entire object.

The day is 1-based where day 1 is the first day of the month. Legal values are in the range 1-31.

day_of_month

Functions exactly like day.

day_of_year

my $yday = $t->day_of_year;
$t->day_of_year = $yday;
$t->day_of_year += 365;
$t->day_of_year++;
$t->day_of_year--;

$t = $t->day_of_year($new_day);

Returns or sets the current day of the year, updating the epoch accordingly.

If the form $t->day_of_year($new_day) is used, it likewise sets the current day of the year but returns the entire object.

The day is 1-based where day 1 is the first day of the year. Legal values are in the range 1-366.

day_of_quarter

my $qday = $t->day_of_quarter;
$t->day_of_quarter = $qday;
$t->day_of_quarter += 90;
$t->day_of_quarter++;
$t->day_of_quarter--;

$t = $t->day_of_quarter($new_day);

Returns or sets the current day of the quarter, updating the epoch accordingly.

If the form $t->day_of_quarter($new_day) is used, it likewise sets the current day of the quarter but returns the entire object.

The day is 1-based where day 1 is the first day in the first month of the quarter. Legal values are in the range 1-92.

day_of_week

my $wday = $t->day_of_week;
$t->day_of_week = $wday;
$t->day_of_week += 7;
$t->day_of_week++;
$t->day_of_week--;

$t = $t->day_of_week($new_day);

Returns or sets the current day of the week, updating the epoch accordingly. This module uses Time::Moment which counts days in the week starting from 1 with Monday, and ending on 7 with Sunday.

If the form $t->day_of_week($new_day) is used, it likewise sets the current day of the week but returns the entire object.

The day is 1-based where day 1 is Monday. Legal values are in the range 1-7.

hour

my $hour = $t->hour;
$t->hour = $hour;
$t->hour += 24;
$t->hour++;
$t->hour--;

$t = $t->hour($new_hour);

Returns or sets the current hour of the day, updating the epoch accordingly.

If the form $t->hour($new_hour) is used, it likewise sets the current hour but returns the entire object.

The hour is 0-based where hour 0 is midnight. Legal values are in the range 0-23.

minute

my $minute = $t->minute;
$t->minute = $minute;
$t->minute += 60;
$t->minute++;
$t->minute--;

$t = $t->minute($new_minute);

Returns or sets the current minute of the hour, updating the epoch accordingly.

If the form $t->minute($new_minute) is used, it likewise sets the current minute but returns the entire object.

The minute is 0-based where minute 0 is the first minute of the hour. Legal values are in the range 0-59.

second

my $second = $t->second;
$t->second = $second;
$t->second += 60;
$t->second++;
$t->second--;

$t = $t->second($new_second);

Returns or sets the current second of the minute, updating the epoch accordingly.

If the form $t->second($new_second) is used, it likewise sets the current second but returns the entire object.

The second is 0-based where second 0 is the first second of the minute. Legal values are in the range 0-59.

METHODS

diff

my $d = $t1->diff($t2);
my $d = $t1->diff($epoch);

Creates a Time::D object from $t1 and $t2 or $epoch. It accepts either an arbitrary object that has an ->epoch accessor returning an epoch, or a straight epoch.

AUTHOR

Andreas Guldstrand <andreas.guldstrand@gmail.com>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The MIT (X11) License

To install Time::C, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Time::C

CPAN shell

perl -MCPAN -e shell
install Time::C

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)