NAME

DateTime::Calendar::Pataphysical - Dates in the Pataphysical calendar

VERSION

version 0.07

SYNOPSIS

  use DateTime::Calendar::Pataphysical;

  $dt = DateTime::Calendar::Pataphysical->new( year  => 1752,
                                               month => 10,
                                               day   => 4 );

DESCRIPTION

DateTime::Calendar::Pataphysical is the implementation of the Pataphysical calendar. Each year in this calendar contains 13 months of 29 days. This regularity makes this a convenient alternative for the irregular Gregorian calendar.

This module is designed to be easy to use in combination with DateTime. Most of its methods correspond to a DateTime method of the same name.

CLASS METHODS

new

    my $dt = DateTime::Calendar::Pataphysical-new(
        year  => $year_in_the_pataphysical_era,
        month => $pataphysical_month_number,
        day   => $pataphysical_day_number,
    );

This class method accepts parameters for each date and time component: year, month, day. Additionally, it accepts a locale parameter.

The rd_secs parameter is also accepted. This parameter is only useful in conversions to other calendars; this calendar does not use its value.

from_epoch

    my $dt = DateTime::Calendar::Pataphysical->from_epoch( epoch => $epoch, ... );

This class method can be used to construct a new object from an epoch time instead of components. Just as with the new constructor, it accepts a locale parameter.

now

    my $dt = DateTime::Calendar::Pataphysical->now;

This class method is equivalent to calling from_epoch() with the value returned from Perl's time function.

from_object

    my $dt = DateTime::Calendar::Pataphysical->from_object( object => $object, ... );

This class method can be used to construct a new object from any object that implements the utc_rd_values method. All DateTime::Calendar modules must implement this method in order to provide cross-calendar compatibility. This method accepts a locale parameter.

The time part of $object is stored, and will only be used if the created object is converted to another calendar. Only the date part of $object is used to calculate the pataphysical date. This calculation is based on the local time and date of $object.

last_day_of_month

    my $dt = DateTime::Calendar::Pataphysical->last_day_of_month( ... );

This constructor takes the same arguments as can be given to the now method, except for day. Additionally, both year and month are required.

METHODS

clone

    my $clone = $dt->clone;

This object method returns a replica of the given object.

year

Returns the year.

month

Returns the month of the year, from 1 .. 13.

month_name

Returns the name of the current month.

day_of_month

day

mday

Returns the day of the month, from 1 .. 29.

day_of_week

wday

dow

Returns the day of the week as a number, from 1 .. 7, with 1 being Sunday and 7 being Saturday. Returns undef if the day is a "hunyadi".

day_name

Returns the name of the current day of the week.

day_of_year

doy

Returns the day of the year.

ymd

mdy

dmy

     my $string = $dt->ymd( $optional_separator );

Each method returns the year, month, and day, in the order indicated by the method name. Years are zero-padded to three digits. Months and days are 0-padded to two digits.

By default, the values are separated by a dash (-), but this can be overridden by passing a value to the method.

date

Alias for ymd.

datetime

Equivalent to

    $dt->ymd('-') . 'EP'

is_leap_year

This method returns a true or false indicating whether or not the DateTime object is in a leap year.

week

    my ( $week_year, $week_number ) = $dt->week;

Returns information about the calendar week which contains this DateTime object. The values returned by this method are also available separately through the week_year and week_number methods.

week_year

Returns the year of the week. In the Pataphysical calendar, this is equal to the year of the date, as all weeks fall in one year only.

week_number

Returns the week of the year, from 1 .. 53.

The 29th of each month falls outside of any week; week_number returns undef for these dates.

utc_rd_values

Returns the current UTC Rata Die days and seconds as a two element list. This exists primarily to allow other calendar modules to create objects based on the values provided by this object.

utc_rd_as_seconds

Returns the current UTC Rata Die days and seconds purely as seconds. This is useful when you need a single number to represent a date.

strftime

    my $string = $dt->strftime( $format, ... );

This method implements functionality similar to the strftime() method in C. However, if given multiple format strings, then it will return multiple elements, one for each format string.

See DateTime for a list of all possible format specifiers. This module implements all specifiers related to dates. There is one additional specifier: %* represents the feast of that date.

feast

Returns the feast or vacuation of the given date.

type_of_feast

Returns the type of feast or vacuation.

  '*' means Fête Suprème Première première
  '1' means Fête Suprème Première seconde
  '2' means Fête Suprème Seconde
  '3' means Fête Suprème Tierce
  '4' means Fête Suprème Quarte
  'v' means Vacuation

is_imaginary

Returns true or false indicating whether the DateTime object represents an imaginary date.

set

This method can be used to change the local components of a date time, or its locale. This method accepts any parameter allowed by new.

truncate

    $dt->truncate( to => ... );

This method allows you to reset some of the local time components in the object to their zero values. The to parameter is used to specify which values to truncate, and it may be one of year, month, or day.

add_duration

    $dt->add_duration( $duration_object );

This method adds a DateTime::Duration to the current DateTime. See the DateTime::Duration documentation for more details.

add

    $dt->add( %arguments );

This method is syntactic sugar around the add_duration method. It simply creates a new DateTime::Duration object using the parameters given, and then calls the add_duration method.

subtract_duration

    $dt->subtract_duration( $duration_object );

When given a DateTime::Duration object, this method simply calls invert on that object and passes that new duration to the add_duration method.

subtract

    $dt->subtract( %arguments );

Like add, this is syntactic sugar for the subtract_duration method.

subtract_datetime

    $dt->subtract_datetime( $datetime );

This method returns a new DateTime::Duration object representing the difference between the two dates.

compare

    $cmp = DateTime->compare( $dt1, $dt2 );

    @dates = sort { DateTime->compare( $a, $b ) } @dates;

Compare two DateTime objects. The semantics are compatible with Perl's sort function; it returns -1 if $a < $b, 0 if $a == $b, and 1 if $a > $b.

Of course, since DateTime objects overload comparison operators, you can just do this anyway:

    @dates = sort @dates;

BUGS

  • Adding a week to a date is exactly equivalent to adding seven days in this module because of the way DateTime::Duration is implemented. The Hunyadis are not taken into account.

  • from_epoch and now probably only work on Unix.

SUPPORT

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

SEE ALSO

DateTime

datetime@perl.org mailing list

AUTHOR

Eugene van der Pijll <pijll@gmx.net>

Maintained by Philippe Bruhat (BooK) since 2014.

COPYRIGHT

Copyright (c) 2003, 2004 Eugene van der Pijll. All rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.