Karen Etheridge > DateTime-Format-Duration-1.04 > DateTime::Format::Duration

Download:
DateTime-Format-Duration-1.04.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

New  3
Open  6
View/Report Bugs
Module Version: 1.04   Source  

NAME ^

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

VERSION ^

version 1.04

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 values 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 equivalent 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.

SEE ALSO ^

datetime@perl.org mailing list

http://datetime.perl.org/

SUPPORT ^

Bugs may be submitted through the RT bug tracker (or bug-DateTime-Format-Duration@rt.cpan.org).

There is also a mailing list available for users of this distribution, at http://lists.perl.org/list/datetime.html.

I am also usually active on irc, as 'ether' at irc.perl.org.

AUTHOR ^

Rick Measham <rickm@cpan.org>

CONTRIBUTOR ^

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE ^

This software is copyright (c) 2003 by Rick Measham.

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

syntax highlighting: