DateUtils

How DateUtils Calculates

Most date questions have more than one defensible answer. This page records the rule each DateUtils calculator follows, so you can check whether a result answers the question you are asking. The rules are written from the calculation code and are covered by automated tests. For background on the concepts themselves, see the date reference.

Calendar and supported dates

  • Dates are Gregorian calendar dates from 1 January of year 1 to 31 December 9999. The Gregorian rules are applied to years before 1582 as well (the proleptic Gregorian calendar), so historical dates recorded in the Julian calendar will not match.
  • Calendar dates have no time of day and no time zone. Arithmetic on them is exact integer arithmetic on day numbers and does not depend on your device's time zone or daylight saving rules. The exceptions are the Countdown, Unix Timestamp, Time Zone Converter and World Clock, which work with real instants.
  • A year is a leap year if it is divisible by 4, except century years, which are leap years only if divisible by 400. "Previous" and "next" leap year mean strictly before and strictly after the year entered.
  • Results that would fall outside years 1 to 9999 are reported as out of range rather than calculated.

Date difference

  • The day count is the end date minus the start date. The start date is not counted as an extra day, so 1 January to 2 January is 1 day.
  • With Include end date, one day is added and both dates are counted: 1 January to 2 January becomes 2 days. See counting days between dates for when each convention applies.
  • If the end date is before the start date, the count is shown as a positive number with a note on the direction.
  • The months-and-days figure counts whole months forward from the earlier date. If that date's day does not exist in a month, the last day of the month is used, so 31 January to 28 February 2025 is exactly 1 month. Remaining days are counted from that point.
  • Hours and minutes are the day count multiplied by 24 and by 1,440. Calendar dates carry no time or zone, so daylight saving changes are not reflected.

Adding and subtracting

  • Days and weeks are added exactly; a week is always 7 days.
  • Months and years keep the same day of the month. When that day does not exist in the target month, the result is the last day of that month: 31 January plus 1 month is 28 February (29 in a leap year), 29 February 2024 plus 1 year is 28 February 2025, and 31 March minus 1 month is the last day of February. The result never spills into the following month.
  • Because of that rule, month arithmetic is not always reversible, and adding months in two steps can differ from adding them in one. Adding months and years explains why and compares other conventions.

Age

  • Age is the months-and-days calendar difference from the date of birth to the chosen date, so a person is a year older on their birthday and not before.
  • A 29 February birthday is treated as falling on 28 February in common years. Some jurisdictions use 1 March instead for legal purposes.
  • The next birthday is the first one on or after the chosen date. On the birthday itself, the days until the next birthday is 0.
  • The date of birth is kept in the page's memory only. It is not put in the address bar, stored or sent anywhere.

Business days

  • Working days are Monday to Friday by default and can be changed to any set of weekdays.
  • Holidays are only the dates you enter. DateUtils has no built-in public holiday calendars. A holiday reduces the count only if it falls on a working day.
  • When counting between two dates, the start date counts if it is a working day and the end date does not. Include end date counts the end date too. If the end is before the start, the dates are swapped and a note is shown.
  • Working days, weekend days and holidays on working days always add up to the number of calendar days in the range.
  • When adding business days, the start date is never counted: adding 1 business day to a Friday gives the following Monday when that Monday is a working day. Adding 0 returns the start date.

See business days and working days for how these conventions compare with spreadsheet functions.

Countdown

  • The countdown measures real elapsed time from now to the target moment, in your device's time zone. A "day" in the result is 24 elapsed hours, so a countdown across a daylight saving change differs by an hour from the clock-face difference.
  • If no time is entered, the target is midnight at the start of the target date.
  • The presets (New Year, Valentine's Day, Halloween, Christmas, New Year's Eve) are fixed-date occasions and use the next occurrence on or after today. Movable holidays such as Easter are not included.

ISO week numbers

  • Week numbers follow ISO 8601: weeks start on Monday, week 1 is the week containing the year's first Thursday, and a week belongs to the year in which its Thursday falls. A date in late December can be in week 1 of the next year, and a date in early January can be in week 52 or 53 of the previous year.
  • In the calendar view with weeks starting on Sunday or Saturday, each row is labelled with the ISO week of that row's Thursday.

More detail and examples: ISO week numbers.

Weekdays, day numbers, quarters and periods

  • The day of the year counts 1 January as day 1. Day 366 exists only in leap years; days remaining in the year is the year's length minus the day number.
  • Quarters are calendar quarters: Q1 is January to March, Q2 April to June, Q3 July to September and Q4 October to December. Days remaining in a quarter is the quarter's last day minus the date, so it is 0 on the last day.
  • Start and end of a period are both inclusive dates. A week runs for seven days from the chosen first day of the week (Monday by default, or Sunday or Saturday); months, quarters and years run from their first to their last day.

Date formats

  • Numeric formats are always labelled explicitly (DD/MM/YYYY, MM/DD/YYYY, YYYY-MM-DD) and are never guessed from your device's locale, because 03/04/2025 means 3 April in most of the world and 4 March in the United States.
  • The ISO 8601 date-and-time and the Unix timestamp shown for a date are for midnight UTC at the start of that date.

Unix timestamps

  • A Unix timestamp is the number of seconds, or milliseconds, since 00:00:00 UTC on 1 January 1970. Negative values are dates before 1970.
  • Leap seconds are not counted: every day is treated as 86,400 seconds, as in Unix time itself.
  • The supported range is that of JavaScript's date type, about 275,000 years either side of 1970, so the 2038 limit of 32-bit second counters does not apply.
  • A seconds value of 100,000,000,000 or more is almost certainly milliseconds, and the converter suggests switching unit. It never changes the unit on its own.

Time zones

  • Time zones are IANA zone names (such as Europe/London or America/New_York), and conversions use your browser's copy of the IANA time zone database, so daylight saving changes come from each zone's real rules rather than fixed offsets.
  • A local time that does not exist, because clocks moved forward, is read with the offset in force before the change: 02:30 on the spring-forward date in New York is treated as 03:30 EDT. The result says when this has happened.
  • A local time that occurs twice, because clocks moved back, uses the first occurrence, and the second is reported.
  • The UTC offset is always shown. Abbreviations such as EST are shown only where the browser provides an unambiguous one, because many abbreviations are shared by more than one zone. See time zones and daylight saving.

Time units

  • The time converter uses fixed units: 1 minute is 60 seconds, 1 hour 3,600 seconds, 1 day 86,400 seconds and 1 week 604,800 seconds. Months and years are not offered because their length varies.
  • Results are rounded to 12 significant digits to remove floating-point noise.

What the calculators do not do

  • They do not know public holidays, local business customs or legal rules for deadlines. Where a contract, court or regulator defines how days are counted, that definition applies.
  • They do not convert between the Gregorian calendar and other calendars, such as the Julian, Hebrew, Islamic or Chinese calendars.

If a result looks wrong, please report it. Calculation errors are fixed as bugs and get a regression test.