Sam Vilain > Date-Holidays-NZ-1.02 > Date::Holidays::NZ

Download:
Date-Holidays-NZ-1.02.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  1
View/Report Bugs
Module Version: 1.02   Source  

NAME ^

Date::Holidays::NZ - Determine New Zealand public holidays

SYNOPSIS ^

  use Date::Holidays::NZ;
  my ($year, $month, $day) = (localtime)[ 5, 4, 3 ];
  $year  += 1900;
  $month += 1;
  print "Woohoo" if is_nz_holiday( $year, $month, $day );

  # supply Census 2001 region codes (1-19), or names like
  # "Wellington", "Canterbury (South)", etc
  print "Yes!" if is_nz_holiday( $year, $month, $day, $region );

  my $h = nz_holidays($year);
  printf "Dec. 25th is named '%s'\n", $h->{'1225'};

DESCRIPTION ^

Determines whether a given date is a New Zealand public holiday or not.

As described at http://www.ers.dol.govt.nz/holidays_act_2003/dates/, the system of determining holidays in New Zealand is a complicated matter. Not only do you need to know what region the country is living in to figure out the relevant Anniversary Day, but sometimes the district too (for the West Coast and Canterbury). As regions are free to pick the actual days observed for particular holidays, this module cannot guarantee dates past the last time it was checked against the Employment Relations Service web site (currently returns known good values for statutory holidays 2003 - 2009 and regional holidays for 2005).

This module hopes to return values that are Mostly Right(tm) when passed in census 2001 region codes (widely used throughout government and industry), and can also be passed in textual region labels, which includes the appropriate Anniversary Day.

Also, there is a difference between what is considered a holiday by the Holidays Act 2003 - and hence entitling a person to time in lieu and/or extra pay - and what is considered to be a Bank Holiday. This module returns Bank Holiday dates, so if Christmas Day falls on a Sunday, the 26th will be called "Boxing Day", and the 27th "Christmas Day Holiday".

Functions ^

is_nz_holiday($year, $month, $date, [$region])

Returns the name of the Holiday that falls on the given day, or undef if there is none.

Optionally, a region may be specified, which also checks the anniversary day applicable to that region.

nz_holidays($year, [$region])

Returns a hashref of all defined holidays in the year. Keys in the hashref are in 'mmdd' format, the values are the names of the holidays.

As per the previous function, a region name may be specified. If you do not specify a region, then no regional holidays are included in the returned hash.

nz_regional_day($region)

Returns the name of the regional holiday for the specified region.

This can be passed into the next function to find the actual date for a given year.

Valid regions are:

  Number    Region Name
    1       Northland
    1       Northland
    2       Auckland
    3       Waikato
    4       Bay of Plenty
    5       Gisbourne
    6       Hawkes' Bay
    7       Taranaki
    8       Manuwatu-Wanganui
    9       Wellington
    12      West Coast
    13      Canterbury
   -13      Canterbury (South)
    14      Otago
    15      Southland
    16      Tasman
    17      Nelson
    18      Marlborough
    99      Outside Regional Authority

Note: for the purposes of calculating a holiday, 99 is considered to be Chatham Islands, as there is no Regional Authority there.

Sorry about the -13 for South Canterbury. That's a bit of a hack. Better ideas welcome.

nz_holiday_date($year, $holiday)

Return the actual day that a given holiday falls on for a particular year.

Valid holiday names are:

  ANZAC Day
  Boxing Day
  Christmas Day
  Day after New Years Day
  Dominion Day
  Easter Monday
  Good Friday
  Labour Day
  New Years Day
  Queens Birthday
  Waitangi Day
  
  Auckland Anniversary Day
  Chatham Islands Anniversary Day
  Christchurch Show Day
  Hawkes' Bay Anniversary Day
  Marlborough Anniversary Day
  Nelson Anniversary Day
  Otago Anniversary Day
  Southland Anniversary Day
  Taranaki Anniversary Day
  Wellington Anniversary Day
  Westland Anniversary Day

Somebody let me know if any of those are incorrect.

Date::Holidays::NZ version 1.00 and later also supports referring to Queen's Birthday as "Birthday of the Reigning Sovereign". Not that it has anything to do with the Queen's Birthday, really - it's just another day off to stop us British subjects getting all restless, revolutionary and whatnot.

ERRATA ^

Otago Anniversary Day is due to fall on Easter Monday in 2035 and 2046. When this happened in 2008, the council made Easter Tuesday the anniversary day; however this is not currently codified as a general rule, as it is up to the council to declare this in advance. This was only fixed in Date::Holidays::NZ 1.02, which was released very close to the actual anniversary day - apologies for the delay in the update. For those days (in 2035 and beyond), depending on which method you call you might get a different answer as to why that day is a holiday for that region.

Also in 1.02 was a fix which affected functions which would return the "normal" day for a holiday, rather than the day listed on the official government site, for a couple of regional days which did not match the general rule for when they were due.

Note that district councils are free to alter the holidays schedule at any time. Also, strictly speaking, it is the Pope that decides the date of Easter, upon which Easter Friday and Monday are based.

I'm not entirely sure on which Anniversary Day the following NZ regions observe, so if it matters for you, please check that it is correct and let me know if I need to fix anything:

Maybe someone can shed some light on the situation in the West Coast, although this is confounded by the matter that the whole concept of holidays or even time there is only a loosely observed phenomenon.

EXPORTS ^

Exports the four listed functions in this manual page by default.

You may also import various internal variables and methods used by this module if you like. Log a ticket if you want any of them to be added to the documentation.

BUGS ^

This module does not support Te Reo Māori. If you would be interested in translating the holiday names, region names or manual page to Māori, please contact the author.

Please report issues via CPAN RT:

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Holidays-NZ

or by sending mail to

  bug-Date-Holidays-NZ@rt.cpan.org

AUTHORS ^

Modified for NZ holidays by Sam Vilain <samv@cpan.org>, from Date::Holidays::DK, by Lars Thegler <lars@thegler.dk>

COPYRIGHT ^

portions:

Copyright (c) 2004 Lars Thegler. All rights reserved.

some modifications

Copyright (c) 2005, 2008, Sam Vilain. All rights reserved.

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

syntax highlighting: