Class Joining
- java.lang.Object
-
- one.util.streamex.CancellableCollector<java.lang.CharSequence,Joining.Accumulator,java.lang.String>
-
- one.util.streamex.Joining
-
- All Implemented Interfaces:
java.util.stream.Collector<java.lang.CharSequence,Joining.Accumulator,java.lang.String>
public class Joining extends CancellableCollector<java.lang.CharSequence,Joining.Accumulator,java.lang.String>
An advanced implementation of joiningCollector
. This collector is capable to join the inputCharSequence
elements with given delimiter optionally wrapping into given prefix and suffix and optionally limiting the length of the resulting string (in Unicode code units, code points or grapheme clusters) adding the specified ellipsis sequence. This collector supersedes the standard JDKCollectors.joining(CharSequence, CharSequence, CharSequence)
collectors family.This collector is short-circuiting when the string length is limited in either of ways. Otherwise it's not short-circuiting.
Every specific collector represented by this class is immutable, so you can share it. A bunch of methods is provided to create a new collector based on this one.
To create
Joining
collector usewith(CharSequence)
static method and specify the delimiter. For further setup use specific instance methods which return newJoining
objects like this:StreamEx.of(source).collect(Joining.with(", ").wrap("[", "]") .maxCodePoints(100).cutAtWord());
The intermediate accumulation type of this collector is the implementation detail and not exposed to the API. If you want to cast it to
Collector
type, use ? as accumulator type variable:Collector<CharSequence, ?, String> joining = Joining.with(", ");
- Since:
- 0.4.1
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description (package private) static class
Joining.Accumulator
-
Field Summary
Fields Modifier and Type Field Description private static int
CUT_AFTER_DELIMITER
private static int
CUT_ANYWHERE
private static int
CUT_BEFORE_DELIMITER
private static int
CUT_CODEPOINT
private static int
CUT_GRAPHEME
private static int
CUT_WORD
private int
cutStrategy
private int
delimCount
private java.lang.String
delimiter
private java.lang.String
ellipsis
private static int
LENGTH_CHARS
private static int
LENGTH_CODEPOINTS
private static int
LENGTH_ELEMENTS
private static int
LENGTH_GRAPHEMES
private int
lenStrategy
private int
limit
private int
maxLength
private java.lang.String
prefix
private java.lang.String
suffix
-
Constructor Summary
Constructors Modifier Constructor Description private
Joining(java.lang.String delimiter, java.lang.String ellipsis, java.lang.String prefix, java.lang.String suffix, int cutStrategy, int lenStrategy, int maxLength)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.function.BiConsumer<Joining.Accumulator,java.lang.CharSequence>
accumulator()
java.util.Set<java.util.stream.Collector.Characteristics>
characteristics()
java.util.function.BinaryOperator<Joining.Accumulator>
combiner()
private static int
copy(char[] buf, int pos, java.lang.String str)
private int
copyCut(char[] buf, int pos, java.lang.String str, int limit, int cutStrategy)
Joining
cutAfterDelimiter()
Returns aCollector
which behaves like this collector, but cuts the resulting string after the delimiter when limit is reached.Joining
cutAnywhere()
Returns aCollector
which behaves like this collector, but cuts the resulting string at any point when limit is reached.Joining
cutAtCodePoint()
Returns aCollector
which behaves like this collector, but cuts the resulting string between any code points when limit is reached.Joining
cutAtGrapheme()
Returns aCollector
which behaves like this collector, but cuts the resulting string at grapheme cluster boundary when limit is reached.Joining
cutAtWord()
Returns aCollector
which behaves like this collector, but cuts the resulting string at word boundary when limit is reached.Joining
cutBeforeDelimiter()
Returns aCollector
which behaves like this collector, but cuts the resulting string before the delimiter when limit is reached.Joining
ellipsis(java.lang.CharSequence ellipsis)
Returns aCollector
which behaves like this collector, but uses the specified ellipsisCharSequence
instead of default"..."
when the string limit (if specified) is reached.(package private) java.util.function.Predicate<Joining.Accumulator>
finished()
java.util.function.Function<Joining.Accumulator,java.lang.String>
finisher()
private java.lang.String
finisherNoOverflow(Joining.Accumulator acc)
private void
init()
private int
length(java.lang.CharSequence s, boolean content)
Joining
maxChars(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal length of the resulting string to the specified number of UTF-16 characters (or Unicode code units).Joining
maxCodePoints(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal number of Unicode code points of the resulting string.Joining
maxElements(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal number of elements to join.Joining
maxGraphemes(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal number of grapheme clusters.java.util.function.Supplier<Joining.Accumulator>
supplier()
static Joining
with(java.lang.CharSequence delimiter)
Returns aCollector
that concatenates the input elements, separated by the specified delimiter, in encounter order.private Joining
withCut(int cutStrategy)
private Joining
withLimit(int lenStrategy, int maxLength)
Joining
wrap(java.lang.CharSequence prefix, java.lang.CharSequence suffix)
Returns aCollector
which behaves like this collector, but additionally wraps the result with the specified prefix and suffix.
-
-
-
Field Detail
-
CUT_ANYWHERE
private static final int CUT_ANYWHERE
- See Also:
- Constant Field Values
-
CUT_CODEPOINT
private static final int CUT_CODEPOINT
- See Also:
- Constant Field Values
-
CUT_GRAPHEME
private static final int CUT_GRAPHEME
- See Also:
- Constant Field Values
-
CUT_WORD
private static final int CUT_WORD
- See Also:
- Constant Field Values
-
CUT_BEFORE_DELIMITER
private static final int CUT_BEFORE_DELIMITER
- See Also:
- Constant Field Values
-
CUT_AFTER_DELIMITER
private static final int CUT_AFTER_DELIMITER
- See Also:
- Constant Field Values
-
LENGTH_CHARS
private static final int LENGTH_CHARS
- See Also:
- Constant Field Values
-
LENGTH_CODEPOINTS
private static final int LENGTH_CODEPOINTS
- See Also:
- Constant Field Values
-
LENGTH_GRAPHEMES
private static final int LENGTH_GRAPHEMES
- See Also:
- Constant Field Values
-
LENGTH_ELEMENTS
private static final int LENGTH_ELEMENTS
- See Also:
- Constant Field Values
-
delimiter
private final java.lang.String delimiter
-
ellipsis
private final java.lang.String ellipsis
-
prefix
private final java.lang.String prefix
-
suffix
private final java.lang.String suffix
-
cutStrategy
private final int cutStrategy
-
lenStrategy
private final int lenStrategy
-
maxLength
private final int maxLength
-
limit
private int limit
-
delimCount
private int delimCount
-
-
Method Detail
-
init
private void init()
-
length
private int length(java.lang.CharSequence s, boolean content)
-
copy
private static int copy(char[] buf, int pos, java.lang.String str)
-
copyCut
private int copyCut(char[] buf, int pos, java.lang.String str, int limit, int cutStrategy)
-
finisherNoOverflow
private java.lang.String finisherNoOverflow(Joining.Accumulator acc)
-
withLimit
private Joining withLimit(int lenStrategy, int maxLength)
-
withCut
private Joining withCut(int cutStrategy)
-
with
public static Joining with(java.lang.CharSequence delimiter)
Returns aCollector
that concatenates the input elements, separated by the specified delimiter, in encounter order.This collector is similar to
Collectors.joining(CharSequence)
, but can be further set up in a flexible way, for example, specifying the maximal allowed length of the resultingString
.- Parameters:
delimiter
- the delimiter to be used between each element- Returns:
- A
Collector
which concatenates CharSequence elements, separated by the specified delimiter, in encounter order - See Also:
Collectors.joining(CharSequence)
-
wrap
public Joining wrap(java.lang.CharSequence prefix, java.lang.CharSequence suffix)
Returns aCollector
which behaves like this collector, but additionally wraps the result with the specified prefix and suffix.The collector returned by
Joining.with(delimiter).wrap(prefix, suffix)
is equivalent toCollectors.joining(CharSequence, CharSequence, CharSequence)
, but can be further set up in a flexible way, for example, specifying the maximal allowed length of the resultingString
.If length limit is specified for the collector, the prefix length and the suffix length are also counted towards this limit. If the length of the prefix and the suffix exceed the limit, the resulting collector will not accumulate any elements and produce the same output. For example,
stream.collect(Joining.with(",").wrap("prefix", "suffix").maxChars(9))
will produce"prefixsuf"
string regardless of the input stream content.You may wrap several times:
Joining.with(",").wrap("[", "]").wrap("(", ")")
is equivalent toJoining.with(",").wrap("([", "])")
.- Parameters:
prefix
- the sequence of characters to be used at the beginning of the joined resultsuffix
- the sequence of characters to be used at the end of the joined result- Returns:
- a new
Collector
which wraps the result with the specified prefix and suffix.
-
ellipsis
public Joining ellipsis(java.lang.CharSequence ellipsis)
Returns aCollector
which behaves like this collector, but uses the specified ellipsisCharSequence
instead of default"..."
when the string limit (if specified) is reached.- Parameters:
ellipsis
- the sequence of characters to be used at the end of the joined result to designate that not all of the input elements are joined due to the specified string length restriction.- Returns:
- a new
Collector
which will use the specified ellipsis instead of current setting.
-
maxChars
public Joining maxChars(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal length of the resulting string to the specified number of UTF-16 characters (or Unicode code units). This setting overwrites any limit previously set bymaxChars(int)
,maxCodePoints(int)
,maxGraphemes(int)
ormaxElements(int)
call.The
String
produced by the resulting collector is guaranteed to havelength
which does not exceed the specified limit. An ellipsis sequence (by default"..."
) is used to designate whether the limit was reached. Useellipsis(CharSequence)
to set custom ellipsis sequence.The collector returned by this method is short-circuiting: it may not process all the input elements if the limit is reached.
- Parameters:
limit
- the maximal number of UTF-16 characters in the resulting String.- Returns:
- a new
Collector
which will produce String no longer than given limit.
-
maxCodePoints
public Joining maxCodePoints(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal number of Unicode code points of the resulting string. This setting overwrites any limit previously set bymaxChars(int)
,maxCodePoints(int)
,maxGraphemes(int)
ormaxElements(int)
call.The
String
produced by the resulting collector is guaranteed to have no more code points than the specified limit. An ellipsis sequence (by default"..."
) is used to designate whether the limit was reached. Useellipsis(CharSequence)
to set custom ellipsis sequence.The collector returned by this method is short-circuiting: it may not process all the input elements if the limit is reached.
- Parameters:
limit
- the maximal number of code points in the resulting String.- Returns:
- a new
Collector
which will produce String no longer than given limit.
-
maxGraphemes
public Joining maxGraphemes(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal number of grapheme clusters. This setting overwrites any limit previously set bymaxChars(int)
,maxCodePoints(int)
,maxGraphemes(int)
ormaxElements(int)
call.The grapheme cluster is defined in Unicode Text Segmentation technical report. Basically, it counts base character and the following combining characters as single object. The
String
produced by the resulting collector is guaranteed to have no more grapheme clusters than the specified limit. An ellipsis sequence (by default"..."
) is used to designate whether the limit was reached. Useellipsis(CharSequence)
to set custom ellipsis sequence.The collector returned by this method is short-circuiting: it may not process all the input elements if the limit is reached.
- Parameters:
limit
- the maximal number of grapheme clusters in the resulting String.- Returns:
- a new
Collector
which will produce String no longer than given limit.
-
maxElements
public Joining maxElements(int limit)
Returns aCollector
which behaves like this collector, but sets the maximal number of elements to join. This setting overwrites any limit previously set bymaxChars(int)
,maxCodePoints(int)
ormaxGraphemes(int)
ormaxElements(int)
call.The
String
produced by the resulting collector is guaranteed to have no more input elements than the specified limit. An ellipsis sequence (by default"..."
) is used to designate whether the limit was reached. Useellipsis(CharSequence)
to set custom ellipsis sequence. The cutting strategy is mostly irrelevant for this mode exceptcutBeforeDelimiter()
.The collector returned by this method is short-circuiting: it may not process all the input elements if the limit is reached.
- Parameters:
limit
- the maximal number of input elements in the resulting String.- Returns:
- a new
Collector
which will produce String no longer than given limit. - Since:
- 0.6.7
-
cutAnywhere
public Joining cutAnywhere()
Returns aCollector
which behaves like this collector, but cuts the resulting string at any point when limit is reached.The resulting collector will produce
String
which length is exactly equal to the specified limit if the limit is reached. If used withmaxChars(int)
, the resulting string may be cut in the middle of surrogate pair.- Returns:
- a new
Collector
which cuts the resulting string at any point when limit is reached.
-
cutAtCodePoint
public Joining cutAtCodePoint()
Returns aCollector
which behaves like this collector, but cuts the resulting string between any code points when limit is reached.The resulting collector will not split the surrogate pair when used with
maxChars(int)
ormaxCodePoints(int)
. However it may remove the combining character which may result in incorrect rendering of the last displayed grapheme.- Returns:
- a new
Collector
which cuts the resulting string between code points.
-
cutAtGrapheme
public Joining cutAtGrapheme()
Returns aCollector
which behaves like this collector, but cuts the resulting string at grapheme cluster boundary when limit is reached. This is the default behavior.The grapheme cluster is defined in Unicode Text Segmentation technical report. Thus the resulting collector will not split the surrogate pair and will preserve any combining characters or remove them with the base character.
- Returns:
- a new
Collector
which cuts the resulting string at grapheme cluster boundary.
-
cutAtWord
public Joining cutAtWord()
Returns aCollector
which behaves like this collector, but cuts the resulting string at word boundary when limit is reached.The beginning and end of every input stream element or delimiter is always considered as word boundary, so the stream of
"one", "two three"
collected withJoining.with("").maxChars(n).ellipsis("").cutAtWord()
may produce the following strings depending onn
:"" "one" "onetwo" "onetwo " "onetwo three"
- Returns:
- a new
Collector
which cuts the resulting string at word boundary.
-
cutBeforeDelimiter
public Joining cutBeforeDelimiter()
Returns aCollector
which behaves like this collector, but cuts the resulting string before the delimiter when limit is reached.- Returns:
- a new
Collector
which cuts the resulting string at before the delimiter.
-
cutAfterDelimiter
public Joining cutAfterDelimiter()
Returns aCollector
which behaves like this collector, but cuts the resulting string after the delimiter when limit is reached.- Returns:
- a new
Collector
which cuts the resulting string at after the delimiter.
-
supplier
public java.util.function.Supplier<Joining.Accumulator> supplier()
-
accumulator
public java.util.function.BiConsumer<Joining.Accumulator,java.lang.CharSequence> accumulator()
-
combiner
public java.util.function.BinaryOperator<Joining.Accumulator> combiner()
-
finisher
public java.util.function.Function<Joining.Accumulator,java.lang.String> finisher()
-
characteristics
public java.util.Set<java.util.stream.Collector.Characteristics> characteristics()
-
finished
java.util.function.Predicate<Joining.Accumulator> finished()
- Specified by:
finished
in classCancellableCollector<java.lang.CharSequence,Joining.Accumulator,java.lang.String>
-
-