Humanize for Java

Humanize is a Java facility for adding a “human touch” to data. It is thread-safe and supports per-thread internationalization.

The main modules are provided in two complementary variants:

humanize-slim

Lightweight distribution that only depends on Guava and standard Java APIs.

humanize-icu

Provides a concise facade for access to the International Components for Unicode (ICU) Java APIs. Includes the slim distribution.

Extensions

Unified Emoji — Easy Emoji handling for the JVM
Joda time — Joda time message format extensions
UCUM — Unified Units of Measurement
JSF — Java Server Faces converters
Taglib — JSP tag library

Getting Started

Maven

Current version:

<humanize.version>1.2.2</humanize.version>

Slim distribution:

<dependency>
  <groupId>com.github.mfornos</groupId>
  <artifactId>humanize-slim</artifactId>
  <version>${humanize.version}</version>
</dependency>

Full-fledged ICU distribution:

<dependency>
  <groupId>com.github.mfornos</groupId>
  <artifactId>humanize-icu</artifactId>
  <version>${humanize.version}</version>
</dependency>

Usage

Using Humanize is quite simple.

Import the static methods of the Humanize class that you want to call.
Invoke these methods.

import static humanize.Humanize.binaryPrefix;

class SomeClass {

  void doSomething() {

    String size = binaryPrefix(1325899906842624L); // 1.18 PB

  }

}

Principal Methods

Date&Time

| Method | Description | Output | Slim | ICU | |------------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|------|-----| | naturalDay | For dates that are the current day or within one day, return ‘today’,‘tomorrow’ or ‘yesterday’, as appropriate. | ‘today’, ‘tomorrow’, ‘yesterday’ or the date formatted | ✔ | ✔ | | naturalTime | Computes both past and future relative dates with optional precision. | ‘2 days from now’, ‘3 decades ago’, ‘3 days 16 hours from now’, ‘3 minutes from now’, ‘3 days 15 hours 38 minutes ago’, ‘moments ago’, etc. | ✔ | ✔ | | nanoTime | Formats a number of nanoseconds as the proper ten power unit. | ‘1.5µs’, ‘10.51ms’, ‘30ns’, etc. | ✔ | - | | duration | Formats a number of seconds as hours, minutes and seconds. | ‘1 sec.’, ‘1:02:10’, etc. | ✔ | ✔ | | smartDateFormat | Guesses the best locale-dependent pattern to format the date/time fields that the skeleton specifies. | skeleton ‘MMMd’ produces ‘11 Dec.’ | - | ✔ | | prettyTimeFormat | Returns a PrettyTime instance for the current thread. | - | ✔ | - |

Frequencies

| Method | Description | Output | Slim | ICU | |------------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|------|-----| | times | Interprets numbers as occurrences. | ‘never’, ‘once’, ‘5 times’, etc. | ✔ | - | | paceFormat | Matches a pace (value and interval) with a logical time frame. Very useful for slow paces. e.g. heartbeats, ingested calories, hyperglycemic crises. | ‘Approximately 7 times per day.’ | ✔ | - |

Numbers

| Method | Description | Output | Slim | ICU | |----------------|-------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------|-----| | compactDecimal | Abbreviates numbers with short and long styles according to CLDR. | ‘2,4 Mio’, ‘100K’, ‘1M’, ‘2 millones’, ‘100 Tsd’, ‘100 Millionen’, etc. | - | ✔ | | ordinal | Converts a number to its ordinal as a string. | ‘1st’, ‘2nd’, ‘3rd’, etc. | ✔ | ✔ | | spellBigNumber | Converts a big number to a friendly text representation. | ‘2.3 thousand’, ‘1 million’, ‘–1.55 billion’, ‘3 decillion’, ‘2 googol’, etc. | ✔ | - | | spellDigit | For decimal digits, returns the number spelled out. | ‘one’, ‘two’, ‘three’, etc. | ✔ | - | | spellNumber | Converts the given number to words. | ‘twenty-three’, ‘two thousand eight hundred and forty’, ‘one million four hundred and twelve thousand six hundred and five’, etc. | - | ✔ |

Units

| Method | Description | Output | Slim | ICU | |----------------------|---------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|------|-----| | binaryPrefix | Converts a given number to a string preceded by the corresponding binary International System of Units (SI) prefix. | ‘2 bytes’, ‘1.5 KB’, ‘5 MB’, ‘1.18 PB’, etc. | ✔ | - | | metricPrefix | Converts a given number to a string preceded by the corresponding decimal multiplicative prefix. | ‘100k’, ‘1M’, ‘3.5M’, etc. | ✔ | - | | formatCurrency | Smartly formats the given number as a monetary amount. | ‘£34’, ‘£1,000’, ‘£12.50’, etc. | ✔ | ✔ | | formatPluralCurrency | Smartly formats the given number as a monetary amount in plural form. | ‘34 British pounds sterling’, ‘1,500.55 British pounds sterling’, ‘1 euro’, etc. | - | ✔ | | formatPercent | Formats the given ratio as a percentage. | ‘500%’, ‘56%’, etc. | ✔ | ✔ |

Humanize

Install / Use

README