view release on metacpan or  search on metacpan

README.mkdn  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

README.mkdn  view on Meta::CPAN

use Class::Date qw(:errors);
```

Possible error values are:

- E\_OK

    No errors.

- 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.

- 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.

- E\_UNPARSABLE

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

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

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

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

# 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
```

# 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.

# 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.

# 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()