    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.text.SimpleDateFormat;
    020import java.util.ArrayList;
    021import java.util.Calendar;
    022import java.util.Date;
    023import java.util.GregorianCalendar;
    024import java.util.Objects;
    025import java.util.TimeZone;
    026import java.util.stream.Stream;
    027
    028import org.apache.commons.lang3.StringUtils;
    029import org.apache.commons.lang3.Validate;
    030
    031/**
    032 * Duration formatting utilities and constants. The following table describes the tokens
    033 * used in the pattern language for formatting.
    034 * <table border="1">
    035 *  <caption>Pattern Tokens</caption>
    036 *  <tr><th>character</th><th>duration element</th></tr>
    037 *  <tr><td>y</td><td>years</td></tr>
    038 *  <tr><td>M</td><td>months</td></tr>
    039 *  <tr><td>d</td><td>days</td></tr>
    040 *  <tr><td>H</td><td>hours</td></tr>
    041 *  <tr><td>m</td><td>minutes</td></tr>
    042 *  <tr><td>s</td><td>seconds</td></tr>
    043 *  <tr><td>S</td><td>milliseconds</td></tr>
    044 *  <tr><td>'text'</td><td>arbitrary text content</td></tr>
    045 * </table>
    046 *
    047 * <b>Note: It's not currently possible to include a single-quote in a format.</b>
    048 * <br>
    049 * Token values are printed using decimal digits.
    050 * A token character can be repeated to ensure that the field occupies a certain minimum
    051 * size. Values will be left-padded with 0 unless padding is disabled in the method invocation.
    052 * <br>
    053 * Tokens can be marked as optional by surrounding them with brackets [ ]. These tokens will
    054 * only be printed if the token value is non-zero. Literals within optional blocks will only be
    055 * printed if the preceding non-literal token is non-zero. Leading optional literals will only
    056 * be printed if the following non-literal is non-zero.
    057 * Multiple optional blocks can be used to group literals with the desired token.
    058 * <p>
    059 * Notes on Optional Tokens:<br>
    060 * <b>Multiple optional tokens without literals can result in impossible to understand output.</b><br>
    061 * <b>Patterns where all tokens are optional can produce empty strings.</b><br>
    062 * (See examples below)
    063 * </p>
    064 * <br>
    065 * <table border="1">
    066 * <caption>Example Output</caption>
    067 * <tr><th>pattern</th><th>Duration.ofDays(1)</th><th>Duration.ofHours(1)</th><th>Duration.ofMinutes(1)</th><th>Duration.ZERO</th></tr>
    068 * <tr><td>d'd'H'h'm'm's's'</td><td>1d0h0m0s</td><td>0d1h0m0s</td><td>0d0h1m0s</td><td>0d0h0m0s</td></tr>
    069 * <tr><td>d'd'[H'h'm'm']s's'</td><td>1d0s</td><td>0d1h0s</td><td>0d1m0s</td><td>0d0s</td></tr>
    070 * <tr><td>[d'd'H'h'm'm']s's'</td><td>1d0s</td><td>1h0s</td><td>1m0s</td><td>0s</td></tr>
    071 * <tr><td>[d'd'H'h'm'm's's']</td><td>1d</td><td>1h</td><td>1m</td><td></td></tr>
    072 * <tr><td>['{'d'}']HH':'mm</td><td>{1}00:00</td><td>01:00</td><td>00:01</td><td>00:00</td></tr>
    073 * <tr><td>['{'dd'}']['&lt;'HH'&gt;']['('mm')']</td><td>{01}</td><td>&lt;01&gt;</td><td>(00)</td><td></td></tr>
    074 * <tr><td>[dHms]</td><td>1</td><td>1</td><td>1</td><td></td></tr>
    075 * </table>
    076 * <b>Note: Optional blocks cannot be nested.</b>
    077 *
    078 * @since 2.1
    079 */
    080public class DurationFormatUtils {
    081
    082    /**
    083     * Element that is parsed from the format pattern.
    084     */
    085    static class Token {
    086
    087        /** Empty array. */
    088        private static final Token[] EMPTY_ARRAY = {};
    089
    090        /**
    091         * Helper method to determine if a set of tokens contain a value
    092         *
    093         * @param tokens set to look in
    094         * @param value to look for
    095         * @return boolean {@code true} if contained
    096         */
    097        static boolean containsTokenWithValue(final Token[] tokens, final Object value) {
    098            return Stream.of(tokens).anyMatch(token -> token.getValue() == value);
    099        }
    100
    101        private final CharSequence value;
    102        private int count;
    103        private int optionalIndex = -1;
    104
    105        /**
    106         * Wraps a token around a value. A value would be something like a 'Y'.
    107         *
    108         * @param value value to wrap, non-null.
    109         * @param optional whether the token is optional
    110         * @param optionalIndex the index of the optional token within the pattern
    111         */
    112        Token(final CharSequence value, final boolean optional, final int optionalIndex) {
    113            this.value = Objects.requireNonNull(value, "value");
    114            this.count = 1;
    115            if (optional) {
    116                this.optionalIndex = optionalIndex;
    117            }
    118        }
    119
    120        /**
    121         * Supports equality of this Token to another Token.
    122         *
    123         * @param obj2 Object to consider equality of
    124         * @return boolean {@code true} if equal
    125         */
    126        @Override
    127        public boolean equals(final Object obj2) {
    128            if (obj2 instanceof Token) {
    129                final Token tok2 = (Token) obj2;
    130                if (this.value.getClass() != tok2.value.getClass()) {
    131                    return false;
    132                }
    133                if (this.count != tok2.count) {
    134                    return false;
    135                }
    136                if (this.value instanceof StringBuilder) {
    137                    return this.value.toString().equals(tok2.value.toString());
    138                }
    139                if (this.value instanceof Number) {
    140                    return this.value.equals(tok2.value);
    141                }
    142                return this.value == tok2.value;
    143            }
    144            return false;
    145        }
    146
    147        /**
    148         * Gets the current number of values represented
    149         *
    150         * @return int number of values represented
    151         */
    152        int getCount() {
    153            return count;
    154        }
    155
    156        /**
    157         * Gets the particular value this token represents.
    158         *
    159         * @return Object value, non-null.
    160         */
    161        Object getValue() {
    162            return value;
    163        }
    164
    165        /**
    166         * Returns a hash code for the token equal to the
    167         * hash code for the token's value. Thus 'TT' and 'TTTT'
    168         * will have the same hash code.
    169         *
    170         * @return The hash code for the token
    171         */
    172        @Override
    173        public int hashCode() {
    174            return this.value.hashCode();
    175        }
    176
    177        /**
    178         * Adds another one of the value
    179         */
    180        void increment() {
    181            count++;
    182        }
    183
    184        /**
    185         * Represents this token as a String.
    186         *
    187         * @return String representation of the token
    188         */
    189        @Override
    190        public String toString() {
    191            return StringUtils.repeat(this.value.toString(), this.count);
    192        }
    193    }
    194
    195    private static final int MINUTES_PER_HOUR = 60;
    196
    197    private static final int SECONDS_PER_MINUTES = 60;
    198
    199    private static final int HOURS_PER_DAY = 24;
    200
    201    /**
    202     * Pattern used with {@link FastDateFormat} and {@link SimpleDateFormat}
    203     * for the ISO 8601 period format used in durations.
    204     *
    205     * @see org.apache.commons.lang3.time.FastDateFormat
    206     * @see java.text.SimpleDateFormat
    207     */
    208    public static final String ISO_EXTENDED_FORMAT_PATTERN = "'P'yyyy'Y'M'M'd'DT'H'H'm'M's.SSS'S'";
    209
    210    static final String y = "y";
    211
    212    static final String M = "M";
    213
    214    static final String d = "d";
    215
    216    static final String H = "H";
    217
    218    static final String m = "m";
    219
    220    static final String s = "s";
    221
    222    static final String S = "S";
    223
    224    /**
    225     * The internal method to do the formatting.
    226     *
    227     * @param tokens  the tokens
    228     * @param years  the number of years
    229     * @param months  the number of months
    230     * @param days  the number of days
    231     * @param hours  the number of hours
    232     * @param minutes  the number of minutes
    233     * @param seconds  the number of seconds
    234     * @param milliseconds  the number of millis
    235     * @param padWithZeros  whether to pad
    236     * @return the formatted string
    237     */
    238    static String format(final Token[] tokens, final long years, final long months, final long days, final long hours, final long minutes,
    239            final long seconds,
    240            final long milliseconds, final boolean padWithZeros) {
    241        final StringBuilder buffer = new StringBuilder();
    242        boolean lastOutputSeconds = false;
    243        boolean lastOutputZero = false;
    244        int optionalStart = -1;
    245        boolean firstOptionalNonLiteral = false;
    246        int optionalIndex = -1;
    247        boolean inOptional = false;
    248        for (final Token token : tokens) {
    249            final Object value = token.getValue();
    250            final boolean isLiteral = value instanceof StringBuilder;
    251            final int count = token.getCount();
    252            if (optionalIndex != token.optionalIndex) {
    253              optionalIndex = token.optionalIndex;
    254              if (optionalIndex > -1) {
    255                //entering new optional block
    256                optionalStart = buffer.length();
    257                lastOutputZero = false;
    258                inOptional = true;
    259                firstOptionalNonLiteral = false;
    260              } else {
    261                //leaving optional block
    262                inOptional = false;
    263              }
    264            }
    265            if (isLiteral) {
    266                if (!inOptional || !lastOutputZero) {
    267                    buffer.append(value.toString());
    268                }
    269            } else if (value.equals(y)) {
    270                lastOutputSeconds = false;
    271                lastOutputZero = years == 0;
    272                if (!inOptional || !lastOutputZero) {
    273                    buffer.append(paddedValue(years, padWithZeros, count));
    274                }
    275            } else if (value.equals(M)) {
    276                lastOutputSeconds = false;
    277                lastOutputZero = months == 0;
    278                if (!inOptional || !lastOutputZero) {
    279                    buffer.append(paddedValue(months, padWithZeros, count));
    280                }
    281            } else if (value.equals(d)) {
    282                lastOutputSeconds = false;
    283                lastOutputZero = days == 0;
    284                if (!inOptional || !lastOutputZero) {
    285                    buffer.append(paddedValue(days, padWithZeros, count));
    286                }
    287            } else if (value.equals(H)) {
    288                lastOutputSeconds = false;
    289                lastOutputZero = hours == 0;
    290                if (!inOptional || !lastOutputZero) {
    291                    buffer.append(paddedValue(hours, padWithZeros, count));
    292                }
    293            } else if (value.equals(m)) {
    294                lastOutputSeconds = false;
    295                lastOutputZero = minutes == 0;
    296                if (!inOptional || !lastOutputZero) {
    297                    buffer.append(paddedValue(minutes, padWithZeros, count));
    298                }
    299            } else if (value.equals(s)) {
    300                lastOutputSeconds = true;
    301                lastOutputZero = seconds == 0;
    302                if (!inOptional || !lastOutputZero) {
    303                    buffer.append(paddedValue(seconds, padWithZeros, count));
    304                }
    305            } else if (value.equals(S)) {
    306                lastOutputZero = milliseconds == 0;
    307                if (!inOptional || !lastOutputZero) {
    308                    if (lastOutputSeconds) {
    309                        // ensure at least 3 digits are displayed even if padding is not selected
    310                        final int width = padWithZeros ? Math.max(3, count) : 3;
    311                        buffer.append(paddedValue(milliseconds, true, width));
    312                    } else {
    313                        buffer.append(paddedValue(milliseconds, padWithZeros, count));
    314                    }
    315                }
    316                lastOutputSeconds = false;
    317            }
    318            //as soon as we hit first nonliteral in optional, check for literal prefix
    319            if (inOptional && !isLiteral && !firstOptionalNonLiteral) {
    320                firstOptionalNonLiteral = true;
    321                if (lastOutputZero) {
    322                    buffer.delete(optionalStart, buffer.length());
    323                }
    324            }
    325        }
    326        return buffer.toString();
    327    }
    328
    329    /**
    330     * Formats the time gap as a string, using the specified format, and padding with zeros.
    331     *
    332     * <p>This method formats durations using the days and lower fields of the
    333     * format pattern. Months and larger are not used.</p>
    334     *
    335     * @param durationMillis  the duration to format
    336     * @param format  the way in which to format the duration, not null
    337     * @return the formatted duration, not null
    338     * @throws IllegalArgumentException if durationMillis is negative
    339     */
    340    public static String formatDuration(final long durationMillis, final String format) {
    341        return formatDuration(durationMillis, format, true);
    342    }
    343
    344    /**
    345     * Formats the time gap as a string, using the specified format.
    346     * Padding the left-hand side side of numbers with zeroes is optional.
    347     *
    348     * <p>This method formats durations using the days and lower fields of the
    349     * format pattern. Months and larger are not used.</p>
    350     *
    351     * @param durationMillis  the duration to format
    352     * @param format  the way in which to format the duration, not null
    353     * @param padWithZeros  whether to pad the left-hand side side of numbers with 0's
    354     * @return the formatted duration, not null
    355     * @throws IllegalArgumentException if durationMillis is negative
    356     */
    357    public static String formatDuration(final long durationMillis, final String format, final boolean padWithZeros) {
    358        Validate.inclusiveBetween(0, Long.MAX_VALUE, durationMillis, "durationMillis must not be negative");
    359
    360        final Token[] tokens = lexx(format);
    361
    362        long days = 0;
    363        long hours = 0;
    364        long minutes = 0;
    365        long seconds = 0;
    366        long milliseconds = durationMillis;
    367
    368        if (Token.containsTokenWithValue(tokens, d)) {
    369            days = milliseconds / DateUtils.MILLIS_PER_DAY;
    370            milliseconds -= days * DateUtils.MILLIS_PER_DAY;
    371        }
    372        if (Token.containsTokenWithValue(tokens, H)) {
    373            hours = milliseconds / DateUtils.MILLIS_PER_HOUR;
    374            milliseconds -= hours * DateUtils.MILLIS_PER_HOUR;
    375        }
    376        if (Token.containsTokenWithValue(tokens, m)) {
    377            minutes = milliseconds / DateUtils.MILLIS_PER_MINUTE;
    378            milliseconds -= minutes * DateUtils.MILLIS_PER_MINUTE;
    379        }
    380        if (Token.containsTokenWithValue(tokens, s)) {
    381            seconds = milliseconds / DateUtils.MILLIS_PER_SECOND;
    382            milliseconds -= seconds * DateUtils.MILLIS_PER_SECOND;
    383        }
    384
    385        return format(tokens, 0, 0, days, hours, minutes, seconds, milliseconds, padWithZeros);
    386    }
    387
    388    /**
    389     * Formats the time gap as a string.
    390     *
    391     * <p>The format used is ISO 8601-like: {@code HH:mm:ss.SSS}.</p>
    392     *
    393     * @param durationMillis  the duration to format
    394     * @return the formatted duration, not null
    395     * @throws IllegalArgumentException if durationMillis is negative
    396     */
    397    public static String formatDurationHMS(final long durationMillis) {
    398        return formatDuration(durationMillis, "HH:mm:ss.SSS");
    399    }
    400
    401    /**
    402     * Formats the time gap as a string.
    403     *
    404     * <p>The format used is the ISO 8601 period format.</p>
    405     *
    406     * <p>This method formats durations using the days and lower fields of the
    407     * ISO format pattern, such as P7D6TH5M4.321S.</p>
    408     *
    409     * @param durationMillis  the duration to format
    410     * @return the formatted duration, not null
    411     * @throws IllegalArgumentException if durationMillis is negative
    412     */
    413    public static String formatDurationISO(final long durationMillis) {
    414        return formatDuration(durationMillis, ISO_EXTENDED_FORMAT_PATTERN, false);
    415    }
    416
    417    /**
    418     * Formats an elapsed time into a pluralization correct string.
    419     *
    420     * <p>This method formats durations using the days and lower fields of the
    421     * format pattern. Months and larger are not used.</p>
    422     *
    423     * @param durationMillis  the elapsed time to report in milliseconds
    424     * @param suppressLeadingZeroElements  suppresses leading 0 elements
    425     * @param suppressTrailingZeroElements  suppresses trailing 0 elements
    426     * @return the formatted text in days/hours/minutes/seconds, not null
    427     * @throws IllegalArgumentException if durationMillis is negative
    428     */
    429    public static String formatDurationWords(
    430        final long durationMillis,
    431        final boolean suppressLeadingZeroElements,
    432        final boolean suppressTrailingZeroElements) {
    433
    434        // This method is generally replaceable by the format method, but
    435        // there are a series of tweaks and special cases that require
    436        // trickery to replicate.
    437        String duration = formatDuration(durationMillis, "d' days 'H' hours 'm' minutes 's' seconds'");
    438        if (suppressLeadingZeroElements) {
    439            // this is a temporary marker on the front. Like ^ in regexp.
    440            duration = " " + duration;
    441            String tmp = StringUtils.replaceOnce(duration, " 0 days", StringUtils.EMPTY);
    442            if (tmp.length() != duration.length()) {
    443                duration = tmp;
    444                tmp = StringUtils.replaceOnce(duration, " 0 hours", StringUtils.EMPTY);
    445                if (tmp.length() != duration.length()) {
    446                    duration = tmp;
    447                    tmp = StringUtils.replaceOnce(duration, " 0 minutes", StringUtils.EMPTY);
    448                    duration = tmp;
    449                }
    450            }
    451            if (!duration.isEmpty()) {
    452                // strip the space off again
    453                duration = duration.substring(1);
    454            }
    455        }
    456        if (suppressTrailingZeroElements) {
    457            String tmp = StringUtils.replaceOnce(duration, " 0 seconds", StringUtils.EMPTY);
    458            if (tmp.length() != duration.length()) {
    459                duration = tmp;
    460                tmp = StringUtils.replaceOnce(duration, " 0 minutes", StringUtils.EMPTY);
    461                if (tmp.length() != duration.length()) {
    462                    duration = tmp;
    463                    tmp = StringUtils.replaceOnce(duration, " 0 hours", StringUtils.EMPTY);
    464                    if (tmp.length() != duration.length()) {
    465                        duration = StringUtils.replaceOnce(tmp, " 0 days", StringUtils.EMPTY);
    466                    }
    467                }
    468            }
    469        }
    470        // handle plurals
    471        duration = " " + duration;
    472        duration = StringUtils.replaceOnce(duration, " 1 seconds", " 1 second");
    473        duration = StringUtils.replaceOnce(duration, " 1 minutes", " 1 minute");
    474        duration = StringUtils.replaceOnce(duration, " 1 hours", " 1 hour");
    475        duration = StringUtils.replaceOnce(duration, " 1 days", " 1 day");
    476        return duration.trim();
    477    }
    478
    479    /**
    480     * Formats the time gap as a string, using the specified format.
    481     * Padding the left-hand side side of numbers with zeroes is optional.
    482     *
    483     * @param startMillis  the start of the duration
    484     * @param endMillis  the end of the duration
    485     * @param format  the way in which to format the duration, not null
    486     * @return the formatted duration, not null
    487     * @throws IllegalArgumentException if startMillis is greater than endMillis
    488     */
    489    public static String formatPeriod(final long startMillis, final long endMillis, final String format) {
    490        return formatPeriod(startMillis, endMillis, format, true, TimeZone.getDefault());
    491    }
    492
    493    /**
    494     * <p>Formats the time gap as a string, using the specified format.
    495     * Padding the left-hand side side of numbers with zeroes is optional and
    496     * the time zone may be specified.
    497     *
    498     * <p>When calculating the difference between months/days, it chooses to
    499     * calculate months first. So when working out the number of months and
    500     * days between January 15th and March 10th, it choose 1 month and
    501     * 23 days gained by choosing January-&gt;February = 1 month and then
    502     * calculating days forwards, and not the 1 month and 26 days gained by
    503     * choosing March -&gt; February = 1 month and then calculating days
    504     * backwards.</p>
    505     *
    506     * <p>For more control, the <a href="https://www.joda.org/joda-time/">Joda-Time</a>
    507     * library is recommended.</p>
    508     *
    509     * @param startMillis  the start of the duration
    510     * @param endMillis  the end of the duration
    511     * @param format  the way in which to format the duration, not null
    512     * @param padWithZeros  whether to pad the left-hand side side of numbers with 0's
    513     * @param timezone  the millis are defined in
    514     * @return the formatted duration, not null
    515     * @throws IllegalArgumentException if startMillis is greater than endMillis
    516     */
    517    public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros,
    518            final TimeZone timezone) {
    519        Validate.isTrue(startMillis <= endMillis, "startMillis must not be greater than endMillis");
    520
    521        // Used to optimize for differences under 28 days and
    522        // called formatDuration(millis, format); however this did not work
    523        // over leap years.
    524        // TODO: Compare performance to see if anything was lost by
    525        // losing this optimization.
    526
    527        final Token[] tokens = lexx(format);
    528
    529        // time zones get funky around 0, so normalizing everything to GMT
    530        // stops the hours being off
    531        final Calendar start = Calendar.getInstance(timezone);
    532        start.setTime(new Date(startMillis));
    533        final Calendar end = Calendar.getInstance(timezone);
    534        end.setTime(new Date(endMillis));
    535
    536        // initial estimates
    537        long milliseconds = end.get(Calendar.MILLISECOND) - start.get(Calendar.MILLISECOND);
    538        int seconds = end.get(Calendar.SECOND) - start.get(Calendar.SECOND);
    539        int minutes = end.get(Calendar.MINUTE) - start.get(Calendar.MINUTE);
    540        int hours = end.get(Calendar.HOUR_OF_DAY) - start.get(Calendar.HOUR_OF_DAY);
    541        int days = end.get(Calendar.DAY_OF_MONTH) - start.get(Calendar.DAY_OF_MONTH);
    542        int months = end.get(Calendar.MONTH) - start.get(Calendar.MONTH);
    543        int years = end.get(Calendar.YEAR) - start.get(Calendar.YEAR);
    544
    545        // each initial estimate is adjusted in case it is under 0
    546        while (milliseconds < 0) {
    547            milliseconds += DateUtils.MILLIS_PER_SECOND;
    548            seconds -= 1;
    549        }
    550        while (seconds < 0) {
    551            seconds += SECONDS_PER_MINUTES;
    552            minutes -= 1;
    553        }
    554        while (minutes < 0) {
    555            minutes += MINUTES_PER_HOUR;
    556            hours -= 1;
    557        }
    558        while (hours < 0) {
    559            hours += HOURS_PER_DAY;
    560            days -= 1;
    561        }
    562
    563        if (Token.containsTokenWithValue(tokens, M)) {
    564            while (days < 0) {
    565                days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
    566                months -= 1;
    567                start.add(Calendar.MONTH, 1);
    568            }
    569
    570            while (months < 0) {
    571                months += 12;
    572                years -= 1;
    573            }
    574
    575            if (!Token.containsTokenWithValue(tokens, y) && years != 0) {
    576                while (years != 0) {
    577                    months += 12 * years;
    578                    years = 0;
    579                }
    580            }
    581        } else {
    582            // there are no M's in the format string
    583
    584            if (!Token.containsTokenWithValue(tokens, y)) {
    585                int target = end.get(Calendar.YEAR);
    586                if (months < 0) {
    587                    // target is end-year -1
    588                    target -= 1;
    589                }
    590
    591                while (start.get(Calendar.YEAR) != target) {
    592                    days += start.getActualMaximum(Calendar.DAY_OF_YEAR) - start.get(Calendar.DAY_OF_YEAR);
    593
    594                    // Not sure I grok why this is needed, but the brutal tests show it is
    595                    if (start instanceof GregorianCalendar &&
    596                            start.get(Calendar.MONTH) == Calendar.FEBRUARY &&
    597                            start.get(Calendar.DAY_OF_MONTH) == 29) {
    598                        days += 1;
    599                    }
    600
    601                    start.add(Calendar.YEAR, 1);
    602
    603                    days += start.get(Calendar.DAY_OF_YEAR);
    604                }
    605
    606                years = 0;
    607            }
    608
    609            while (start.get(Calendar.MONTH) != end.get(Calendar.MONTH)) {
    610                days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
    611                start.add(Calendar.MONTH, 1);
    612            }
    613
    614            months = 0;
    615
    616            while (days < 0) {
    617                days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
    618                months -= 1;
    619                start.add(Calendar.MONTH, 1);
    620            }
    621
    622        }
    623
    624        // The rest of this code adds in values that
    625        // aren't requested. This allows the user to ask for the
    626        // number of months and get the real count and not just 0->11.
    627
    628        if (!Token.containsTokenWithValue(tokens, d)) {
    629            hours += HOURS_PER_DAY * days;
    630            days = 0;
    631        }
    632        if (!Token.containsTokenWithValue(tokens, H)) {
    633            minutes += MINUTES_PER_HOUR * hours;
    634            hours = 0;
    635        }
    636        if (!Token.containsTokenWithValue(tokens, m)) {
    637            seconds += SECONDS_PER_MINUTES * minutes;
    638            minutes = 0;
    639        }
    640        if (!Token.containsTokenWithValue(tokens, s)) {
    641            milliseconds += DateUtils.MILLIS_PER_SECOND * seconds;
    642            seconds = 0;
    643        }
    644
    645        return format(tokens, years, months, days, hours, minutes, seconds, milliseconds, padWithZeros);
    646    }
    647
    648    /**
    649     * Formats the time gap as a string.
    650     *
    651     * <p>The format used is the ISO 8601 period format.</p>
    652     *
    653     * @param startMillis  the start of the duration to format
    654     * @param endMillis  the end of the duration to format
    655     * @return the formatted duration, not null
    656     * @throws IllegalArgumentException if startMillis is greater than endMillis
    657     */
    658    public static String formatPeriodISO(final long startMillis, final long endMillis) {
    659        return formatPeriod(startMillis, endMillis, ISO_EXTENDED_FORMAT_PATTERN, false, TimeZone.getDefault());
    660    }
    661
    662    /**
    663     * Parses a classic date format string into Tokens
    664     *
    665     * @param format  the format to parse, not null
    666     * @return array of Token[]
    667     */
    668    static Token[] lexx(final String format) {
    669        final ArrayList<Token> list = new ArrayList<>(format.length());
    670
    671        boolean inLiteral = false;
    672        // Although the buffer is stored in a Token, the Tokens are only
    673        // used internally, so cannot be accessed by other threads
    674        StringBuilder buffer = null;
    675        Token previous = null;
    676        boolean inOptional = false;
    677        int optionalIndex = -1;
    678        for (int i = 0; i < format.length(); i++) {
    679            final char ch = format.charAt(i);
    680            if (inLiteral && ch != '\'') {
    681                buffer.append(ch); // buffer can't be null if inLiteral is true
    682                continue;
    683            }
    684            String value = null;
    685            switch (ch) {
    686            // TODO: Need to handle escaping of '
    687            case '[':
    688                if (inOptional) {
    689                    throw new IllegalArgumentException("Nested optional block at index: " + i);
    690                }
    691                optionalIndex++;
    692                inOptional = true;
    693                break;
    694            case ']':
    695                if (!inOptional) {
    696                    throw new IllegalArgumentException("Attempting to close unopened optional block at index: " + i);
    697                }
    698                inOptional = false;
    699                break;
    700            case '\'':
    701                if (inLiteral) {
    702                    buffer = null;
    703                    inLiteral = false;
    704                } else {
    705                    buffer = new StringBuilder();
    706                    list.add(new Token(buffer, inOptional, optionalIndex));
    707                    inLiteral = true;
    708                }
    709                break;
    710            case 'y':
    711                value = y;
    712                break;
    713            case 'M':
    714                value = M;
    715                break;
    716            case 'd':
    717                value = d;
    718                break;
    719            case 'H':
    720                value = H;
    721                break;
    722            case 'm':
    723                value = m;
    724                break;
    725            case 's':
    726                value = s;
    727                break;
    728            case 'S':
    729                value = S;
    730                break;
    731            default:
    732                if (buffer == null) {
    733                    buffer = new StringBuilder();
    734                    list.add(new Token(buffer, inOptional, optionalIndex));
    735                }
    736                buffer.append(ch);
    737            }
    738
    739            if (value != null) {
    740                if (previous != null && previous.getValue().equals(value)) {
    741                    previous.increment();
    742                } else {
    743                    final Token token = new Token(value, inOptional, optionalIndex);
    744                    list.add(token);
    745                    previous = token;
    746                }
    747                buffer = null;
    748            }
    749        }
    750        if (inLiteral) { // i.e. we have not found the end of the literal
    751            throw new IllegalArgumentException("Unmatched quote in format: " + format);
    752        }
    753        if (inOptional) { // i.e. we have not found the end of the literal
    754            throw new IllegalArgumentException("Unmatched optional in format: " + format);
    755        }
    756        return list.toArray(Token.EMPTY_ARRAY);
    757    }
    758
    759    /**
    760     * Converts a {@code long} to a {@link String} with optional
    761     * zero padding.
    762     *
    763     * @param value the value to convert
    764     * @param padWithZeros whether to pad with zeroes
    765     * @param count the size to pad to (ignored if {@code padWithZeros} is false)
    766     * @return the string result
    767     */
    768    private static String paddedValue(final long value, final boolean padWithZeros, final int count) {
    769        final String longString = Long.toString(value);
    770        return padWithZeros ? StringUtils.leftPad(longString, count, '0') : longString;
    771    }
    772
    773    /**
    774     * DurationFormatUtils instances should NOT be constructed in standard programming.
    775     *
    776     * <p>This constructor is public to permit tools that require a JavaBean instance
    777     * to operate.</p>
    778     *
    779     * @deprecated TODO Make private in 4.0.
    780     */
    781    @Deprecated
    782    public DurationFormatUtils() {
    783        // empty
    784    }
    785
    786}