de.ipcon.tools

Class TextJoiner

java.lang.Object

de.ipcon.tools.TextJoiner

public final class TextJoiner
extends java.lang.Object

Fluent builder for joining strings, collections, and object arrays with configurable delimiters, filtering, deduplication, escaping, and wrapping.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_SEPARATOR The default separator for String joining and splitting: ", "

Method Summary

Modifier and Type	Method and Description
void	appendTo(java.lang.StringBuilder sb, java.util.Collection<?> collection)
static TextJoiner	create() Creates a new fluent TextJoiner instance with default settings.
TextJoiner	escape(boolean escape) Configures whether escaping is enabled (default is true).
static java.lang.String	escape(java.lang.String str, java.lang.String charsToEscape) Escapes backslashes and any character present in charsToEscape by prefixing them with a single backslash ('\').
java.lang.String	join(java.util.Collection<?> col)
java.lang.String	join(java.lang.Object[] array)
java.lang.String	join(java.lang.String[] array)
static java.lang.String	joinAll(java.util.Collection<?> col) Joins collection elements using default delimiter (", ").
static java.lang.String	joinAll(java.lang.Object[] array) Joins array elements using default delimiter (", ").
static java.lang.String	joinAll(java.lang.String[] array) Joins array elements using default delimiter (", ").
static java.lang.String	joinLastDifferent(java.lang.String[] strs, java.lang.String lastSep, java.lang.String sep) Joins elements for natural language output where the final separator differs.
java.lang.String	joinTwo(java.lang.String s1, java.lang.String s2) Specialized joiner for 2 strings adhering to the contract: returns null if both inputs are null.
static TextJoiner	on(java.lang.String separator) Creates a builder preconfigured with a specific delimiter to save on boilerplate code.
TextJoiner	removeDuplicates(boolean removeDuplicates) Deduplicates elements while preserving insertion order (first-seen wins).
TextJoiner	removeEmptyStrings(boolean removeEmptyStrings) Drops empty, whitespace-only, and null strings during iteration (equivalent to StringUtils.isBlank).
TextJoiner	removeNulls(boolean removeNulls) Drops literal null values during iteration.
TextJoiner	separateBy(java.lang.String separator) Convenience alias for withSeparator(String).
TextJoiner	surroundWith(java.lang.String surround) Surrounds each element by prepending AND appending this exact string.
static java.lang.String	unescape(java.lang.String str) Unescapes strings that were escaped using escape(String, String) without regex overhead.
TextJoiner	withDefault(java.lang.String defaultString) Fallback string returned when the input collection or array is null or empty.
TextJoiner	withEscaper(java.util.function.BiFunction<java.lang.String,java.lang.String,java.lang.String> escaper) Supplies the custom escaping function (value, separator) -> escapedValue.
TextJoiner	withPrefix(java.lang.String prefix) Prepends this string once at the beginning of the rendered output.
TextJoiner	withSeparator(java.lang.String separator) Sets the delimiter inserted between elements.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SEPARATOR

public static final java.lang.String DEFAULT_SEPARATOR

The default separator for String joining and splitting: ", "

See Also:

Constant Field Values

Method Detail

escape

public static java.lang.String escape(java.lang.String str,
                                      java.lang.String charsToEscape)

Escapes backslashes and any character present in charsToEscape by prefixing them with a single backslash ('\').

Parameters:

str - the string to escape

charsToEscape - characters that need escaping (e.g. delimiters)

Returns:

the escaped string, or the input string if null/empty

Throws:

java.lang.NullPointerException - if str is null.

unescape

public static java.lang.String unescape(java.lang.String str)

Unescapes strings that were escaped using escape(String, String) without regex overhead.

Parameters:

str - string to unescape

Returns:

unescaped string, or original if null/empty

Throws:

java.lang.NullPointerException - if str is null.

create

public static TextJoiner create()

Creates a new fluent TextJoiner instance with default settings.

on

public static TextJoiner on(java.lang.String separator)

Creates a builder preconfigured with a specific delimiter to save on boilerplate code. Equivalent to TextJoiner.create().withSeparator(separator).

joinAll

public static java.lang.String joinAll(java.util.Collection<?> col)

Joins collection elements using default delimiter (", ").

joinAll

public static java.lang.String joinAll(java.lang.Object[] array)

Joins array elements using default delimiter (", ").

joinAll

public static java.lang.String joinAll(java.lang.String[] array)

Joins array elements using default delimiter (", ").

withSeparator

public TextJoiner withSeparator(java.lang.String separator)

Sets the delimiter inserted between elements. Default is ", ".

separateBy

public TextJoiner separateBy(java.lang.String separator)

Convenience alias for withSeparator(String).

withDefault

public TextJoiner withDefault(java.lang.String defaultString)

Fallback string returned when the input collection or array is null or empty.

surroundWith

public TextJoiner surroundWith(java.lang.String surround)

Surrounds each element by prepending AND appending this exact string.

withPrefix

public TextJoiner withPrefix(java.lang.String prefix)

Prepends this string once at the beginning of the rendered output.

escape

public TextJoiner escape(boolean escape)

Configures whether escaping is enabled (default is true).

withEscaper

public TextJoiner withEscaper(java.util.function.BiFunction<java.lang.String,java.lang.String,java.lang.String> escaper)

Supplies the custom escaping function (value, separator) -> escapedValue.

removeNulls

public TextJoiner removeNulls(boolean removeNulls)

Drops literal null values during iteration.

removeEmptyStrings

public TextJoiner removeEmptyStrings(boolean removeEmptyStrings)

Drops empty, whitespace-only, and null strings during iteration (equivalent to StringUtils.isBlank).

removeDuplicates

public TextJoiner removeDuplicates(boolean removeDuplicates)

Deduplicates elements while preserving insertion order (first-seen wins).

join

public java.lang.String join(java.util.Collection<?> col)

join

public java.lang.String join(java.lang.Object[] array)

join

public java.lang.String join(java.lang.String[] array)

joinTwo

public java.lang.String joinTwo(java.lang.String s1,
                                java.lang.String s2)

Specialized joiner for 2 strings adhering to the contract: returns null if both inputs are null.

joinLastDifferent

public static java.lang.String joinLastDifferent(java.lang.String[] strs,
                                                 java.lang.String lastSep,
                                                 java.lang.String sep)

Joins elements for natural language output where the final separator differs. Example: ["Tom", "Dick", "Harry"] -> "Tom, Dick and Harry".

appendTo

public void appendTo(java.lang.StringBuilder sb,
                     java.util.Collection<?> collection)