GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DATE::ICAL::DURATION (3)

.ds Aq ’

NAME

Date::ICal::Duration - durations in iCalendar format, for math purposes.

CONTENTS

VERSION

$Revision: 1.61 $

SYNOPSIS



    use Date::ICal::Duration;

    $d = Date::ICal::Duration->new( ical => -P1W3DT2H3M45S );

    $d = Date::ICal::Duration->new( weeks => 1,
                                    days => 1,
                                    hours => 6,
                                    minutes => 15,
                                    seconds => 45);

    # a one hour duration, without other components
    $d = Date::ICal::Duration->new( seconds => "3600");

    # Read-only accessors:
    $d->weeks;
    $d->days;
    $d->hours;
    $d->minutes;
    $d->seconds;
    $d->sign;

    # TODO: Resolve sign() discussion from rk-devel and update synopsis.
   
    $d->as_seconds ();   # returns just seconds
    $d->as_elements ();  # returns a hash of elements, like the accessors above
    $d->as_ical();       # returns an iCalendar duration string



DESCRIPTION

This is a trivial class for representing duration objects, for doing math in Date::ICal

AUTHOR

Rich Bowen, and the Reefknot team. Alas, Reefknot is no more. See http://datetime.perl.org/ for more modern modules.

Last touched by $Author: rbowen $

METHODS

Date::ICal::Duration has the following methods available:

    new

A new Date::ICal::Duration object can be created with an iCalendar string :



    my $ical = Date::ICal::Duration->new ( ical => P3W2D );
    # 3 weeks, 2 days, positive direction
    my $ical = Date::ICal::Duration->new ( ical => -P6H3M30S );
    # 6 hours, 3 minutes, 30 seconds, negative direction



Or with a number of seconds:



    my $ical = Date::ICal::Duration->new ( seconds => "3600" );
    # one hour positive



Or, better still, create it with components



    my $date = Date::ICal::Duration->new (
                           weeks => 6,
                           days => 2,
                           hours => 7,
                           minutes => 15,
                           seconds => 47,
                           sign => "+"
                           );



The sign defaults to +, but + and - are legal values.

    sign, weeks, days, hours, minutes, seconds

Read-only accessors for the elements of the object.

    as_seconds

Returns the duration in raw seconds.

WARNING — this folds in the number of days, assuming that they are always 86400 seconds long (which is not true twice a year in areas that honor daylight savings time). If you’re using this for date arithmetic, consider using the add() method from a Date::ICal object, as this will behave better. Otherwise, you might experience some error when working with times that are specified in a time zone that observes daylight savings time.

    as_days



    $days = $duration->as_days;



Returns the duration as a number of days. Not to be confused with the days method, this method returns the total number of days, rather than mod’ing out the complete weeks. Thus, if we have a duration of 33 days, weeks will return 4, days will return 5, but as_days will return 33.

Note that this is a lazy convenience function which is just weeks*7 + days.

    as_ical

Return the duration in an iCalendar format value string (e.g., PT2H0M0S)

    as_elements

Returns the duration as a hashref of elements.

INTERNALS

head2 GENERAL MODEL

Internally, we store 3 data values: a number of days, a number of seconds (anything shorter than a day), and a sign (1 or -1). We are assuming that a day is 24 hours for purposes of this module; yes, we know that’s not completely accurate because of daylight-savings-time switchovers, but it’s mostly correct. Suggestions are welcome.

NOTE: The methods below SHOULD NOT be relied on to stay the same in future versions.

_set_from_ical ($self, CW$duration_string)

Converts a RFC2445 DURATION format string to the internal storage format.

    _parse_ical_string ($string)

Regular expression for parsing iCalendar into usable values.

_set_from_components ($self, CW$hashref)

Converts from a hashref to the internal storage format. The hashref can contain elements sign, weeks, days, hours, minutes, seconds.

_set_from_ical ($self, CW$num_seconds)

Sets internal data storage properly if we were only given seconds as a parameter.

CW$self->_hms();

Return an arrayref to hours, minutes, and second components, or undef if nsecs is undefined. If given an arrayref, computes the new nsecs value for the duration.

CW$self->_wd()

Return an arrayref to weeks and day components, or undef if ndays is undefined. If Given an arrayref, computs the new ndays value for the duration.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DATE::ICAL::DURATION (3) 2010-02-24

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.