Rick Measham > DateTime-Format-Duration-1.03a > DateTime::Format::Duration

Download:
DateTime-Format-Duration-1.03a.tgz

Dependencies

Annotate this POD (2)

CPAN RT

New  7
Open  4
View/Report Bugs
Module Version: 1.03   Source  

NAME ^

DateTime::Format::Duration - Format and parse DateTime::Durations

SYNOPSIS ^

        use DateTime::Format::Duration;

        $d = DateTime::Format::Duration->new(
                pattern => '%Y years, %m months, %e days, '.
                                '%H hours, %M minutes, %S seconds'
        );

        print $d->format_duration(
                DateTime::Duration->new(
                        years   => 3,
                        months  => 5,
                        days    => 1,
                        hours   => 6,
                        minutes => 15,
                        seconds => 45,
                        nanoseconds => 12000
                )
        );
        # 3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds


        $duration = $d->parse_duration(
                '3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds'
        );
        # Returns DateTime::Duration object


        print $d->format_duration_from_deltas(
                years   => 3,
                months  => 5,
                days    => 1,
                hours   => 6,
                minutes => 15,
                seconds => 45,
                nanoseconds => 12000
        );
        # 3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds

        %deltas = $d->parse_duration_as_deltas(
                '3 years, 5 months, 1 days, 6 hours, 15 minutes, 45 seconds'
        );
        # Returns hash:
        # (years=>3, months=>5, days=>1, hours=>6, minutes=>15, seconds=>45)

ABSTRACT ^

This module formats and parses DateTime::Duration objects as well as other durations representations.

CONSTRUCTOR ^

This module contains a single constructor:

METHODS ^

DateTime::Format::Duration has the following methods:

ACCESSORS ^

SETTERS ^

All setters return the object so that they can be strung together.

NOTES ^

Patterns

This module uses a similar set of patterns to strftime. These patterns have been kept as close as possible to the original time-based patterns.

Precision can be changed for any and all the above values. For all but nanoseconds (%N), the precision is the zero-padding. To change the precision insert a number between the '%' and the letter. For example: 1 year formatted with %6Y would return 000001 rather than the default 0001. Likewise, to remove padding %1Y would just return a 1.

Nanosecond precision is the other way (nanoseconds are fractional and thus should be right padded). 123456789 nanoseconds formatted with %3N would return 123 and formatted as %12N would return 123456789000.

Normalisation

This module contains a complex method for normalising durations. The method ensures that the vslues for all components are as close to zero as possible. Rather than returning 68 minutes, it is normalised to 1 hour, 8 minutes.

The complexity comes from three places:

Normalising without a base

This module includes two ways to normalise without a base.

Deltas vs Duration Objects

This module can bypass duration objects and just work with delta hashes. This used to be of greatest value with earlier versions of DateTime::Duration when DateTime::Duration assumed a duration with one negative component was a negative duration (that is, -2 hours, 34 minutes was assumed to be -2 hours, -34 minutes).

These extra methods have been left in here firstly for backwards-compatibility but also as an added 'syntactic sugar'. Consider these two equivelent expressions:

        $one = $o->format_duration(
                DateTime::Duration->new(
                        years => -2,
                        days  => 13,
                        hours => -1
                )
        );

        $two = $o->format_duration_from_deltas(
                years => -2,
                days  => 13,
                hours => -1
        );

These both create the same string in $one and $two, but if you don't already have a DateTime::Duration object, the later looks cleaner.

AUTHOR ^

Rick Measham <rickm@cpan.org>

COPYRIGHT ^

Copyright (c) 2003 - 2004 Rick Measham. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO ^

datetime@perl.org mailing list

http://datetime.perl.org/

syntax highlighting: