Java 8 String API Join() Method Example

1. Java 8 String join() Overview

In this tutorial, We'll learn about Java 8 String API new join() method with example java programs.

join() method is introduced in java.lang.String class to concatenate the given strings with the delimiter.

Join method returns a new String composed of copies of the CharSequence elements joined together with a copy of the specified delimiter.
Join is static method. No need of creating object for String class.

Internally it works based on the new java 8 class StringJoiner class.

Static initializers and blocks in java


In this post, We will write example programs first and then next will see how it is implemented internally.

2. Join() Method Syntax

Join method has two variants and it is an overloaded method in String class.

public static String join​(CharSequence delimiter, CharSequence... elements)
public static String join​(CharSequence delimiter, Iterable elements)

Join method takes two parameters and both are type of CharSequence.

The first overloaded method takes arguments as below.

First argument: It is a delimiter which can be char or String.
Second argument: It is Var-Args arguments. We can pass multiple arguments type of String or StringBuffer. But all parameters type should be same.

The second overloaded method takes arguments as below.
First argument: It is a delimiter which can be char or String.
Second argument: Takes any Collection api class as argument such as ArrayList, Hashset etc.

CharSequence is an interface and it implementation classes are CharBuffer, Segment, String, StringBuffer, StringBuilder. So, we can pass any of these as parameter to join method. We will write with examples.

3. Join() method example

We will implement java programs on join() method.

3.1 Joining with '-' Example

In this example, We are passing "-" as delimiter and passing elements which to be joined with delimiter.

package examples.java.w3schools.string.join;

public class StringJoinExample1 {
 public static void main(String[] args) {

  String joinString = String.join(" - ", "java", "is", "a", "prigramming", "language");
  System.out.println("Final joinString : " + joinString);
 }
}

Output:

Final joinString : java - is - a - prigramming - language

3.2 Joining numbers with greater than symbol '>' Example

package examples.java.w3schools.string.join;

public class StringJoinExample2 {
 public static void main(String[] args) {

  String joinString = String.join(" > ", "10", "8", "6", "4", "2");
  System.out.println("Final joinString : " + joinString);
 }
}

Output:

Final joinString : 10 > 8 > 6 > 4 > 2

3.3 StringBuffer Example using Join() method

public class StringJoinSBExample {

 public static void main(String[] args) {

  StringBuffer buffer1 = new StringBuffer();
  buffer1.append("java");

  StringBuffer buffer2 = new StringBuffer();
  buffer2.append("w3schools");

  String joinString = String.join("-", buffer1, buffer2);
  System.out.println("Final joinString : " + joinString);
 }

} 

Output:

Final joinString : java-w3schools

3.4 Join() Example With null element

Note that if an element or value is null, then "null" is added to the returned string.

public class StringJoinNullExample {

 public static void main(String[] args) {

  String joinString = String.join("***", null, null);
  System.out.println("null example joinString : " + joinString);
 }
}

Output:

null example joinString : null***null

3.5 Join() With delimiter as null

If the delimiter is null then NullPointerException will be thrown.

String joinString = String.join(null, "hello"); 

Output:

Exception in thread "main" java.lang.NullPointerException
 at java.base/java.util.Objects.requireNonNull(Objects.java:221)
 at java.base/java.lang.String.join(String.java:2393)
 at w3schools/examples.java.w3schools.string.join.StringJoinExample.main(StringJoinExample.java:8)

3.6 Join() Example with Collection api - ArrayList

Join method takes collection as well as arguments using following method.

public static String join​(CharSequence delimiter, Iterable elements)

Here is the example to join the list of elements. We can pass all collection api classes to join method.

import java.util.ArrayList;
import java.util.List;

public class StringJoinExample {
 public static void main(String[] args) {

  List fruits = new ArrayList<>();
  fruits.add("Orange");
  fruits.add("Papaya");
  fruits.add("Banana");
  fruits.add("Kiwi");
  fruits.add("Apple");

  String joinString = String.join("***", fruits);

  System.out.println("List example joinString : " + joinString);
 }
}

Output:

List example joinString : Orange***Papaya***Banana***Kiwi***Apple

4. Internal Implementation of Join method

Join method internally does mainly three steps.

Step 1) Null check for delimiter. if null then NullPointerException will be thrown.

Step 2) Null check for elements. if null then NullPointerException will be thrown.

Step 3) Creating StringJoiner instances by adding delimiter and iterating elements elements, adding to StringJoiner.

Internal Code:

public static String join(CharSequence delimiter, CharSequence... elements) {
        Objects.requireNonNull(delimiter);
        Objects.requireNonNull(elements);
        // Number of elements not likely worth Arrays.stream overhead.
        StringJoiner joiner = new StringJoiner(delimiter);
        for (CharSequence cs: elements) {
            joiner.add(cs);
        }
        return joiner.toString();
    }
 
 
public static String join(CharSequence delimiter,
            Iterable elements) {
        Objects.requireNonNull(delimiter);
        Objects.requireNonNull(elements);
        StringJoiner joiner = new StringJoiner(delimiter);
        for (CharSequence cs: elements) {
            joiner.add(cs);
        }
        return joiner.toString();
    }

5. Conclusion

In this article, We've seen what is new java 8 String API Join() method and what are the varients added to this method.

Further in this post, discussed many example programs on String, StringBuffer, ArrayList API.

Explained how join() method works internally step by step.

Example code snippets shown in this article is available on GitHub.