view release on metacpan or  search on metacpan

lib/DateTime/Fiscal/Retail454.pm  view on Meta::CPAN

    my %params = @_;

    if ($params{to} eq 'r454year') {
        my $tmp = $self->r454_start(as_obj => 1);
        %{$self} = %{$tmp};
    } elsif ($params{to} eq 'period') {
        my $tmp = $self->r454_period_start(as_obj => 1);
        %{$self} = %{$tmp};
    } else {
        $self->SUPER::truncate(%params);
    }

    return ($self);
}

1;

__END__

=head1 NAME

DateTime::Fiscal::Retail454 - create 4-5-4 Calendar data from DateTime objects.

=head1 DEPRECATED

This module has been deprecated! Please use L<DateTimeX::Fiscal::Fiscal5253>
instead. The new module has enhanced support for NRF 4-5-4 calenders as well
as for 52/53 week fiscal years in general.

=head1 SYNOPSIS

 use DateTime::Fiscal::Retail454;
 
 my $r454 = DateTime::Fiscal::Retail454->new( year => 2006 );
 
 my $fiscalyear = $r454->r454_year; # Might NOT be what you expect!
 
 if ( $r454->is_r454_leap_year ) {
   # do something here
 }

 my $startdate = $r454->r454_start;		# start of fiscal year
 my $enddate = $r454->r454_end;			# end of fiscal year

 my @fiscalperiod_data = $r454->r454_period;	# returns all period data
 my $fp_number = $r454->r454_period;		# returns period number

 my $fp_weeks = $r454->r454_period_weeks;	# number of weeks in period
 my $fp_start = $r454->r454_period_start;	# period start date
 my $fp_end = $r454->r454_period_end;		# period end date
 my $fp_end = $r454->r454_period_publish;	# period publish date
 
See the details below for each method for options.

=head1 DESCRIPTION

This module is a sub-class of C<DateTime> and inherits all methods and
capabilities, including constructors, of that module.

The purpose of this module is to make it easy to work with the 4-5-4
calendar that is common among merchandisers.  Details of the calendar itself
can be found at the National Retail Federation (NRF) website.
L<http://www.nrf.com/modules.php?name=Pages&sp_id=391>

All objects returned by any of the methods in this module or of the class
C<DateTime::Fiscal::Retail454> unless otherwise specified.

=head1 EXPORTS

None.

=head1 DEPENDENCIES

 Carp
 DateTime

=head1 CONSTRUCTORS

All of the constructors from the parent C<DateTime> class can be used to
obtain a new object.

In addition,  an additional constructor named C<from_r454year> has been added.

=head2 from_r454year

 my $r454 = DateTime::Fiscal::Retail454->from_r454year( r454year => 2000 );

Returns an object of type C<DateTime::Fiscal::Retail454> with a value of the
first day in the specified RETAIL year.
The C<r454year> parameter is B<mandatory> and an exception will result if it
is missing.

The returned object  will have a date in the range
'YYYY-01-29' - 'YYYY-02-04' depending on what day of the week Jan 31 of the
specified year YYYY falls on.

The algorythm for selecting the starting date can be stated as follows:

Obtain the day of the week for Jan 31 of the specified year as a number in
the range 1 - 7 where Monday = 1, Tuesday = 2, etc.

If the day of the week is < 3, then subtract that number of days from Jan 31
to obtain the date of the preceding Sunday as the starting date.

If the day of the week is < 7, then first substract that number from 7, and
then add the resulting number of days to Jan 31 to obtain the date of the
following Sunday as the starting date.

If the day of the week is 7 (or Sunday) then no further changes are needed and
the starting date is in fact YYYY-01-31 for that year.

=head1 METHODS

=head2 r454_year

 my $r454 = DateTime::Fiscal::Retail454->new( year => 2006, month = 4 );
 print $r454->r454_year;	# print "2006"
 
 my $r454_2 = DateTime::Fiscal::Retail454->new( year => 2006, month = 1 );
 print $r454->r454_year;	# print "2005"

Returns a scalar containing the Fiscal Year that the object is in.  This is
not always the same as the calendar year, especially for dates in January and
occasionally in February.  This is because the start of the Fiscal Year is
tied to what day of the week Jan 31 of any given year falls on.

=head2 is_r454_leap_year

 my $r454 = DateTime::Fiscal::Retail454->new( r454year => 2006 );
 print "This is a Fiscal Leap Year" if $r454->is_r454_leap_year;

Returns a Boolean value indicating whether or not the Fiscal Year for the
object has 53 weeks instead of the standard 52 weeks.

=head2 r454_start

  my $startdate = $r454->r454_start;
  my $startobj = $r454->r454_start( as_obj => 1 );

Returns the starting date for the object's Fiscal Year as either a string or
an object as specified by the C<as_obj> parameter (default is string).

=head2 r454_end

  my $enddate = $r454->r454_end;
  my $endobj = $r454->r454_end( as_obj => 1 );

Returns the ending date for the object's Fiscal Year as either a string or
an object as specified by the C<as_obj> parameter (default is string).

=head2 r454_period

This is the workhorse method and can be called in several ways.

 # Return the current R454 period number
 my $fp_number = $r454->r454_period;
 
 # Return a list containing all data for the current period.
 # The array is
 # ( fp_number, fp_weeks, fp_start, fp_end, fp_publish, fp_year ).
 my @fp_data = $r454->r454_period;
 
 # As above but with objects for fp_start and fp_end instead of strings
 my @fp_data = $r454->r454_period( as_obj => 1 );
 
 # Specify the period for which data is returned.
 my @fp_data = $r454->r454_period( period => 5 );
 my @fp_data = $r454->r454_period( period => 5, as_obj => 1 );

As can be seen above, the calling context affects the return values.
When called in scalar context it defaults to returning a scalar containing
the current period number for the calling object.
When called in list context it returns a list containing all avaiable data
for a period. The list is structured as follows:

 ( fp_number, fp_weeks, fp_start, fp_end, fp_publish, fp_year )

If the C<as_obj> parameter is specified the values for C<fp_start> and
C<fp_end> will objects of class C<DateTime::Fiscal::Retail454>.

A specific period may be requested by using the C<period> parameter.
Using this parameter with no others will result in that period number being
returned, probably not what you wanted.