view release on metacpan or  search on metacpan

lib/Date/Manip/Delta.pod  view on Meta::CPAN

# Copyright (c) 1995-2026 Sullivan Beck. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself.

=pod

=head1 NAME

Date::Manip::Delta - Methods for working with deltas

=head1 SYNOPSIS

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

=head1 DESCRIPTION

This module contains functions useful in parsing and manipulating
deltas.  As used in this module, the term delta refers to an amount
of time elapsed.  It includes no information about a starting or
ending time.

There are several concepts involved in understanding the properties
of a delta.

=over 4

=item B<standard and business delta>

There are two different modes for working with deltas: standard and
business.  The mode used depends on how you treat the calendar.

Standard deltas use the full calendar without any modifications.

A business delta uses a calendar in the way a business might.  In a
business calendar, anything outside of a business day is ignored.
Typically, this includes holidays and weekends.  In addition, the part
of the day outside of business hours is also ignored, so a day may
only run from 08:00 to 17:00 and everything outside of this is
ignored.

The length of a work day is usually not 24 hours.  It is defined by
the start and end of the work day and is set using the config
variables: B<WorkDayBeg> and B<WorkDayEnd> (B<WorkDay24Hr> may be used to
specify a 24-hour work day).  The work week is defined using the
config variables: B<WorkWeekBeg> and B<WorkWeekEnd>.

Daylight saving time are ignored with business calculations because
time changes occur at night (usually on the weekends) outside of
business hours.  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.

=item B<fields>

A delta consists of 7 fields: years, months, weeks, days, hours,
minutes, and seconds, usually expressed as a colon-separated string.
For example:

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

refers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4 days,
5 hours, 6 minutes, and 7 seconds long.

=item B<normalized>

A delta can be normalized or not. A normalized delta has values which
have been simplified based on how a human would think of them.  As an
example, the delta:

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

is not normalized since 70 seconds is typically thought of as 1 minute
10 seconds. The normalized form of this delta would be:

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

By default, deltas are converted to a normalized form in most
functions that create/modify a delta, but this can be overridden.

=item B<Types of deltas>

There are 4 type of deltas that are available.

=over 8

=item 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).  The lengths are defined as:

   1 hour   = 3600 seconds