net.time4j

Class PrettyTime

java.lang.Object

net.time4j.PrettyTime

public final class PrettyTime
extends Object

Enables formatted output as usually used in social media in different languages.

Parsing is not included because there is no general solution for all locales. Instead users must keep the backing duration object and use it for printing.

Since:

1.2

Author:

Meno Hochschild

Method Summary

Methods

Modifier and Type	Method and Description
Locale	getLocale() Gets the language of this instance.
TimeSource<?>	getReferenceClock() Yields the reference clock for formatting of relative times.
static PrettyTime	of(Locale locale) Gets an instance of PrettyTime for given language, possibly cached.
String	print(Duration<?> duration, TextWidth width) Formats the total given duration.
String	print(Duration<?> duration, TextWidth width, boolean printZero, int maxLength) Formats given duration.
String	print(long amount, CalendarUnit unit, TextWidth width) Formats given duration in calendar units.
String	print(long amount, ClockUnit unit, TextWidth width) Formats given duration in clock units.
String	printRelative(UnixTime moment, String tzid) Formats given time point relative to the current time of getReferenceClock() as duration in at most second precision or less.
String	printRelative(UnixTime moment, TZID tzid) Formats given time point relative to the current time of getReferenceClock() as duration in at most second precision or less.
PrettyTime	withEmptyUnit(CalendarUnit emptyUnit) Defines the time unit used for formatting an empty duration.
PrettyTime	withEmptyUnit(ClockUnit emptyUnit) Defines the time unit used for formatting an empty duration.
PrettyTime	withReferenceClock(TimeSource<?> clock) Yields a changed copy of this instance with given reference clock.
PrettyTime	withWeeksToDays() Determines that weeks will always be normalized to days.
PrettyTime	withZeroDigit(char zeroDigit) Defines the localized zero digit.

Methods inherited from class java.lang.Object

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

Method Detail

of

public static PrettyTime of(Locale locale)

Gets an instance of PrettyTime for given language, possibly cached.

Parameters:

locale - the language an instance is searched for

Returns:

pretty time object for formatting durations or relative time

Since:

1.2

getLocale

public Locale getLocale()

Gets the language of this instance.

Returns:

language

Since:

1.2

getReferenceClock

public TimeSource<?> getReferenceClock()

Yields the reference clock for formatting of relative times.

Returns:

reference clock or system clock if not yet specified

Since:

1.2

See Also:

withReferenceClock(TimeSource), printRelative(UnixTime, TZID), printRelative(UnixTime, String)

withReferenceClock

public PrettyTime withReferenceClock(TimeSource<?> clock)

Yields a changed copy of this instance with given reference clock.

Parameters:

clock - new reference clock

Returns:

new instance of PrettyTime with changed reference clock

Since:

1.2

See Also:

getReferenceClock(), printRelative(UnixTime, TZID), printRelative(UnixTime, String)

withZeroDigit

public PrettyTime withZeroDigit(char zeroDigit)

Defines the localized zero digit.

In most languages the zero digit is just ASCII-"0", but in arabic locales the digit can also be the char U+0660. By default Time4J will try to use the JDK-setting. This method can override it however.

Parameters:

zeroDigit - localized zero digit

Returns:

changed copy of this instance

Since:

1.2

See Also:

DecimalFormatSymbols.getZeroDigit()

withEmptyUnit

public PrettyTime withEmptyUnit(CalendarUnit emptyUnit)

Defines the time unit used for formatting an empty duration.

Time4J uses seconds as default. This method can override the default however.

Parameters:

emptyUnit - time unit for usage in an empty duration

Returns:

changed copy of this instance

Since:

1.2

See Also:

print(Duration, TextWidth)

withEmptyUnit

public PrettyTime withEmptyUnit(ClockUnit emptyUnit)

Defines the time unit used for formatting an empty duration.

Time4J uses seconds as default. This method can override the default however.

Parameters:

emptyUnit - time unit for usage in an empty duration

Returns:

changed copy of this instance

Since:

1.2

See Also:

print(Duration, TextWidth)

withWeeksToDays

public PrettyTime withWeeksToDays()

Determines that weeks will always be normalized to days.

Returns:

changed copy of this instance

Since:

2.0

print

public String print(long amount,
           CalendarUnit unit,
           TextWidth width)

Formats given duration in calendar units.

Note: Millennia, centuries and decades are automatically normalized to years while quarter-years are normalized to months.

Parameters:

amount - count of units (quantity)

unit - calendar unit

width - text width (ABBREVIATED as synonym for SHORT)

Returns:

formatted output

Since:

1.2

See Also:

print(Duration, TextWidth)

print

public String print(long amount,
           ClockUnit unit,
           TextWidth width)

Formats given duration in clock units.

Parameters:

amount - count of units (quantity)

unit - clock unit

width - text width (ABBREVIATED as synonym for SHORT)

Returns:

formatted output

Since:

1.2

See Also:

print(Duration, TextWidth)

print

public String print(Duration<?> duration,
           TextWidth width)

Formats the total given duration.

A localized output is only supported for the units CalendarUnit.YEARS, CalendarUnit.MONTHS, CalendarUnit.WEEKS, CalendarUnit.DAYS and all ClockUnit-units. This method performs an internal normalization if any other unit is involved.

Note: If the local script variant is from right to left then a unicode-RLM-marker will automatically be inserted before each number.

Parameters:

duration - object representing a duration which might contain several units and quantities

width - text width (ABBREVIATED as synonym for SHORT)

Returns:

formatted list output

Since:

1.2

print

public String print(Duration<?> duration,
           TextWidth width,
           boolean printZero,
           int maxLength)

Formats given duration.

Like print(Duration, TextWidth), but offers the option to limit the count of displayed duration items and also to print items with zero amount. The first printed duration item has always a non-zero amount however. Example:

  Duration<?> dur =
      Duration.ofZero().plus(1, DAYS).plus(4, ClockUnit.MINUTES);
  System.out.println(
      PrettyTime.of(Locale.FRANCE).print(dur, TextWidth.WIDE, true, 3));
  // output: 1 jour, 0 heure et 4 minutes
 

Parameters:

duration - object representing a duration which might contain several units and quantities

width - text width (ABBREVIATED as synonym for SHORT)

printZero - determines if zero amounts shall be printed, too

maxLength - maximum count of displayed items

Returns:

formatted list output

Throws:

IllegalArgumentException - if maxLength is smaller than 1

Since:

2.0

printRelative

public String printRelative(UnixTime moment,
                   TZID tzid)

Formats given time point relative to the current time of getReferenceClock() as duration in at most second precision or less.

Parameters:

moment - relative time point

tzid - time zone id for translating to a local duration

Returns:

formatted output of relative time, either in past or in future

Since:

1.2

printRelative

public String printRelative(UnixTime moment,
                   String tzid)

Formats given time point relative to the current time of getReferenceClock() as duration in at most second precision or less.

Parameters:

moment - relative time point

tzid - time zone id for translating to a local duration

Returns:

formatted output of relative time, either in past or in future

Since:

1.2