Humanize for Java

Humanize is a Java facility for adding a “human touch” to data. It is thread-safe and supports per-thread internationalization. Additionally provides a concise facade for access to the standard internationalization Java APIs.

Getting Started

The project is not yet available in any public Maven repository, so you can fork it on Github or download the jar package from the project downloads section.

Runtime Dependencies

Humanize has no runtime dependencies besides JRE 1.6.

Usage

Using Humanize is dead simple. See the documentation (javadoc).

1. Import the static methods of Humanize class that you plan to call
2. Invoke the methods.

import static org.nikko.humanize.Humanize.binaryPrefix; 
 
 class SomeClass {
   void doSomething() {
     String size = binaryPrefix(1325899906842624L);
  }
}

Principal Methods

All methods support internationalization. The table listings shows outputs for en_GB locale as reference.

Date&Time

Method	Description	Output
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.	‘one day ago’, ‘one day from now’, ‘10 years ago’, ‘3 minutes from now’, ‘right now’, etc.

Numbers

Method	Description	Output
ordinalize	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.
toText	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
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.
formatPercent	Formats the given ratio as a percentage.	‘500%’, ‘56%’, etc.

Text

Method	Description	Output
pluralize	Constructs a message with pluralization logic by the means of ChoiceFormat. Supports templates.	–
camelize	Makes a phrase camel case. Spaces and underscores will be removed.	–
capitalize	Capitalizes a string (first letter uppercase and the rest lowercase).	–
decamelize	Converts a camel case string into a human-readable name.	–
titleize	Capitalize all the words, and replace some characters in the string to create a nice looking title.	–
wordWrap	Truncate a string to the closest word boundary after a number of characters.	–

Extensibility

NumberText

Language-dependent providers for number to text conversion.

You can plug your own NumberText provider implementations just dropping a jar in the classpath with the proper META-INF/services/nikko.humanize.spi.number.NumberText file.

Supported languages

Languages supported by the Java internationalization APIs.

Humanize nowadays, since it is in an early stage, only have translations for the following reference languages:

Common functions

• English (United Kingdom) [en_GB]
• English (United States) [en_US]
• Spanish (Spain) [es_ES]

Text to number

• Chinese (simplified) [zh_CN]
• Chinese (traditional) [zh_TW]
• English (United Kingdom) [en_GB]
• English (United States) [en_US]
• Spanish (Spain) [es_ES]

Examples

See src/test/.../HumanizeTest for examples.

Build Status

Epilog

Have fun and stay fresh!