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