Date::Manip::Delta(3)

✨ NAME ✨

Date::Manip::Delta — bestie, this is the whole methods-for-working-with-deltas situation 💖

(It's the Date::Manip::Delta page from the User Contributed Perl Documentation, and we're doing this in three parts, so buckle up 🎀)

---

🌸 SYNOPSIS 🌸

use Date::Manip::Delta;
$date = new Date::Manip::Delta;

periodt. that's the whole intro 🫶

---

🦋 DESCRIPTION 🦋

Okay so this module is packed with functions that are useful for parsing and manipulating deltas. And what even is a delta, you ask? 💅

A delta = an amount of time that has elapsed. That's it. It has zero info about when it started or when it ended. It's just vibes and duration, no timestamps. 🕰️

There are a few concepts you gotta understand to really get delta properties, so let's go one by one:

💫 standard and business delta

There are two modes for working with deltas: standard and business. Which one you're in depends on how you treat the calendar. 📅

• Standard deltas use the full calendar, no modifications, no notes, nothing. Straight up the calendar as-is.
• A business delta uses a calendar the way a business would. In a business calendar, anything outside of a business day is simply ignored. Usually that means holidays and weekends. And on top of that, the part of the day outside business hours is ignored too — so like, a day might only run from 08:00 to 17:00, and everything outside of that? ignored, bestie. 🙈

The length of a work day is usually not 24 hours. It's defined by the start and end of the work day, and you set it with these config variables: WorkDayBeg and WorkDayEnd (and you can use WorkDay24Hr if you want to specify a 24-hour work day). The work week gets defined with: WorkWeekBeg and WorkWeekEnd. ⭐

Daylight saving time is ignored with business calculations, because time changes happen at night (usually on the weekends) outside of business hours. Now — this may yield unexpected results if the work day is defined to be 24-hours and the work week includes a day when a time change occurs. So like, heads up on that one 👀

💫 fields

A delta is made of 7 fields: years, months, weeks, days, hours, minutes, and seconds. Usually written as a colon-separated string. For example:

1:2:3:4:5:6:7

means an elapsed amount of time that is 1 year, 2 months, 3 weeks, 4 days, 5 hours, 6 minutes, and 7 seconds long. seven little numbers, one big time vibe 🌈

💫 normalized

A delta can be normalized or not. A normalized delta has values that have been simplified based on how a human would think of them. 🧠✨

Example time! This delta:

0:0:0:0:0:10:70

is not normalized, because 70 seconds is typically thought of as 1 minute 10 seconds. The normalized form would be:

0:0:0:0:0:11:10

By default, deltas get converted into a normalized form in most functions that create/modify a delta — but this can be overridden. 💅

💫 Types of deltas

There are 4 types of deltas available. Let's meet them 👑

🌟 Exact deltas

The most common type (and the default in most situations) is an exact delta. An exact delta is one where only fields which have exactly known lengths are allowed to be non-zero.

For standard calculations, there are only three exactly known fields: hours, minutes, and seconds. Their lengths are defined as:

1 hour   = 3600 seconds
1 minute = 60 seconds

Note that since a day is NOT always 24 hours (daylight saving time changes, hello 😭), a day is not an exactly known field.

For business calculations, a day IS an exactly known field. Since business mode ignores daylight saving time, the length of the day can be calculated based on the config variables listed above. So for example, if the work day is 08:00-17:00, the length of the day is 9 hours. The length of the week is still unknown though, since some work weeks may have fewer days than others due to holidays. 🎀

All fields which are not exactly known will always have zero value. no cap.

🌟 Semi-exact deltas

A semi-exact delta treats the day/week fields as if they were exactly known.

For standard calculations, this is done by using the relationships:

1 day  = 24 hours
1 week = 7 days

For business calculations, it's done by treating a week as a constant length (determined by the config variables listed above), ignoring holidays. So if a typical work week is Mon-Fri, the length of the week is 5 days.

For semi-exact deltas, the value of the year/month must be zero. 🚫

Although this may yield some values that aren't exactly accurate around daylight saving time transitions, strictly speaking, they yield results that are useful in terms of how humans think of deltas. it's giving practical 💖

🌟 Approximate deltas

