Guava – Join and Split Collections

1. Overview

In this tutorial, we will learn how to use the Joiner and Splitter in the Guava library. We’ll convert collections into a String with the Joiner and we’ll split a String into a collection with the Splitter.

2. Convert List into String Using Joiner

Let’s start with a simple example to join a List into a String using Joiner. In the following example, we join a List of names into one String using the comma “,” as a separator:

public void whenConvertListToString_thenConverted() {
    List<String> names = Lists.newArrayList("John", "Jane", "Adam", "Tom");
    String result = Joiner.on(",").join(names);

    assertEquals(result, "John,Jane,Adam,Tom");

3. Convert Map to String Using Joiner

Next – let’s see how to use Joiner to convert a Map to a String. In the following example, we use withKeyValueSeparator() to join the key with its value:

public void whenConvertMapToString_thenConverted() {
    Map<String, Integer> salary = Maps.newHashMap();
    salary.put("John", 1000);
    salary.put("Jane", 1500);
    String result = Joiner.on(" , ").withKeyValueSeparator(" = ")

    assertThat(result, containsString("John = 1000"));
    assertThat(result, containsString("Jane = 1500"));

4. Join Nested Collections

Now – let’s see how to join nested collections into a String. In the following example, we join the result of transforming each List to a String:

public void whenJoinNestedCollections_thenJoined() {
    List<ArrayList<String>> nested = Lists.newArrayList(
      Lists.newArrayList("apple", "banana", "orange"),
      Lists.newArrayList("cat", "dog", "bird"),
      Lists.newArrayList("John", "Jane", "Adam"));
    String result = Joiner.on(";").join(Iterables.transform(nested,
      new Function<List<String>, String>() {
          public String apply(List<String> input) {
              return Joiner.on("-").join(input);

    assertThat(result, containsString("apple-banana-orange"));
    assertThat(result, containsString("cat-dog-bird"));
    assertThat(result, containsString("apple-banana-orange"));

5. Handle Null Values While Using Joiner

Now – let’s see different ways to Handle Null Values While Using Joiner.

To skip null values while joining collection use skipNulls() as in the following example:

public void whenConvertListToStringAndSkipNull_thenConverted() {
    List<String> names = Lists.newArrayList("John", null, "Jane", "Adam", "Tom");
    String result = Joiner.on(",").skipNulls().join(names);

    assertEquals(result, "John,Jane,Adam,Tom");

If you don’t want to skip null values and want to replace them instead, use useForNull() as in the following example:

public void whenUseForNull_thenUsed() {
    List<String> names = Lists.newArrayList("John", null, "Jane", "Adam", "Tom");
    String result = Joiner.on(",").useForNull("nameless").join(names);

    assertEquals(result, "John,nameless,Jane,Adam,Tom");

Note that useForNull() doesn’t change the original list, it only affect the output of the join.

6. Create List From String Using Splitter

Now – let’s see how to split a String into a List. In the following example, we use “-” separator to split the input String to List:

public void whenCreateListFromString_thenCreated() {
    String input = "apple - banana - orange";
    List<String> result = Splitter.on("-").trimResults()

    assertThat(result, contains("apple", "banana", "orange"));

Note that trimResults() removes the leading and trailing whitespace from the resulting substrings.

7. Create Map From String Using Splitter

Next – let’s see how Create Map from String Using Splitter. In the following example, we use withKeyValueSeparator() to split a String into a Map:

public void whenCreateMapFromString_thenCreated() {
    String input = "John=first,Adam=second";
    Map<String, String> result = Splitter.on(",")

    assertEquals("first", result.get("John"));
    assertEquals("second", result.get("Adam"));

8. Split String With Multiple Separators

Now – let’s see how to split a String with multiple separators. In the following example, we use both “.” and “,” to split our String:

public void whenSplitStringOnMultipleSeparator_thenSplit() {
    String input = "apple.banana,,orange,,.";
    List<String> result = Splitter.onPattern("[.,]")

    assertThat(result, contains("apple", "banana", "orange"));

Note that omitEmptyStrings() ignores empty strings and doesn’t add them to the resulting List.

9. Split a String at Specific Length

Next – let’s take a look on splitting a String at specific length. In the following example, we split our String every 3 characters:

public void whenSplitStringOnSpecificLength_thenSplit() {
    String input = "Hello world";
    List<String> result = Splitter.fixedLength(3).splitToList(input);

    assertThat(result, contains("Hel", "lo ", "wor", "ld"));

10. Limit the Split Result

Finally – let’s see how to Limit the Split Result. If you want the Splitter to stop splitting after specific number of items – use limit() as in the following example:

public void whenLimitSplitting_thenLimited() {
    String input = "a,b,c,d,e";
    List<String> result = Splitter.on(",")

    assertEquals(4, result.size());
    assertThat(result, contains("a", "b", "c", "d,e"));

11. Conclusion

In this tutorial we illustrated how to use both the Joiner and Splitter in Guava to do a variety of transformations between collections and Strings.

The implementation of all these examples and code snippets can be found in my Guava github project – this is an Eclipse based project, so it should be easy to import and run as it is.