Guava Utilities: Joiner, Splitter, CharMatcher, Charsets, CaseFormat, and Primitive Types

Joiner

Joiner simplifies concatenating a sequence of strings with a delimiter and handles null values gracefully. For example,

Joiner joiner = Joiner.on("; ").skipNulls(); return joiner.join("Harry", null, "Ron", "Hermione");

produces "Harry; Ron; Hermione". You can also replace nulls with a specific string using useForNull(String). Joiner works with objects by calling their toString() method. Note that Joiner instances are immutable and thread‑safe, so they can be defined as static final constants.

Joiner.on(",").join(Arrays.asList(1, 5, 7)); // returns "1,5,7"

Splitter

Splitter provides a fluent API to split strings while handling edge cases such as trailing delimiters. For the input ",a,,b,", String.split(",") returns ["", "a", "", "b", ""]. Using Guava:

Splitter.on(',')
        .trimResults()
        .omitEmptyStrings()
        .split("foo,bar,,   qux");

This returns an Iterable<String> containing "foo", "bar", and "qux". Splitter can be configured with characters, strings, regular expressions, or custom CharMatcher s. It also offers a factory table of methods such as Splitter.on(char), Splitter.on(CharMatcher), Splitter.on(String), Splitter.on(Pattern), and Splitter.fixedLength(int).

Splitter Modifiers

Method

Description

omitEmptyStrings()

Automatically ignore empty strings in the result.

trimResults()

Remove leading and trailing whitespace from each result.

trimResults(CharMatcher)

Remove characters matching the given matcher from the ends of each result.

limit(int)

Limit the number of split strings returned.

Splitter instances are also immutable and thread‑safe.

CharMatcher

CharMatcher represents a predicate over characters (e.g., digits, whitespace). It provides methods to trim, collapse, remove, retain, replace, and test characters. Example usages:

String noControl = CharMatcher.JAVA_ISO_CONTROL.removeFrom(string);
String theDigits = CharMatcher.DIGIT.retainFrom(string);
String spaced = CharMatcher.WHITESPACE.trimAndCollapseFrom(string, ' ');
String noDigits = CharMatcher.JAVA_DIGIT.replaceFrom(string, "*");
String lowerAndDigit = CharMatcher.JAVA_DIGIT.or(CharMatcher.JAVA_LOWER_CASE).retainFrom(string);

CharMatcher works only with char values and does not understand Unicode supplementary characters.

Obtaining CharMatchers

Constant

Description

ANY

Matches any character.

NONE

Matches no character.

WHITESPACE

Matches all whitespace characters.

BREAKING_WHITESPACE

Matches whitespace that can break lines.

INVISIBLE

Matches invisible characters.

DIGIT

Matches decimal digits.

JAVA_LETTER

Matches any Java letter.

JAVA_DIGIT

Matches any Java digit.

JAVA_LOWER_CASE

Matches lower‑case letters.

JAVA_UPPER_CASE

Matches upper‑case letters.

ASCII

Matches ASCII characters.

SINGLE_WIDTH

Matches single‑width characters.

Additional factory methods include anyOf(CharSequence), is(char), and inRange(char, char), as well as combinators negate(), and(CharMatcher), and or(CharMatcher).

Charsets

Instead of using string literals for charset names, use Guava's Charsets constants, e.g., bytes = string.getBytes(Charsets.UTF_8);. This avoids UnsupportedEncodingException and works on all Java platforms.

CaseFormat

CaseFormat converts strings between common ASCII naming conventions such as LOWER_CAMEL, LOWER_HYPHEN, LOWER_UNDERSCORE, UPPER_CAMEL, and UPPER_UNDERSCORE. Example:

CaseFormat.UPPER_UNDERSCORE.to(CaseFormat.LOWER_CAMEL, "CONSTANT_NAME"); // returns "constantName"

This is especially useful for code generators.

Primitive Types

Guava provides utility classes for all Java primitive types (byte, short, int, long, float, double, char, boolean) in the com.google.common.primitives package. Classes include Bytes, SignedBytes, UnsignedBytes, Shorts, Ints, UnsignedInts, Longs, UnsignedLongs, Floats, Doubles, Chars, and Booleans. They offer methods for array conversion, containment checks, min/max, lexicographical comparison, and byte‑order conversion.

Primitive Array Utilities

Method Signature

Description

Similar JDK Method

Applicability

List<Wrapper> asList(prim… backingArray)

Convert a primitive array to a List of its wrapper type.

Arrays.asList

Sign‑agnostic*

prim[] toArray(Collection<Wrapper> collection)

Copy a collection into a new primitive array (thread‑safe).

Collection.toArray()

Sign‑agnostic

prim[] concat(prim[]… arrays)

Concatenate multiple primitive arrays.

Iterables.concat

Sign‑agnostic

boolean contains(prim[] array, prim target)

Check if the array contains a given value.

Collection.contains

Sign‑agnostic

int indexOf(prim[] array, prim target)

Return the first index of the target value, or -1 if absent.

List.indexOf

Sign‑agnostic

int lastIndexOf(prim[] array, prim target)

Return the last index of the target value, or -1 if absent.

List.lastIndexOf

Sign‑agnostic

prim min(prim… array)

Return the smallest value in the array.

Collections.min

Sign‑related*

prim max(prim… array)

Return the largest value in the array.

Collections.max

Sign‑related

String join(String separator, prim… array)

Join array elements into a single string with the given separator.

Joiner.on(separator).join

Sign‑related

Comparator<prim[]> lexicographicalComparator()

Comparator that orders primitive arrays lexicographically.

Ordering.natural().lexicographical()

Sign‑related

*Sign‑agnostic methods exist for all primitive types; sign‑related methods exist only for those where sign matters.

General Primitive Utilities

Guava adds methods not present in JDK6, such as int compare(prim a, prim b) (a primitive comparator) and safe casting methods prim checkedCast(long value) and prim saturatedCast(long value) for signed integral types.

Byte‑Conversion Methods

Guava provides big‑endian conversion between primitive values and byte arrays. Each primitive class defines a constant BYTES indicating its size, and methods prim fromByteArray(byte[] bytes), prim fromBytes(byte b1, …, byte bk), and byte[] toByteArray(prim value).

Unsigned Support

For signed integral types, Guava offers unsigned utility classes ( UnsignedInts, UnsignedLongs) and wrapper classes ( UnsignedInteger, UnsignedLong) that provide parsing, formatting, and arithmetic without sign overflow. Example methods include parseUnsignedInt(String), toString(int), and arithmetic operations on unsigned values.

All the above material is adapted from the original Chinese tutorial (source: 并发编程网).