Reduce or Increase a date to a given start or end of a TimeUnit granularity.

This allows you to modify a date to reset to minimum or maximum values all values below a given TimeUnit granularity.

This operates in local time zone so if you are not in UTC time zone and you output date in UTC time zone the date fields will not be to the start or end of the TimeUnit.

Example TimeUnit.startOfTime Hour date will return a modified date with

• Minutes to 0
• Seconds to 0
• Milliseconds to 0

Example TimeUnit.endOfTime Hour date will return a modified date with

• Minutes to 59
• Seconds to 59
• Milliseconds to 999

Warning about using endOfTime for date ranges

In the past when I have encountered people using a function like endOfTime (max date at a given granularity) it was being used in ways that could introduce problems.

Here is why:

• You want to do a date range comparison between the minimum date (or current date) and this maximum date. In all the cases I can remember they were doing a date range comparison using Greater Than Or Equal To minimum date and Less Than or Equal To maximum date.
  • I can't state strongly enough that this is not the way to do date ranges it leads to missed matches that fall between the generated maximum date and the following date at the same granularity in systems were you are working at a granularity larger than the underlying stored granularity. Even if you are working at the smallest granularity of the system its a not a good way to think about ranges.
  • When comparing date ranges I strongly suggest you always use a half closed interval. This means always build date ranges using Greater Than or Equal To minimum date and Less Than maximum date. (This applies to floating point numbers as well).
    • Its equivalently safe to go Greater Than minimum and Less Than or Equal to maximum, in my experience business understanding nearly always dictated include minimum excluded maximum.
  • Once you do this there is no possible gap and it becomes easier to think about.