view release on metacpan or  search on metacpan

lib/Class/Date.pm  view on Meta::CPAN

  $date = Class::Date->new( [$year,$month,$day,$hour,$min,$sec],'GMT');
  $date = gmdate "2001-11-12 17:13";
  ...

  # creating absolute date object in any other timezone
  $date = Class::Date->new( [$year,$month,$day,$hour,$min,$sec],'Iceland' );
  $date = date "2001-11-12 17:13", 'Iceland';
  $date2 = $date->new([$y2, $m2, $d2, $h2, $m2, $s2]); 
    # ^- timezone is inherited from the $date object

  # creating relative date object
  # (normally you don't need to create this object explicitly)
  $reldate = Class::Date::Rel->new( "3Y 1M 3D 6h 2m 4s" );
  $reldate = Class::Date::Rel->new( "6Y" );
  $reldate = Class::Date::Rel->new( $secs );  # secs
  $reldate = Class::Date::Rel->new( [$year,$month,$day,$hour,$min,$sec] );
  $reldate = Class::Date::Rel->new( { year => $year, month => $month, day => $day,
    hour => $hour, min => $min, sec => $sec } );
  $reldate = Class::Date::Rel->new( "2001-11-12 07:13:12" );
  $reldate = Class::Date::Rel->new( "2001-12-11" );

  # getting values of an absolute date object
  $date;              # prints the date in default output format (see below)
  $date->year;        # year, e.g: 2001
  $date->_year;       # year - 1900, e.g. 101
  $date->yr;          # 2-digit year 0-99, e.g 1
  $date->mon;         # month 1..12
  $date->month;       # same as prev.
  $date->_mon;        # month 0..11
  $date->_month;      # same as prev.
  $date->day;         # day of month
  $date->mday;        # day of month
  $date->day_of_month;# same as prev.
  $date->hour;
  $date->min;
  $date->minute;      # same as prev.
  $date->sec;
  $date->second;      # same as prev.
  $date->wday;        # 1 = Sunday
  $date->_wday;       # 0 = Sunday
  $date->day_of_week; # same as prev.
  $date->yday;        
  $date->day_of_year; # same as prev.
  $date->isdst;       # DST?
  $date->daylight_savings; # same as prev.
  $date->epoch;       # UNIX time_t
  $date->monname;     # name of month, eg: March
  $date->monthname;   # same as prev.
  $date->wdayname;    # Thursday
  $date->day_of_weekname # same as prev.
  $date->hms          # 01:23:45
  $date->ymd          # 2000/02/29
  $date->mdy          # 02/29/2000
  $date->dmy          # 29/02/2000
  $date->meridiam     # 01:23 AM
  $date->ampm         # AM/PM
  $date->string       # 2000-02-29 12:21:11 (format can be changed, look below)
  "$date"             # same as prev.
  $date->tzoffset     # timezone-offset
  $date->strftime($format) # POSIX strftime (without the huge POSIX.pm)
  $date->tz           # returns the base timezone as you specify, eg: CET
  $date->tzdst        # returns the real timezone with dst information, eg: CEST

  ($year,$month,$day,$hour,$min,$sec)=$date->array;
  ($year,$month,$day,$hour,$min,$sec)=@{ $date->aref };
  # !! $year: 1900-, $month: 1-12

  ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=$date->struct;
  ($sec,$min,$hour,$day,$mon,$year,$wday,$yday,$isdst)=@{ $date->sref };
  # !! $year: 0-, $month: 0-11

  $hash=$date->href; # $href can be reused as a constructor
  print $hash->{year}."-".$hash->{month}. ... $hash->{sec} ... ;
  
  %hash=$date->hash;
  # !! $hash{year}: 1900-, $hash{month}: 1-12

  $date->month_begin  # First day of the month (date object)
  $date->month_end    # Last day of the month
  $date->days_in_month # 28..31

  # constructing new date based on an existing one:
  $new_date = $date->clone;
  $new_date = $date->clone( year => 1977, sec => 14 );
  # valid keys: year, _year, month, mon, _month, _mon, day, mday, day_of_month,
  #             hour, min, minute, sec, second, tz
  # constructing a new date, which is the same as the original, but in 
  # another timezone:
  $new_date = $date->to_tz('Iceland');

  # changing date format
  {
    local $Class::Date::DATE_FORMAT="%Y%m%d%H%M%S";
    print $date       # result: 20011222000000
    $Class::Date::DATE_FORMAT=undef;
    print $date       # result: Thu Oct 13 04:54:34 1994
    $Class::Date::DATE_FORMAT="%Y/%m/%d"
    print $date       # result: 1994/10/13
  }

  # error handling
  $a = date($date_string);
  if ($a) { # valid date
    ...
  } else { # invalid date
    if ($a->error == E_INVALID) { ... }
    print $a->errstr;
  }

  # adjusting DST in calculations  (see the doc)
  $Class::Date::DST_ADJUST = 1; # this is the default
  $Class::Date::DST_ADJUST = 0;

  # "month-border adjust" flag 
  $Class::Date::MONTH_BORDER_ADJUST = 0; # this is the default
  print date("2001-01-31")+'1M'; # will print 2001-03-03
  $Class::Date::MONTH_BORDER_ADJUST = 1;
  print date("2001-01-31")+'1M'; # will print 2001-02-28

  # date range check
  $Class::Date::RANGE_CHECK = 0; # this is the default

