Date::I...uration(3)

💖 NAME 💖

Date::ICal::Duration — durations in iCalendar format, for math purposes. That's the whole thing bestie, that's the assignment. 🎀

---

🌸 VERSION 🌸

$Revision: 682 $

---

🦋 SYNOPSIS 🦋

okay so here's the vibe, copy-paste ready:

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

(yeah the TODO is literally in the docs, iconic honestly, no cap 💀)

---

🌈 DESCRIPTION 🌈

This is a trivial class for representing duration objects, for doing math in Date::ICal. It's giving "small but mighty", and we love her for it. 💅

---

👑 AUTHOR 👑

Rich Bowen, and the Reefknot team. Alas, Reefknot is no more. 😭 See <https://github.com/houseabsolute/DateTime.pm/wiki> or <https://metacpan.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 the legal values. That's it. Those two. Don't be weird about it. 🙈

🔍 sign, weeks, days, hours, minutes, seconds

Read-only accessors for the elements of the object. Look, don't touch. 🫶

⏱️ 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 one returns the total number of days, rather than mod'ing out the complete weeks. So like, if we have a duration of 33 days, "weeks" will return 4, "days" will return 5, but "as_days" will return 33. slay. ✨

Note that this is a lazy convenience function which is just weeks*7 + days. She said low effort, high reward. 💅

📆 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 🧠

🏗️ 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. They are not your bestie, they are acquaintances at best. 😭

_set_from_ical ($self, $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, $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, $num_seconds)

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

$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.

$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.

---

📜 LICENSE AND COPYRIGHT 📜

© 2001-2022 Rich Bowen

© 2022-2023 Michal Josef Špaček

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

---

okay bestie that's a wrap 🎀 this lil page came to you via perl v5.42.0, dated 2025-07-25, and that's the whole manual, mwah 💋 go do some date math, you got this 👑