NAME

Net::ICal::Duration -- represent a length of time

SYNOPSIS

  use Net::ICal;

  # 3 days 6 hours 15 minutes 10 seconds
  $d = Net::ICal::Duration->new("P3DT6H15M10S");

  # 1 hour, in seconds
  $d = Net::ICal::Duration->new(3600);

DESCRIPTION

Duration represents a length of time, such a 3 days, 30 seconds or 7 weeks. You would use this for representing an abstract block of time; "I want to have a 1-hour meeting sometime." If you want a calendar- and timezone-specific block of time, see Net::ICal::Period.

CONSTRUCTOR

new(SECONDS | DURATION )

Create a new DURATION object. It can be constructed from an integer (the number of seconds since the UNIX epoch), a DURATION string (ala 2445 section 4.3.6), or the individual components (i.e., weeks, days, hours, minutes and seconds). See the component update methods below for caveats on updating these values individually.

METHODS

weeks([WEEKS])

Return (or set) the number of weeks in the duration.

days([DAYS])

Return (or set) the number of days in the duration.

NOTE: If more than six (6) days are specified, the value will be normalized, and the weeks portion of the duration will be updated (and the old value destroyed). See the ndays() method if you want more exact control over the "calendar" portion of the duration.

hours([HOURS])

Return (or set) the number of hours in the duration.

NOTE: Specifying more than 24 hours will NOT increment or update the number of days in the duration. The day portion and time portion are considered separate, since the time portion specifies an absolute amount of time, whereas the day portion is not absolute due to daylight savings adjustments. See the nsecs() method if you want more exact control over the "absolute" portion of the duration.

minutes([MINUTES])

Return (or set) the number of minutes in the duration. If more than 59 minutes are specified, the value will be normalized, and the hours portion of the duration will be updated (and the old value destroyed). See the nsecs() method if you want more exact control over the "absolute" portion of the duration.

seconds([SECONDS])

Return (or set) the number of seconds in the duration. If more than 59 seconds are specified, the value will be normalized, and the minutes AND hours portion of the duration will be updated (and the old values destroyed). See the nsecs() method if you want more exact control over the "absolute" portion of the duration.

nsecs([SECONDS])

Retrieve or set the number of seconds in the duration. This sets the entire "absolute" portion of the duration.

ndays([DAYS])

Retrieve or set the number of days in the duration. This sets the entire "calendar" portion of the duration.

clone()

Return a new copy of the duration.

is_valid()

Returns a truth value indicating whether the current object is a valid duration.

as_int()

Return the length of the duration as 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 Net::ICal::Time 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_ical()

Return the duration as a fragment of an iCal property-value string (e.g., ":PT2H0M0S").

as_ical_value()

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

add(DURATION)

Return a new duration that is the sum of this and DURATION. Does not modify this object. Note that the day and time components are added separately, and the resulting sign is taken only from the days. RFC 2445 is unclear on this, so you may want to avoid this method, and do your own calendar/absolute time calculations to ensure that you get the behavior that you expect in your application.

subtract($duration)

Return a new duration that is the difference between this and DURATION. Does not modify this object. Note that the day and time components are added separately, and the resulting sign is taken only from the days. RFC 2445 is unclear on this.

BUGS

   * RFC 2445 is unclear about how days work in durations.
     This code might need to be modified if/when section 4.3.6
     is updated

   * According to the RFC, there's no limit on how many
     seconds, minutes, etc. can be in a duration.  However,
     this implementation always normalizes the day and time
     components, and always reports hours, minutes, and seconds
     (even if one or more of them are zero or weren't initially
     defined).

AUTHOR

See the Reefknot AUTHORS file, or

   http://reefknot.sourceforge.net/

SEE ALSO

More documentation pointers can be found in Net::ICal.

cpanm Net::ICal

perl -MCPAN -e shell
install Net::ICal