An approximate delta can have non-zero values for all fields. When normalizing the fields, the year/month fields are treated as one set using the relationship:

1 year  = 12 months

The remaining fields are normalized using the semi-exact relationships. 🌸

🌟 Estimated deltas

The final type of delta is the estimated delta. These are deltas where an estimated length is applied to all the approximate fields.

For standard deltas, the additional relationship:

1 year = 365.2425 days

is used. For business deltas, the additional relationship:

1 year   = X/7 * 365.2425 days

(where X is the number of work days in a week) is used.

Fractional seconds will be discarded (not rounded). 💀

NOTE: it is not possible to look at a delta and determine what type it is. For example, a standard delta with a non-zero day value might be approximate or semi-exact. The type will need to be explicitly selected, or determined by the context of the operation. 👑

💫 signs

Each field has a sign associated with it. For example, the delta "1 year ago" is written as:

-1:0:0:0:0:0:0

The sign of any field is optional, and if you omit it, it's the same as the next higher field. So these two are identical:

+1:2:3:4:5:6:7
+1:+2:+3:+4:+5:+6:+7

In a normalized delta, all fields in a set will have the same sign. So this standard delta:

0:0:+3:-2:0:0:0:0   (3 weeks -2 days)

is not normalized. The normalized version would be:

0:0:+2:5:0:0:0:0    (2 weeks, 5 days)

Since an approximate delta has two sets (the y/m set and the w/d/h/mn/s set), these deltas may have two signs. So the following is a fully normalized approximate delta:

+1:0:-3:3:1:0:0

💫 fractional values

Fractional fields are allowed, such as:

1.25 days
1.1 years

but whenever you parse a delta with fractional fields, the delta will be normalized using the estimated relationships described above. Fractional seconds will be discarded. 🫶

---

🎀 METHODS 🎀

okay bestie so there's a whole lil squad of methods that don't actually live here — they're inherited from the parent class. here's the roll call, and you go read Date::Manip::Obj for the deets:

• new
• new_config
• new_date
• new_delta
• new_recur
• base
• tz
• is_date
• is_delta
• is_recur
• config
• err

Please refer to the Date::Manip::Obj documentation for these methods.

---

🌸 parse 🌸

$err = $delta->parse($string, \%opts);
$err = $delta->parse($string [,$business] [,$no_normalize]);

so this second format? it's still hanging around for backward compatibility, but it's deprecated and it's getting yeeted in Date::Manip 7.00. bestie, it's literally just shorthand for this:

$err = $delta->parse($string, { business => $business,
                                nonorm   => $no_normalize });

what it does: you hand it a string, it peeks at it to see if it's a valid delta. if yes — error code 0 comes back and $delta is now holding that delta's value. if no — error code 1, and an error condition gets set on the delta. that's it, that's the whole vibe check. ✨

Recognized options are:

mode      : standard/business
            to specify if it is a business delta or a standard delta
nonorm    : 0/1
            1 if the delta should not be normalized
type      : exact, semi, approx, estimated

and heads up: when you specify the type, the delta you pass in has to actually satisfy that type's requirements — like, no year field for an exact delta. it's giving "read the rules before you submit." 💅

a delta string is usually written in compact notation, which is just a colon-separated list of numbers (signs optional, slay):

Examples:
   0:0:0:0:4:3:-2
   +4:3:-2
   +4::3

in compact notation you can give anywhere from 1 to 7 of the fields. like, you can do D:H:MN:S and only specify four of them. no spaces allowed in the string, but omitting some fields is totally fine — 5::3:30 is valid, and any missing field just defaults to 0. easy.

the delta string can also be written using common field abbreviations, and that's all described down in the "ADDITIONAL DELTA NOTATIONS" section. 🦋

---

🌈 input 🌈

$str = $delta->input();

returns the string that got parsed to make this delta. the receipts, basically. 🧾

---

💜 set 💜

$err = $delta->set(\%opts);
$err = $delta->set($field,$val [,$no_normalize]);

again with the second format — backward compat only, deprecated, gone in Date::Manip 7.00. it's equivalent to:

$err = $delta->set( $field => $val, 'nonorm' => $no_normalize );

this method explicitly sets one or more parts of a delta. %opts is a bunch of key/value pairs:

$key     $val

