Jakarta Commons Cookbook

1.15. Truncating Date Objects

Problem

You need to truncate a date to a calendar field.

Solution

Use DateUtils.truncate() to throw out all fields less significant than the specified field. When a Date is truncated to the Calendar.MONTH field, DateUtils.truncate( ) will return a Date object set to the first instance of the month. The day, hour, minute, second, and millisecond field will each contain the minimum possible value for that field. Example 1-9 truncates a date at the month field and the hour field.

Example 1-9. Truncating a Date object at Calendar.MONTH

import org.apache.commons.lang.time.DateUtils;
import org.apache.commons.lang.time.FastDateFormat;
import org.apache.commons.lang.time.DateFormatUtils;

FastDateFormat dtFormat = DateFormatUtils.ISO_DATETIME_FORMAT;

Date now = new Date( );
Date truncatedMonth = DateUtils.truncate( now, Calendar.MONTH );
Date truncatedHour = DateUtils.truncate( now, Calendar.HOUR ); 

System.out.println( "Now: " + dtFormat.format( now ) );
System.out.println( "Truncated Month: " 
                 + dtFormat.format( truncatedMonth ) );
System.out.println( "Truncated Hour: " 
                    + dtFormat.format( truncatedHour ) );

Assuming that the current date is March 28, 2004, and the current time is 1:48 P.M., this example produces the following output:

Now: 2004-03-28T13:48:12
Truncated Month: 2004-03-01T00:00:00
Truncated Hour: 2004-03-28T13:00:00

Discussion

If you want to associate every event that happened between 2 P.M. and 3 P.M. with the 2 P.M. hour, or every event that happened in a particular year with the first instant of that year, you need to truncate a Date at a specified Calendar field. When a Date is truncated, it is rounded down; DateUtils.truncate() is the equivalent of Math.floor( ) for the Date class. If it is 4:02 P.M. on October 31, 1975, a Date object truncated at the Calendar.HOUR field will point to 4:00 P.M., and a Date truncated at the Calendar.YEAR field will point to the first millisecond of the first minute, of the first hour, of the first day of year 2005: January 01 2005: 12:00:00.000 A.M.

See Also

DateUtils.truncate( ) can also be used to truncate a date to the nearest DateUtils.SEMI_MONTH. Recipe 1.14 discusses DateUtils.SEMI_MONTH in more detail.