=begin pod

=TITLE role Dateish

=SUBTITLE Object that can be treated as a date

    role Dateish { ... }

Both L<Date|/type/Date> and L<DateTime|/type/DateTime> support accessing a
year, month and day-of-month, as well as related functionality such as
calculating the day of the week.

=head1 Methods

=head2 method year

Defined as:

    method year(Date:D:) returns Int:D

Usage:

    Dateish.year

Returns the year of the date

=head2 method month

Defined as:

    method month(Date:D:) returns Int:D

Usage:

    Dateish.month

Returns the month of the date (1..12)

=head2 method day

Defined as:

    method day(Date:D:) returns Int:D

Usage:

    Dateish.day

Returns the day of the month of the date (1..31)

=head2 method formatter

Defined as:

    method formatter(DateTime:D:)

Usage:

    Dateish.formatter

Returns the formatting function which is used for conversion to
L<Str|/type/Str>. If none was provided at object construction, a
default formatter is used.  In that case the method will return a
Callable type object.

The formatting function is called by L<#method Str> with the invocant as its
only argument.

=head2 method is-leap-year

Defined as:

    method is-leap-year($year = self.year) returns Bool:D

Usage:

    Dateish.is-leap-year(YEAR?)

Returns C<True> if C<$year> is a leap year. Can be called as a class method
if the year is provided.

=head2 method day-of-month

Defined as:

    method day-of-month(Date:D:) returns Int:D

Usage:

    Dateish.day-of-month

Returns the day of the month of the date (1..31). Synonymous to the C<day>
method.

=head2 method day-of-week

Defined as:

    method day-of-week(Date:D:) returns Int:D

Usage:

    Dateish.day-of-week

Returns the day of the week, where 1 is Monday, 2 is Tuesday and Sunday is 7.

=head2 method day-of-year

Defined as:

    method day-of-year(Date:D:) returns Int:D

Usage:

    Dateish.day-of-year

Returns the day of the year (1..366).

=head2 method days-in-month

Defined as:

    method days-in-month(year = self.year, month = self.month) returns Int:D

Usage:

    Dateish.days-in-month(YEAR?, MONTH?)

Returns the number of days in a month, where year and month default to that
of the invocant. If both year and month are provided, it can be called as
a class method.

=head2 method week

Defined as:

    method week()

Usage:

    Dateish.week

Returns a list of two integers: the year, and the week number. This is because
at the start or end of a year, the week may actually belong to the other year.

    my ($year, $week) = Date.new("2014-12-31").week;
    say $year;      # 2015
    say $week;      # 1
    say Date.new('2015-01-31').week;        # 2014 5

=end pod