delta    [Y,M,W,D,H,MN,S]  sets the entire delta
business [Y,M,W,D,H,MN,S]  sets the entire delta
standard [Y,M,W,D,H,MN,S]  sets the entire delta
y        YEAR              sets one field
M        MONTH
w        WEEK
d        DAY
h        HOUR
m        MINUTE
s        SECOND

nonorm   0/1
mode     business, standard
type     exact, semi, estimated, approx

if you pass in invalid data, you get an error back. rude, but fair.

%opts can only include one key that affects each field — so you can set delta or business but not both, and you can't set both delta and y... but you CAN set both y and w. make it make sense, it does. 🙈

when you set the entire delta with business or standard, it flags the delta as a business or standard mode delta respectively. in those cases you're not allowed to set the mode option. partial deltas are allowed though (like [H,MN,S]), and then zeros get added for every field you didn't specify. cute.

when you set the entire delta with delta, the flag stays exactly how it was — unless you also passed in the mode option.

also, when you're setting the entire delta, signs do NOT carry from one field to another, so [-1,2,...] is the same as [-1,+2,...]. noted. 📝

by default a delta gets normalized, but setting the nonorm key to a true value means nope, we're not doing that.

for backwards compatibility, normal can be used in place of standard — both as $field or as $val. this is deprecated and will be removed in Date::Manip 7.00.

when you set any field in the delta, the type of the delta gets figured out automatically: exact (if the only non-zero fields are the exactly-known ones), semi (if only semi-exact or exact fields are included), or approx otherwise. if the type option is set, it'll be used — provided it's valid (i.e. you can't set it to exact when fields that aren't exactly known are set). 👑

---

✨ printf ✨

$out = $delta->printf($in);
@out = $delta->printf(@in);

takes a string or a list of strings that can contain any number of special formatting directives. those directives get swapped out for info living inside the delta, and literally everything else in the string comes back untouched. 💖

a directive always starts with %, and they're all described below in the "PRINTF DIRECTIVES" section. iykyk.

---

🦋 calc 🦋

Please refer to the Date::Manip::Calc documentation for details.

---

🎀 type 🎀

$flag = $delta->type($op);

this tests whether a delta is of a certain type. $op can be:

• business — returns 1 if it's a business delta
• standard — returns 1 if it's a standard (non-business) delta
• exact — returns 1 if it's exact
• semi — returns 1 if it's semi-exact
• approx — returns 1 if it's approximate
• estimated — returns 1 if it's estimated

---

🍓 value 🍓

$val = $delta->value();
@val = $delta->value();

returns the value of the delta. in scalar context it gives you the printable string (same as the printf directive '%Dt'). in list context it hands you back a list of fields. 🔥

and if there's no valid delta stored in $delta? you get an empty string/list. nothing. silence. 💀

---

💅 convert 💅

$delta->convert($to);

this converts a delta from one type to another. $to can be 'exact', 'semi', or 'approx'. the conversion uses the approximate and estimated relationships listed above to do its thing.

so like, if the exact non-business delta $delta contains:

0:0:0:0:44:0:0

then this call:

$delta->convert('semi')

would produce the semi-exact delta:

0:0:0:1:20:0:0

and the result will always be normalized. periodt.

converting from one type to another that's less exact (so, exact → semi-exact, or semi-exact → approx) is supported. converting the other direction is supported for backward compatibility, but it's getting removed in 7.00 — because that operation is not one that is well defined. don't do it, bestie.

there's currently no support for converting business to non-business (or vice-versa). nope. 🙅

---

🌈 cmp 🌈

$flag = $delta1->cmp($delta2);

this compares two deltas — using those approximate relationships listed above — and returns -1, 0, or 1, which you could use to sort them by length of time. main character energy for sorting algorithms. 👑

both deltas have to be valid, and both have to be either business or non-business deltas. they do not need to be the same one out of exact, semi-exact, and approximate though — mix and match, we love that.

you'll get undef back if either delta is invalid, or if you try to compare a business delta with a non-business one. 🫶

---

🌸 ADDITIONAL DELTA NOTATIONS 🌸

okay so bestie, when you're parsing a delta you don't have to use the colon-separated thing. you can literally just spell the fields out. it's giving ✨full sentences✨

this expanded notation spells out the fields in some language-specific form, like:

