DateUtils

Date Reference

The rules behind date calculations, explained once and in full: how the calendar is built, how days and months are counted, and how timestamps and time zones work.

Whether the first day counts, what one month after 31 January is, and which week 1 January belongs to all have more than one accepted answer. These pages explain the rules and their alternatives with worked examples, and link to the calculators that apply them.

How the calendar works

  • The Gregorian calendar The calendar most of the world uses for civil dates: where it came from, how it differs from the Julian calendar, and how dates before 1582 are handled.
  • Leap years The three-part Gregorian leap-year rule, why century years are different, a list of leap years, and what 29 February does to date arithmetic.
  • Days in each month A table of month lengths, the day of the year each month starts on, quarter lengths, and how to remember which months have 30 or 31 days.
  • ISO week numbers How ISO 8601 numbers weeks, why a year can have 53 weeks, why 1 January can belong to the previous year, and how ISO weeks differ from other week numbering.

Counting and date arithmetic

  • Counting days between dates Why two people can count the same date range and get different answers: inclusive and exclusive counting, calendar days versus elapsed time, and month-based spans.
  • Adding months and years What "one month after 31 January" means, why adding months in steps can give a different answer, and how spreadsheets and programming languages disagree.
  • Business days What counts as a business day, how weekends and holidays are excluded, the counting conventions behind deadlines, and how spreadsheet functions compare.

Timestamps and time zones

  • Unix time What a Unix timestamp counts, how to tell seconds from milliseconds, negative timestamps, the year 2038 problem and why leap seconds are ignored.
  • Time zones and daylight saving UTC offsets, IANA zone names, why abbreviations are ambiguous, how daylight saving creates skipped and repeated times, and why the gap between two cities changes.

How DateUtils calculates

  • Methodology The exact rules each DateUtils calculator follows, including counting conventions, month-end handling and time zone edge cases.