This group of methods allow you to add a specified period to a date or time. You can also subtract periods just by making the value to be added negative.
There are a number of methods that I have added to the date object to make these additions and subtractions easy. Firstly there are those that only add or subtract one part of the date or time. The purpose of these methods is obvious from their names and each takes one parameter which is a number representing the period in the units that the method names indicate.
There is also one method that allows you to update all six of these at the same time using one call and passing the six values.
This group of methods will make many of the date comparisons that you are likely to need a much easier prospect. In each case since we are comparing dates the parameters that these methods expect are themselves date objects. These first two compare dates anre return the number of days between them. The difference between the two is that the business day version doesn't count Saturdays and Sundays. Note that the result will be a positive number of days regardless of which of the two dates comes first.
This next method is the one to use for determining someone's age on any date. Simply pass in their date of birth as the date object parameter and the function returns their age in whole years without the imprecision that some people end up with in their calculations. This method will increase their age by one only on their birthday.
Another useful comparison is to be able to test if one date/time is between two other date/times and so this method takes two date objects as parameters and returns true if the value of this date object is between them and false if it isn't.
The following characters have the specified meanings when included in the format_string.
- d Day of the month, 2 digits with leading zeros 1-31
- D A textual representation of a day, three letters Mon through Sun
- j Day of the month without leading zeros 1 to 31
- l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
- N ISO-8601 numeric representation of the day of the week 1 (for Monday) through 7 (for Sunday)
- S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
- w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
- z The day of the year (starting from 0) 0 through 365
- W ISO-8601 week number of year, weeks starting on Monday Example: 42 (the 42nd week in the year)
- F A full textual representation of a month, such as January or March January through December
- m Numeric representation of a month, with leading zeros 01 through 12
- M A short textual representation of a month, three letters Jan through Dec
- n Numeric representation of a month, without leading zeros 1 through 12
- t Number of days in the given month 28 through 31
- L Whether it's a leap year 1 if it is a leap year, 0 otherwise.
- o ISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
- Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003
- y A two digit representation of a year Examples: 99 or 03
- a Lowercase Ante meridiem and Post meridiem am or pm
- A Uppercase Ante meridiem and Post meridiem AM or PM
- B Swatch Internet time 000 through 999
- g 12-hour format of an hour without leading zeros 1 through 12
- G 24-hour format of an hour without leading zeros 0 through 23
- h 12-hour format of an hour with leading zeros 01 through 12
- H 24-hour format of an hour with leading zeros 00 through 23
- i Minutes with leading zeros 00 to 59
- s Seconds, with leading zeros 00 through 59
- I (capital i) Whether or not the date is in daylight saving time 1 if Daylight Saving Time, 0 otherwise.
- O Difference to Greenwich time (GMT) in hours Example: +0200
- P Difference to Greenwich time (GMT) with colon between hours and minutes Example: +02:00
- Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 through 50400
- c ISO 8601 date Example: 2004-02-12T15:19:21+00:00
- r RFC 2822 formatted date Example: Thu, 21 Dec 2000 16:01:07 +0200
- U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)
- X week number where weeks run Sunday to Saturday and 1st Jan is always in week 1
- x as X bit with a leading zero where the week number is less than 10
- R day of year with 1st Jan = 001 (always 3 digits including leading zeroes).
- J Julian Day number
- K returns 'DST for daylight saving time, otherwise returns 'Std'
- ^ escapes the meaning of the following character so that it will display in the string returned instead of being interpreted as above
The following methods can also be called separately when you do not need the full power of the format method.
This article written by Stephen Chapman, Felgall Pty Ltd.