Examples:
   +4 hours +3mn -2second
   + 4 hr 3 minutes -2
   4 hour + 3 min -2 s
   4 hr 2 s

each field in the expanded notation is: an optional sign, a number, and a string that says what kind of field it is. and here's the tea — if the sign is absent, it defaults to the sign of the next larger element. so these two are literally the same thing:

-4 hr 3 min 2 sec
-4 hr -3 min -2 sec

the valid strings for each field live in the "Delta field names" section of the appropriate Date::Manip::Lang::<LANGUAGE> document. go check the Date::Manip::Lang doc for the list of languages 💜

for example, for English the doc is Date::Manip::Lang::English and the field names include strings like:

y:  y, yr, year, years
m:  m, mon, mons, month, months
w:  w, wk, ws, wks, week, weeks
d:  d, day, days
h:  h, hr, hrs, hour, hours
mn: mn, min, mins, minute, minutes
s:  s, sec, secs, second, seconds

heads up: this list may not be complete. you should refer to the language document for the full list, fr fr.

the "seconds" string may be omitted. and the sign, number, and string may all be separated from each other by any amount of whitespace. but — and this is important — the string specifying the unit must be separated from a following number by whitespace or a comma, so this next one will NOT work:

4hours3minutes

at minimum, it must be expressed as:

4hours 3minutes
4 hours, 3 minutes

in the the expanded format, all fields must be given in the order: Y M W D H MN S. any number of them may be omitted as long as the rest stay in the correct order. small numbers may be spelled out, so

in two weeks
in 2 weeks

both work (but do not rely on this to work for large numbers, bestie 🙈).

most languages also let you use a word to say whether the delta is an amount of time after or before a fixed point. in English, the word "in" means a time after a fixed point, and "ago" means a point before a fixed point. so these deltas are equivalent:

1:0:0:0:0:0:0
in 1 year

and these are equivalent:

-1:0:0:0:0:0:0
1 year ago

the word "in" is completely ignored. the word "ago" has the affect of reversing all signs that appear in front of the components of the delta. in other words, these two strings are identical:

-12 yr  6 mon ago
+12 yr +6 mon

(don't forget there's an implied minus sign in front of the 6 in the first string, because when no sign is explicitly given, it carries the previously entered sign. slay, consistency 💅)

the in/ago words only apply to the expanded format, so this next one is invalid:

1:0:0 ago

a delta may be standard (non-business) or business. by default a delta is treated as non-business, but you can change that in two different ways 👑

the first way to make a delta be business is to pass in the appropriate option. for example:

$delta->parse($string, { 'mode' => 'business' });
$delta->parse($string, { 'mode' => 'standard' });

the second way is to include a key word in the string that's parsed. if this string is included, it should not conflict with the value of a 'mode' option.

most languages include a word like "business" which can be used to specify that the resulting delta is a business delta or a non-business delta. other languages have equivalent words. the placement of the word is not important. also, the "business" word can be included with all types of deltas, and in both compact and expanded notation, so these are valid and equivalent:

in 4 hours business
4:0:0 business
business 0:0:0:0:4:0:0

there are also words "exact" or "approximate" which may be included in the delta for backward compatibility. however, they will be ignored. they will be removed in Date::Manip 7.00. the accuracy of delta (exact, semi-exact, approximate) will be determined only by what fields are present in the delta and the options passed in. and when a delta is parsed, it is automatically normalized — unless the 'nonorm' option is passed in 😌

---

💖 PRINTF DIRECTIVES 💖

the following printf directives get replaced with information from the delta. a directive may be replaced by the value of a single field in the delta (i.e. the hours or weeks field), the value of several fields expressed in terms of one of them (i.e. the number of years and months expressed in terms of months), or the directive may format either the entire delta, or portions of it. it's giving versatility ✨

🎀 Simple directives

these are directives which print simple characters. currently the only one is:

• %% — Replaced by a single '%'

as an example:

$delta->printf('|%%|');
   => |%|

🦋 Directives to print out a single field

the following directive is used to print out the value of a single field. spaces are included here for clarity, but are not in the actual directive.

% [+] [pad] [width] Xv

here, X is one of (y,M,w,d,h,m,s). the directive will print out the value for that field.

