This file was automatically generated from http://svn.pugscode.org/pugs/misc/Date/lib/Date/Gregorian.pod on Thu Jul 12 12:23:25 2007 GMT, revision 16992.
Date::Gregorian - dates on the Gregorian Calendar
# note: -DateParse uses Date::Parse and requires Perl 5 embedding.
use Date::Gregorian qw(date localdate gmdate now -DateParse);
# creating non-timezones date object ('floating' time)
$date = Date::Gregorian.new($year,$month,$day,$hour,$min,$sec);
$date = date [$year,$month,$day,$hour,$min,$sec];
$date = date ( :year($year), :month($month), :day($day),
:hour($hour), :min($min), :sec($sec) );
$date = date "2001-11-12 07:13:12"; # or any ISO-8601 format
$date = date 1e9; # Unix epoch time if an Int
$date = date 0.0; # Perl 6 date if a Float
# add a month to it:
$date += "1M";
$date += "P1M"; # ISO-8601 Periods supported
$date += [0,1,0,0,0,0]; # constructor formats supported
$date += 31*24*60*60; # seconds
# intuitive arithmetic between dates via Duration::Gregorian
$days_between = ( date('2001-11-12')
- date('2001-07-04') ).days; # prints 131
# creating date object in local timezone
$date = localdate "2001-12-11"; # force local time
$date = now; # the same as date(time)
# creating absolute date object (UTC)
$date = Date::Gregorian.new([$yyyy,$mm,$dd,$HH,$MM,$SS], 'UTC');
$date = gmdate "2001-11-12 17:13";
# creating absolute date object in any other timezone
$date = date [$year,$month,$day,$hour,$min,$sec], 'Iceland';
$date = date "2001-11-12 17:13", 'Iceland';
# getting parts out - comprehensive methods available
my $year = $date.year; # full
my $year_C = $date._year; # year - 1900 (or 1904 on Mac?)
my $month = $date.mon; # 1..12
my $month_C = $date._mon; # 0..11
($year,$month,$day,$hour,$min,$sec)=$date.array;
print date([2001,12,11,4,5,6]).truncate;
# will print "2001-12-11"
# modifying date properties
$date.set( :year<1977>, :sec<14> );
$date.year = 1978;
$date.sec = 15;
# constructing new date based on an existing one:
$new_date = $date.clone;
$new_date.clone( :year<1977>, :sec<14> );
# constructing a new date, which is the same absolute time as
# the original, but expressed in another timezone:
$new_date = $date.as_tz('Iceland');
# comparison between absolute dates
say $date1 > $date2 ?? "I am older" !! "I am younger";
# comparison between relative dates
say $reldate1 > $reldate2 ?? "I am faster" !! "I am slower";
# Adding / Subtracting months and years are sometimes
# tricky; in general be sure whether you mean "one month"
# or "30 days", etc:
say date("2001-01-29") + '1M' - '1M'; # gives "2001-02-01"
say date("2000-02-29") + '1Y' - '1Y'; # gives "2000-03-01"
Date::Gregorian represents dates on the Gregorian calendar as Perl 6 objects.
You can use the +, -, < and > operators as with
native perl data types.
Date::Gregorian operations fall into these categories:
You can create a date object by the (exported by default) "date",
"localdate" or "gmdate" functions, or by calling the
Date::Gregorian.new() constructor.
date() and Date::Gregorian.new() are equivalent, both have two
arguments (each of which may be composed of multiple parts): The date
and (optionally) the timezone.
$date1 = date [2000,11,12]; $date2 = Date::Gregorian->new([2000,06,11,13,11,22],'GMT'); $date2 = $date1->new([2000,06,11,13,11,22]);
You can also supply the date information in any of the following forms:
$date = date("2003-12-31 12:56:59");
$date = date("2003-12-31 12:56:59 +12:00");
$date = date([$year,$month,$day,$hour,$min,$sec]);
$date = date( :year(2003), :month(12), :day(31),
:hour(12), :min(56), :sec(59),
:tz<Pacific/Auckland> );
See /Valid Date Formats for more information on the allowable formats of the date.
Dates may be cloned using the constructor, or the clone()
method:
$date2 = $date.new(); $date2 = $date.clone(); $date2 = $date.clone( :year($newyear), :sec($newsec) );
When constructing a new date from scratch, if the timezone information
is omitted, then the date is "floating" (unless you set
$Date::Gregorian::DEFAULT_TIMEZONE).
If the date is being extracted from the system clock, then it always has a time zone set.
You can override this behaviour to always assume the local time zone,
by setting $Date::Gregorian::DEFAULT_TIMEZONE to
$Date::Gregorian::LOCAL_TIMEZONE.
localdate $x is equivalent to date $x,
$Date::Gregorian::LOCAL_TIMEZONE, and gmdate $x is equivalent to
date $x, 'UTC'
$date1 = localdate [2000,11,12]; $date2 = gmdate [2000,4,2,3,33,33]; $date = localdate(time);
The time offset can also be specified in ISO-8601 notation; however the time zone of the resulting date is fixed to that offset, and not to any country's 'dynamic' time zone:
$date = date("2001-01-17 10:10:00 +12:00");
print $date->tz; # prints "+12:00";
Such dates may freely be converted to a local time zone using the
.clone(:tz($timezone)) copy constructor, or the
.tz($new_timezone)) mutator (or any of its equivalent variants):
$date = date("2001-01-17 10:10:00 +12:00")
->to_tz("Pacific/Auckland");
Note that if you want to merely change the timezone without adjusting
the time, you must first convert the date to floating, by setting the
timezone to the undefined value or "Floating".
Dates that have a timezone attached are converted according to the interpretation of the TimeZone you passed; 'floating' dates simply have the timezone attached.
All ISO-8601 formats are supported for the scalar use; for example:
Dates:
YY -MM --DD YY-MM YYYY YYDDD YY-DDD YYYYMM YYYY-MM YYYYDDD YYYYMMDD YY-MM-DD YYYY-MM-DD YYYYWNN YYYYWNND
(note: the W is a literal W or w, and is for specifying the week
of the year).
These formats must be strings. Int inputs will be interpreted as Unix epoch seconds, and Float inputs as Perl epoch seconds.
Times (must be preceded/seperated from the date with a literal T or
t where ambiguous with the above forms, or follow a complete date
with a space):
HH HH.HHH... HH,HHH... HH:MM HHMM HH:MM.MMM... HH:MM,MMM... HH:MM:SS HHMMSS HH:MM:SS.SSS... HH:MM:SS,SSS...
Valid integers are interpreted as a unix epoch times. Some systems may not handle epoch times outside of the signed 32 bit range.
Note that this is ambiguous with compact ISO-8601 date forms above
when the type of the scalar is a junction of Str and Int
compatible types. To force the intended behaviour in this case, it is
recommended that you explicitly force integer convertion by prepending
0+ to the time (or using int()).
These are the recommended methods for unix date input:
$date = date(0+$myEpochTime); $date = date(int($myEpochTime)); $date = date(:epoch($myEpochTime)); $date = epoch($myEpochTime);
This form of construction implies a local timezone by default.
$date = date(time());
Perl dates are returned as floating point seconds since 1999. 0.0 means midnight on the First of January, 2005, UTC.
This form of construction implies a local timezone by default.
An array reference with 7 or fewer elements. Individual elements may be undefined, in which case they simply remain unspecified and do not default to any particular time, like midnight or the 1st of January 1900 or anything like that.
However, such implication of default values may happen when performing arithmetic with absent units; in which case the lower unit always defaults to the lowest value, while upper units remain unspecified.
You can specify -DateParse as an import parameter, e.g:
use Date::Gregorian qw(date -DateParse);
With this, the module will try to load Date::Parse Perl 5 module, and if it find it then all these formats can be used as an input. See Date::Parse for more.