View Javadoc
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.ArrayList;
20  import java.util.Calendar;
21  import java.util.Date;
22  import java.util.GregorianCalendar;
23  import java.util.TimeZone;
24  
25  import org.apache.commons.lang3.StringUtils;
26  import org.apache.commons.lang3.Validate;
27  
28  /**
29   * <p>Duration formatting utilities and constants. The following table describes the tokens 
30   * used in the pattern language for formatting. </p>
31   * <table border="1" summary="Pattern Tokens">
32   *  <tr><th>character</th><th>duration element</th></tr>
33   *  <tr><td>y</td><td>years</td></tr>
34   *  <tr><td>M</td><td>months</td></tr>
35   *  <tr><td>d</td><td>days</td></tr>
36   *  <tr><td>H</td><td>hours</td></tr>
37   *  <tr><td>m</td><td>minutes</td></tr>
38   *  <tr><td>s</td><td>seconds</td></tr>
39   *  <tr><td>S</td><td>milliseconds</td></tr>
40   *  <tr><td>'text'</td><td>arbitrary text content</td></tr>
41   * </table>
42   *
43   * <b>Note: It's not currently possible to include a single-quote in a format.</b>
44   * <br>
45   * Token values are printed using decimal digits.
46   * A token character can be repeated to ensure that the field occupies a certain minimum
47   * size. Values will be left-padded with 0 unless padding is disabled in the method invocation.
48   * @since 2.1
49   * @version $Id: DurationFormatUtils.java 1606051 2014-06-27 12:22:17Z ggregory $
50   */
51  public class DurationFormatUtils {
52  
53      /**
54       * <p>DurationFormatUtils instances should NOT be constructed in standard programming.</p>
55       *
56       * <p>This constructor is public to permit tools that require a JavaBean instance
57       * to operate.</p>
58       */
59      public DurationFormatUtils() {
60          super();
61      }
62  
63      /**
64       * <p>Pattern used with <code>FastDateFormat</code> and <code>SimpleDateFormat</code>
65       * for the ISO 8601 period format used in durations.</p>
66       * 
67       * @see org.apache.commons.lang3.time.FastDateFormat
68       * @see java.text.SimpleDateFormat
69       */
70      public static final String ISO_EXTENDED_FORMAT_PATTERN = "'P'yyyy'Y'M'M'd'DT'H'H'm'M's.SSS'S'";
71  
72      //-----------------------------------------------------------------------
73      /**
74       * <p>Formats the time gap as a string.</p>
75       * 
76       * <p>The format used is ISO 8601-like: {@code HH:mm:ss.SSS}.</p>
77       *
78       * @param durationMillis  the duration to format
79       * @return the formatted duration, not null
80       * @throws java.lang.IllegalArgumentException if durationMillis is negative
81       */
82      public static String formatDurationHMS(final long durationMillis) {
83          return formatDuration(durationMillis, "HH:mm:ss.SSS");
84      }
85  
86      /**
87       * <p>Formats the time gap as a string.</p>
88       * 
89       * <p>The format used is the ISO 8601 period format.</p>
90       * 
91       * <p>This method formats durations using the days and lower fields of the
92       * ISO format pattern, such as P7D6TH5M4.321S.</p>
93       * 
94       * @param durationMillis  the duration to format
95       * @return the formatted duration, not null
96       * @throws java.lang.IllegalArgumentException if durationMillis is negative
97       */
98      public static String formatDurationISO(final long durationMillis) {
99          return formatDuration(durationMillis, ISO_EXTENDED_FORMAT_PATTERN, false);
100     }
101 
102     /**
103      * <p>Formats the time gap as a string, using the specified format, and padding with zeros.</p>
104      * 
105      * <p>This method formats durations using the days and lower fields of the
106      * format pattern. Months and larger are not used.</p>
107      * 
108      * @param durationMillis  the duration to format
109      * @param format  the way in which to format the duration, not null
110      * @return the formatted duration, not null
111      * @throws java.lang.IllegalArgumentException if durationMillis is negative
112      */
113     public static String formatDuration(final long durationMillis, final String format) {
114         return formatDuration(durationMillis, format, true);
115     }
116 
117     /**
118      * <p>Formats the time gap as a string, using the specified format.
119      * Padding the left hand side of numbers with zeroes is optional.</p>
120      * 
121      * <p>This method formats durations using the days and lower fields of the
122      * format pattern. Months and larger are not used.</p>
123      * 
124      * @param durationMillis  the duration to format
125      * @param format  the way in which to format the duration, not null
126      * @param padWithZeros  whether to pad the left hand side of numbers with 0's
127      * @return the formatted duration, not null
128      * @throws java.lang.IllegalArgumentException if durationMillis is negative
129      */
130     public static String formatDuration(final long durationMillis, final String format, final boolean padWithZeros) {
131         Validate.inclusiveBetween(0, Long.MAX_VALUE, durationMillis, "durationMillis must not be negative");        
132 
133         final Token[] tokens = lexx(format);
134 
135         long days         = 0;
136         long hours        = 0;
137         long minutes      = 0;
138         long seconds      = 0;
139         long milliseconds = durationMillis;
140         
141         if (Token.containsTokenWithValue(tokens, d) ) {
142             days = milliseconds / DateUtils.MILLIS_PER_DAY;
143             milliseconds = milliseconds - (days * DateUtils.MILLIS_PER_DAY);
144         }
145         if (Token.containsTokenWithValue(tokens, H) ) {
146             hours = milliseconds / DateUtils.MILLIS_PER_HOUR;
147             milliseconds = milliseconds - (hours * DateUtils.MILLIS_PER_HOUR);
148         }
149         if (Token.containsTokenWithValue(tokens, m) ) {
150             minutes = milliseconds / DateUtils.MILLIS_PER_MINUTE;
151             milliseconds = milliseconds - (minutes * DateUtils.MILLIS_PER_MINUTE);
152         }
153         if (Token.containsTokenWithValue(tokens, s) ) {
154             seconds = milliseconds / DateUtils.MILLIS_PER_SECOND;
155             milliseconds = milliseconds - (seconds * DateUtils.MILLIS_PER_SECOND);
156         }
157 
158         return format(tokens, 0, 0, days, hours, minutes, seconds, milliseconds, padWithZeros);
159     }
160 
161     /**
162      * <p>Formats an elapsed time into a plurialization correct string.</p>
163      * 
164      * <p>This method formats durations using the days and lower fields of the
165      * format pattern. Months and larger are not used.</p>
166      * 
167      * @param durationMillis  the elapsed time to report in milliseconds
168      * @param suppressLeadingZeroElements  suppresses leading 0 elements
169      * @param suppressTrailingZeroElements  suppresses trailing 0 elements
170      * @return the formatted text in days/hours/minutes/seconds, not null
171      * @throws java.lang.IllegalArgumentException if durationMillis is negative
172      */
173     public static String formatDurationWords(
174         final long durationMillis,
175         final boolean suppressLeadingZeroElements,
176         final boolean suppressTrailingZeroElements) {
177 
178         // This method is generally replacable by the format method, but 
179         // there are a series of tweaks and special cases that require 
180         // trickery to replicate.
181         String duration = formatDuration(durationMillis, "d' days 'H' hours 'm' minutes 's' seconds'");
182         if (suppressLeadingZeroElements) {
183             // this is a temporary marker on the front. Like ^ in regexp.
184             duration = " " + duration;
185             String tmp = StringUtils.replaceOnce(duration, " 0 days", "");
186             if (tmp.length() != duration.length()) {
187                 duration = tmp;
188                 tmp = StringUtils.replaceOnce(duration, " 0 hours", "");
189                 if (tmp.length() != duration.length()) {
190                     duration = tmp;
191                     tmp = StringUtils.replaceOnce(duration, " 0 minutes", "");
192                     duration = tmp;
193                     if (tmp.length() != duration.length()) {
194                         duration = StringUtils.replaceOnce(tmp, " 0 seconds", "");
195                     }
196                 }
197             }
198             if (duration.length() != 0) {
199                 // strip the space off again
200                 duration = duration.substring(1);
201             }
202         }
203         if (suppressTrailingZeroElements) {
204             String tmp = StringUtils.replaceOnce(duration, " 0 seconds", "");
205             if (tmp.length() != duration.length()) {
206                 duration = tmp;
207                 tmp = StringUtils.replaceOnce(duration, " 0 minutes", "");
208                 if (tmp.length() != duration.length()) {
209                     duration = tmp;
210                     tmp = StringUtils.replaceOnce(duration, " 0 hours", "");
211                     if (tmp.length() != duration.length()) {
212                         duration = StringUtils.replaceOnce(tmp, " 0 days", "");
213                     }
214                 }
215             }
216         }
217         // handle plurals
218         duration = " " + duration;
219         duration = StringUtils.replaceOnce(duration, " 1 seconds", " 1 second");
220         duration = StringUtils.replaceOnce(duration, " 1 minutes", " 1 minute");
221         duration = StringUtils.replaceOnce(duration, " 1 hours", " 1 hour");
222         duration = StringUtils.replaceOnce(duration, " 1 days", " 1 day");
223         return duration.trim();
224     }
225 
226     //-----------------------------------------------------------------------
227     /**
228      * <p>Formats the time gap as a string.</p>
229      * 
230      * <p>The format used is the ISO 8601 period format.</p>
231      * 
232      * @param startMillis  the start of the duration to format
233      * @param endMillis  the end of the duration to format
234      * @return the formatted duration, not null
235      * @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis
236      */
237     public static String formatPeriodISO(final long startMillis, final long endMillis) {
238         return formatPeriod(startMillis, endMillis, ISO_EXTENDED_FORMAT_PATTERN, false, TimeZone.getDefault());
239     }
240 
241     /**
242      * <p>Formats the time gap as a string, using the specified format.
243      * Padding the left hand side of numbers with zeroes is optional.
244      * 
245      * @param startMillis  the start of the duration
246      * @param endMillis  the end of the duration
247      * @param format  the way in which to format the duration, not null
248      * @return the formatted duration, not null
249      * @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis
250      */
251     public static String formatPeriod(final long startMillis, final long endMillis, final String format) {
252         return formatPeriod(startMillis, endMillis, format, true, TimeZone.getDefault());
253     }
254 
255     /**
256      * <p>Formats the time gap as a string, using the specified format.
257      * Padding the left hand side of numbers with zeroes is optional and 
258      * the timezone may be specified. </p>
259      *
260      * <p>When calculating the difference between months/days, it chooses to 
261      * calculate months first. So when working out the number of months and 
262      * days between January 15th and March 10th, it choose 1 month and 
263      * 23 days gained by choosing January-&gt;February = 1 month and then 
264      * calculating days forwards, and not the 1 month and 26 days gained by 
265      * choosing March -&gt; February = 1 month and then calculating days 
266      * backwards. </p>
267      *
268      * <p>For more control, the <a href="http://joda-time.sf.net/">Joda-Time</a>
269      * library is recommended.</p>
270      * 
271      * @param startMillis  the start of the duration
272      * @param endMillis  the end of the duration
273      * @param format  the way in which to format the duration, not null
274      * @param padWithZeros  whether to pad the left hand side of numbers with 0's
275      * @param timezone  the millis are defined in
276      * @return the formatted duration, not null
277      * @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis
278      */
279     public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros, 
280             final TimeZone timezone) {
281         Validate.isTrue(startMillis <= endMillis, "startMillis must not be greater than endMillis");
282         
283 
284         // Used to optimise for differences under 28 days and 
285         // called formatDuration(millis, format); however this did not work 
286         // over leap years. 
287         // TODO: Compare performance to see if anything was lost by 
288         // losing this optimisation. 
289         
290         final Token[] tokens = lexx(format);
291 
292         // timezones get funky around 0, so normalizing everything to GMT 
293         // stops the hours being off
294         final Calendar start = Calendar.getInstance(timezone);
295         start.setTime(new Date(startMillis));
296         final Calendar end = Calendar.getInstance(timezone);
297         end.setTime(new Date(endMillis));
298 
299         // initial estimates
300         int milliseconds = end.get(Calendar.MILLISECOND) - start.get(Calendar.MILLISECOND);
301         int seconds = end.get(Calendar.SECOND) - start.get(Calendar.SECOND);
302         int minutes = end.get(Calendar.MINUTE) - start.get(Calendar.MINUTE);
303         int hours = end.get(Calendar.HOUR_OF_DAY) - start.get(Calendar.HOUR_OF_DAY);
304         int days = end.get(Calendar.DAY_OF_MONTH) - start.get(Calendar.DAY_OF_MONTH);
305         int months = end.get(Calendar.MONTH) - start.get(Calendar.MONTH);
306         int years = end.get(Calendar.YEAR) - start.get(Calendar.YEAR);
307 
308         // each initial estimate is adjusted in case it is under 0
309         while (milliseconds < 0) {
310             milliseconds += 1000;
311             seconds -= 1;
312         }
313         while (seconds < 0) {
314             seconds += 60;
315             minutes -= 1;
316         }
317         while (minutes < 0) {
318             minutes += 60;
319             hours -= 1;
320         }
321         while (hours < 0) {
322             hours += 24;
323             days -= 1;
324         }
325        
326         if (Token.containsTokenWithValue(tokens, M)) {
327             while (days < 0) {
328                 days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
329                 months -= 1;
330                 start.add(Calendar.MONTH, 1);
331             }
332 
333             while (months < 0) {
334                 months += 12;
335                 years -= 1;
336             }
337 
338             if (!Token.containsTokenWithValue(tokens, y) && years != 0) {
339                 while (years != 0) {
340                     months += 12 * years;
341                     years = 0;
342                 }
343             }
344         } else {
345             // there are no M's in the format string
346 
347             if( !Token.containsTokenWithValue(tokens, y) ) {
348                 int target = end.get(Calendar.YEAR);
349                 if (months < 0) {
350                     // target is end-year -1
351                     target -= 1;
352                 }
353                 
354                 while (start.get(Calendar.YEAR) != target) {
355                     days += start.getActualMaximum(Calendar.DAY_OF_YEAR) - start.get(Calendar.DAY_OF_YEAR);
356                     
357                     // Not sure I grok why this is needed, but the brutal tests show it is
358                     if (start instanceof GregorianCalendar &&
359                             start.get(Calendar.MONTH) == Calendar.FEBRUARY &&
360                             start.get(Calendar.DAY_OF_MONTH) == 29) {
361                         days += 1;
362                     }
363                     
364                     start.add(Calendar.YEAR, 1);
365                     
366                     days += start.get(Calendar.DAY_OF_YEAR);
367                 }
368                 
369                 years = 0;
370             }
371             
372             while( start.get(Calendar.MONTH) != end.get(Calendar.MONTH) ) {
373                 days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
374                 start.add(Calendar.MONTH, 1);
375             }
376             
377             months = 0;            
378 
379             while (days < 0) {
380                 days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
381                 months -= 1;
382                 start.add(Calendar.MONTH, 1);
383             }
384             
385         }
386 
387         // The rest of this code adds in values that 
388         // aren't requested. This allows the user to ask for the 
389         // number of months and get the real count and not just 0->11.
390 
391         if (!Token.containsTokenWithValue(tokens, d)) {
392             hours += 24 * days;
393             days = 0;
394         }
395         if (!Token.containsTokenWithValue(tokens, H)) {
396             minutes += 60 * hours;
397             hours = 0;
398         }
399         if (!Token.containsTokenWithValue(tokens, m)) {
400             seconds += 60 * minutes;
401             minutes = 0;
402         }
403         if (!Token.containsTokenWithValue(tokens, s)) {
404             milliseconds += 1000 * seconds;
405             seconds = 0;
406         }
407 
408         return format(tokens, years, months, days, hours, minutes, seconds, milliseconds, padWithZeros);
409     }
410 
411     //-----------------------------------------------------------------------
412     /**
413      * <p>The internal method to do the formatting.</p>
414      * 
415      * @param tokens  the tokens
416      * @param years  the number of years
417      * @param months  the number of months
418      * @param days  the number of days
419      * @param hours  the number of hours
420      * @param minutes  the number of minutes
421      * @param seconds  the number of seconds
422      * @param milliseconds  the number of millis
423      * @param padWithZeros  whether to pad
424      * @return the formatted string
425      */
426     static String format(final Token[] tokens, final long years, final long months, final long days, final long hours, final long minutes, final long seconds,
427             final long milliseconds, final boolean padWithZeros) {
428         final StringBuilder buffer = new StringBuilder();
429         boolean lastOutputSeconds = false;
430         for (final Token token : tokens) {
431             final Object value = token.getValue();
432             final int count = token.getCount();
433             if (value instanceof StringBuilder) {
434                 buffer.append(value.toString());
435             } else {
436                 if (value == y) {
437                     buffer.append(paddedValue(years, padWithZeros, count));
438                     lastOutputSeconds = false;
439                 } else if (value == M) {
440                     buffer.append(paddedValue(months, padWithZeros, count));
441                     lastOutputSeconds = false;
442                 } else if (value == d) {
443                     buffer.append(paddedValue(days, padWithZeros, count));
444                     lastOutputSeconds = false;
445                 } else if (value == H) {
446                     buffer.append(paddedValue(hours, padWithZeros, count));
447                     lastOutputSeconds = false;
448                 } else if (value == m) {
449                     buffer.append(paddedValue(minutes, padWithZeros, count));
450                     lastOutputSeconds = false;
451                 } else if (value == s) {
452                     buffer.append(paddedValue(seconds, padWithZeros, count));
453                     lastOutputSeconds = true;
454                 } else if (value == S) {
455                     if (lastOutputSeconds) {
456                         // ensure at least 3 digits are displayed even if padding is not selected
457                         final int width = padWithZeros ? Math.max(3, count) : 3;
458                         buffer.append(paddedValue(milliseconds, true, width));
459                     } else {
460                         buffer.append(paddedValue(milliseconds, padWithZeros, count));
461                     }
462                     lastOutputSeconds = false;
463                 }
464             }
465         }
466         return buffer.toString();
467     }
468 
469     /**
470      * <p>Converts a {@code long} to a {@code String} with optional
471      * zero padding.</p>
472      *
473      * @param value the value to convert
474      * @param padWithZeros whether to pad with zeroes
475      * @param count the size to pad to (ignored if {@code padWithZeros} is false)
476      * @return the string result
477      */
478     private static String paddedValue(final long value, final boolean padWithZeros, final int count) {
479         final String longString = Long.toString(value);
480         return padWithZeros ? StringUtils.leftPad(longString, count, '0') : longString;
481     }
482 
483     static final Object y = "y";
484     static final Object M = "M";
485     static final Object d = "d";
486     static final Object H = "H";
487     static final Object m = "m";
488     static final Object s = "s";
489     static final Object S = "S";
490     
491     /**
492      * Parses a classic date format string into Tokens
493      *
494      * @param format  the format to parse, not null
495      * @return array of Token[]
496      */
497     static Token[] lexx(final String format) {
498         final ArrayList<Token> list = new ArrayList<Token>(format.length());
499 
500         boolean inLiteral = false;
501         // Although the buffer is stored in a Token, the Tokens are only
502         // used internally, so cannot be accessed by other threads
503         StringBuilder buffer = null;
504         Token previous = null;
505         for (int i = 0; i < format.length(); i++) {
506             final char ch = format.charAt(i);
507             if (inLiteral && ch != '\'') {
508                 buffer.append(ch); // buffer can't be null if inLiteral is true
509                 continue;
510             }
511             Object value = null;
512             switch (ch) {
513             // TODO: Need to handle escaping of '
514             case '\'':
515                 if (inLiteral) {
516                     buffer = null;
517                     inLiteral = false;
518                 } else {
519                     buffer = new StringBuilder();
520                     list.add(new Token(buffer));
521                     inLiteral = true;
522                 }
523                 break;
524             case 'y':
525                 value = y;
526                 break;
527             case 'M':
528                 value = M;
529                 break;
530             case 'd':
531                 value = d;
532                 break;
533             case 'H':
534                 value = H;
535                 break;
536             case 'm':
537                 value = m;
538                 break;
539             case 's':
540                 value = s;
541                 break;
542             case 'S':
543                 value = S;
544                 break;
545             default:
546                 if (buffer == null) {
547                     buffer = new StringBuilder();
548                     list.add(new Token(buffer));
549                 }
550                 buffer.append(ch);
551             }
552 
553             if (value != null) {
554                 if (previous != null && previous.getValue() == value) {
555                     previous.increment();
556                 } else {
557                     final Token token = new Token(value);
558                     list.add(token);
559                     previous = token;
560                 }
561                 buffer = null;
562             }
563         }
564         if (inLiteral) { // i.e. we have not found the end of the literal
565             throw new IllegalArgumentException("Unmatched quote in format: " + format);
566         }
567         return list.toArray(new Token[list.size()]);
568     }
569 
570     //-----------------------------------------------------------------------
571     /**
572      * Element that is parsed from the format pattern.
573      */
574     static class Token {
575 
576         /**
577          * Helper method to determine if a set of tokens contain a value
578          *
579          * @param tokens set to look in
580          * @param value to look for
581          * @return boolean <code>true</code> if contained
582          */
583         static boolean containsTokenWithValue(final Token[] tokens, final Object value) {
584             for (final Token token : tokens) {
585                 if (token.getValue() == value) {
586                     return true;
587                 }
588             }
589             return false;
590         }
591 
592         private final Object value;
593         private int count;
594 
595         /**
596          * Wraps a token around a value. A value would be something like a 'Y'.
597          *
598          * @param value to wrap
599          */
600         Token(final Object value) {
601             this.value = value;
602             this.count = 1;
603         }
604 
605         /**
606          * Wraps a token around a repeated number of a value, for example it would 
607          * store 'yyyy' as a value for y and a count of 4.
608          *
609          * @param value to wrap
610          * @param count to wrap
611          */
612         Token(final Object value, final int count) {
613             this.value = value;
614             this.count = count;
615         }
616 
617         /**
618          * Adds another one of the value
619          */
620         void increment() { 
621             count++;
622         }
623 
624         /**
625          * Gets the current number of values represented
626          *
627          * @return int number of values represented
628          */
629         int getCount() {
630             return count;
631         }
632 
633         /**
634          * Gets the particular value this token represents.
635          * 
636          * @return Object value
637          */
638         Object getValue() {
639             return value;
640         }
641 
642         /**
643          * Supports equality of this Token to another Token.
644          *
645          * @param obj2 Object to consider equality of
646          * @return boolean <code>true</code> if equal
647          */
648         @Override
649         public boolean equals(final Object obj2) {
650             if (obj2 instanceof Token) {
651                 final Token tok2 = (Token) obj2;
652                 if (this.value.getClass() != tok2.value.getClass()) {
653                     return false;
654                 }
655                 if (this.count != tok2.count) {
656                     return false;
657                 }
658                 if (this.value instanceof StringBuilder) {
659                     return this.value.toString().equals(tok2.value.toString());
660                 } else if (this.value instanceof Number) {
661                     return this.value.equals(tok2.value);
662                 } else {
663                     return this.value == tok2.value;
664                 }
665             }
666             return false;
667         }
668 
669         /**
670          * Returns a hash code for the token equal to the 
671          * hash code for the token's value. Thus 'TT' and 'TTTT' 
672          * will have the same hash code. 
673          *
674          * @return The hash code for the token
675          */
676         @Override
677         public int hashCode() {
678             return this.value.hashCode();
679         }
680 
681         /**
682          * Represents this token as a String.
683          *
684          * @return String representation of the token
685          */
686         @Override
687         public String toString() {
688             return StringUtils.repeat(this.value.toString(), this.count);
689         }
690     }
691 
692 }