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 Statistics NZ 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 https://www.govt.nz/browse/work/public-holidays-and-work/public-holidays-and-anniversary-dates/, the system of determining holidays in New Zealand is a complicated atter. 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 New Zealand Government web site (which, at the time of revision provides statutory holiday details from 2021 to 2024 regional holidays for 2022 and 2023).
This module hopes to return values that are Mostly Right(tm) when passed in Statistics NZ 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 2 Auckland 3 Waikato 4 Bay of Plenty 5 Gisborne 6 Hawke's Bay 7 Taranaki 8 Manawatū-Wanganui 9 Wellington 12 West Coast 13 Canterbury -13 Canterbury (South) 14 Otago 15 Southland 16 Tasman 17 Nelson 18 Marlborough 99 Outside Regional AuthorityNote: 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 Year's Day Dominion Day Easter Monday Good Friday Labour Day Matariki (from 2022) New Year's Day Queen's Birthday Waitangi Day Auckland Anniversary Day Chatham Islands Anniversary Day Christchurch Show Day Hawke's Bay Anniversary Day Marlborough Anniversary Day Nelson Anniversary Day Otago Anniversary Day Southland Anniversary Day Taranaki Anniversary Day Wellington Anniversary Day Westland Anniversary DaySomebody let me know if any of those are incorrect.
Date::Holidays::NZversion 1.00 and later also support referring to Queen's Birthday as "Birthday of the Reigning Sovereign".
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.
In 1.03 was a fix to correct for the newly Monday-ised Anzac and Waitangi days, which came into force on 1 January 2014, but had no effect until 25 April 2015. Pre-2014 instances of these holidays are unaffected and will continue to match their original dates.
Note that district councils are free to alter the holidays schedule at any time. Also, strictly speaking, it is the Pope who 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:
Waikato (assumed Auckland)
BOP (assumed Auckland)
Gisborne (assumed Auckland)
Tasman (assumed Nelson)
Area 99 - that is, areas outside regional authority. The biggest one of these is the Chatham Islands, so this module assumes Region 99 is the Chatham Islands.
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-NZor by sending mail to
bug-Date-Holidays-NZ@rt.cpan.orgAUTHORS
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.
further modifications
Copyright (c) 2015, Haydn Newport. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.