Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Date::Manip::Delta(3) User Contributed Perl DocumentationDate::Manip::Delta(3)

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

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

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.

       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: WorkDayBeg and WorkDayEnd	(WorkDay24Hr may be used to
	   specify a 24-hour work day).	 The work week is defined using	the
	   config variables: WorkWeekBeg and 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.

       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.

       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.

       Types of	deltas
	   There are 4 type of deltas that are available.

	   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
		      1	minute = 60 seconds

		   Note	that since a day is NOT	always 24 hours	(due to
		   daylight saving time	changes), 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 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.

	   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 is 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 are	not exactly
		   accurate around daylight saving time	transitions, strictly
		   speaking, they yield	results	that are useful	in terms of
		   how humans think of deltas.

	   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 are estimated deltas.  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 omitted, it is the	same
	   as the next higher field.  So, the following	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 the 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	parsing	a delta	with fractional	fields,	the delta will
	   be normalized using the estimated relationships described above.
	   Fractional seconds will be discarded.

METHODS
       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]);

	   The second format is	supported for backward compatibility, but is
	   deprecated and will be removed in Date::Manip 7.00.	The second
	   form	is equivalent to:

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

	   This	takes a	string and parses it to	see if it is a valid delta. If
	   it is, an error code	of 0 is	returned and $delta now	contains the
	   value of the	delta. Otherwise, an error code	of 1 is	returned and
	   an error condition is set in	the delta.

	   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

	   When	specifying the type, the delta given must satisfy the
	   requirements	of the type (i.e. no year field	for an exact delta).

	   A delta string is usually specified in compact notation which
	   consists of a colon separated list of numbers (with optional
	   signs):

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

	   In compact notation,	from 1 to 7 of the fields may be given.	 For
	   example D:H:MN:S may	be given to specify only four of the fields.
	   No spaces may be present in the string, but it is allowed to	omit
	   some	of the fields. For example 5::3:30 is valid. In	this case,
	   missing fields default to the value 0.

	   The delta string may	also be	specified using	common field
	   abbreviations.  This	is described below in the "ADDITIONAL DELTA
	   NOTATIONS" section.

       input
	      $str = $delta->input();

	   This	returns	the string that	was parsed to form the delta.

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

	   The second format is	supported for backward compatibility, but is
	   deprecated and will be removed in Date::Manip 7.00.	The second
	   form	is equivalent to:

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

	   This	explicitly sets	one or more parts of a delta.  %opts is	a set
	   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

	   An error is returned	if an invalid data is passed in.

	   %opts can only include a single key that affects each field (i.e.
	   you can set delta or	business but not both, and you cannot set both
	   delta and y,	but you	CAN set	both y and w).

	   When	setting	the entire delta with business or standard, it flags
	   the delta as	a business or standard mode delta respectively.	In
	   those cases,	you are	not allowed to set the mode option.  Partial
	   deltas are allowed (i.e. [H,MN,S]) in which case zeros are added
	   for all fields not specified.

	   When	setting	the entire delta with delta, the flag is left
	   unchanged (unless the mode option is	also passed in).

	   Also, when setting the entire delta,	signs are not carried from one
	   field to another, so	[-1,2,...] is equivalent to [-1,+2,...].

	   By default, a delta is normalized, but setting the nonorm key to a
	   true	value will not do 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	setting	any field in the delta,	the type of delta will be
	   determined automatically as either exact (if	only fields that are
	   exactly known are have non-zero fields), semi (if only fields that
	   are semi-exact or exact are included), or approx otherwise.	If the
	   type	option is set, it will be used provided	it is valid (i.e. you
	   cannot set it to exact if fields that are not exactly known are
	   set).

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

	   This	takes a	string or list of strings which	may contain any	number
	   of special formatting directives. These directives are replaced
	   with	information contained in the delta. Everything else in the
	   string is returned unmodified.

	   A directive always begins with '%'. They are	described in the
	   section below in the	section	"PRINTF	DIRECTIVES".

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

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

	   This	tests to see if	a delta	is of a	certain	type. $op can be;

	      business	: returns 1 if it is a business	delta
	      standard	: returns 1 if it is a standard	(non-business delta)

	      exact	: returns 1 if it is exact
	      semi	: returns 1 if it is semi-exact
	      approx	: returns 1 if it is approximate
	      estimated	: returns 1 if it is estimated

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

	   This	returns	the value of the delta.	In scalar context, it returns
	   the printable string	(equivalent to the printf directive '%Dt'). In
	   list	context, it returns a list of fields.

	   An empty string/list	is returned if there is	no valid delta stored
	   in $delta.

       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 convert the delta.

	   For example,	if the exact non-business delta	$delta contains:

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

	   then	the following call:

	      $delta->convert('semi')

	   would produce the semi-exact	delta:

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

	   The result will always be normalized.

	   Converting from one type to another that is less exact (i.e.	exact
	   to semi-exact or semi-exact to approx) is supported.	 Converting
	   the other direction is supported for	backward compatibility,	but
	   will	be removed in 7.00 because that	operation is not one that is
	   well	defined.

	   There is currently no support for converting	business to non-
	   business (or	vice-versa).

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

	   This	compares two deltas (using the approximate relationships
	   listed above) and returns -1, 0, or 1 which could be	used to	sort
	   them	by length of time.

	   Both	deltas must be valid, and both must be either business or non-
	   business deltas.  They do not need to be the	same out of exact,
	   semi-exact, and approximate.

	   undef will be returned if either delta is invalid, or you try to
	   compare a business and non-business delta.

