001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 * 
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 * 
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.time;
018
019import java.util.ArrayList;
020import java.util.Calendar;
021import java.util.Date;
022import java.util.GregorianCalendar;
023import java.util.TimeZone;
024
025import org.apache.commons.lang3.StringUtils;
026
027/**
028 * <p>Duration formatting utilities and constants. The following table describes the tokens 
029 * used in the pattern language for formatting. </p>
030 * <table border="1">
031 *  <tr><th>character</th><th>duration element</th></tr>
032 *  <tr><td>y</td><td>years</td></tr>
033 *  <tr><td>M</td><td>months</td></tr>
034 *  <tr><td>d</td><td>days</td></tr>
035 *  <tr><td>H</td><td>hours</td></tr>
036 *  <tr><td>m</td><td>minutes</td></tr>
037 *  <tr><td>s</td><td>seconds</td></tr>
038 *  <tr><td>S</td><td>milliseconds</td></tr>
039 *  <tr><td>'text'</td><td>arbitrary text content</td></tr>
040 * </table>
041 *
042 * <b>Note: It's not currently possible to include a single-quote in a format.</b>
043 * <br/>
044 * Token values are printed using decimal digits.
045 * A token character can be repeated to ensure that the field occupies a certain minimum
046 * size. Values will be left-padded with 0 unless padding is disabled in the method invocation.
047 * @since 2.1
048 * @version $Id: DurationFormatUtils.java 1573807 2014-03-03 23:31:53Z sebb $
049 */
050public class DurationFormatUtils {
051
052    /**
053     * <p>DurationFormatUtils instances should NOT be constructed in standard programming.</p>
054     *
055     * <p>This constructor is public to permit tools that require a JavaBean instance
056     * to operate.</p>
057     */
058    public DurationFormatUtils() {
059        super();
060    }
061
062    /**
063     * <p>Pattern used with <code>FastDateFormat</code> and <code>SimpleDateFormat</code>
064     * for the ISO8601 period format used in durations.</p>
065     * 
066     * @see org.apache.commons.lang3.time.FastDateFormat
067     * @see java.text.SimpleDateFormat
068     */
069    public static final String ISO_EXTENDED_FORMAT_PATTERN = "'P'yyyy'Y'M'M'd'DT'H'H'm'M's.S'S'";
070
071    //-----------------------------------------------------------------------
072    /**
073     * <p>Formats the time gap as a string.</p>
074     * 
075     * <p>The format used is ISO8601-like:
076     * <i>H</i>:<i>m</i>:<i>s</i>.<i>S</i>.</p>
077     * 
078     * @param durationMillis  the duration to format
079     * @return the formatted duration, not null
080     */
081    public static String formatDurationHMS(final long durationMillis) {
082        return formatDuration(durationMillis, "H:mm:ss.SSS");
083    }
084
085    /**
086     * <p>Formats the time gap as a string.</p>
087     * 
088     * <p>The format used is the ISO8601 period format.</p>
089     * 
090     * <p>This method formats durations using the days and lower fields of the
091     * ISO format pattern, such as P7D6TH5M4.321S.</p>
092     * 
093     * @param durationMillis  the duration to format
094     * @return the formatted duration, not null
095     */
096    public static String formatDurationISO(final long durationMillis) {
097        return formatDuration(durationMillis, ISO_EXTENDED_FORMAT_PATTERN, false);
098    }
099
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->February = 1 month and then 
256     * calculating days forwards, and not the 1 month and 26 days gained by 
257     * choosing March -> 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}