Time::DayOfWeek - calculate which Day-of-Week a date is


This documentation refers to version 1.8 of Time::DayOfWeek, which was released on Fri Jul 22 10:16:29:07 -0500 2016.


  use strict;use warnings;use utf8;use v5.10;
  use Time::DayOfWeek qw(:dow);

  my         ($year, $month, $day)  =  (2003, 12, 7);

  say "The Day-of-Week of $year/$month/$day (YMD) is: ",
    DayOfWeek($year, $month, $day);

  say 'The 3-letter abbreviation       of the Dow is: ',
    Dow(      $year, $month, $day);

  say 'The 0-based  index              of the DoW is: ',
    DoW(      $year, $month, $day);


This module just calculates the Day-of-Week for any particular date. It was inspired by the clean Time::DaysInMonth module written by David Muir Sharnoff <Muir@Idiom.Com>.


DoW(<Year>, <Month>, <Day>)

Time::DayOfWeek's core function which does the calculation and returns the weekday index answer between 0 and 6. If no Year is supplied, 2000 C.E. is assumed. If no Month or Day is supplied, they are set to 1. Months are 1-based with values between 1 and 12. Days similarly range from 1 through 31.

DoW() is the only function that is exported from a normal 'use Time::DayOfWeek;' command. Other functions can be imported into the local namespace explicitly or with the following tags:

  :all - every function described here
  :dow - only DoW(), Dow(), and DayOfWeek()
  :nam - only DayNames()  and  MonthNames()
  :day - everything       but  MonthNames()

Dow(<Year>, <Month>, <Day>)

Dow() is the same as DoW() above but returns 3-letter day abbreviations running from 'Sun' through 'Sat'.

DayOfWeek(<Year>, <Month>, <Day>)

DayOfWeek() is the same as DoW() above but returns full day names from 'Sunday' through 'Saturday'.


DayNames() can override default day names with the strings in @NewDayNames. The current list of day names is returned so call DayNames() with no parameters to obtain a list of the default day names.

An example call for Spanish days would be:

  DayNames('Domingo', 'Lunes',  'Martes',  'Miercoles', 'Jueves', 'Viernes', 'Sabado');


MonthNames() has also been included to provide a centralized name set. Just like DayNames(), this function returns the current list of month names so call it with no parameters to obtain a list of the default month names.


Revision history for Perl extension Time::DayOfWeek:

- 1.8 G7MMAGT7 Fri Jul 22 10:16:29:07 -0500 2016

* updated license to GPLv3

* removed PT from VERSION

- 1.6.A6FFxZB Tue Jun 15 15:59:35:11 2010

* had to bump minor version to keep them ascending

- 1.4.A6FCO7V Tue Jun 15 12:24:07:31 2010

* added hack to shift days right one between Feb2008..2009 (still not sure why algorithm skewed)

- 1.4.75R5ulZ Sun May 27 05:56:47:35 2007

* added kwalitee && POD tests, bumped minor version

* condensed code && moved POD to bottom

- 1.2.4CCMRd5 Sun Dec 12 22:27:39:05 2004

* updated License

- 1.0.429BmYk Mon Feb 9 11:48:34:46 2004

* updated DoW param tests to turn zero month or day to one

* updated POD to contain links

- 1.0.41M4ecn Thu Jan 22 04:40:38:49 2004

* made bin/dow as EXE_FILES && added named month param detection

- 1.0.3CNH7Fs Tue Dec 23 17:07:15:54 2003

* removed most eccentric misspellings

- 1.0.3CCA4sO Fri Dec 12 10:04:54:24 2003

* removed indenting from POD NAME field

- 1.0.3CB7PxT Thu Dec 11 07:25:59:29 2003

* added month name data and tidied up for release

- 1.0.3C7IOam Sun Dec 7 18:24:36:48 2003

* wrote pod and made tests

- 1.0.3C7Exdx Sun Dec 7 14:59:39:59 2003

* original version


- figure out why 2008 needed increment hack
- test that UTF-8 characters work in MonthNames and DayNames
- write many more tests for boundary conditions


From the command shell, please run:

  `perl -MCPAN -e "install Time::DayOfWeek"`

or uncompress the package and run the standard:

  `perl Makefile.PL;       make;       make test;       make install`
    or if you don't have  `make` but Module::Build is installed, try:
  `perl    Build.PL; perl Build; perl Build test; perl Build install`


Most source code should be Free! Code I have lawful authority over is and shall be! Copyright: (c) 2003-2016, Pip Stuart. Copyleft : This software is licensed under the GNU General Public License (version 3 or later). Please consult HTTP://GNU.Org/licenses/gpl-3.0.txt for important information about your freedom. This is Free Software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. See HTTP://FSF.Org for further information.


Pip Stuart <Pip@CPAN.Org>