com.neeve.util

Class UtlUnit

java.lang.Object

com.neeve.util.UtlUnit

public class UtlUnit
extends Object

Utilities for unit conversion.

This class MAY BE used by end users, but is unsupported and is subject to change without notice.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	UtlUnit.ByteUnit Represents byte size unit.
static class	UtlUnit.Unit Enumerates the units handled by this class.

Constructor Summary

Constructors

Constructor and Description
UtlUnit()

Method Summary

Modifier and Type	Method and Description
static double	convertBytes(double size, UtlUnit.ByteUnit sourceUnit, UtlUnit.ByteUnit targetUnit) Converts a byte unit from one unit to another.
static double	convertDuration(double duration, TimeUnit sourceTimeUnit, TimeUnit targetTimeUnit) Converts a duration from one time unit to another.
static String	formatDuration(double duration, TimeUnit unit) Converts a duration to a human readable string.
static String	formatDuration(double duration, TimeUnit unit, int decimalPoints) Converts a duration to a human readable string.
static double	parseBytes(String size, UtlUnit.ByteUnit targetUnit) Parse a number of bytes and returns the resulting number of bytes in the specified target unit.
static double	parseBytes(String size, UtlUnit.ByteUnit defaultUnit, UtlUnit.ByteUnit targetUnit) Parse a number of bytes and returns the resulting number of bytes in the specified target unit.
static double	parseDuration(String duration, TimeUnit defaultUnit, TimeUnit targetUnit) Parse a time duration and returns the parsed value in the specified TimeUnit.
static String	readableBytesSize(long size) Returns a readable string for the given number of bytes.
static long	toNumBytes(String size) Converts a string to a number of bytes.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UtlUnit

public UtlUnit()

Method Detail

readableBytesSize

public static String readableBytesSize(long size)

Returns a readable string for the given number of bytes.

Parameters:

size - The size in bytes to convert.

Returns:

A readable string for the given number of bytes.

parseBytes

public static double parseBytes(String size,
                                UtlUnit.ByteUnit targetUnit)

Parse a number of bytes and returns the resulting number of bytes in the specified target unit.

This is equivalent to calling parseBytes(size, ByteUnit.Bytes, targetUnit)

Parameters:

size - The size to parse.

targetUnit - The target unit in which to return the result.

Returns:

The parsed result.

parseBytes

public static double parseBytes(String size,
                                UtlUnit.ByteUnit defaultUnit,
                                UtlUnit.ByteUnit targetUnit)

Parse a number of bytes and returns the resulting number of bytes in the specified target unit.

The input string is interpreted as a decimal byte size that can use comma separators for thousands optionally followed by whitespace and the unit of bytes that the unit of the byte size supplied.

Valid byte unit specifiers

The following table lists how byte units can be specified. When no byte unit is specified in the string to be parsed it is interpreted as the string representing a value in bytes.

Byte Unit	Aliases
"Bytes"	"Byte", "b"
"Kilobytes"	"kilobyte", "kb", "k"
"Megabytes"	"megabyte", "mb", "m"
"Gigabytes"	"gigabyte", "gb", "g"
"Terabytes"	"terabyte", "tb", "t"

Examples:

• parseBytes("1kb", Bytes.Bytes) would yield 1024.
• parseBytes(".5 megabytes", Bytes.Bytes) would yield 524288.
• parseBytes(".5 megabytes", Bytes.Megabytes) would yield .5.

Parameters:

size - The size in bytes in string form: #,###.# [byte unit]

defaultUnit - How to interpret the provided size when the string does not specify a unit.

targetUnit - The target unit in which to return the parsed result.

Returns:

The number of bytes.

convertBytes

public static double convertBytes(double size,
                                  UtlUnit.ByteUnit sourceUnit,
                                  UtlUnit.ByteUnit targetUnit)

Converts a byte unit from one unit to another.

Parameters:

size - The size to convert.

sourceUnit - The byte unit of the size to convert.

targetUnit - The target unit into which to convert the size.

Returns:

The converted value.

toNumBytes

public static long toNumBytes(String size)

Converts a string to a number of bytes.

This method is equivalent to calling (long) parseBytes(size, Bytes.Bytes).

Parameters:

size - The size in bytes in String form.

Returns:

The number of bytes.

parseDuration

public static final double parseDuration(String duration,
                                         TimeUnit defaultUnit,
                                         TimeUnit targetUnit)

Parse a time duration and returns the parsed value in the specified TimeUnit.

The input string is interpreted as a decimal duration length that can use comma separators for thousands that is followed by whitespace and the time unit that specifies the duration length.

Valid time unit specifiers

The following table lists how duration time units can be specified. When no time unit is specified in the string to be parsed the defaultUnit provided to this method is used. All duration aliases listed below are case insensitive except where noted.

Time Unit	Aliases
TimeUnit.DAYS	"d"†, "day", "days"
TimeUnit.HOURS	"h"†, "hour", "hours"
TimeUnit.MINUTES	"m"†, "minute", "minutes"
TimeUnit.SECONDS	"s"†, "second", "seconds"
TimeUnit.MILLISECONDS	"ms", "millisecond", "milliseconds"
TimeUnit.MICROSECONDS	"us", "microsecond", "microseconds"
TimeUnit.NANOSECONDS	"ns", "nanosecond", "nanoseconds"

† Case sensitive.

Examples:

• parseDuration("1s", TimeUnit.MILLISECONDS, TimeUnit.MILLISECONDS) would yield 1000.
• parseDuration("1", TimeUnit.MILLISECONDS, TimeUnit.MILLISECONDS) would yield 1.
• parseDuration("1", TimeUnit.SECONDS, TimeUnit.MILLISECONDS) would yield 1000.
• parseDuration(".5s", TimeUnit.SECONDS, TimeUnit.MILLISECONDS) would yield 500.

Parameters:

duration - The duration string in the form: #,###.# [duration unit]

defaultUnit - How to interpret the duration when the string does not specify a duration.

targetUnit - The duration unit to convert to on return.

Returns:

The parsed and converted duration

convertDuration

public static final double convertDuration(double duration,
                                           TimeUnit sourceTimeUnit,
                                           TimeUnit targetTimeUnit)

Converts a duration from one time unit to another.

For example, given an input time of 1.5, a source unit of DAYS and a target unit HOURS, this method would yield 36.

Parameters:

duration - The duration to format.

sourceTimeUnit - The time unit of the duration to convert.

targetTimeUnit - The time unit to convert to.

Returns:

The converted time.

formatDuration

public static final String formatDuration(double duration,
                                          TimeUnit unit)

Converts a duration to a human readable string.

The conversion displays the duration in the largest significant unit of days,hours,minutes,seconds,millis,micros, or nanos to 1 decimal point.

Parameters:

duration - The duration to format.

unit - The time unit of the duration.

Returns:

The formatted duration.

formatDuration

public static final String formatDuration(double duration,
                                          TimeUnit unit,
                                          int decimalPoints)

Converts a duration to a human readable string.

The conversion displays the duration in the largest significant unit of days,hours,minutes,seconds,millis,micros, or nanos to 1 decimal point.

Parameters:

duration - The duration to format.

unit - The time unit of the duration.

decimalPoints - The number the number of digits after the decimal separator (or 0 for no decimal digits). A value of < 0 will result in an IllegalArgumentException.

Returns:

The formatted duration.

Throws:

IllegalArgumentException - if the decimalPoints is less than 0.