--~~ JS-Time ~~--

  A framework agnostic Javascript utility class, performing 
  time calculations. Piggybacks on <code>Date</code>, adding
  a bunch of utility functions.

  The test suite runs successfully on IE6-IE8, Safari 3 and 4,
  Firefox 3 and Opera 9. Probably more, send me a message if
  you ran the tests successfully in an unlisted browser.
  
--~~ Installing/using ~~--

  1. Download the JS, http://github.com/augustl/js-time/raw/master/time.js
  2. Include it on your page

--~~ Features ~~--

  -~ Creating new time instances ~-

  Use regular Javascript constructors to create new
  <code>Time</code> instances.

new Time();
new Time(208, 5, 17);
new Time().epoch(1244405763000) // Remember: JS uses milliseconds, not seconds

  -~ Getting and setting time attributes ~-

  Creating instances.

var time = new Time();
time.hour();
time.hour(17);

  You can get and set the following attributes.

year
month
hour
minute
second
millisecond
epoch     // (UNIX time in milliseconds)
weekday   // (1-7)


var time = new Time(2008, 5, 17);
time.year()   // 2008
time.moth()   // 5
time.month(3)
time.month()   // 3


   -~ Setting the first day of the week ~-

  When using `weekday`, `firstDayInCalendarMonth` and similar,
  the library uses `Time.firstDayOfWeek` in these calculations.
  This is 1 (Sunday) by default. Set it to any value between 1
  and 7.

Time.firstDayOfWeek = 2; // defaults to 1

  -~ Time-stepping ~-

  JS-Time provides the following time-stepping functions.
  
beginningOfYear    endOfYear
beginningOfMonth  endOfMonth
beginningOfDay    endOfDay
beginningOfHour    endOfHour
beginningOfMinute  endOfMinute
beginningOfWeek    endOfWeek

previousMonth    nextMonth

advanceMonths
advanceDays

new Time(2008, 5, 17).beginningOfYear();              // January 1st 2008, 00:00
new Time(2008, 5, 17, 23, 52).beginningOfDay();       // May 5th 2008, 00:00
new Time(2008, 5, 17, 16, 30).endOfHour()             // May 5th 2008, 16:59
new Time(2008, 5, 17).endOfYear()                     // December 31th 2008, 23:59
new Time(2008, 1).previousMonth();                    // December 1th 2007, 00:00
new Time(2007, 1, 31).advanceMonths(1)                // February 28th 2007
new Time(2008, 1, 31).advanceMonths(1)                // February 29th 2008
new Time(2008, 1, 3).advanceMonths(-13)               // December 3rd 2006
new Time(2008, 5, 17, 16, 30).advanceDays(1)          // May 18th 2008, 16:30

  Keep in mind that all of these functions mutates the receiver,
  they do not create new `Time` instances. If you wantto create
  new instances, use `clone` (documentation below).

--~~ Utility ~~--

  -~ clone ~-

  Clones and returns a copy of the `Time` instance.

<code>var time = new Time(2006);
var timeClone = time.clone().setYear(1999)
time.year()                                         // 2006
timeClone.year()                                    // 1999

  -~ daysInMonth ~-

  Returns, as you might expect, the number of days in the month
  of that `Time`> instance.

new Time(2008, 1).daysInMonth();                    // 31
new Time(2007, 2).daysInMonth();                    // 28
new Time(2007, 4).daysInMonth();                    // 30

  -~ isLeapYear ~-

  Returns true or false, depending on wether or not the year in
  question is a leap year.

new Time(1804).isLeapYear(); // true

  -~ firstDayInCalendarMonth ~-

  Useful when rendering month calendar grids. Uses
  `Time.firstDayOfWeek`.

new Time(2008, 1).firstDayInCalendarMonth()         // December 30th 2007
new Time(2008, 4).firstDayInCalendarMonth()         // March 30th 2008


  -~ weeksInMonth ~-

  Also useful for calendars. Uses `Time.firstDayOfWeek`.

new Time(2008, 2).weeksInMonth()                    // 5
new Time(2008, 3).weeksInMonth()                    // 6