The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Time-C-0.002
River stage zero No dependents
/ Time::C

NAME

Time::C - Convenient time manipulation.

VERSION

version 0.002

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++ > 1);

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 is the year. If not specified, new() will call now_utc().
$month is the month. If not specified it defaults to 1.
$day is the day of the month. If not specified it defaults to 1.
$hour is the hour. If not specified it defaults to 0.
$minute is the minute. If not specified it defaults to 0.
$second is the second. If not specified it defaults to 0.
$tz 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 is the time in seconds since the system epoch, usually 1970-01-01T00:00:00Z.
$tz 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 is the time in seconds since the system epoch, usually 1970-01-01T00:00:00Z.

now

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

Creates a Time::C object for the current epoch in 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_epoch

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

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

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

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 is the string that will be parsed by either "strptime" in Time::Piece or "from_string" in Time::Moment.
$format is the format that "strptime" in Time::Piece will be given, by default it is undef. If it is not defined, Time::Moment/from_string 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.

epoch

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

Returns or sets the epoch according to the specified timezone.

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 instead changes the internal tz and returns the entire object.

offset

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

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

tm

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

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

string

  my $str = $t->string;
  my $str = $t->string($format);
  $t->string = $str;
  $t->string($format) = $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 the strptime $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.

year

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

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

quarter

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

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

month

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

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

week

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

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

day

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

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

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--;

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

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--;

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

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--;

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.

hour

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

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

minute

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

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

second

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

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

millisecond

  my $msec = $t->millisecond;
  $t->millisecond = $msec;
  $t->millisecond += 1000;
  $t->millisecond++;
  $t->millisecond--;

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

microsecond

  use utf8;
  my $µsec = $t->microsecond;
  $t->microsecond = $µsec;
  $t->microsecond += 1_000_000;
  $t->microsecond++;
  $t->microsecond--;

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

nanosecond

  my $nsec = $t->nanosecond;
  $t->nanosecond = $nsec;
  $t->nanosecond += 1_000_000_000;
  $t->nanosecond++;
  $t->nanosecond--;

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

SEE ALSO

Time::Moment
Time::Piece
Time::Zone::Olson

AUTHOR

Andreas Guldstrand <andreas.guldstrand@gmail.com>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Andreas Guldstrand.

This is free software, licensed under:

  The MIT (X11) License