[Date] docs

Author: moritz

lib/Date.pod

@@ -0,0 +1,107 @@
+=begin pod
+
+=TITLE class Date
+
+    class Date { }
+
+A C<Date> is an immutable object identifying a day in the Gregorian calendar.
+
+Date objects support addition and subtraction of integers, where an
+integer is interpreted as the number of days. C<Date.today> creates
+an object the current day according to the system clock.
+
+=head1 Methods
+
+=head2 new
+
+    proto method new() {*}
+    multi method new($year,   $month,  $day) returns Date:D
+    multi method new(:$year, :$month, :$day) returns Date:D
+    multi method new(Str $date)              returns Date:D
+    multi method new(DateTime:D $dt)         returns Date:D
+
+Creates a new C<Date> object, either from a tripple of (year, month, day)
+integers, or from a string of the form C<YYYY-MM-DD>
+(L<ISO 8601|http://en.wikipedia.org/wiki/ISO_8601>), or from a DateTime
+object.
+
+=head2 today
+
+    method today() returns Date:D
+
+Returns a C<Date> object for the current day.
+
+    my $d = Date.new(2012, 12, 24); # Christmas Eve!
+    say $d;                         # 2012-12-24
+    say $d.year;                    # 2012
+    say $d.month;                   # 12
+    say $d.day;                     # 24
+    say $d.day-of-week;             # 1  (that's Monday)
+    my $n = Date.new('2012-12-31'); # New Year's Eve
+    say $n - $d;                    # 7
+    say $n + 1;                     # 2013-01-01
+
+=head2 year
+
+    method year(Date:D:) returns Int:D
+
+Returns the year of the date
+
+=head2 month
+
+    method month(Date:D:) returns Int:D
+
+Returns the month of the date (1..12)
+
+=head2 day
+
+    method day(Date:D:) returns Int:D
+
+Returns the day of the month of the date (1..31)
+
+=head2 day-of-week
+
+    method day-of-week(Date:D:) returns Int:D
+
+Returns the day of the week, where 0 is Sunday, 1 is Monday etc.
+
+=head2 day-of-year
+
+    method day-of-year(Date:D:) returns Int:D
+
+Returns the day of the year.
+
+=head2 day-of-month
+
+    method day-of-month(Date:D:) returns Int:D
+
+Returns the day of the month of the date (1..31). Synonymous to the C<day>
+method.
+
+=head2 succ
+
+    method succ(Date:D:) return Date:D
+
+Returns the following day
+
+=head2 prev
+
+    method prev(Date:D:) return Date:D
+
+Returns the previous day
+
+=head2 Str
+
+    multi method Str(Date:D:) returns Str:D
+
+Returns the date in C<YYYY-MM-DD> format (L<ISO 8601|http://en.wikipedia.org/wiki/ISO_8601>)
+
+=head2 gist
+
+    multi method gist(Date:D:) returns Str:D
+
+Returns the date in C<YYYY-MM-DD> format (L<ISO 8601|http://en.wikipedia.org/wiki/ISO_8601>)
+
+=head2 
+
+=end pod