Class StringConcatenation
- All Implemented Interfaces:
CharSequence
A StringConcatenation
allows for efficient, indentation aware concatenation of character sequences.
In addition to the methods that are specified by the implemented interface CharSequence
, there are some other
public operations that allow to modify the contents of this sequence. The string representation of arbitrary objects
can be appended to an instance of StringConcatenation
. There are overloaded variants of
append(Object, String)
that allow to pass an indentation that should be applied to each line of the appended
content. Each line break that is part of the new content will be replaced by the line delimiter that was configured
for this StringConcatenation
.
The append
-operation ignores null
arguments. This is different to what
StringBuffer
or StringBuilder
do and that's the reason why the Appendable
interface is not
fulfilled by a StringConcatenation
.
The object uses an internal List
of Strings
that is concatenated on demand to a complete
sequence. Use toString()
to get the joined version of a StringConcatenation
.
Object.equals(Object)
and Object.hashCode()
are not specialized for a StringConcatenation
, that is, the
semantics are based on identity similar to what StringBuffer
and StringBuilder
do.
- Since:
- 2.3
- Author:
- Sebastian Zarnekow - Initial contribution and API
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The default line delimiter that is used by instances ofStringConcatenation
. -
Constructor Summary
ConstructorDescriptionCreate a new concatenation that uses the system line delimiter.StringConcatenation
(String lineDelimiter) Create a new concatenation with the specified delimiter. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Append the string representation of the given object to this sequence.protected void
void
Add the string representation of the given object to this sequence.protected void
Add the string representation of the given object to this sequence at the given index.void
Append the given string to this sequence.void
Add the given string to this sequence.void
append
(StringConcatenation concat) Append the contents of a given StringConcatenation to this sequence.void
append
(StringConcatenationClient client) Append the contents of a given StringConcatenationClient to this sequence.void
append
(StringConcatenationClient client, String indentation) Append the contents of a given StringConcatenationClient to this sequence.void
append
(StringConcatenation concat, String indentation) Append the contents of a given StringConcatenation to this sequence.void
appendImmediate
(Object object, String indentation) Add the string representation of the given object to this sequence immediately.protected void
appendSegments
(int index, List<String> otherSegments) Add the list of segments to this sequence at the given index.protected void
appendSegments
(int index, List<String> otherSegments, String otherDelimiter) Add the list of segments to this sequence at the given index.protected void
appendSegments
(String indentation, int index, List<String> otherSegments, String otherDelimiter) Add the list of segments to this sequence at the given index.char
charAt
(int index) Return the actual content of this sequence, including all trailing whitespace.protected String
Allows subtypes to access the configured line delimiter.Compute the significant content of this sequence.protected String
getStringRepresentation
(Object object) Computes the string representation of the given object.int
length()
void
newLine()
Add a newline to this sequence according to the configured lineDelimiter.void
Add a newline to this sequence according to the configured lineDelimiter if the last line contains something besides whitespace.splitLinesAndNewLines
(String text) Return a list of segments where each segment is either the content of a line in the given text or a line-break according to the configured delimiter.subSequence
(int start, int end) toString()
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
Methods inherited from interface java.lang.CharSequence
chars, codePoints, isEmpty
-
Field Details
-
DEFAULT_LINE_DELIMITER
The default line delimiter that is used by instances ofStringConcatenation
. It usesSystem.getProperty("line.separator")
.- Since:
- 2.3
-
-
Constructor Details
-
StringConcatenation
public StringConcatenation()Create a new concatenation that uses the system line delimiter. -
StringConcatenation
Create a new concatenation with the specified delimiter.- Parameters:
lineDelimiter
- the used delimiter.- Throws:
IllegalArgumentException
- if the lineDelimiter isnull
or the empty String.- Since:
- 2.3
-
-
Method Details
-
append
Append the string representation of the given object to this sequence. Does nothing if the object isnull
.- Parameters:
object
- the to-be-appended object.
-
append
Append the given string to this sequence. Does nothing if the string isnull
.- Parameters:
str
- the to-be-appended string.- Since:
- 2.11
-
append
Append the contents of a given StringConcatenation to this sequence. Does nothing if the concatenation isnull
.- Parameters:
concat
- the to-be-appended StringConcatenation.- Since:
- 2.11
-
append
Append the contents of a given StringConcatenationClient to this sequence. Does nothing if the argument isnull
.- Parameters:
client
- the to-be-appended StringConcatenationClient.- Since:
- 2.11
-
append
-
append
Add the string representation of the given object to this sequence. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
object
- the appended object.indentation
- the indentation string that should be prepended. May not benull
.
-
append
Add the given string to this sequence. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
str
- the appended string.indentation
- the indentation string that should be prepended. May not benull
.- Since:
- 2.11
-
append
Append the contents of a given StringConcatenation to this sequence. Does nothing if the concatenation isnull
. The given indentation will be prepended to each line except the first one.- Parameters:
concat
- the to-be-appended StringConcatenation.indentation
- the indentation string that should be prepended. May not benull
.- Since:
- 2.11
-
append
Append the contents of a given StringConcatenationClient to this sequence. Does nothing if that argument isnull
. The given indentation will be prepended to each line except the first one.- Parameters:
client
- the to-be-appended StringConcatenationClient.indentation
- the indentation string that should be prepended. May not benull
.- Since:
- 2.11
-
append
Add the string representation of the given object to this sequence at the given index. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
object
- the to-be-appended object.indentation
- the indentation string that should be prepended. May not benull
.index
- the index in the list of segments.
-
getStringRepresentation
Computes the string representation of the given object. The default implementation will just invokeObject.toString()
but clients may override and specialize the logic.- Parameters:
object
- the object that shall be appended. Nevernull
.- Returns:
- the string representation. May not be
null
. - Since:
- 2.5
-
appendImmediate
Add the string representation of the given object to this sequence immediately. That is, all the trailing whitespace of this sequence will be ignored and the string is appended directly after the last segment that contains something besides whitespace. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
object
- the to-be-appended object.indentation
- the indentation string that should be prepended. May not benull
.
-
appendSegments
protected void appendSegments(String indentation, int index, List<String> otherSegments, String otherDelimiter) Add the list of segments to this sequence at the given index. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
indentation
- the indentation string that should be prepended. May not benull
.index
- the index in this instance's list of segments.otherSegments
- the to-be-appended segments. May not benull
.otherDelimiter
- the line delimiter that was used in the otherSegments list.
-
appendSegments
Add the list of segments to this sequence at the given index. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
index
- the index in this instance's list of segments.otherSegments
- the to-be-appended segments. May not benull
.otherDelimiter
- the line delimiter that was used in the otherSegments list.- Since:
- 2.5
-
appendSegments
Add the list of segments to this sequence at the given index. The given indentation will be prepended to each line except the first one if the object has a multi-line string representation.- Parameters:
index
- the index in this instance's list of segments.otherSegments
- the to-be-appended segments. May not benull
.- Since:
- 2.5
-
newLine
public void newLine()Add a newline to this sequence according to the configured lineDelimiter. -
newLineIfNotEmpty
public void newLineIfNotEmpty()Add a newline to this sequence according to the configured lineDelimiter if the last line contains something besides whitespace. -
toString
- Specified by:
toString
in interfaceCharSequence
- Overrides:
toString
in classObject
-
getContent
Return the actual content of this sequence, including all trailing whitespace. The return value is unsafe, that is modification to thisStringConcatenation
will cause changes in a previously obtained result and vice versa.- Returns:
- the actual content of this instance. Never
null
. - Since:
- 2.8
-
getSignificantContent
Compute the significant content of this sequence. That is, trailing whitespace after the last line-break will be ignored if the last line contains only whitespace. The return value is unsafe, that is modification to thisStringConcatenation
will cause changes in a previously obtained result and vice versa.- Returns:
- the significant content of this instance. Never
null
.
-
getLineDelimiter
Allows subtypes to access the configured line delimiter.- Returns:
- the line delimiter
- Since:
- 2.5
-
length
public int length()Only the significant content of this sequence is considered.
- Specified by:
length
in interfaceCharSequence
-
charAt
public char charAt(int index) Only the significant content of this sequence is considered.
- Specified by:
charAt
in interfaceCharSequence
-
subSequence
Only the significant content of this sequence is considered.
- Specified by:
subSequence
in interfaceCharSequence
-
splitLinesAndNewLines
Return a list of segments where each segment is either the content of a line in the given text or a line-break according to the configured delimiter. Existing line-breaks in the text will be replaced by this's instances delimiter.- Parameters:
text
- the to-be-splitted text. May benull
.- Returns:
- a list of segments. Is never
null
.
-