Coverage Report

Coverage Report - org.apache.commons.lang3.time.DateFormatUtils

Classes in this File

Line Coverage

Branch Coverage

Complexity

DateFormatUtils

96%

29/30

N/A

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  * 
  *      http://www.apache.org/licenses/LICENSE-2.0
  * 
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.lang3.time;
 
 import java.util.Calendar;
 import java.util.Date;
 import java.util.Locale;
 import java.util.TimeZone;
 
 /**
  * <p>Date and time formatting utilities and constants.</p>
  *
  * <p>Formatting is performed using the thread-safe
  * {@link org.apache.commons.lang3.time.FastDateFormat} class.</p>
  *
  * <p>Note that the JDK has a bug wherein calling Calendar.get(int) will 
  * override any previously called Calendar.clear() calls. See LANG-755.</p>
  *
  * @since 2.0
  * @version $Id: DateFormatUtils.java 1436770 2013-01-22 07:09:45Z ggregory $
  */
 public class DateFormatUtils {
 
     /**
      * The UTC time zone (often referred to as GMT).
      * This is private as it is mutable.
      */
     private static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
     /**
      * ISO8601 formatter for date-time without time zone.
      * The format used is <tt>yyyy-MM-dd'T'HH:mm:ss</tt>.
      */
     public static final FastDateFormat ISO_DATETIME_FORMAT
             = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
 
     /**
      * ISO8601 formatter for date-time with time zone.
      * The format used is <tt>yyyy-MM-dd'T'HH:mm:ssZZ</tt>.
      */
     public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
             = FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
 
     /**
      * ISO8601 formatter for date without time zone.
      * The format used is <tt>yyyy-MM-dd</tt>.
      */
     public static final FastDateFormat ISO_DATE_FORMAT
             = FastDateFormat.getInstance("yyyy-MM-dd");
 
     /**
      * ISO8601-like formatter for date with time zone.
      * The format used is <tt>yyyy-MM-ddZZ</tt>.
      * This pattern does not comply with the formal ISO8601 specification
      * as the standard does not allow a time zone  without a time.
      */
     public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
             = FastDateFormat.getInstance("yyyy-MM-ddZZ");
 
     /**
      * ISO8601 formatter for time without time zone.
      * The format used is <tt>'T'HH:mm:ss</tt>.
      */
     public static final FastDateFormat ISO_TIME_FORMAT
             = FastDateFormat.getInstance("'T'HH:mm:ss");
 
     /**
      * ISO8601 formatter for time with time zone.
      * The format used is <tt>'T'HH:mm:ssZZ</tt>.
      */
     public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
             = FastDateFormat.getInstance("'T'HH:mm:ssZZ");
 
     /**
      * ISO8601-like formatter for time without time zone.
      * The format used is <tt>HH:mm:ss</tt>.
      * This pattern does not comply with the formal ISO8601 specification
      * as the standard requires the 'T' prefix for times.
      */
     public static final FastDateFormat ISO_TIME_NO_T_FORMAT
             = FastDateFormat.getInstance("HH:mm:ss");
 
     /**
      * ISO8601-like formatter for time with time zone.
      * The format used is <tt>HH:mm:ssZZ</tt>.
      * This pattern does not comply with the formal ISO8601 specification
      * as the standard requires the 'T' prefix for times.
      */
     public static final FastDateFormat ISO_TIME_NO_T_TIME_ZONE_FORMAT
             = FastDateFormat.getInstance("HH:mm:ssZZ");
 
     /**
      * SMTP (and probably other) date headers.
      * The format used is <tt>EEE, dd MMM yyyy HH:mm:ss Z</tt> in US locale.
      */
     public static final FastDateFormat SMTP_DATETIME_FORMAT
             = FastDateFormat.getInstance("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
 
     //-----------------------------------------------------------------------
     /**
      * <p>DateFormatUtils instances should NOT be constructed in standard programming.</p>
      *
      * <p>This constructor is public to permit tools that require a JavaBean instance
      * to operate.</p>
      */
     public DateFormatUtils() {
         super();
     }
 
     /**
      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
      * 
      * @param millis  the date to format expressed in milliseconds
      * @param pattern  the pattern to use to format the date, not null
      * @return the formatted date
      */
     public static String formatUTC(final long millis, final String pattern) {
         return format(new Date(millis), pattern, UTC_TIME_ZONE, null);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
      * 
      * @param date  the date to format, not null
      * @param pattern  the pattern to use to format the date, not null
      * @return the formatted date
      */
     public static String formatUTC(final Date date, final String pattern) {
         return format(date, pattern, UTC_TIME_ZONE, null);
     }
     
     /**
      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
      * 
      * @param millis  the date to format expressed in milliseconds
      * @param pattern  the pattern to use to format the date, not null
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String formatUTC(final long millis, final String pattern, final Locale locale) {
         return format(new Date(millis), pattern, UTC_TIME_ZONE, locale);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
      * 
      * @param date  the date to format, not null
      * @param pattern  the pattern to use to format the date, not null
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String formatUTC(final Date date, final String pattern, final Locale locale) {
         return format(date, pattern, UTC_TIME_ZONE, locale);
     }
     
     /**
      * <p>Formats a date/time into a specific pattern.</p>
      * 
      * @param millis  the date to format expressed in milliseconds
      * @param pattern  the pattern to use to format the date, not null
      * @return the formatted date
      */
     public static String format(final long millis, final String pattern) {
         return format(new Date(millis), pattern, null, null);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern.</p>
      * 
      * @param date  the date to format, not null
      * @param pattern  the pattern to use to format the date, not null
      * @return the formatted date
      */
     public static String format(final Date date, final String pattern) {
         return format(date, pattern, null, null);
     }
 
     /**
      * <p>Formats a calendar into a specific pattern.</p>
      * 
      * @param calendar  the calendar to format, not null
      * @param pattern  the pattern to use to format the calendar, not null
      * @return the formatted calendar
      * @see FastDateFormat#format(Calendar)
      * @since 2.4
      */
     public static String format(final Calendar calendar, final String pattern) {
         return format(calendar, pattern, null, null);
     }
     
     /**
      * <p>Formats a date/time into a specific pattern in a time zone.</p>
      * 
      * @param millis  the time expressed in milliseconds
      * @param pattern  the pattern to use to format the date, not null
      * @param timeZone  the time zone  to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String format(final long millis, final String pattern, final TimeZone timeZone) {
         return format(new Date(millis), pattern, timeZone, null);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern in a time zone.</p>
      * 
      * @param date  the date to format, not null
      * @param pattern  the pattern to use to format the date, not null
      * @param timeZone  the time zone  to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String format(final Date date, final String pattern, final TimeZone timeZone) {
         return format(date, pattern, timeZone, null);
     }
 
     /**
      * <p>Formats a calendar into a specific pattern in a time zone.</p>
      * 
      * @param calendar  the calendar to format, not null
      * @param pattern  the pattern to use to format the calendar, not null
      * @param timeZone  the time zone  to use, may be <code>null</code>
      * @return the formatted calendar
      * @see FastDateFormat#format(Calendar)
      * @since 2.4
      */
     public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone) {
         return format(calendar, pattern, timeZone, null);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern in a locale.</p>
      * 
      * @param millis  the date to format expressed in milliseconds
      * @param pattern  the pattern to use to format the date, not null
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String format(final long millis, final String pattern, final Locale locale) {
         return format(new Date(millis), pattern, null, locale);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern in a locale.</p>
      * 
      * @param date  the date to format, not null
      * @param pattern  the pattern to use to format the date, not null
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String format(final Date date, final String pattern, final Locale locale) {
         return format(date, pattern, null, locale);
     }
 
     /**
      * <p>Formats a calendar into a specific pattern in a locale.</p>
      * 
      * @param calendar  the calendar to format, not null
      * @param pattern  the pattern to use to format the calendar, not null
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted calendar
      * @see FastDateFormat#format(Calendar)
      * @since 2.4
      */
     public static String format(final Calendar calendar, final String pattern, final Locale locale) {
         return format(calendar, pattern, null, locale);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern in a time zone  and locale.</p>
      * 
      * @param millis  the date to format expressed in milliseconds
      * @param pattern  the pattern to use to format the date, not null
      * @param timeZone  the time zone  to use, may be <code>null</code>
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String format(final long millis, final String pattern, final TimeZone timeZone, final Locale locale) {
         return format(new Date(millis), pattern, timeZone, locale);
     }
 
     /**
      * <p>Formats a date/time into a specific pattern in a time zone  and locale.</p>
      * 
      * @param date  the date to format, not null
      * @param pattern  the pattern to use to format the date, not null, not null
      * @param timeZone  the time zone  to use, may be <code>null</code>
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted date
      */
     public static String format(final Date date, final String pattern, final TimeZone timeZone, final Locale locale) {
         final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
         return df.format(date);
     }
 
     /**
      * <p>Formats a calendar into a specific pattern in a time zone  and locale.</p>
      * 
      * @param calendar  the calendar to format, not null
      * @param pattern  the pattern to use to format the calendar, not null
      * @param timeZone  the time zone  to use, may be <code>null</code>
      * @param locale  the locale to use, may be <code>null</code>
      * @return the formatted calendar
      * @see FastDateFormat#format(Calendar)
      * @since 2.4
      */
     public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone, final Locale locale) {
         final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
         return df.format(calendar);
     }
 
 }

1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17		package org.apache.commons.lang3.time;
18
19		import java.util.Calendar;
20		import java.util.Date;
21		import java.util.Locale;
22		import java.util.TimeZone;
23
24		/**
25		* <p>Date and time formatting utilities and constants.</p>
26		*
27		* <p>Formatting is performed using the thread-safe
28		* {@link org.apache.commons.lang3.time.FastDateFormat} class.</p>
29		*
30		* <p>Note that the JDK has a bug wherein calling Calendar.get(int) will
31		* override any previously called Calendar.clear() calls. See LANG-755.</p>
32		*
33		* @since 2.0
34		* @version $Id: DateFormatUtils.java 1436770 2013-01-22 07:09:45Z ggregory $
35		*/
36		public class DateFormatUtils {
37
38		/**
39		* The UTC time zone (often referred to as GMT).
40		* This is private as it is mutable.
41		*/
42	1	private static final TimeZone UTC_TIME_ZONE = TimeZone.getTimeZone("GMT");
43		/**
44		* ISO8601 formatter for date-time without time zone.
45		* The format used is <tt>yyyy-MM-dd'T'HH:mm:ss</tt>.
46		*/
47	1	public static final FastDateFormat ISO_DATETIME_FORMAT
48		= FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ss");
49
50		/**
51		* ISO8601 formatter for date-time with time zone.
52		* The format used is <tt>yyyy-MM-dd'T'HH:mm:ssZZ</tt>.
53		*/
54	1	public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
55		= FastDateFormat.getInstance("yyyy-MM-dd'T'HH:mm:ssZZ");
56
57		/**
58		* ISO8601 formatter for date without time zone.
59		* The format used is <tt>yyyy-MM-dd</tt>.
60		*/
61	1	public static final FastDateFormat ISO_DATE_FORMAT
62		= FastDateFormat.getInstance("yyyy-MM-dd");
63
64		/**
65		* ISO8601-like formatter for date with time zone.
66		* The format used is <tt>yyyy-MM-ddZZ</tt>.
67		* This pattern does not comply with the formal ISO8601 specification
68		* as the standard does not allow a time zone without a time.
69		*/
70	1	public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
71		= FastDateFormat.getInstance("yyyy-MM-ddZZ");
72
73		/**
74		* ISO8601 formatter for time without time zone.
75		* The format used is <tt>'T'HH:mm:ss</tt>.
76		*/
77	1	public static final FastDateFormat ISO_TIME_FORMAT
78		= FastDateFormat.getInstance("'T'HH:mm:ss");
79
80		/**
81		* ISO8601 formatter for time with time zone.
82		* The format used is <tt>'T'HH:mm:ssZZ</tt>.
83		*/
84	1	public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
85		= FastDateFormat.getInstance("'T'HH:mm:ssZZ");
86
87		/**
88		* ISO8601-like formatter for time without time zone.
89		* The format used is <tt>HH:mm:ss</tt>.
90		* This pattern does not comply with the formal ISO8601 specification
91		* as the standard requires the 'T' prefix for times.
92		*/
93	1	public static final FastDateFormat ISO_TIME_NO_T_FORMAT
94		= FastDateFormat.getInstance("HH:mm:ss");
95
96		/**
97		* ISO8601-like formatter for time with time zone.
98		* The format used is <tt>HH:mm:ssZZ</tt>.
99		* This pattern does not comply with the formal ISO8601 specification
100		* as the standard requires the 'T' prefix for times.
101		*/
102	1	public static final FastDateFormat ISO_TIME_NO_T_TIME_ZONE_FORMAT
103		= FastDateFormat.getInstance("HH:mm:ssZZ");
104
105		/**
106		* SMTP (and probably other) date headers.
107		* The format used is <tt>EEE, dd MMM yyyy HH:mm:ss Z</tt> in US locale.
108		*/
109	1	public static final FastDateFormat SMTP_DATETIME_FORMAT
110		= FastDateFormat.getInstance("EEE, dd MMM yyyy HH:mm:ss Z", Locale.US);
111
112		//-----------------------------------------------------------------------
113		/**
114		* <p>DateFormatUtils instances should NOT be constructed in standard programming.</p>
115		*
116		* <p>This constructor is public to permit tools that require a JavaBean instance
117		* to operate.</p>
118		*/
119		public DateFormatUtils() {
120	1	super();
121	1	}
122
123		/**
124		* <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
125		*
126		* @param millis the date to format expressed in milliseconds
127		* @param pattern the pattern to use to format the date, not null
128		* @return the formatted date
129		*/
130		public static String formatUTC(final long millis, final String pattern) {
131	1	return format(new Date(millis), pattern, UTC_TIME_ZONE, null);
132		}
133
134		/**
135		* <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
136		*
137		* @param date the date to format, not null
138		* @param pattern the pattern to use to format the date, not null
139		* @return the formatted date
140		*/
141		public static String formatUTC(final Date date, final String pattern) {
142	1	return format(date, pattern, UTC_TIME_ZONE, null);
143		}
144
145		/**
146		* <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
147		*
148		* @param millis the date to format expressed in milliseconds
149		* @param pattern the pattern to use to format the date, not null
150		* @param locale the locale to use, may be <code>null</code>
151		* @return the formatted date
152		*/
153		public static String formatUTC(final long millis, final String pattern, final Locale locale) {
154	2	return format(new Date(millis), pattern, UTC_TIME_ZONE, locale);
155		}
156
157		/**
158		* <p>Formats a date/time into a specific pattern using the UTC time zone.</p>
159		*
160		* @param date the date to format, not null
161		* @param pattern the pattern to use to format the date, not null
162		* @param locale the locale to use, may be <code>null</code>
163		* @return the formatted date
164		*/
165		public static String formatUTC(final Date date, final String pattern, final Locale locale) {
166	1	return format(date, pattern, UTC_TIME_ZONE, locale);
167		}
168
169		/**
170		* <p>Formats a date/time into a specific pattern.</p>
171		*
172		* @param millis the date to format expressed in milliseconds
173		* @param pattern the pattern to use to format the date, not null
174		* @return the formatted date
175		*/
176		public static String format(final long millis, final String pattern) {
177	1	return format(new Date(millis), pattern, null, null);
178		}
179
180		/**
181		* <p>Formats a date/time into a specific pattern.</p>
182		*
183		* @param date the date to format, not null
184		* @param pattern the pattern to use to format the date, not null
185		* @return the formatted date
186		*/
187		public static String format(final Date date, final String pattern) {
188	2	return format(date, pattern, null, null);
189		}
190
191		/**
192		* <p>Formats a calendar into a specific pattern.</p>
193		*
194		* @param calendar the calendar to format, not null
195		* @param pattern the pattern to use to format the calendar, not null
196		* @return the formatted calendar
197		* @see FastDateFormat#format(Calendar)
198		* @since 2.4
199		*/
200		public static String format(final Calendar calendar, final String pattern) {
201	1	return format(calendar, pattern, null, null);
202		}
203
204		/**
205		* <p>Formats a date/time into a specific pattern in a time zone.</p>
206		*
207		* @param millis the time expressed in milliseconds
208		* @param pattern the pattern to use to format the date, not null
209		* @param timeZone the time zone to use, may be <code>null</code>
210		* @return the formatted date
211		*/
212		public static String format(final long millis, final String pattern, final TimeZone timeZone) {
213	8	return format(new Date(millis), pattern, timeZone, null);
214		}
215
216		/**
217		* <p>Formats a date/time into a specific pattern in a time zone.</p>
218		*
219		* @param date the date to format, not null
220		* @param pattern the pattern to use to format the date, not null
221		* @param timeZone the time zone to use, may be <code>null</code>
222		* @return the formatted date
223		*/
224		public static String format(final Date date, final String pattern, final TimeZone timeZone) {
225	8	return format(date, pattern, timeZone, null);
226		}
227
228		/**
229		* <p>Formats a calendar into a specific pattern in a time zone.</p>
230		*
231		* @param calendar the calendar to format, not null
232		* @param pattern the pattern to use to format the calendar, not null
233		* @param timeZone the time zone to use, may be <code>null</code>
234		* @return the formatted calendar
235		* @see FastDateFormat#format(Calendar)
236		* @since 2.4
237		*/
238		public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone) {
239	0	return format(calendar, pattern, timeZone, null);
240		}
241
242		/**
243		* <p>Formats a date/time into a specific pattern in a locale.</p>
244		*
245		* @param millis the date to format expressed in milliseconds
246		* @param pattern the pattern to use to format the date, not null
247		* @param locale the locale to use, may be <code>null</code>
248		* @return the formatted date
249		*/
250		public static String format(final long millis, final String pattern, final Locale locale) {
251	1	return format(new Date(millis), pattern, null, locale);
252		}
253
254		/**
255		* <p>Formats a date/time into a specific pattern in a locale.</p>
256		*
257		* @param date the date to format, not null
258		* @param pattern the pattern to use to format the date, not null
259		* @param locale the locale to use, may be <code>null</code>
260		* @return the formatted date
261		*/
262		public static String format(final Date date, final String pattern, final Locale locale) {
263	2	return format(date, pattern, null, locale);
264		}
265
266		/**
267		* <p>Formats a calendar into a specific pattern in a locale.</p>
268		*
269		* @param calendar the calendar to format, not null
270		* @param pattern the pattern to use to format the calendar, not null
271		* @param locale the locale to use, may be <code>null</code>
272		* @return the formatted calendar
273		* @see FastDateFormat#format(Calendar)
274		* @since 2.4
275		*/
276		public static String format(final Calendar calendar, final String pattern, final Locale locale) {
277	1	return format(calendar, pattern, null, locale);
278		}
279
280		/**
281		* <p>Formats a date/time into a specific pattern in a time zone and locale.</p>
282		*
283		* @param millis the date to format expressed in milliseconds
284		* @param pattern the pattern to use to format the date, not null
285		* @param timeZone the time zone to use, may be <code>null</code>
286		* @param locale the locale to use, may be <code>null</code>
287		* @return the formatted date
288		*/
289		public static String format(final long millis, final String pattern, final TimeZone timeZone, final Locale locale) {
290	1	return format(new Date(millis), pattern, timeZone, locale);
291		}
292
293		/**
294		* <p>Formats a date/time into a specific pattern in a time zone and locale.</p>
295		*
296		* @param date the date to format, not null
297		* @param pattern the pattern to use to format the date, not null, not null
298		* @param timeZone the time zone to use, may be <code>null</code>
299		* @param locale the locale to use, may be <code>null</code>
300		* @return the formatted date
301		*/
302		public static String format(final Date date, final String pattern, final TimeZone timeZone, final Locale locale) {
303	29	final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
304	29	return df.format(date);
305		}
306
307		/**
308		* <p>Formats a calendar into a specific pattern in a time zone and locale.</p>
309		*
310		* @param calendar the calendar to format, not null
311		* @param pattern the pattern to use to format the calendar, not null
312		* @param timeZone the time zone to use, may be <code>null</code>
313		* @param locale the locale to use, may be <code>null</code>
314		* @return the formatted calendar
315		* @see FastDateFormat#format(Calendar)
316		* @since 2.4
317		*/
318		public static String format(final Calendar calendar, final String pattern, final TimeZone timeZone, final Locale locale) {
319	2	final FastDateFormat df = FastDateFormat.getInstance(pattern, timeZone, locale);
320	2	return df.format(calendar);
321		}
322
323		}