if a '+' is included immediately after the '%', a sign will always be included. by default, only negative values will include a sign.

'width' and 'pad' are used to set the width of the string containing the field as well as how it's padded.

'width' is any positive integer (without a sign). if 'width' is included, it sets the length of the output string (unless the string is already longer than that, in which case the 'width' is ignored).

if 'pad' is included, it may be the character '<', '>', or '0'. it will be ignored if 'width' is not included, or the string is already longer than 'width'. if the formatted delta field is shorter than 'width', it will be padded with spaces on the left (if 'pad' is '<'), or right (if 'pad' is '>'), or it will be padded on the left (after any sign) with zeroes (if 'pad' is '0'). periodt 💅

in the following examples, $delta contains the delta: 1:2:3:4:5:6:7

$delta->printf('|Month: %Mv|');
   => |Month: 2|

$delta->printf('|Day: %+05dv|');
   => |Day: +0004|

$delta->printf('|Day: %+<5dv|');
   => |Day:    +4|

$delta->printf('|Day: %>5sv|');
   => |Day: 7    |

🌈 Directives to print out several fields in terms of one of them

the following directive is used to print out the value of several different fields, expressed in terms of a single field.

% [+] [pad] [width] [.precision] XYZ

here, X, Y, and Z are each one of (y,M,w,d,h,m,s). the directive will print out the value for fields Y through Z expressed in terms of field X.

Y must come before Z in the sequence (y,M,w,d,h,m,s) or it can be the same as Z.

so, to print the day and hour fields in terms of seconds, use the directive:

%sdh

any time all of X, Y, and Z are from a single set of fields, exact relationships are used.

if the X, Y, and Z fields do not all belong to the same set of fields, approximate relationships are used.

for non-business deltas, an approximate relationship is needed to link the Y/M part of the delta to the W/D part and a semi-approximate relationship is needed to link the W/D part with the H/MN/S part. these relationships are:

1 day    = 24 hours
1 year   = 365.2425

for business deltas, the approximate and semi-approximate relationships used to link the fields together are:

1 week   = X    (length of business week in days)
1 year   = X/7 * 365.2425

for business deltas, the length of the day is defined using WorkDayStart and WorkDayEnd. for non-business deltas, a day is 24 hours long (i.e. daylight saving time is ignored). 🕐

if 'precision' is included, it is the number of decimal places to print. if it is not included, but 'width' is included, precision will be set automatically to display the maximum number of decimal places given 'width'.

if 'pad' is included, it may be the character '<', '>', or '0', and is used in the same way as printing out a single field.

in the following examples, $delta contains the delta: 1:2:3:4:5:6:7

$delta->printf('|%.4Myw|');
   => |14.6900|
   1 year, 2 months, 3 weeks is approximately
   14.6900 months

🌸 Directives to print out portions of the delta

the following directives may be used to print out some or all of a delta.

% [+] [pad] [width] Dt
% [+] [pad] [width] DXY

the first directive will print out the entire delta.

the second will print out the delta from the X to Y fields inclusive (where X and Y are each one of (y,M,w,d,h,m,s) and X must come before Y in the sequence).

'pad' is optional and can be either '<' or '>' meaning to pad on the left or right with spaces. it defaults to '<'.

if a '+' is included immediately following the '%', every field will have a sign attached. otherwise, only the leftmost field in each set of fields will include a sign.

$delta->printf('|%Dt|');
   => |+1:2:+3:+4:5:6:7|

$delta->printf('|%+Dyd|');
   => |+1:+2:+3:+4|

---

💀 KNOWN BUGS 💀

None known. (we love a clean record, no cap 🙌)

😭 BUGS AND QUESTIONS 😭

please refer to the Date::Manip::Problems documentation for information on submitting bug reports or questions to the author. they wanna hear from you bestie 🫶

👑 SEE ALSO 👑

• Date::Manip - main module documentation

📜 LICENSE 📜

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

✨ AUTHOR ✨

Sullivan Beck (https://github.com/SBECK-github/)

---

and that's a wrap on Date::Manip::Delta(3) 💖 this whole page is the perl v5.42.3 version, dated 2026-09-01 — go forth and delta responsibly, bestie. slay, normalize, and always read your language docs 🌈🎀