Jarkko Hietaniemi > perl-5.7.2 > Time::Piece

Download:
perl-5.7.2.tar.gz

Dependencies

Annotate this POD

Module Version: 0.13   Source  

NAME ^

Time::Piece - Object Oriented time objects

SYNOPSIS ^

    use Time::Piece;
    
    my $t = localtime;
    print "Time is $t\n";
    print "Year is ", $t->year, "\n";

DESCRIPTION ^

This module replaces the standard localtime and gmtime functions with implementations that return objects. It does so in a backwards compatible manner, so that using localtime/gmtime in the way documented in perlfunc will still return what you expect.

The module actually implements most of an interface described by Larry Wall on the perl5-porters mailing list here: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2000-01/msg00241.html

USAGE ^

After importing this module, when you use localtime(0 or gmtime() in scalar context, rather than getting an ordinary scalar string representing the date and time, you get a Time::Piece object, whose stringification happens to produce the same effect as the localtime() and gmtime(0 functions.

There is also a new() constructor provided, which is the same as localtime(), except when passed a Time::Piece object, in which case it's a copy constructor.

The following methods are available on the object:

    $t->s                    # 0..61
                             # 60 and 61: leap second and double leap second
    $t->sec                  # same as $t->s
    $t->second               # same as $t->s
    $t->min                  # 0..59
    $t->h                    # 0..24
    $t->hour                 # same as $t->h
    $t->d                    # 1..31
    $t->mday                 # same as $t->d
    $t->mon                  # 1 = January
    $t->_mon                 # 0 = January
    $t->monname              # Feb
    $t->monthname            # February
    $t->month                # same as $t->monthname
    $t->y                    # based at 0 (year 0 AD is, of course 1 BC)
    $t->year                 # same as $t->y
    $t->_year                # year minus 1900
    $t->wday                 # 1 = Sunday
    $t->day_of_week          # 0 = Sunday
    $t->_wday                # 0 = Sunday
    $t->wdayname             # Tue
    $t->weekdayname          # Tuesday
    $t->weekday              # same as weekdayname
    $t->yday                 # also available as $t->day_of_year, 0 = Jan 01
    $t->isdst                # also available as $t->daylight_savings
    $t->daylight_savings     # same as $t->isdst

    $t->hms                  # 12:34:56
    $t->hms(".")             # 12.34.56
    $t->time                 # same as $t->hms

    $t->ymd                  # 2000-02-29
    $t->date                 # same as $t->ymd
    $t->mdy                  # 02-29-2000
    $t->mdy("/")             # 02/29/2000
    $t->dmy                  # 29-02-2000
    $t->dmy(".")             # 29.02.2000
    $t->datetime             # 2000-02-29T12:34:56 (ISO 8601)
    $t->cdate                # Tue Feb 29 12:34:56 2000
    "$t"                     # same as $t->cdate
   
    $t->epoch                # seconds since the epoch
    $t->tzoffset             # timezone offset in a Time::Seconds object

    $t->julian_day           # number of days since Julian period began
    $t->mjd                  # modified Julian day

    $t->week                 # week number (ISO 8601)

    $t->is_leap_year                  # true if it its
    Time::Piece::_is_leap_year($year) # true if it its
    $t->month_last_day                # 28..31

    $t->time_separator($s)   # set the default separator (default ":")
    $t->date_separator($s)   # set the default separator (default "-")
    $t->wday_names(@days)    # set the default weekday names, abbreviated
    $t->weekday_names(@days) # set the default weekday names
    $t->mon_names(@days)     # set the default month names, abbreviated
    $t->month_names(@days)   # set the default month names

    $t->strftime($format)    # date and time formatting
    $t->strftime()           # "Tue, 29 Feb 2000 12:34:56 GMT"

    $t->_strftime($format)   # same as POSIX::strftime (without the
                             # overhead of the full POSIX extension),
                             # calls the operating system libraries,
                             # as opposed to $t->strftime()

    use Time::Piece 'strptime'; # date parsing
    my %p = strptime("%H:%M", "12:34"); # $p{H} and ${M} will be set

Local Locales

Both wdayname (day) and monname (month) allow passing in a list to use to index the name of the days against. This can be useful if you need to implement some form of localisation without actually installing or using the locales provided by the operating system.

  my @weekdays = qw( Dimanche Lundi Merdi Mercredi Jeudi Vendredi Samedi );
  
  my $french_day = localtime->day(@weekdays);

These settings can be overriden globally too:

  Time::Piece::weekday_names(@weekdays);
  Time::Piece::wday_names(@wdays);

Or for months:

  Time::Piece::month_names(@months);
  Time::Piece::mon_names(@mon);

And locally for months:

  print localtime->month(@months);

Date Calculations

It's possible to use simple addition and subtraction of objects:

    use Time::Seconds;
    
    my $seconds = $t1 - $t2;
    $t1 += ONE_DAY; # add 1 day (constant from Time::Seconds)

The following are valid ($t1 and $t2 are Time::Piece objects):

    $t1 - $t2; # returns Time::Seconds object
    $t1 - 42; # returns Time::Piece object
    $t1 + 533; # returns Time::Piece object

However adding a Time::Piece object to another Time::Piece object will cause a runtime error.

Note that the first of the above returns a Time::Seconds object, so while examining the object will print the number of seconds (because of the overloading), you can also get the number of minutes, hours, days, weeks and years in that delta, using the Time::Seconds API.

Date Comparisons

Date comparisons are also possible, using the full suite of "<", ">", "<=", ">=", "<=>", "==" and "!=".

YYYY-MM-DDThh:mm:ss

The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the time format to be hh:mm:ss (24 hour clock), and if combined, they should be concatenated with the date first and with a capital 'T' in front of the time.

Week Number

The week number may be an unknown concept to some readers. The ISO 8601 standard defines that weeks begin on a Monday and week 1 of the year is the week that includes both January the 4th and the first Thursday of the year. In other words, if the first Monday of January is the 2nd, 3rd, or 4th, the preceding days of the January are part of the last week of the preceding year. Week numbers range from 1 to 53.

strftime method

The strftime() method can be used to format Time::Piece objects for output. The argument to strftime() is the format string to be used, for example:

        $t->strftime("%H:%M");

will output the hours and minutes concatenated with a colon. The available format characters are as in the standard strftime() function (unless otherwise indicated the implementation is in pure Perl, no operating system strftime() is invoked):

%%

The percentage character "%".

%a

The abbreviated weekday name, e.g. 'Tue'. Note that the abbreviations are not necessarily three characters wide in all languages.

%A

The weekday name, e.g. 'Tuesday'.

%b

The abbreviated month name, e.g. 'Feb'. Note that the abbreviations are not necessarily three characters wide in all languages.

%B

The month name, e.g. 'February'.

%c

The ctime format, or the localtime()/gmtime() format: %a %b %m %H:%M:%S %Y.

(Should be avoided: use $t->timedate instead.)

%C

The 'centuries' number, e.g. 19 for the year 1999 and 20 for the year 2000.

%d

The zero-filled right-aligned day of the month, e.g. '09' or '10'.

%D

%m/%d/%d.

(Should be avoided: use $t->date instead.)

%e

The space-filled right-aligned day of the month, e.g. ' 9' or '10'.

%h

Same as %b, the abbreviated monthname.

%H

The zero-filled right-aligned hours in 24 hour clock, e.g. '09' or '10'.

%I

The zero-filled right-aligned hours in 12 hour clock, e.g. '09' or '10'.

%j

The zero-filled right-aligned day of the year, e.g. '001' or '365'.

%m

The zero-filled right-aligned month number, e.g. '09' or '10'.

%M

The zero-filled right-aligned minutes, e.g. '09' or '10'.

%n

The newline character "\n".

%p

Notice that this is somewhat meaningless in 24 hour clocks.

%r

%I:%M:%S %p.

(Should be avoided: use $t->time instead.)

%R

%H:%M.

%S

The zero-filled right-aligned seconds, e.g. '09' or '10'.

%t

The tabulator character "\t".

%T

%H:%M%S

(Should be avoided: use $t->time instead.)

%u

The day of the week with Monday as 1 (one) and Sunday as 7.

%U

The zero-filled right-aligned week number of the year, Sunday as the first day of the week, from '00' to '53'.

(Currently taken care by the operating system strftime().)

%V

The zero-filled right-aligned week of the year, e.g. '01' or '53'. (ISO 8601)

%w

The day of the week with Sunday as 0 (zero) and Monday as 1 (one).

%W

The zero-filled right-aligned week number of the year, Monday as the first day of the week, from '00' to '53'.

(Currently taken care by the operating system strftime().)

%x

%m/%d/%y.

(Should be avoided: use $t->date instead.)

%y

The zero-filled right-aligned last two numbers of the year, e.g. 99 for 1999 and 01 for 2001.

(Should be avoided: this is the Y2K bug alive and well.)

%Y

The year, e.g. 1999 or 2001.

%Z

The timezone name, for example "GMT" or "EET".

(Taken care by the operating system strftime().)

The format Z and any of the O* and E* formats are handled by the operating system, not by Time::Piece, because those formats are usually rather unportable and non-standard. (For example 'MST' can mean almost anything: 'Mountain Standard Time' or 'Moscow Standard Time'.)

strptime function

You can export the strptime() function and use it to parse date and time strings back to numbers. For example the following will return the hours, minutes, and seconds as $parse{H}, $parse{M}, and $parse{S}.

    use Time::Piece 'strptime';
    my %parse = strptime('%H:%M:S', '12:34:56');

For 'compound' formats like for example 'T' strptime() will return the 'components'.

strptime() does not perform overly strict checks on the dates and times, it will be perfectly happy with the 31st day of February, for example. Stricter validation should be performed by other means.

Global Overriding

Finally, it's possible to override localtime and gmtime everywhere, by including the ':override' tag in the import list:

    use Time::Piece ':override';

SEE ALSO ^

The excellent Calendar FAQ at http://www.tondering.dk/claus/calendar.html

If you just want an object-oriented interface to the usual time functions see Time::localtime and Time::gmtime which are part of the standard distribution. Beware, though, that their fields are as in the C library: the year is year-1900 (like $t->_year in Time::Piece) and months begin from zero (like $t->_mon).

strftime(3), strftime(3)

AUTHOR ^

Matt Sergeant, matt@sergeant.org

This module is based on Time::Object, with changes suggested by Jarkko Hietaniemi before including in core perl.

License

This module is free software, you may distribute it under the same terms as Perl.

Bugs

The test harness leaves much to be desired. Patches welcome.

syntax highlighting: