Date::Manip::Base man page on Mandriva

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

Date::Manip::Base(3)  User Contributed Perl Documentation Date::Manip::Base(3)

NAME
       Date::Manip::Base - Base methods for date manipulation

SYNOPSIS
	  use Date::Manip::Base;
	  $dmb = new Date::Manip::Base;

DESCRIPTION
       The Date::Manip package of modules consists of several modules for
       doing high level date operations with full error checking and a lot of
       flexibility.

       The high level operations, though intended to be used in most
       situations, have a lot of overhead associated with them. As such, a
       number of the most useful low level routines (which the high level
       routines use to do much of the real work) are included in this module
       and are available directly to users.

       These low level routines are powerful enough that they can be used
       independent of the high level routines and perform useful (though much
       simpler) operations. They are also significantly faster than the high
       level routines.

       These routines do NO error checking on input. Invalid data will result
       in meaningless results.	If you need error checking, you must call the
       higher level Date::Manip routines instead of these.

       These routines also ignore all effects of time zones and daylight
       savings time. One way to think of these routines is working with times
       and dates in the GMT time zone.

BASE METHODS
       This class inherits several base methods from the Date::Manip::Obj
       class. Please refer to the documentation for that class for a
       description of those methods.

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

       config
	      $dmb->config($var1,$val1,$var2,$val2,...);

	   This will set the value of any configuration variable. Please refer
	   to the Date::Manip::Config manual for a list of all configuration
	   variables and their description.

DATE METHODS
       In all of the following methods, the following variables are used:

       $date
	   This is a list reference containing a full date and time:

	      [$y, $m, $d, $h, $mn, $s]

       $ymd
	   A list reference containing only the date portion:

	      [$y, $m, $d]

       $hms
	   A list reference containing only the time portion:

	      [$h, $mn, $s]

       $time
	   A list reference containing an amount of time:

	      [$dh, $dmn, $ds]

       $delta
	   A list containing a full delta:

	      [$dy, $dm, $dw, $dd, $dh, $dmn, $ds]

       $offset
	   A list containing a time zone expressed as an offset:

	      [ $offh, $offm, $offs ]

       In all of the above, the elements ($y, $m, $d, $h, $mn, $s) are all
       numeric. In most of the routines described below, no error checking is
       done on the input.  $y should be between 1 and 9999, $m between 1 and
       12, $d between 1 and 31, $h should be between 0 and 23, $mn and $s
       between 0 and 59.

       $hms can be between 00:00:00 and 24:00:00, but an $offset must be
       between -23:59:59 and +23:59:59.

       Years are not translated to 4 digit years, so passing in a year of "04"
       will be equivalent to "0004", NOT "2004".

       The elements ($dy, $dm, $dw, $dd, $dh, $dmn, $ds) are all numeric, but
       can be positive or negative. They represent an elapsed amount of time
       measured in years, months, weeks, etc.

       Since no error checking is done, passing in ($y,$m,$d) = (2004,2,31)
       will NOT trigger an error, even though February does not have 31 days.
       Instead, some meaningless result will be returned.

       calc_date_date
       calc_date_days
       calc_date_delta
       calc_date_time
       calc_time_time
	   These are all routines for doing simple date and time calculations.
	   As mentioned above, they ignore all affects of time zones and
	   daylight savings time.

	   The following methods are available:

	      $time = $dmb->calc_date_date($date1,$date2);

	   This take two dates and determine the amount of time between them.

	      $date = $dmb->calc_date_days($date,$n [,$subtract]);
	      $ymd  = $dmb->calc_date_days($ymd,$n [,$subtract]);

	   This returns a date $n days later (if $n>0) or earlier (if $n<0)
	   than the date passed in. If $subtract is passed in, the sign of $n
	   is reversed.

	      $date = $dmb->calc_date_delta($date,$delta [,$subtract]);

	   This take a date and add the given delta to it (or subtract the
	   delta if $subtract is non-zero).

	      $date = $dmb->calc_date_time($date,$time [,$subtract]);

	   This take a date and add the given time to it (or subtract the time
	   if $subtract is non-zero).

	      $time = $dmb->calc_time_time(@time1,@time2 [,$subtract]);

	   This take two times and add them together (or subtract the second
	   from the first if $subtract is non-zero).

       check
       check_time
	      $valid = $dmb->check($date);
	      $valid = $dmb->check_time($hms);

	   This tests a list of values to see if they form a valid date or
	   time ignoring all time zone affects. The date/time would be valid
	   in GMT, but perhaps not in all time zones.

	   1 is returned if the the fields are valid, 0 otherwise.

	   $hms is in the range 00:00:00 to 24:00:00.

       cmp
	      $flag = $dmb->cmp($date1,$date2);

	   Returns -1, 0, or 1 if date1 is before, the same as, or after
	   date2.

       day_of_week
	      $day = $dmb->day_of_week($date);
	      $day = $dmb->day_of_week($ymd);

	   Returns the day of the week (1 for Monday, 7 for Sunday).

       day_of_year
	      $day = $dmb->day_of_year($ymd);
	      $day = $dmb->day_of_year($date);

	   In the first case, returns the day of the year (1 to 366) for $y,
	   $m, $d.  In the second case, it returns a fractional day (1.0 <=
	   $day < 366.0 or 1.0 <= $day < 367.0 for a leap-year).  For example,
	   day 1.5 falls on Jan 1, at noon.  The somewhat non-intuitive answer
	   (1.5 instead of 0.5) is to make the two forms return numerically
	   equivalent answers for times of 00:00:00 . You can look at the
	   integer part of the number as being the day of the year, and the
	   fractional part of the number as the fraction of the day that has
	   passed at the given time.

	   The inverse operations can also be done:

	      $ymd   = $dmb->day_of_year($y,$day);
	      $date  = $dmb->day_of_year($y,$day);

	   If $day is an integer, the year, month, and day is returned. If
	   $day is a floating point number, it returns the year, month, day,
	   hour, minutes, and decimal seconds.

	   $day must be greater than or equal to 1 and less than 366 on non-
	   leap years or 367 on leap years.

       days_in_month
	      $days = $dmb->days_in_month($y,$m);

	   Returns the number of days in the month.

	      @days = $dmb->days_in_month($y,0);

	   Returns a list of 12 elements with the days in each month of the
	   year.

       days_in_year
	      $days = $dmb->days_in_year($y);

	   Returns the number of days in the year (365 or 366)

       days_since_1BC
	      $days = $dmb->days_since_1BC($date);
	      $days = $dmb->days_since_1BC($ymd);

	   Returns the number of days since Dec 31, 1BC. Since the calendar
	   has changed a number of times, the number returned is based on the
	   current calendar projected backwards in time, and in no way
	   reflects a true number of days since then. As such, the result is
	   largely meaningless, except when called twice as a means of
	   determining the number of days separating two dates.

	   The inverse operation is also available:

	      $ymd = $dmb->days_since_1BC($days);

	   Returns the date $days since Dec 31, 1BC. So day 1 is Jan 1, 0001.

       leapyear
	      $flag = $dmb->leapyear($y);

	   Returns 1 if the argument is a leap year.  Originally copied from
	   code written by David Muir Sharnoff <muir@idiom.com>.

       nth_day_of_week
	      $ymd = $dmb->nth_day_of_week($y,$n,$dow);

	   Returns the $n'th occurrence of $dow (1 for Monday, 7 for Sunday)
	   in the year.	 $n must be between 1 and 53 or -1 through -53.

	      $ymd = $dmb->nth_day_of_week($y,$n,$dow,$m);

	   Returns the $n'th occurrence of $dow in the given month.  $n must
	   be between 1 and 5 or it can be -1 through -5.

	   In all cases, nothing is returned if $n is beyond the last actual
	   result (i.e. the 5th Sunday in a month with only four Sundays).

       secs_since_1970
	      $secs = $dmb->secs_since_1970($date);

	   Returns the number of seconds since Jan 1, 1970 00:00:00 (negative
	   if date is earlier).

	      $date = $dmb->secs_since_1970($secs);

	   Translates number of seconds into a date.

       split
       join
	   The split and join functions are used to take a string containing a
	   common type of time data and split it into a list of fields. The
	   join function takes the list and forms it into a string.

	   Rudimentary error checking is performed with both of these
	   functions and undef is returned in the case of any error. No error
	   checking is done on the specific values.

	   The following are allowed:

	      $date = $dmb->split("date",$string);
	      $string = $dmb->join("date",$date);

	   This splits a string containing a date or creates one from a list
	   reference.  The string split must be of one of the forms:

	      YYYYMMDDHH:MN:SS
	      YYYYMMDDHHMNSS
	      YYYY-MM-DD-HH:MN:SS

	   The string formed by join is one of the above, depending on the
	   value of the Printable config variable. The default format is
	   YYYYMMDDHH:MN:SS, but if Printable is set to 1, YYYYMMDDHHMNSS is
	   produced, and if Printable is set to 2, the YYYY-MM-DD-HH:MN:SS
	   form is produced.

	      $hms = $dmb->split("hms",$string);
	      $string = $dmb->join("hms",$hms);

	   This works with the hours, minutes, and seconds portion of a date.

	   When splitting a string, the string can be of any of the forms:

	      H
	      H:MN
	      H:MN:SS
	      HH
	      HHMN
	      HHMNSS

	   Here, H is a 1 or 2 digit representation of the hours. All other
	   fields are two digit representations.

	   The string formed by the join function will always be of the form
	   HH:MN:SS.

	   The time must be between 00:00:00 and 24:00:00.

	      $offset = $dmb->split("offset",$string);
	      $string = $dmb->join("offset",$offset);

	   An offset string should have a sign (though it is optional if it is
	   positive) and is any of the forms:

	      +H
	      +H:MN
	      +H:MN:SS
	      +HH
	      +HHMN
	      +HHMNSS

	   Here, H is a 1 or 2 digit representation of the hours. All other
	   fields are two digit representations.

	   The string formed by the join function will always be of the form
	   +HH:MN:SS.

	      $time = $dmb->split("time",$string);
	      $string = $dmb->join("time",$time);

	   This works with an amount of time in hours, minutes, and seconds.
	   The string is of the format:

	      +H:MN:S

	   where all signs are optional. The returned value (whether a list
	   reference from the split function, or a string from the join
	   function) will have all fields normalized (see Date::Manip::Delta
	   for an explanation).

	      $delta = $dmb->split("delta",$string);
	      $delta = $dmb->split("business",$string);

	      $string = $dmb->join("delta",$delta);
	      $string = $dmb->join("business",$delta);

	   Both of these split a string containing a delta, or create a string
	   containing one. The difference is whether the delta is treated as a
	   business or non-business delta (see Date::Manip::Delta
	   documentation for a detailed description).

	   The string that can be split is of the form:

	     +Y:M:+W:+D:H:MN:S

	   All signs are optional in the string being split. The string
	   produced is of the form +Y:M:+W:D:H:MN:S (for a non-business delta)
	   or +Y:M:+W:+D:H:MN:S (for a business delta).

	   Fields may be omitted entirely. For example:

	     D:H:MN:S
	     D:::S

	   are both valid.

	   The string or list output is normalized.

       week1_day1
	      $ymd = $dmb->week1_day1($y);

	   This returns the date of the 1st day of the 1st week in the given
	   year.  Note that this uses the ISO 8601 definition of week, so the
	   year returned may be the year before the one passed in.

	   This uses the FirstDay and Jan1Week1 config variables to evaluate
	   the results.

       weeks_in_year
	      $w = $dmb->weeks_in_year($y);

	   This returns the number of ISO 8601 weeks in the year. It will
	   always be 52 or 53.

       week_of_year
	      ($y,$w) = $dmb->week_of_year($date);
	      ($y,$w) = $dmb->week_of_year($ymd);

	   This returns the week number (1-53) of the given date and the year
	   that it falls in. Since the ISO 8601 definition of a week is used,
	   the year returned is not necessarily the one passed in (it may
	   differ for the first or last week of the year).

	   The inverse operation is also available:

	      $ymd = $dmb->week_of_year($y,$w);

	   which returns the first day of the given week.

	   This uses the FirstDay and Jan1Week1 config variables to evaluate
	   the results.

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.10.1			  2010-01-12		  Date::Manip::Base(3)
[top]

List of man pages available for Mandriva

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