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,	a delta	refers only to the 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
	   Deltas can refer to changes in either the full calendar (standard
	   deltas), or they can	refer to a business calendar.

	   With	a business delta, non-business days are	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	will have no impact on business	calculations
	   because time	changes	occur at night (usually	on the weekends)
	   outside of business hours.  As such,	they are ignored in business
	   calculations.

       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 made	consistent with	the type of data they
	   represent. For example, a delta of:

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

	   is not normalized since 70 seconds is better	expressed 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.

       sets of fields
	   When	normalizing a delta, fields are	grouped	together in sets where
	   the exact relationship is known between all fields in the set.

	   For example,	there is an exactly known relationship between seconds
	   and minutes (Date::Manip ignores leap seconds, so there are always
	   60 seconds in a minute), so they will be in one set.

	   Likewise, the relationship between years and	months is known, so
	   they	will be	in one set.  There is no known relationship between
	   months and weeks though, so they will be in separate	sets.

	   A standard (i.e. non-business) delta	contains 3 sets	of fields:

	      approximate:  year, month
	      semi-exact:   week, day
	      exact:	    hour, minute, second

	   The following known relationships exist:

	      1	year   = 12 months
	      1	week   = 7 days
	      1	hour   = 60 minutes
	      1	minute = 60 seconds

	   The following semi-approximate relationships	are used to link the
	   semi-exact and exact	fields when required:

	      1	day    = 24 hours

	   The following approximate relationship is used to link the
	   approximate fields to the semi-exact	fields when required:

	      1	year = 365.2425

	   Business deltas differ slightly,  Since daylight saving times
	   effects are ignored,	the length of the work day is constant,	but
	   due to there	being holidays,	the length of a	week is	not known, so
	   a business delta has	the following sets of fields:

	      approximate:  year, month
	      semi-exact:   week
	      exact:	    day, hour, minute, second

	   and the relationships used are:

	      1	year   = 12 months
	      1	day    = length	of business day
	      1	hour   = 60 minutes
	      1	minute = 60 seconds

	   The semi-approximate	relationship may be used to link the semi-
	   approximate and exact fields	together:

	      1	week   = X  (length of business	week in	days)

	   and the following approximate relationship may be used:

	      1	year   = X/7 * 365.2425

	   When	normalizing a delta, no	data from one set will ever be mixed
	   with	data from another set.

	   As a	result,	the following delta is normalized:

	      0:3:8:0:0:0:0

	   Although 8 weeks is clearly more than 1 month, we don't know	the
	   relationship	between	the two, so they don't mix.

       exact, semi-exact, and approximate deltas
	   An exact delta is one which every value is of an exactly known
	   length (i.e.	it only	includes the exact fields listed above).

	   A semi-exact	delta is a delta which includes	the exact fields as
	   well	as semi-exact ones.

	   An approximate delta	can include any	of the fields.

	   So, the delta:

	      0:3:8:0:0:0:0

	   is approximate.  The	delta:

	      0:0:0:0:30:0:0

	   is exact.  The delta:

	      0:0:0:1:30:0:0

	   is semi-exact (if it	is non-business) or exact (if it is business).

	   The term "semi-exact" needs a little	explanation.  Date::Manip
	   tries to do things in a way which humans think of them.  It is
	   immediately recognized that the approximate fields are of
	   completely unknown length, and the exact fields are of known
	   length. The "semi-exact" fields are termed such since humans	have a
	   way of looking at them which	is consistent, even if it is not
	   exact.

	   For example,	a day is thought of as the same	wall clock time	on two
	   successive days, so from noon on one	day to noon the	next day is
	   one day.  Usually that is 24	hours (for standard deltas), but if
	   you cross a daylight	saving time change, it might be	23 or 25 hours
	   (or something different if a	very irregular time change occurs).
	   So where possible, in a standard delta, a day field will change the
	   date, but leave the time alone.

	   Likewise, a business	week is	thought	of as 7	days (i.e. Wednesday
	   to Wednesday) regardless of whether there was a holiday in there.

       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

	   Since there is no mixing of data between sets of fields, you	can
	   end up with a delta with as many as four signs. So, the following
	   is a	fully normalized business delta:

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

       fractional values
	   Fractional fields are allowed such as:

	      1.25 days
	      1.1 years

	   When	parsing	a delta	with fractional	fields,	the delta will ALWAY
	   be normalized using the exact, semi-exact, and approximate
	   relationships described above.

	   For example,	for a non-business delta, a delta of 1.1 years will
	   use the following relationships:

	      1	year = 365.2425	days
	      1	year = 12 months
	      1	day  = 24 hours

	   Since the delta includes approximate	fields,	as much	of the 1.1
	   year	portion	of the delta will be stored in the approximate fields
	   as possible.

	   Using the above approximate relationships, we can see that:

	      1	month =	365.2425/12 days = 30.436875 days

	   so

	      1.1 years
	      =	1 year,	1.2 months
	      =	1 year,	1 month, 6.087375 days
	      =	1 year,	1 month, 6 days, 2 hours, 5 minutes, 49	seconds

	   Fractional seconds will be discarded	(no rounding).

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 [,$business]	[,$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.

	   A valid delta is in one of two forms: compact or expanded.

	   The compact format is a colon separated list	of numbers (with
	   optional signs):

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

	   In the compact format, 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 compact format. 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 expanded	format 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 format 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, month, months
	      w:  w, wk, ws, wks, week,	weeks
	      d:  d, day, days
	      h:  h, hr, hour, hours
	      mn: mn, min, minute, minutes
	      s:  s, sec, 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. Numbers may be spelled out, so

	      in two weeks
	      in 2 weeks

	   both	work.

	   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 2nd
	   argument to the function.  The $business argument may be a string
	   'standard' or 'business' to explicitly set the type of delta.
	   Alternately,	any non-zero value for $business will force the	delta
	   to be a business delta.

	   So the following are	identical:

	      $delta->parse($string,'business');
	      $delta->parse($string,1);

	   and the following are identical:

	      $delta->parse($string);
	      $delta->parse($string,'standard');
	      $delta->parse($string,0);

	   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.
	   When	this is	done, these strings override any value of the
	   $business argument.

	   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	both types of deltas, 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.  The accuracy of delta (exact, semi-exact, approximate)
	   will	be determined only by what fields are present in the delta.

	   When	a delta	is parsed, it is automatically normalized, unless the
	   $no_normalize argument is passed in.	 It can	be the string
	   'nonormalize' or any	non-zero value.	 If passing it as a non-zero
	   value, the $business	argument MUST be included (though it can be
	   zero) in order to avoid ambiguity.

	   So the following are	equivalent:

	      $delta->parse($string,'nonormalize');
	      $delta->parse($string,$business,1);

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

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

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

	   This	explicitly sets	one or more fields in a	delta.

	   $field can be any of	the following:

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

	      mode     business, standard

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

	   When	setting	the entire delta with "business" or "normal", it flags
	   the delta as	a business or non-business delta respectively. When
	   setting the entire delta with "delta", the flag is left unchanged.
	   Also, when setting the entire delta,	signs are not carried from one
	   field to another.

	   By default, a delta is normalized, but passing $no_normalize	as any
	   true	value, this will not be	done.

	   If $no_normalize is not passed in, the current value	for the	delta
	   (which defaults to 0) will be used.

	   For backwards compatibility,	'normal' can be	used in	place of
	   'standard', both as $field or as $val.

       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
	      $date2  =	$delta->calc($date1 [,$subtract]);
	      $delta3 =	$delta1->calc($delta2 [,$subtract]);

	   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

       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 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
	   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, and will be strictly positive
	   or negative (i.e. all fields	will have the same sign).

	   This	function can be	used to	take an	exact delta and	turn it	into a
	   semi-exact delta (with a day	being treated as 24 hours in non-
	   business mode).

	   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.

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	(in the	normalized delta).

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

	   '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 unless 'width' is included.	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.24.1			  2017-03-01		 Date::Manip::Delta(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | 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+12.0-RELEASE+and+Ports>

home | help