lib/Class/Date.pm  view on Meta::CPAN

the ":errors" tag:

  use Class::Date qw(:errors);

Possible error values are:

=over 4

=item E_OK

No errors.

=item E_INVALID

Invalid date. It is set when some of the parts of the date are invalid, and
Time::Local functions cannot convert them to a valid date.

=item E_RANGE

This error is set, when parts of the date are valid, but the whole date is
not valid, e.g. 2001-02-31. When the $Class::Date::RANGE_CHECK is not set, then
these date values are automatically converted to a valid date: 2001-03-03,
but the $date->error value are set to E_RANGE. If $Class::Date::RANGE_CHECK
is set, then a date "2001-02-31" became invalid date.

=item E_UNPARSABLE

This error is set, when the constructor cannot be created from a scalar, e.g:

  $a = date("4kd sdlsdf lwekrmk");

=item E_UNDEFINED

This error is set, when you want to create a date object from an undefined
value:

  $a = Class::Date->new(undef);

Note, that localdate(undef) will create a valid object, because it calls
$Class::Date(time).

=back

You can get the error in string form by calling the "errstr" method.

=head1 DST_ADJUST

$DST_ADJUST is an important configuration option.

If it is set to true (default), then the module adjusts the date and time
when the operation switches the border of DST. With this setting, you are
ignoring the effect of DST.

When $DST_ADJUST is set to false, then no adjustment is done, the
calculation will be based on the exact time difference.

You will see the difference through an example:

  $Class::Date::DST_ADJUST=1;

  print date("2000-10-29", "CET") + "1D";
  # This will print 2000-10-30 00:00:00

  print date("2001-03-24 23:00:00", "CET") + "1D";
  # This will be 2001-03-25 23:00:00

  print date("2001-03-25", "CET") + "1D";
  # This will be 2001-03-26 00:00:00


  $Class::Date::DST_ADJUST=0;

  print date("2000-10-29", "CET") + "1D";
  # This will print 2000-10-29 23:00:00

  print date("2001-03-24 23:00:00", "CET") + "1D";
  # This will be 2001-03-26 00:00:00

=head1 MONTHS AND YEARS

If you add or subtract "months" and "years" to a date, you may get wrong 
dates, e.g when you add one month to 2001-01-31, you expect to get
2001-02-31, but this date is invalid and converted to 2001-03-03. Thats' why

  date("2001-01-31") + '1M' - '1M' != "2001-01-31"

This problem can occur only with months and years, because others can 
easily be converted to seconds.

=head1 MONTH_BORDER_ADJUST

$MONTH_BORDER_ADJUST variable is used to switch on or off the 
month-adjust feature. This is used only when someone adds months or years to
a date and then the resulted date became invalid. An example: adding one
month to "2001-01-31" will result "2001-02-31", and this is an invalid date.

When $MONTH_BORDER_ADJUST is false, this result simply normalized, and
becomes "2001-03-03". This is the default behaviour.

When $MONTH_BORDER_ADJUST is true, this result becomes "2001-02-28". So when
the date overflows, then it returns the last day insted.

Both settings keep the time information.

=head1 TIMEZONE SUPPORT

Since 1.0.11, Class::Date handle timezones natively on most platforms (see
the BUGS AND LIMITATIONS section for more info).

When the module is loaded, then it determines the local base timezone by
calling the Class::Date::local_timezone() function, and stores these values
into two variables, these are: $Class::Date::LOCAL_TIMEZONE and
$Class::Date::DEFAULT_TIMEZONE. The first value is used, when you call the
"localdate" function, the second value is used, when you call the "date"
function and you don't specify the timezone. There is
a $Class::Date::GMT_TIMEZONE function also, which is used by the "gmdate"
function, this is set to 'GMT'.

You can query the timezone of a date object by calling the $date->tz
method. Note this value returns the timezone as you specify, so if you
create the object with an unknown timezone, you will get this back. If you
want to query the effective timezone, you can call the $date->tzdst method.
This method returns only valid timezones, but it is not necessarily the
timezone which can be used to create a new object. For example
$date->tzdst can return 'CEST', which is not a valid base timezone, because
it contains daylight savings information also. On Linux systems, you can
see the possible base timezones in the /usr/share/zoneinfo directory.

In Class::Date 1.1.6, a new environment variable is introduced:
$Class::Date::NOTZ_TIMEZONE. This variable stores the local timezone, which
is used, when the TZ environment variable is not set. It is introduced,
because there are some systems, which cannot handle the queried timezone
well. For example the local timezone is CST, it is returned by the tzname()
perl function, but when I set the TZ environment variable to CST, it
works like it would be GMT.  The workaround is NOTZ_TIMEZONE: if a date
object has a timezone, which is the same as NOTZ_TIMEZONE, then the TZ