ADDITIONAL DELTA NOTATIONS
       When parsing a delta, the string	may be specified with the field
       spelled out, rather than	using the colon	separated fields.

       This expanded notation has the fields spelled out in some language
       specific	form:

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

       A field in the expanded notation	has an optional	sign, a	number,	and a
       string specifying the type of field.  If	the sign is absent, it
       defaults	to the sign of the next	larger element.	 So the	following are
       equivalent:

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

       The valid strings describing each of the	fields is contained in "Delta
       field names" section of the appropriate Date::Manip::Lang::<LANGUAGE>
       document.  Refer	to the Date::Manip::Lang document for a	list of
       languages.

       For example, for	English, the document 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

       This list may not be complete.  You should refer	to the language
       document	for the	full list.

       The "seconds" string may	be omitted.  The sign, number, and string may
       all be separated	from each other	by any amount of whitespace. The
       string specifying the unit must be separated from a following number by
       whitespace or a comma, so the following example 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 provided the rest	remain
       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).

       Most languages also allow a word	to specify whether the delta is	an
       amount of time after or before a	fixed point. In	English, the word "in"
       refers to a time	after a	fixed point, and "ago" refers to a point
       before a	fixed point. So, the following deltas are equivalent:

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

       and the following 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, the following two strings are identical:

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

       (don't forget that there	is 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).

       The in/ago words	only apply to the expanded format, so the following is
       invalid:

	  1:0:0	ago

       A delta may be standard (non-business) or business. By default, a delta
       is treated as a non-business delta, but this can	be changed 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 to specify whether a delta is business or	non-business
       is to include a key word	in the string that is 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 the
       following 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.  When a delta is
       parsed, it is automatically normalized, unless the 'nonorm' option is
       passed in.

PRINTF DIRECTIVES
       The following printf directives are replaced with information from the
       delta. Directives may be	replaced by the	values 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.

       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 is 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').

	   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.

BUGS AND QUESTIONS
       Please refer to the Date::Manip::Problems documentation for information
       on submitting bug reports or questions to the author.

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 (sbeck@cpan.org)

perl v5.32.1			  2020-06-01		 Date::Manip::Delta(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | ADDITIONAL DELTA NOTATIONS | PRINTF DIRECTIVES | KNOWN BUGS | BUGS AND QUESTIONS | SEE ALSO | LICENSE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Date::Manip::Delta&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help