Date::Manip::Delta man page on OpenMandriva

Man page or keyword search:  
man Server   8135 pages
apropos Keyword Search (all sections)
Output format
OpenMandriva logo
[printable version]

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.

       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

	   Deltas are automatically converted to a normalized form in almost
	   all functions.

       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, in a normal delta, it is known that there are exactly
	   60 seconds in a minute, exactly 60 minutes in an hour, etc.

	   It is NOT known how many weeks are in a month however. So, the year
	   and month fields form one set, and the weeks, days, hours, minutes,
	   and seconds form a second set.

	   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 deltas
	   An exact delta is one which does not include any fields which
	   cannot be exactly written in terms of seconds. For example, a delta
	   which includes a year or month field can never be exact since there
	   is no exact length for either.

	   So, the delta:

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

	   is not exact, but the delta:

	      0:0:0:12:30:0:0

	   is exact.

       business delta
	   Deltas can refer to changes in either the full calendar, or they
	   can refer to a business calendar.

	   Business deltas have the added complexity that there is no definite
	   relationship between the number of work days in a work week (there
	   may be a holiday during the week). As a result, there are three
	   sets of fields: year/month, week, day/hour/minute/second.  An exact
	   business delta will not have a year, month, or week field.

	   There IS a definite relationship between hours and days, but it is
	   probably not 24 hours = 1 day. Common definitions of a work day
	   include 8 hours long (09:00-17:00) or 9 hours long (08:00-17:00),
	   and any other definition may be included may be defined as long as
	   the start time is earlier in the day than the end time. The config
	   variables WorkDayBeg, WorkDayEnd, and WorkDay24Hr can be used to
	   defined the length of the work day.

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

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

	   Since there is no mixing of data between sets of fields, you can
	   end up with a delta with two (or three in the case of business
	   deltas) signs. So, the following is a fully normalized business
	   delta:

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

	   Note that for a fully normalized delta, the leading field in each
	   set of fields will always have a sign, even when it is redundant or
	   unnecessary.

	   For example:

	      +2:1:+2:6:23:51:30
	      +0:0:+0:0:0:0:10

	   In a normalized delta, all fields in a set will have the same sign.

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

	   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.

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

	   The colon format is:

	      +Y:+M:+W:+D:+H:+MN:+S
		 examples:
		    0:0:0:0:4:3:-2
		    +4:3:-2
		    +4::3

	   In the colon 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 colon 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 is:

	      +Yy +Mm +Ww +Dd +Hh +MNmn +Ss
		 examples:
		    +4 hours +3mn -2second
		    + 4 hr 3 minutes -2
		    4 hour + 3 min -2 s
		    4 hr 2 s	   (note that minutes are omitted)

	   A field in the expanded format (+Yy) is a sign, a number, and a
	   string specifying the type of field.	 The sign is "+", "-", or
	   absent (defaults to the next larger element).  The valid strings
	   (in English) specifying the field type are:

	      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

	   Other languages have similar abbreviations.

	   Also, the "seconds" string may be omitted.  The sign, number, and
	   string may all be separated from each other by any number 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 business mode, or non-business mode. By default, a
	   delta is treated as a non-business mode delta, but this can be
	   changed in two different ways.

	   The first way to make a delta be business mode is to pass in the
	   2nd argument to the function that is non-zero. If this is done, the
	   delta will be a business delta by default.

	   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 mode 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 serve to force
	   the delta to be non-business mode. For backward compatibility, both
	   are available and serve the same purpose (they no longer determine
	   whether the delta is exact or not... that is determined only by the
	   fields that are included as described above).

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

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

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

	   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
	      normal   [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, normal

	   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.

       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
	      exact	: returns 1 if it is exact

       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.

	   undef is returned if there is no valid delta stored in $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('|A %% B|');
		=> |A % B|

       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/H/Mn/S part. The
	   relationship used is that a year is assigned a length of 365.2425
	   days.

	   For business deltas, the relationship between weeks and days is set
	   to be the length of the business week (as defined using the
	   WorkWeekBeg and WorkWeekEnd config variables). Also, a factor of
	   X/7 * 365.2425 (where X is the number of days in a work week) is
	   used to determine the number of work days in a year.

	   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.16.3			  2014-02-08		 Date::Manip::Delta(3)
[top]

List of man pages available for OpenMandriva

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net