|
FastDateFormat
and SimpleDateFormat
* for the ISO 8601 period format used in durations.</p>
*
* @see org.apache.commons.lang3.time.FastDateFormat
* @see java.text.SimpleDateFormat
*/
public static final String ISO_EXTENDED_FORMAT_PATTERN = "'P'yyyy'Y'M'M'd'DT'H'H'm'M's.SSS'S'";
//-----------------------------------------------------------------------
/**
* <p>Formats the time gap as a string.
*
* <p>The format used is ISO 8601-like: {@code HH:mm:ss.SSS}.
*
* @param durationMillis the duration to format
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if durationMillis is negative
*/
public static String formatDurationHMS(final long durationMillis) {
return formatDuration(durationMillis, "HH:mm:ss.SSS");
}
/**
* <p>Formats the time gap as a string.
*
* <p>The format used is the ISO 8601 period format.
*
* <p>This method formats durations using the days and lower fields of the
* ISO format pattern, such as P7D6TH5M4.321S.</p>
*
* @param durationMillis the duration to format
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if durationMillis is negative
*/
public static String formatDurationISO(final long durationMillis) {
return formatDuration(durationMillis, ISO_EXTENDED_FORMAT_PATTERN, false);
}
/**
* <p>Formats the time gap as a string, using the specified format, and padding with zeros.
*
* <p>This method formats durations using the days and lower fields of the
* format pattern. Months and larger are not used.</p>
*
* @param durationMillis the duration to format
* @param format the way in which to format the duration, not null
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if durationMillis is negative
*/
public static String formatDuration(final long durationMillis, final String format) {
return formatDuration(durationMillis, format, true);
}
/**
* <p>Formats the time gap as a string, using the specified format.
* Padding the left hand side of numbers with zeroes is optional.</p>
*
* <p>This method formats durations using the days and lower fields of the
* format pattern. Months and larger are not used.</p>
*
* @param durationMillis the duration to format
* @param format the way in which to format the duration, not null
* @param padWithZeros whether to pad the left hand side of numbers with 0's
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if durationMillis is negative
*/
public static String formatDuration(final long durationMillis, final String format, final boolean padWithZeros) {
Validate.inclusiveBetween(0, Long.MAX_VALUE, durationMillis, "durationMillis must not be negative");
final Token[] tokens = lexx(format);
long days = 0;
long hours = 0;
long minutes = 0;
long seconds = 0;
long milliseconds = durationMillis;
if (Token.containsTokenWithValue(tokens, d) ) {
days = milliseconds / DateUtils.MILLIS_PER_DAY;
milliseconds = milliseconds - (days * DateUtils.MILLIS_PER_DAY);
}
if (Token.containsTokenWithValue(tokens, H) ) {
hours = milliseconds / DateUtils.MILLIS_PER_HOUR;
milliseconds = milliseconds - (hours * DateUtils.MILLIS_PER_HOUR);
}
if (Token.containsTokenWithValue(tokens, m) ) {
minutes = milliseconds / DateUtils.MILLIS_PER_MINUTE;
milliseconds = milliseconds - (minutes * DateUtils.MILLIS_PER_MINUTE);
}
if (Token.containsTokenWithValue(tokens, s) ) {
seconds = milliseconds / DateUtils.MILLIS_PER_SECOND;
milliseconds = milliseconds - (seconds * DateUtils.MILLIS_PER_SECOND);
}
return format(tokens, 0, 0, days, hours, minutes, seconds, milliseconds, padWithZeros);
}
/**
* <p>Formats an elapsed time into a pluralization correct string.
*
* <p>This method formats durations using the days and lower fields of the
* format pattern. Months and larger are not used.</p>
*
* @param durationMillis the elapsed time to report in milliseconds
* @param suppressLeadingZeroElements suppresses leading 0 elements
* @param suppressTrailingZeroElements suppresses trailing 0 elements
* @return the formatted text in days/hours/minutes/seconds, not null
* @throws java.lang.IllegalArgumentException if durationMillis is negative
*/
public static String formatDurationWords(
final long durationMillis,
final boolean suppressLeadingZeroElements,
final boolean suppressTrailingZeroElements) {
// This method is generally replaceable by the format method, but
// there are a series of tweaks and special cases that require
// trickery to replicate.
String duration = formatDuration(durationMillis, "d' days 'H' hours 'm' minutes 's' seconds'");
if (suppressLeadingZeroElements) {
// this is a temporary marker on the front. Like ^ in regexp.
duration = " " + duration;
String tmp = StringUtils.replaceOnce(duration, " 0 days", StringUtils.EMPTY);
if (tmp.length() != duration.length()) {
duration = tmp;
tmp = StringUtils.replaceOnce(duration, " 0 hours", StringUtils.EMPTY);
if (tmp.length() != duration.length()) {
duration = tmp;
tmp = StringUtils.replaceOnce(duration, " 0 minutes", StringUtils.EMPTY);
duration = tmp;
if (tmp.length() != duration.length()) {
duration = StringUtils.replaceOnce(tmp, " 0 seconds", StringUtils.EMPTY);
}
}
}
if (duration.length() != 0) {
// strip the space off again
duration = duration.substring(1);
}
}
if (suppressTrailingZeroElements) {
String tmp = StringUtils.replaceOnce(duration, " 0 seconds", StringUtils.EMPTY);
if (tmp.length() != duration.length()) {
duration = tmp;
tmp = StringUtils.replaceOnce(duration, " 0 minutes", StringUtils.EMPTY);
if (tmp.length() != duration.length()) {
duration = tmp;
tmp = StringUtils.replaceOnce(duration, " 0 hours", StringUtils.EMPTY);
if (tmp.length() != duration.length()) {
duration = StringUtils.replaceOnce(tmp, " 0 days", StringUtils.EMPTY);
}
}
}
}
// handle plurals
duration = " " + duration;
duration = StringUtils.replaceOnce(duration, " 1 seconds", " 1 second");
duration = StringUtils.replaceOnce(duration, " 1 minutes", " 1 minute");
duration = StringUtils.replaceOnce(duration, " 1 hours", " 1 hour");
duration = StringUtils.replaceOnce(duration, " 1 days", " 1 day");
return duration.trim();
}
//-----------------------------------------------------------------------
/**
* <p>Formats the time gap as a string.
*
* <p>The format used is the ISO 8601 period format.
*
* @param startMillis the start of the duration to format
* @param endMillis the end of the duration to format
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis
*/
public static String formatPeriodISO(final long startMillis, final long endMillis) {
return formatPeriod(startMillis, endMillis, ISO_EXTENDED_FORMAT_PATTERN, false, TimeZone.getDefault());
}
/**
* <p>Formats the time gap as a string, using the specified format.
* Padding the left hand side of numbers with zeroes is optional.
*
* @param startMillis the start of the duration
* @param endMillis the end of the duration
* @param format the way in which to format the duration, not null
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis
*/
public static String formatPeriod(final long startMillis, final long endMillis, final String format) {
return formatPeriod(startMillis, endMillis, format, true, TimeZone.getDefault());
}
/**
* <p>Formats the time gap as a string, using the specified format.
* Padding the left hand side of numbers with zeroes is optional and
* the timezone may be specified. </p>
*
* <p>When calculating the difference between months/days, it chooses to
* calculate months first. So when working out the number of months and
* days between January 15th and March 10th, it choose 1 month and
* 23 days gained by choosing January->February = 1 month and then
* calculating days forwards, and not the 1 month and 26 days gained by
* choosing March -> February = 1 month and then calculating days
* backwards. </p>
*
* <p>For more control, the Joda-Time
* library is recommended.</p>
*
* @param startMillis the start of the duration
* @param endMillis the end of the duration
* @param format the way in which to format the duration, not null
* @param padWithZeros whether to pad the left hand side of numbers with 0's
* @param timezone the millis are defined in
* @return the formatted duration, not null
* @throws java.lang.IllegalArgumentException if startMillis is greater than endMillis
*/
public static String formatPeriod(final long startMillis, final long endMillis, final String format, final boolean padWithZeros,
final TimeZone timezone) {
Validate.isTrue(startMillis <= endMillis, "startMillis must not be greater than endMillis");
// Used to optimise for differences under 28 days and
// called formatDuration(millis, format); however this did not work
// over leap years.
// TODO: Compare performance to see if anything was lost by
// losing this optimisation.
final Token[] tokens = lexx(format);
// timezones get funky around 0, so normalizing everything to GMT
// stops the hours being off
final Calendar start = Calendar.getInstance(timezone);
start.setTime(new Date(startMillis));
final Calendar end = Calendar.getInstance(timezone);
end.setTime(new Date(endMillis));
// initial estimates
int milliseconds = end.get(Calendar.MILLISECOND) - start.get(Calendar.MILLISECOND);
int seconds = end.get(Calendar.SECOND) - start.get(Calendar.SECOND);
int minutes = end.get(Calendar.MINUTE) - start.get(Calendar.MINUTE);
int hours = end.get(Calendar.HOUR_OF_DAY) - start.get(Calendar.HOUR_OF_DAY);
int days = end.get(Calendar.DAY_OF_MONTH) - start.get(Calendar.DAY_OF_MONTH);
int months = end.get(Calendar.MONTH) - start.get(Calendar.MONTH);
int years = end.get(Calendar.YEAR) - start.get(Calendar.YEAR);
// each initial estimate is adjusted in case it is under 0
while (milliseconds < 0) {
milliseconds += 1000;
seconds -= 1;
}
while (seconds < 0) {
seconds += 60;
minutes -= 1;
}
while (minutes < 0) {
minutes += 60;
hours -= 1;
}
while (hours < 0) {
hours += 24;
days -= 1;
}
if (Token.containsTokenWithValue(tokens, M)) {
while (days < 0) {
days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
months -= 1;
start.add(Calendar.MONTH, 1);
}
while (months < 0) {
months += 12;
years -= 1;
}
if (!Token.containsTokenWithValue(tokens, y) && years != 0) {
while (years != 0) {
months += 12 * years;
years = 0;
}
}
} else {
// there are no M's in the format string
if( !Token.containsTokenWithValue(tokens, y) ) {
int target = end.get(Calendar.YEAR);
if (months < 0) {
// target is end-year -1
target -= 1;
}
while (start.get(Calendar.YEAR) != target) {
days += start.getActualMaximum(Calendar.DAY_OF_YEAR) - start.get(Calendar.DAY_OF_YEAR);
// Not sure I grok why this is needed, but the brutal tests show it is
if (start instanceof GregorianCalendar &&
start.get(Calendar.MONTH) == Calendar.FEBRUARY &&
start.get(Calendar.DAY_OF_MONTH) == 29) {
days += 1;
}
start.add(Calendar.YEAR, 1);
days += start.get(Calendar.DAY_OF_YEAR);
}
years = 0;
}
while( start.get(Calendar.MONTH) != end.get(Calendar.MONTH) ) {
days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
start.add(Calendar.MONTH, 1);
}
months = 0;
while (days < 0) {
days += start.getActualMaximum(Calendar.DAY_OF_MONTH);
months -= 1;
start.add(Calendar.MONTH, 1);
}
}
// The rest of this code adds in values that
// aren't requested. This allows the user to ask for the
// number of months and get the real count and not just 0->11.
if (!Token.containsTokenWithValue(tokens, d)) {
hours += 24 * days;
days = 0;
}
if (!Token.containsTokenWithValue(tokens, H)) {
minutes += 60 * hours;
hours = 0;
}
if (!Token.containsTokenWithValue(tokens, m)) {
seconds += 60 * minutes;
minutes = 0;
}
if (!Token.containsTokenWithValue(tokens, s)) {
milliseconds += 1000 * seconds;
seconds = 0;
}
return format(tokens, years, months, days, hours, minutes, seconds, milliseconds, padWithZeros);
}
//-----------------------------------------------------------------------
/**
* <p>The internal method to do the formatting.
*
* @param tokens the tokens
* @param years the number of years
* @param months the number of months
* @param days the number of days
* @param hours the number of hours
* @param minutes the number of minutes
* @param seconds the number of seconds
* @param milliseconds the number of millis
* @param padWithZeros whether to pad
* @return the formatted string
*/
static String format(final Token[] tokens, final long years, final long months, final long days, final long hours, final long minutes, final long seconds,
final long milliseconds, final boolean padWithZeros) {
final StringBuilder buffer = new StringBuilder();
boolean lastOutputSeconds = false;
for (final Token token : tokens) {
final Object value = token.getValue();
final int count = token.getCount();
if (value instanceof StringBuilder) {
buffer.append(value.toString());
} else {
if (value.equals(y)) {
buffer.append(paddedValue(years, padWithZeros, count));
lastOutputSeconds = false;
} else if (value.equals(M)) {
buffer.append(paddedValue(months, padWithZeros, count));
lastOutputSeconds = false;
} else if (value.equals(d)) {
buffer.append(paddedValue(days, padWithZeros, count));
lastOutputSeconds = false;
} else if (value.equals(H)) {
buffer.append(paddedValue(hours, padWithZeros, count));
lastOutputSeconds = false;
} else if (value.equals(m)) {
buffer.append(paddedValue(minutes, padWithZeros, count));
lastOutputSeconds = false;
} else if (value.equals(s)) {
buffer.append(paddedValue(seconds, padWithZeros, count));
lastOutputSeconds = true;
} else if (value.equals(S)) {
if (lastOutputSeconds) {
// ensure at least 3 digits are displayed even if padding is not selected
final int width = padWithZeros ? Math.max(3, count) : 3;
buffer.append(paddedValue(milliseconds, true, width));
} else {
buffer.append(paddedValue(milliseconds, padWithZeros, count));
}
lastOutputSeconds = false;
}
}
}
return buffer.toString();
}
/**
* <p>Converts a {@code long} to a {@code String} with optional
* zero padding.</p>
*
* @param value the value to convert
* @param padWithZeros whether to pad with zeroes
* @param count the size to pad to (ignored if {@code padWithZeros} is false)
* @return the string result
*/
private static String paddedValue(final long value, final boolean padWithZeros, final int count) {
final String longString = Long.toString(value);
return padWithZeros ? StringUtils.leftPad(longString, count, '0') : longString;
}
static final Object y = "y";
static final Object M = "M";
static final Object d = "d";
static final Object H = "H";
static final Object m = "m";
static final Object s = "s";
static final Object S = "S";
/**
* Parses a classic date format string into Tokens
*
* @param format the format to parse, not null
* @return array of Token[]
*/
static Token[] lexx(final String format) {
final ArrayList<Token> list = new ArrayListHere is a short list of links related to this Java DurationFormatUtils.java source code file:
Java example source code file (DurationFormatUtils.java)
The DurationFormatUtils.java Java example source code/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.lang3.time; import java.util.ArrayList; import java.util.Calendar; import java.util.Date; import java.util.GregorianCalendar; import java.util.TimeZone; import org.apache.commons.lang3.StringUtils; import org.apache.commons.lang3.Validate; /** * <p>Duration formatting utilities and constants. The following table describes the tokens * used in the pattern language for formatting. </p> * <table border="1" summary="Pattern Tokens"> * <tr> | character | duration element | |
---|---|---|---|
y | years | ||
M | months | ||
d | days | ||
H | hours | ||
m | minutes | ||
s | seconds | ||
S | milliseconds | ||
'text' | arbitrary text content |
... this post is sponsored by my books ... | |
#1 New Release! |
FP Best Seller |
Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.
A percentage of advertising revenue from
pages under the /java/jwarehouse
URI on this website is
paid back to open source projects.