Everyday / Orbit Tools field notes

Calendar Dates and Timestamps Answer Different Questions

Use date-only examples to check inclusivity and leap days, then switch to explicit offsets when the task is about a moment.

A spiral-bound desk calendar opened to a monthly view
Photo by Blessing Ri on Unsplash · Unsplash License

Three inputs that reveal the counting convention

In Date Difference, enter 2024-02-28 and 2024-03-01. Elapsed days returns 2 days because 2024 contains February 29. Include both dates returns 3 days because it counts the two endpoint labels and the intervening leap day. Next use the same date for both fields: elapsed is zero and inclusive is one. These examples establish the convention more clearly than testing a random six-month span whose answer you cannot easily check.

The local date tools validate real calendar dates and perform date-only arithmetic using UTC values internally. They do not ask for a timezone because the task is a calendar-label calculation. An end date before the start is rejected by Date Difference. Date Add instead accepts positive or negative whole days: 2024-02-28 plus one day yields 2024-02-29. That operation counts calendar days, not business days, local holidays, billing rules or calendar months.

A timestamp is not a date with extra decoration

Timestamp Converter provides separate modes for Unix seconds and milliseconds. Enter 0 in either numeric mode and expect 1970-01-01T00:00:00.000Z. The same nonzero digits mean very different moments if interpreted in seconds instead of milliseconds, so choose the mode from the source system's contract. Do not infer the unit only from the apparent length when the value is near the epoch or comes from a nonstandard system.

For the reverse conversion, include Z or an explicit offset. The two inputs 2026-10-22T08:00:00+08:00 and 2026-10-22T00:00:00Z identify the same moment and should produce the same seconds value. A local-looking time without an offset is rejected. That prevents the converter from silently guessing the operator's timezone, but it does not resolve ambiguous civil-time rules for a location you have not specified.

Choose the operation before writing a deadline

Do not multiply a Date Difference result by 24 and describe it as measured local-clock hours across a daylight-saving transition. The date tool did not receive the clock times or timezone rules needed for that claim. Conversely, a precise UTC instant is unnecessary baggage for a simple list of included calendar dates. Put the chosen convention next to the result, and seek the governing rule separately when a deadline depends on an institution rather than arithmetic alone.

Ask what kind of interval you need

A question such as how many days are between two dates may mean a count of calendar boundaries or a duration between two exact moments. These are related but different tasks. If a trip begins on Monday and ends on Thursday, the elapsed difference between the date labels is three days, while a count that includes Monday, Tuesday, Wednesday, and Thursday contains four calendar dates. State whether the first and last dates are included.

For a date-only task, use calendar dates and a clearly stated convention. For example, a hotel stay from June 10 through June 13 may count nights, while a work schedule may count both the first and last working dates. A project duration may count elapsed days between milestones. The arithmetic can be simple once the definition is clear, but a calculator cannot choose that definition on your behalf.

Distinguish dates from moments

A calendar date such as 2026-10-13 is a label in a calendar. A timestamp describes a particular moment and is commonly represented with a time and an offset or a UTC marker. A date-only event such as a birthday does not necessarily need a timezone. A meeting at 9 a.m. does, because 9 a.m. can refer to different moments in different places.

Time zones and daylight-saving changes matter when measuring elapsed time across moments. A local clock can move forward or backward during a transition, so a local day does not always contain the same number of elapsed hours. If the question asks for a precise duration in seconds or hours, use timestamps with an agreed timezone. If it asks which calendar dates are included, use dates and avoid introducing a time that could shift them.

Avoid ambiguous date strings in code

Software may interpret similar looking date strings differently. MDN documents that JavaScript Date parses date-only forms without an offset as UTC, while date-time forms without an offset are interpreted as local time. That difference can move the displayed calendar date for someone in another timezone. Do not assume that a string with year, month, and day will always be handled as a local date by every library.

Choose a clear representation and document it. For a global event, include the UTC offset or convert to a timestamp with a known timezone. For a recurring birthday or due date, store a calendar date rather than an arbitrary midnight timestamp when that better matches the meaning. Test the value in the user's timezone and near midnight, because those are the cases where hidden assumptions become visible.

Check boundaries and leap days

When counting a range, decide whether the end is exclusive or inclusive and use that rule consistently. Many programming ranges use an inclusive start and an exclusive end, while everyday descriptions often include both named dates. A small mismatch can shift a billing period, report range, or reservation by one date. Put the convention in a label such as through June 13 or ending before June 13.

Calendar calculations should also account for different month lengths and leap days. Avoid estimating a month as a fixed number of days when the task requires calendar months. A duration tool can count between the dates you provide, but check whether it includes the start date, the end date, or both. Use an independent example around the end of a month or year to confirm the convention.

← Browse all field notes Explore the tool index ↗