Add org.apache.commons.text.TextStringBuilder.wrap(char[], int).
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 1d3ffab..2ef515f 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -63,6 +63,7 @@
<action type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.text.TextStringBuilder.TextStringBuilder(CharSequence).</action>
<action type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.text.matcher.StringMatcherFactory.stringMatcher(char...).</action>
<action type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.text.TextStringBuilder.wrap(char[]).</action>
+ <action type="add" dev="ggregory" due-to="Gary Gregory">Add org.apache.commons.text.TextStringBuilder.wrap(char[], int).</action>
<action type="update" dev="ggregory" due-to="Gary Gregory">[test] junit-jupiter 5.5.1 -> 5.5.2.</action>
<action type="update" dev="ggregory" due-to="Gary Gregory">[test] org.assertj:assertj-core 3.13.2 -> 3.16.1.</action>
<action type="update" dev="ggregory" due-to="Gary Gregory">[build] com.puppycrawl.tools:checkstyle 8.23 -> 8.34.</action>
diff --git a/src/main/java/org/apache/commons/text/TextStringBuilder.java b/src/main/java/org/apache/commons/text/TextStringBuilder.java
index 4a5690e..0aae728 100644
--- a/src/main/java/org/apache/commons/text/TextStringBuilder.java
+++ b/src/main/java/org/apache/commons/text/TextStringBuilder.java
@@ -278,14 +278,30 @@
/**
* Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this
* instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to
- * be initialized without copying the whole input array.
+ * be initialized without copying the input array.
*
- * @param initialBuffer a reference to a character array.
+ * @param initialBuffer The initial array that will back the new builder.
* @return A new instance.
* @since 1.9
*/
public static TextStringBuilder wrap(final char[] initialBuffer) {
- return new TextStringBuilder(initialBuffer);
+ Objects.requireNonNull(initialBuffer, "initialBuffer");
+ return new TextStringBuilder(initialBuffer, initialBuffer.length);
+ }
+
+ /**
+ * Constructs an instance from a reference to a character array. Changes to the input chars are reflected in this
+ * instance until the internal buffer needs to be reallocated. Using a reference to an array allows the instance to
+ * be initialized without copying the input array.
+ *
+ * @param initialBuffer The initial array that will back the new builder.
+ * @param length The length of the subarray to be used; must be non-negative and no larger than
+ * {@code initialBuffer.length}. The new builder's size will be set to {@code length}.
+ * @return A new instance.
+ * @since 1.9
+ */
+ public static TextStringBuilder wrap(final char[] initialBuffer, final int length) {
+ return new TextStringBuilder(initialBuffer, length);
}
/** Internal data storage. */
@@ -310,11 +326,18 @@
/**
* Constructs an instance from a reference to a character array.
*
- * @param initialBuffer a reference to a character array.
+ * @param initialBuffer a reference to a character array, must not be null.
+ * @param length The length of the subarray to be used; must be non-negative and no larger than
+ * {@code initialBuffer.length}. The new builder's size will be set to {@code length}.
+ * @throws NullPointerException If {@code initialBuffer} is null.
+ * @throws IllegalArgumentException if {@length} is bad.
*/
- private TextStringBuilder(final char[] initialBuffer) {
- this.buffer = initialBuffer;
- this.size = initialBuffer.length;
+ private TextStringBuilder(final char[] initialBuffer, final int length) {
+ this.buffer = Objects.requireNonNull(initialBuffer, "initialBuffer");
+ if (length < 0 || length > initialBuffer.length) {
+ throw new IllegalArgumentException("initialBuffer.length=" + initialBuffer.length + ", length=" + length);
+ }
+ this.size = length;
}
/**
@@ -333,8 +356,7 @@
/**
* Constructs an instance with the specified initial capacity.
*
- * @param initialCapacity
- * the initial capacity, zero or less will be converted to 32
+ * @param initialCapacity the initial capacity, zero or less will be converted to 32
*/
public TextStringBuilder(final int initialCapacity) {
super();
@@ -344,8 +366,7 @@
/**
* Constructs an instance from a string, allocating 32 extra characters for growth.
*
- * @param str
- * the string to copy, null treated as blank string
+ * @param str the string to copy, null treated as blank string
*/
public TextStringBuilder(final String str) {
this(StringUtils.length(str) + CAPACITY);
@@ -357,8 +378,7 @@
/**
* Appends a boolean value to the string builder.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final boolean value) {
@@ -375,8 +395,7 @@
/**
* Appends a char value to the string builder.
*
- * @param ch
- * the value to append
+ * @param ch the value to append
* @return this, to enable chaining
*/
@Override
@@ -390,8 +409,7 @@
/**
* Appends a char array to the string builder. Appending null will call {@link #appendNull()}.
*
- * @param chars
- * the char array to append
+ * @param chars the char array to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final char[] chars) {
@@ -411,12 +429,9 @@
/**
* Appends a char array to the string builder. Appending null will call {@link #appendNull()}.
*
- * @param chars
- * the char array to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param chars the char array to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder append(final char[] chars, final int startIndex, final int length) {
@@ -441,8 +456,7 @@
/**
* Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param buf
- * the char buffer to append
+ * @param buf the char buffer to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final CharBuffer buf) {
@@ -464,12 +478,9 @@
/**
* Appends the contents of a char buffer to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param buf
- * the char buffer to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param buf the char buffer to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder append(final CharBuffer buf, final int startIndex, final int length) {
@@ -497,8 +508,7 @@
/**
* Appends a CharSequence to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param seq
- * the CharSequence to append
+ * @param seq the CharSequence to append
* @return this, to enable chaining
*/
@Override
@@ -524,12 +534,9 @@
/**
* Appends part of a CharSequence to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param seq
- * the CharSequence to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid
+ * @param seq the CharSequence to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid
* @return this, to enable chaining
*/
@Override
@@ -549,8 +556,7 @@
/**
* Appends a double value to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final double value) {
@@ -560,8 +566,7 @@
/**
* Appends a float value to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final float value) {
@@ -571,8 +576,7 @@
/**
* Appends an int value to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final int value) {
@@ -582,8 +586,7 @@
/**
* Appends a long value to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final long value) {
@@ -593,8 +596,7 @@
/**
* Appends an object to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param obj
- * the object to append
+ * @param obj the object to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final Object obj) {
@@ -610,8 +612,7 @@
/**
* Appends a string to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string to append
+ * @param str the string to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final String str) {
@@ -631,12 +632,9 @@
/**
* Appends part of a string to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder append(final String str, final int startIndex, final int length) {
@@ -661,10 +659,8 @@
/**
* Calls {@link String#format(String, Object...)} and appends the result.
*
- * @param format
- * the format string
- * @param objs
- * the objects to use in the format string
+ * @param format the format string
+ * @param objs the objects to use in the format string
* @return {@code this} to enable chaining
* @see String#format(String, Object...)
*/
@@ -675,8 +671,7 @@
/**
* Appends a string buffer to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string buffer to append
+ * @param str the string buffer to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final StringBuffer str) {
@@ -696,12 +691,9 @@
/**
* Appends part of a string buffer to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder append(final StringBuffer str, final int startIndex, final int length) {
@@ -726,8 +718,7 @@
/**
* Appends a StringBuilder to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the StringBuilder to append
+ * @param str the StringBuilder to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final StringBuilder str) {
@@ -747,12 +738,9 @@
/**
* Appends part of a StringBuilder to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the StringBuilder to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the StringBuilder to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder append(final StringBuilder str, final int startIndex, final int length) {
@@ -777,8 +765,7 @@
/**
* Appends another string builder to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string builder to append
+ * @param str the string builder to append
* @return this, to enable chaining
*/
public TextStringBuilder append(final TextStringBuilder str) {
@@ -798,12 +785,9 @@
/**
* Appends part of a string builder to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder append(final TextStringBuilder str, final int startIndex, final int length) {
@@ -829,8 +813,7 @@
* Appends each item in an iterable to the builder without any separators. Appending a null iterable will have no
* effect. Each object is appended using {@link #append(Object)}.
*
- * @param iterable
- * the iterable to append
+ * @param iterable the iterable to append
* @return this, to enable chaining
*/
public TextStringBuilder appendAll(final Iterable<?> iterable) {
@@ -846,8 +829,7 @@
* Appends each item in an iterator to the builder without any separators. Appending a null iterator will have no
* effect. Each object is appended using {@link #append(Object)}.
*
- * @param it
- * the iterator to append
+ * @param it the iterator to append
* @return this, to enable chaining
*/
public TextStringBuilder appendAll(final Iterator<?> it) {
@@ -863,10 +845,8 @@
* Appends each item in an array to the builder without any separators. Appending a null array will have no effect.
* Each object is appended using {@link #append(Object)}.
*
- * @param <T>
- * the element type
- * @param array
- * the array to append
+ * @param <T> the element type
+ * @param array the array to append
* @return this, to enable chaining
*/
public <T> TextStringBuilder appendAll(@SuppressWarnings("unchecked") final T... array) {
@@ -897,12 +877,9 @@
* Appends an object to the builder padding on the left to a fixed width. The {@code String.valueOf} of the
* {@code int} value is used. If the formatted value is larger than the length, the left hand side is lost.
*
- * @param value
- * the value to append
- * @param width
- * the fixed field width, zero or negative has no effect
- * @param padChar
- * the pad character to use
+ * @param value the value to append
+ * @param width the fixed field width, zero or negative has no effect
+ * @param padChar the pad character to use
* @return this, to enable chaining
*/
public TextStringBuilder appendFixedWidthPadLeft(final int value, final int width, final char padChar) {
@@ -914,12 +891,9 @@
* used. If the object is larger than the length, the left hand side is lost. If the object is null, the null text
* value is used.
*
- * @param obj
- * the object to append, null uses null text
- * @param width
- * the fixed field width, zero or negative has no effect
- * @param padChar
- * the pad character to use
+ * @param obj the object to append, null uses null text
+ * @param width the fixed field width, zero or negative has no effect
+ * @param padChar the pad character to use
* @return this, to enable chaining
*/
public TextStringBuilder appendFixedWidthPadLeft(final Object obj, final int width, final char padChar) {
@@ -948,12 +922,9 @@
* Appends an object to the builder padding on the right to a fixed length. The {@code String.valueOf} of the
* {@code int} value is used. If the object is larger than the length, the right hand side is lost.
*
- * @param value
- * the value to append
- * @param width
- * the fixed field width, zero or negative has no effect
- * @param padChar
- * the pad character to use
+ * @param value the value to append
+ * @param width the fixed field width, zero or negative has no effect
+ * @param padChar the pad character to use
* @return this, to enable chaining
*/
public TextStringBuilder appendFixedWidthPadRight(final int value, final int width, final char padChar) {
@@ -961,16 +932,13 @@
}
/**
- * Appends an object to the builder padding on the right to a fixed length. The {@code toString} of the object
- * is used. If the object is larger than the length, the right hand side is lost. If the object is null, null text
+ * Appends an object to the builder padding on the right to a fixed length. The {@code toString} of the object is
+ * used. If the object is larger than the length, the right hand side is lost. If the object is null, null text
* value is used.
*
- * @param obj
- * the object to append, null uses null text
- * @param width
- * the fixed field width, zero or negative has no effect
- * @param padChar
- * the pad character to use
+ * @param obj the object to append, null uses null text
+ * @param width the fixed field width, zero or negative has no effect
+ * @param padChar the pad character to use
* @return this, to enable chaining
*/
public TextStringBuilder appendFixedWidthPadRight(final Object obj, final int width, final char padChar) {
@@ -998,8 +966,7 @@
/**
* Appends a boolean value followed by a new line to the string builder.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final boolean value) {
@@ -1009,8 +976,7 @@
/**
* Appends a char value followed by a new line to the string builder.
*
- * @param ch
- * the value to append
+ * @param ch the value to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final char ch) {
@@ -1021,8 +987,7 @@
* Appends a char array followed by a new line to the string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param chars
- * the char array to append
+ * @param chars the char array to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final char[] chars) {
@@ -1033,12 +998,9 @@
* Appends a char array followed by a new line to the string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param chars
- * the char array to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param chars the char array to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final char[] chars, final int startIndex, final int length) {
@@ -1048,8 +1010,7 @@
/**
* Appends a double value followed by a new line to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final double value) {
@@ -1059,8 +1020,7 @@
/**
* Appends a float value followed by a new line to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final float value) {
@@ -1070,8 +1030,7 @@
/**
* Appends an int value followed by a new line to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final int value) {
@@ -1081,8 +1040,7 @@
/**
* Appends a long value followed by a new line to the string builder using {@code String.valueOf}.
*
- * @param value
- * the value to append
+ * @param value the value to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final long value) {
@@ -1093,8 +1051,7 @@
/**
* Appends an object followed by a new line to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param obj
- * the object to append
+ * @param obj the object to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final Object obj) {
@@ -1104,8 +1061,7 @@
/**
* Appends a string followed by a new line to this string builder. Appending null will call {@link #appendNull()}.
*
- * @param str
- * the string to append
+ * @param str the string to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final String str) {
@@ -1116,12 +1072,9 @@
* Appends part of a string followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final String str, final int startIndex, final int length) {
@@ -1131,10 +1084,8 @@
/**
* Calls {@link String#format(String, Object...)} and appends the result.
*
- * @param format
- * the format string
- * @param objs
- * the objects to use in the format string
+ * @param format the format string
+ * @param objs the objects to use in the format string
* @return {@code this} to enable chaining
* @see String#format(String, Object...)
*/
@@ -1146,8 +1097,7 @@
* Appends a string buffer followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string buffer to append
+ * @param str the string buffer to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final StringBuffer str) {
@@ -1158,12 +1108,9 @@
* Appends part of a string buffer followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final StringBuffer str, final int startIndex, final int length) {
@@ -1174,8 +1121,7 @@
* Appends a string builder followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string builder to append
+ * @param str the string builder to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final StringBuilder str) {
@@ -1186,12 +1132,9 @@
* Appends part of a string builder followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string builder to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string builder to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final StringBuilder str, final int startIndex, final int length) {
@@ -1202,8 +1145,7 @@
* Appends another string builder followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string builder to append
+ * @param str the string builder to append
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final TextStringBuilder str) {
@@ -1214,12 +1156,9 @@
* Appends part of a string builder followed by a new line to this string builder. Appending null will call
* {@link #appendNull()}.
*
- * @param str
- * the string to append
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param length
- * the length to append, must be valid
+ * @param str the string to append
+ * @param startIndex the start index, inclusive, must be valid
+ * @param length the length to append, must be valid
* @return this, to enable chaining
*/
public TextStringBuilder appendln(final TextStringBuilder str, final int startIndex, final int length) {
@@ -1257,10 +1196,8 @@
/**
* Appends the pad character to the builder the specified number of times.
*
- * @param length
- * the length to append, negative means no append
- * @param padChar
- * the character to append
+ * @param length the length to append, negative means no append
+ * @param padChar the character to append
* @return this, to enable chaining
*/
public TextStringBuilder appendPadding(final int length, final char padChar) {
@@ -1290,8 +1227,7 @@
* Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
* </p>
*
- * @param separator
- * the separator to use
+ * @param separator the separator to use
* @return this, to enable chaining
*/
public TextStringBuilder appendSeparator(final char separator) {
@@ -1307,10 +1243,8 @@
*
* The separator is appended using {@link #append(char)}.
*
- * @param standard
- * the separator if builder is not empty
- * @param defaultIfEmpty
- * the separator if builder is empty
+ * @param standard the separator if builder is not empty
+ * @param defaultIfEmpty the separator if builder is empty
* @return this, to enable chaining
*/
public TextStringBuilder appendSeparator(final char standard, final char defaultIfEmpty) {
@@ -1340,10 +1274,8 @@
* Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
* </p>
*
- * @param separator
- * the separator to use
- * @param loopIndex
- * the loop index
+ * @param separator the separator to use
+ * @param loopIndex the loop index
* @return this, to enable chaining
*/
public TextStringBuilder appendSeparator(final char separator, final int loopIndex) {
@@ -1371,8 +1303,7 @@
* Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
* </p>
*
- * @param separator
- * the separator to use, null means no separator
+ * @param separator the separator to use, null means no separator
* @return this, to enable chaining
*/
public TextStringBuilder appendSeparator(final String separator) {
@@ -1397,10 +1328,8 @@
* Note that for this simple example, you should use {@link #appendWithSeparators(Iterable, String)}.
* </p>
*
- * @param separator
- * the separator to use, null means no separator
- * @param loopIndex
- * the loop index
+ * @param separator the separator to use, null means no separator
+ * @param loopIndex the loop index
* @return this, to enable chaining
*/
public TextStringBuilder appendSeparator(final String separator, final int loopIndex) {
@@ -1432,10 +1361,8 @@
* selectClause.append(whereClause)
* </pre>
*
- * @param standard
- * the separator if builder is not empty, null means no separator
- * @param defaultIfEmpty
- * the separator if builder is empty, null means no separator
+ * @param standard the separator if builder is not empty, null means no separator
+ * @param defaultIfEmpty the separator if builder is empty, null means no separator
* @return this, to enable chaining
*/
public TextStringBuilder appendSeparator(final String standard, final String defaultIfEmpty) {
@@ -1452,10 +1379,8 @@
* This method tries to avoid doing any extra copies of contents.
* </p>
*
- * @param appendable
- * the appendable to append data to
- * @throws IOException
- * if an I/O error occurs
+ * @param appendable the appendable to append data to
+ * @throws IOException if an I/O error occurs
*
* @see #readFrom(Readable)
*/
@@ -1486,10 +1411,8 @@
* Appends an iterable placing separators between each value, but not before the first or after the last. Appending
* a null iterable will have no effect. Each object is appended using {@link #append(Object)}.
*
- * @param iterable
- * the iterable to append
- * @param separator
- * the separator to use, null means no separator
+ * @param iterable the iterable to append
+ * @param separator the separator to use, null means no separator
* @return this, to enable chaining
*/
public TextStringBuilder appendWithSeparators(final Iterable<?> iterable, final String separator) {
@@ -1510,10 +1433,8 @@
* Appends an iterator placing separators between each value, but not before the first or after the last. Appending
* a null iterator will have no effect. Each object is appended using {@link #append(Object)}.
*
- * @param it
- * the iterator to append
- * @param separator
- * the separator to use, null means no separator
+ * @param it the iterator to append
+ * @param separator the separator to use, null means no separator
* @return this, to enable chaining
*/
public TextStringBuilder appendWithSeparators(final Iterator<?> it, final String separator) {
@@ -1533,10 +1454,8 @@
* Appends an array placing separators between each value, but not before the first or after the last. Appending a
* null array will have no effect. Each object is appended using {@link #append(Object)}.
*
- * @param array
- * the array to append
- * @param separator
- * the separator to use, null means no separator
+ * @param array the array to append
+ * @param separator the separator to use, null means no separator
* @return this, to enable chaining
*/
public TextStringBuilder appendWithSeparators(final Object[] array, final String separator) {
@@ -1558,8 +1477,7 @@
* This method allows the contents of the builder to be read using any standard method that expects a Reader.
* </p>
* <p>
- * To use, simply create a {@code StrBuilder}, populate it with data, call {@code asReader}, and then read
- * away.
+ * To use, simply create a {@code StrBuilder}, populate it with data, call {@code asReader}, and then read away.
* </p>
* <p>
* The internal character array is shared between the builder and the reader. This allows you to append to the
@@ -1621,8 +1539,8 @@
* This method allows you to populate the contents of the builder using any standard method that takes a Writer.
* </p>
* <p>
- * To use, simply create a {@code StrBuilder}, call {@code asWriter}, and populate away. The data is
- * available at any time using the methods of the {@code StrBuilder}.
+ * To use, simply create a {@code StrBuilder}, call {@code asWriter}, and populate away. The data is available at
+ * any time using the methods of the {@code StrBuilder}.
* </p>
* <p>
* The internal character array is shared between the builder and the writer. This allows you to intermix calls that
@@ -1664,11 +1582,9 @@
*
* @see #setCharAt(int, char)
* @see #deleteCharAt(int)
- * @param index
- * the index to retrieve, must be valid
+ * @param index the index to retrieve, must be valid
* @return The character at the index
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
@Override
public char charAt(final int index) {
@@ -1681,11 +1597,9 @@
*
* @see #charAt(int)
* @see #deleteCharAt(int)
- * @param index
- * the index to retrieve, must be valid
+ * @param index the index to retrieve, must be valid
* @return The character at the index
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
* @since 1.9
*/
public char charAtDelete(final int index) {
@@ -1698,8 +1612,8 @@
/**
* Clears the string builder (convenience Collections API style method).
* <p>
- * This method does not reduce the size of the internal character buffer. To do that, call {@code clear()}
- * followed by {@link #minimizeCapacity()}.
+ * This method does not reduce the size of the internal character buffer. To do that, call {@code clear()} followed
+ * by {@link #minimizeCapacity()}.
* </p>
* <p>
* This method is the same as {@link #setLength(int)} called with zero and is provided to match the API of
@@ -1716,8 +1630,7 @@
/**
* Checks if the string builder contains the specified char.
*
- * @param ch
- * the character to find
+ * @param ch the character to find
* @return true if the builder contains the character
*/
public boolean contains(final char ch) {
@@ -1733,8 +1646,7 @@
/**
* Checks if the string builder contains the specified string.
*
- * @param str
- * the string to find
+ * @param str the string to find
* @return true if the builder contains the string
*/
public boolean contains(final String str) {
@@ -1748,8 +1660,7 @@
* the character 'a' followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use, null returns -1
+ * @param matcher the matcher to use, null returns -1
* @return true if the matcher finds a match in the builder
*/
public boolean contains(final StringMatcher matcher) {
@@ -1759,13 +1670,10 @@
/**
* Deletes the characters between the two specified indices.
*
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder delete(final int startIndex, final int endIndex) {
final int actualEndIndex = validateRange(startIndex, endIndex);
@@ -1779,8 +1687,7 @@
/**
* Deletes the character wherever it occurs in the builder.
*
- * @param ch
- * the character to delete
+ * @param ch the character to delete
* @return this, to enable chaining
*/
public TextStringBuilder deleteAll(final char ch) {
@@ -1803,8 +1710,7 @@
/**
* Deletes the string wherever it occurs in the builder.
*
- * @param str
- * the string to delete, null causes no action
+ * @param str the string to delete, null causes no action
* @return this, to enable chaining
*/
public TextStringBuilder deleteAll(final String str) {
@@ -1825,8 +1731,7 @@
* Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete all
* occurrences where the character 'a' is followed by a number.
*
- * @param matcher
- * the matcher to use to find the deletion, null causes no action
+ * @param matcher the matcher to use to find the deletion, null causes no action
* @return this, to enable chaining
*/
public TextStringBuilder deleteAll(final StringMatcher matcher) {
@@ -1838,11 +1743,9 @@
*
* @see #charAt(int)
* @see #setCharAt(int, char)
- * @param index
- * the index to delete
+ * @param index the index to delete
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder deleteCharAt(final int index) {
validateIndex(index);
@@ -1853,8 +1756,7 @@
/**
* Deletes the character wherever it occurs in the builder.
*
- * @param ch
- * the character to delete
+ * @param ch the character to delete
* @return this, to enable chaining
*/
public TextStringBuilder deleteFirst(final char ch) {
@@ -1870,8 +1772,7 @@
/**
* Deletes the string wherever it occurs in the builder.
*
- * @param str
- * the string to delete, null causes no action
+ * @param str the string to delete, null causes no action
* @return this, to enable chaining
*/
public TextStringBuilder deleteFirst(final String str) {
@@ -1888,11 +1789,10 @@
/**
* Deletes the first match within the builder using the specified matcher.
* <p>
- * Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete
- * where the character 'a' is followed by a number.
+ * Matchers can be used to perform advanced deletion behavior. For example you could write a matcher to delete where
+ * the character 'a' is followed by a number.
*
- * @param matcher
- * the matcher to use to find the deletion, null causes no action
+ * @param matcher the matcher to use to find the deletion, null causes no action
* @return this, to enable chaining
*/
public TextStringBuilder deleteFirst(final StringMatcher matcher) {
@@ -1902,14 +1802,10 @@
/**
* Internal method to delete a range without validation.
*
- * @param startIndex
- * the start index, must be valid
- * @param endIndex
- * the end index (exclusive), must be valid
- * @param len
- * the length, must be valid
- * @throws IndexOutOfBoundsException
- * if any index is invalid
+ * @param startIndex the start index, must be valid
+ * @param endIndex the end index (exclusive), must be valid
+ * @param len the length, must be valid
+ * @throws IndexOutOfBoundsException if any index is invalid
*/
private void deleteImpl(final int startIndex, final int endIndex, final int len) {
System.arraycopy(buffer, endIndex, buffer, startIndex, size - endIndex);
@@ -1922,8 +1818,7 @@
* Note that this method handles null input quietly, unlike String.
* </p>
*
- * @param str
- * the string to search for, null returns false
+ * @param str the string to search for, null returns false
* @return true if the builder ends with the string
*/
public boolean endsWith(final String str) {
@@ -1949,8 +1844,7 @@
/**
* Checks the capacity and ensures that it is at least the size specified.
*
- * @param capacity
- * the capacity to ensure
+ * @param capacity the capacity to ensure
* @return this, to enable chaining
*/
public TextStringBuilder ensureCapacity(final int capacity) {
@@ -1963,8 +1857,7 @@
/**
* Checks the contents of this builder against another to see if they contain the same character content.
*
- * @param obj
- * the object to check, null returns false
+ * @param obj the object to check, null returns false
* @return true if the builders contain the same characters in the same order
*/
@Override
@@ -1975,8 +1868,7 @@
/**
* Checks the contents of this builder against another to see if they contain the same character content.
*
- * @param other
- * the object to check, null returns false
+ * @param other the object to check, null returns false
* @return true if the builders contain the same characters in the same order
*/
public boolean equals(final TextStringBuilder other) {
@@ -1987,8 +1879,7 @@
* Checks the contents of this builder against another to see if they contain the same character content ignoring
* case.
*
- * @param other
- * the object to check, null returns false
+ * @param other the object to check, null returns false
* @return true if the builders contain the same characters in the same order
*/
public boolean equalsIgnoreCase(final TextStringBuilder other) {
@@ -2018,8 +1909,7 @@
/**
* Copies the character array into the specified array.
*
- * @param target
- * the target array, null will cause an array to be created
+ * @param target the target array, null will cause an array to be created
* @return The input array, unless that was null or too small
*/
public char[] getChars(char[] target) {
@@ -2034,21 +1924,14 @@
/**
* Copies the character array into the specified array.
*
- * @param startIndex
- * first index to copy, inclusive, must be valid
- * @param endIndex
- * last index, exclusive, must be valid
- * @param target
- * the target array, must not be null or too small
- * @param targetIndex
- * the index to start copying in target
- * @throws NullPointerException
- * if the array is null
- * @throws IndexOutOfBoundsException
- * if any index is invalid
+ * @param startIndex first index to copy, inclusive, must be valid
+ * @param endIndex last index, exclusive, must be valid
+ * @param target the target array, must not be null or too small
+ * @param targetIndex the index to start copying in target
+ * @throws NullPointerException if the array is null
+ * @throws IndexOutOfBoundsException if any index is invalid
*/
- public void getChars(final int startIndex, final int endIndex, final char[] target,
- final int targetIndex) {
+ public void getChars(final int startIndex, final int endIndex, final char[] target, final int targetIndex) {
if (startIndex < 0) {
throw new StringIndexOutOfBoundsException(startIndex);
}
@@ -2092,8 +1975,7 @@
/**
* Searches the string builder to find the first reference to the specified char.
*
- * @param ch
- * the character to find
+ * @param ch the character to find
* @return The first index of the character, or -1 if not found
*/
public int indexOf(final char ch) {
@@ -2103,10 +1985,8 @@
/**
* Searches the string builder to find the first reference to the specified char.
*
- * @param ch
- * the character to find
- * @param startIndex
- * the index to start at, invalid index rounded to edge
+ * @param ch the character to find
+ * @param startIndex the index to start at, invalid index rounded to edge
* @return The first index of the character, or -1 if not found
*/
public int indexOf(final char ch, int startIndex) {
@@ -2128,8 +2008,7 @@
* <p>
* Note that a null input string will return -1, whereas the JDK throws an exception.
*
- * @param str
- * the string to find, null returns -1
+ * @param str the string to find, null returns -1
* @return The first index of the string, or -1 if not found
*/
public int indexOf(final String str) {
@@ -2143,10 +2022,8 @@
* Note that a null input string will return -1, whereas the JDK throws an exception.
* </p>
*
- * @param str
- * the string to find, null returns -1
- * @param startIndex
- * the index to start at, invalid index rounded to edge
+ * @param str the string to find, null returns -1
+ * @param startIndex the index to start at, invalid index rounded to edge
* @return The first index of the string, or -1 if not found
*/
public int indexOf(final String str, int startIndex) {
@@ -2184,8 +2061,7 @@
* character 'a' followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use, null returns -1
+ * @param matcher the matcher to use, null returns -1
* @return The first index matched, or -1 if not found
*/
public int indexOf(final StringMatcher matcher) {
@@ -2199,10 +2075,8 @@
* character 'a' followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use, null returns -1
- * @param startIndex
- * the index to start at, invalid index rounded to edge
+ * @param matcher the matcher to use, null returns -1
+ * @param startIndex the index to start at, invalid index rounded to edge
* @return The first index matched, or -1 if not found
*/
public int indexOf(final StringMatcher matcher, int startIndex) {
@@ -2223,13 +2097,10 @@
/**
* Inserts the value into this builder.
*
- * @param index
- * the index to add at, must be valid
- * @param value
- * the value to insert
+ * @param index the index to add at, must be valid
+ * @param value the value to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final boolean value) {
validateIndex(index);
@@ -2248,13 +2119,10 @@
/**
* Inserts the value into this builder.
*
- * @param index
- * the index to add at, must be valid
- * @param value
- * the value to insert
+ * @param index the index to add at, must be valid
+ * @param value the value to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final char value) {
validateIndex(index);
@@ -2268,13 +2136,10 @@
/**
* Inserts the character array into this builder. Inserting null will use the stored null text value.
*
- * @param index
- * the index to add at, must be valid
- * @param chars
- * the char array to insert
+ * @param index the index to add at, must be valid
+ * @param chars the char array to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final char[] chars) {
validateIndex(index);
@@ -2294,17 +2159,12 @@
/**
* Inserts part of the character array into this builder. Inserting null will use the stored null text value.
*
- * @param index
- * the index to add at, must be valid
- * @param chars
- * the char array to insert
- * @param offset
- * the offset into the character array to start at, must be valid
- * @param length
- * the length of the character array part to copy, must be positive
+ * @param index the index to add at, must be valid
+ * @param chars the char array to insert
+ * @param offset the offset into the character array to start at, must be valid
+ * @param length the length of the character array part to copy, must be positive
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if any index is invalid
+ * @throws IndexOutOfBoundsException if any index is invalid
*/
public TextStringBuilder insert(final int index, final char[] chars, final int offset, final int length) {
validateIndex(index);
@@ -2329,13 +2189,10 @@
/**
* Inserts the value into this builder.
*
- * @param index
- * the index to add at, must be valid
- * @param value
- * the value to insert
+ * @param index the index to add at, must be valid
+ * @param value the value to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final double value) {
return insert(index, String.valueOf(value));
@@ -2344,13 +2201,10 @@
/**
* Inserts the value into this builder.
*
- * @param index
- * the index to add at, must be valid
- * @param value
- * the value to insert
+ * @param index the index to add at, must be valid
+ * @param value the value to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final float value) {
return insert(index, String.valueOf(value));
@@ -2359,13 +2213,10 @@
/**
* Inserts the value into this builder.
*
- * @param index
- * the index to add at, must be valid
- * @param value
- * the value to insert
+ * @param index the index to add at, must be valid
+ * @param value the value to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final int value) {
return insert(index, String.valueOf(value));
@@ -2374,13 +2225,10 @@
/**
* Inserts the value into this builder.
*
- * @param index
- * the index to add at, must be valid
- * @param value
- * the value to insert
+ * @param index the index to add at, must be valid
+ * @param value the value to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final long value) {
return insert(index, String.valueOf(value));
@@ -2390,13 +2238,10 @@
* Inserts the string representation of an object into this builder. Inserting null will use the stored null text
* value.
*
- * @param index
- * the index to add at, must be valid
- * @param obj
- * the object to insert
+ * @param index the index to add at, must be valid
+ * @param obj the object to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, final Object obj) {
if (obj == null) {
@@ -2408,13 +2253,10 @@
/**
* Inserts the string into this builder. Inserting null will use the stored null text value.
*
- * @param index
- * the index to add at, must be valid
- * @param str
- * the string to insert
+ * @param index the index to add at, must be valid
+ * @param str the string to insert
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder insert(final int index, String str) {
validateIndex(index);
@@ -2449,8 +2291,7 @@
/**
* Searches the string builder to find the last reference to the specified char.
*
- * @param ch
- * the character to find
+ * @param ch the character to find
* @return The last index of the character, or -1 if not found
*/
public int lastIndexOf(final char ch) {
@@ -2460,10 +2301,8 @@
/**
* Searches the string builder to find the last reference to the specified char.
*
- * @param ch
- * the character to find
- * @param startIndex
- * the index to start at, invalid index rounded to edge
+ * @param ch the character to find
+ * @param startIndex the index to start at, invalid index rounded to edge
* @return The last index of the character, or -1 if not found
*/
public int lastIndexOf(final char ch, int startIndex) {
@@ -2484,8 +2323,7 @@
* <p>
* Note that a null input string will return -1, whereas the JDK throws an exception.
*
- * @param str
- * the string to find, null returns -1
+ * @param str the string to find, null returns -1
* @return The last index of the string, or -1 if not found
*/
public int lastIndexOf(final String str) {
@@ -2499,10 +2337,8 @@
* Note that a null input string will return -1, whereas the JDK throws an exception.
* </p>
*
- * @param str
- * the string to find, null returns -1
- * @param startIndex
- * the index to start at, invalid index rounded to edge
+ * @param str the string to find, null returns -1
+ * @param startIndex the index to start at, invalid index rounded to edge
* @return The last index of the string, or -1 if not found
*/
public int lastIndexOf(final String str, int startIndex) {
@@ -2538,8 +2374,7 @@
* character 'a' followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use, null returns -1
+ * @param matcher the matcher to use, null returns -1
* @return The last index matched, or -1 if not found
*/
public int lastIndexOf(final StringMatcher matcher) {
@@ -2553,10 +2388,8 @@
* character 'a' followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use, null returns -1
- * @param startIndex
- * the index to start at, invalid index rounded to edge
+ * @param matcher the matcher to use, null returns -1
+ * @param startIndex the index to start at, invalid index rounded to edge
* @return The last index matched, or -1 if not found
*/
public int lastIndexOf(final StringMatcher matcher, int startIndex) {
@@ -2581,8 +2414,7 @@
* available, the whole builder is returned. Thus the returned string may be shorter than the length requested.
* </p>
*
- * @param length
- * the number of characters to extract, negative returns empty string
+ * @param length the number of characters to extract, negative returns empty string
* @return The new string
*/
public String leftString(final int length) {
@@ -2608,16 +2440,14 @@
/**
* Extracts some characters from the middle of the string builder without throwing an exception.
* <p>
- * This method extracts {@code length} characters from the builder at the specified index. If the index is
- * negative it is treated as zero. If the index is greater than the builder size, it is treated as the builder size.
- * If the length is negative, the empty string is returned. If insufficient characters are available in the builder,
- * as much as possible is returned. Thus the returned string may be shorter than the length requested.
+ * This method extracts {@code length} characters from the builder at the specified index. If the index is negative
+ * it is treated as zero. If the index is greater than the builder size, it is treated as the builder size. If the
+ * length is negative, the empty string is returned. If insufficient characters are available in the builder, as
+ * much as possible is returned. Thus the returned string may be shorter than the length requested.
* </p>
*
- * @param index
- * the index to start at, negative means zero
- * @param length
- * the number of characters to extract, negative returns empty string
+ * @param index the index to start at, negative means zero
+ * @param length the number of characters to extract, negative returns empty string
* @return The new string
*/
public String midString(int index, final int length) {
@@ -2669,11 +2499,9 @@
* If possible, reads chars from the provided {@link Readable} directly into underlying character buffer without
* making extra copies.
*
- * @param readable
- * object to read from
+ * @param readable object to read from
* @return The number of characters read
- * @throws IOException
- * if an I/O error occurs
+ * @throws IOException if an I/O error occurs
*
* @see #appendTo(Appendable)
*/
@@ -2747,15 +2575,11 @@
* Replaces a portion of the string builder with another string. The length of the inserted string does not have to
* match the removed length.
*
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid except that if too large it is treated as end of string
- * @param replaceStr
- * the string to replace with, null means delete range
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param replaceStr the string to replace with, null means delete range
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder replace(final int startIndex, int endIndex, final String replaceStr) {
endIndex = validateRange(startIndex, endIndex);
@@ -2771,22 +2595,16 @@
* occurrences where the character 'a' is followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use to find the deletion, null causes no action
- * @param replaceStr
- * the string to replace the match with, null is a delete
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid except that if too large it is treated as end of string
- * @param replaceCount
- * the number of times to replace, -1 for replace all
+ * @param matcher the matcher to use to find the deletion, null causes no action
+ * @param replaceStr the string to replace the match with, null is a delete
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param replaceCount the number of times to replace, -1 for replace all
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if start index is invalid
+ * @throws IndexOutOfBoundsException if start index is invalid
*/
public TextStringBuilder replace(final StringMatcher matcher, final String replaceStr, final int startIndex,
- int endIndex, final int replaceCount) {
+ int endIndex, final int replaceCount) {
endIndex = validateRange(startIndex, endIndex);
return replaceImpl(matcher, replaceStr, startIndex, endIndex, replaceCount);
}
@@ -2794,10 +2612,8 @@
/**
* Replaces the search character with the replace character throughout the builder.
*
- * @param search
- * the search character
- * @param replace
- * the replace character
+ * @param search the search character
+ * @param replace the replace character
* @return this, to enable chaining
*/
public TextStringBuilder replaceAll(final char search, final char replace) {
@@ -2814,10 +2630,8 @@
/**
* Replaces the search string with the replace string throughout the builder.
*
- * @param searchStr
- * the search string, null causes no action to occur
- * @param replaceStr
- * the replace string, null is equivalent to an empty string
+ * @param searchStr the search string, null causes no action to occur
+ * @param replaceStr the replace string, null is equivalent to an empty string
* @return this, to enable chaining
*/
public TextStringBuilder replaceAll(final String searchStr, final String replaceStr) {
@@ -2840,10 +2654,8 @@
* occurrences where the character 'a' is followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use to find the deletion, null causes no action
- * @param replaceStr
- * the replace string, null is equivalent to an empty string
+ * @param matcher the matcher to use to find the deletion, null causes no action
+ * @param replaceStr the replace string, null is equivalent to an empty string
* @return this, to enable chaining
*/
public TextStringBuilder replaceAll(final StringMatcher matcher, final String replaceStr) {
@@ -2853,10 +2665,8 @@
/**
* Replaces the first instance of the search character with the replace character in the builder.
*
- * @param search
- * the search character
- * @param replace
- * the replace character
+ * @param search the search character
+ * @param replace the replace character
* @return this, to enable chaining
*/
public TextStringBuilder replaceFirst(final char search, final char replace) {
@@ -2874,10 +2684,8 @@
/**
* Replaces the first instance of the search string with the replace string.
*
- * @param searchStr
- * the search string, null causes no action to occur
- * @param replaceStr
- * the replace string, null is equivalent to an empty string
+ * @param searchStr the search string, null causes no action to occur
+ * @param replaceStr the replace string, null is equivalent to an empty string
* @return this, to enable chaining
*/
public TextStringBuilder replaceFirst(final String searchStr, final String replaceStr) {
@@ -2895,14 +2703,12 @@
/**
* Replaces the first match within the builder with the replace string.
* <p>
- * Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace
- * where the character 'a' is followed by a number.
+ * Matchers can be used to perform advanced replace behavior. For example you could write a matcher to replace where
+ * the character 'a' is followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use to find the deletion, null causes no action
- * @param replaceStr
- * the replace string, null is equivalent to an empty string
+ * @param matcher the matcher to use to find the deletion, null causes no action
+ * @param replaceStr the replace string, null is equivalent to an empty string
* @return this, to enable chaining
*/
public TextStringBuilder replaceFirst(final StringMatcher matcher, final String replaceStr) {
@@ -2912,21 +2718,15 @@
/**
* Internal method to delete a range without validation.
*
- * @param startIndex
- * the start index, must be valid
- * @param endIndex
- * the end index (exclusive), must be valid
- * @param removeLen
- * the length to remove (endIndex - startIndex), must be valid
- * @param insertStr
- * the string to replace with, null means delete range
- * @param insertLen
- * the length of the insert string, must be valid
- * @throws IndexOutOfBoundsException
- * if any index is invalid
+ * @param startIndex the start index, must be valid
+ * @param endIndex the end index (exclusive), must be valid
+ * @param removeLen the length to remove (endIndex - startIndex), must be valid
+ * @param insertStr the string to replace with, null means delete range
+ * @param insertLen the length of the insert string, must be valid
+ * @throws IndexOutOfBoundsException if any index is invalid
*/
private void replaceImpl(final int startIndex, final int endIndex, final int removeLen, final String insertStr,
- final int insertLen) {
+ final int insertLen) {
final int newSize = size - removeLen + insertLen;
if (insertLen != removeLen) {
ensureCapacity(newSize);
@@ -2945,22 +2745,16 @@
* occurrences where the character 'a' is followed by a number.
* </p>
*
- * @param matcher
- * the matcher to use to find the deletion, null causes no action
- * @param replaceStr
- * the string to replace the match with, null is a delete
- * @param from
- * the start index, must be valid
- * @param to
- * the end index (exclusive), must be valid
- * @param replaceCount
- * the number of times to replace, -1 for replace all
+ * @param matcher the matcher to use to find the deletion, null causes no action
+ * @param replaceStr the string to replace the match with, null is a delete
+ * @param from the start index, must be valid
+ * @param to the end index (exclusive), must be valid
+ * @param replaceCount the number of times to replace, -1 for replace all
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if any index is invalid
+ * @throws IndexOutOfBoundsException if any index is invalid
*/
private TextStringBuilder replaceImpl(final StringMatcher matcher, final String replaceStr, final int from, int to,
- int replaceCount) {
+ int replaceCount) {
if (matcher == null || size == 0) {
return this;
}
@@ -3007,8 +2801,7 @@
* available, the whole builder is returned. Thus the returned string may be shorter than the length requested.
* </p>
*
- * @param length
- * the number of characters to extract, negative returns empty string
+ * @param length the number of characters to extract, negative returns empty string
* @return The new string
*/
public String rightString(final int length) {
@@ -3020,18 +2813,16 @@
return new String(buffer, size - length, length);
}
}
+
/**
* Sets the character at the specified index.
*
* @see #charAt(int)
* @see #deleteCharAt(int)
- * @param index
- * the index to set
- * @param ch
- * the new character
+ * @param index the index to set
+ * @param ch the new character
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public TextStringBuilder setCharAt(final int index, final char ch) {
validateIndex(index);
@@ -3042,11 +2833,9 @@
/**
* Updates the length of the builder by either dropping the last characters or adding filler of Unicode zero.
*
- * @param length
- * the length to set to, must be zero or positive
+ * @param length the length to set to, must be zero or positive
* @return this, to enable chaining
- * @throws IndexOutOfBoundsException
- * if the length is negative
+ * @throws IndexOutOfBoundsException if the length is negative
*/
public TextStringBuilder setLength(final int length) {
if (length < 0) {
@@ -3067,8 +2856,7 @@
/**
* Sets the text to be appended when a new line is added.
*
- * @param newLine
- * the new line text, null means use system default
+ * @param newLine the new line text, null means use system default
* @return this, to enable chaining
*/
public TextStringBuilder setNewLineText(final String newLine) {
@@ -3079,8 +2867,7 @@
/**
* Sets the text to be appended when null is added.
*
- * @param nullText
- * the null text, null means no append
+ * @param nullText the null text, null means no append
* @return this, to enable chaining
*/
public TextStringBuilder setNullText(String nullText) {
@@ -3109,8 +2896,7 @@
* Note that this method handles null input quietly, unlike String.
* </p>
*
- * @param str
- * the string to search for, null returns false
+ * @param str the string to search for, null returns false
* @return true if the builder starts with the string
*/
public boolean startsWith(final String str) {
@@ -3152,11 +2938,9 @@
/**
* Extracts a portion of this string builder as a string.
*
- * @param start
- * the start index, inclusive, must be valid
+ * @param start the start index, inclusive, must be valid
* @return The new string
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public String substring(final int start) {
return substring(start, size);
@@ -3169,13 +2953,10 @@
* builder, and continues without error, unlike StringBuffer or String.
* </p>
*
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
* @return The new string
- * @throws IndexOutOfBoundsException
- * if the index is invalid
+ * @throws IndexOutOfBoundsException if the index is invalid
*/
public String substring(final int startIndex, int endIndex) {
endIndex = validateRange(startIndex, endIndex);
@@ -3194,13 +2975,11 @@
/**
* Copies part of the builder's character array into a new character array.
*
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
* @return a new array that holds part of the contents of the builder
- * @throws IndexOutOfBoundsException
- * if startIndex is invalid, or if endIndex is invalid (but endIndex greater than size is valid)
+ * @throws IndexOutOfBoundsException if startIndex is invalid, or if endIndex is invalid (but endIndex greater than
+ * size is valid)
*/
public char[] toCharArray(final int startIndex, int endIndex) {
endIndex = validateRange(startIndex, endIndex);
@@ -3294,12 +3073,9 @@
/**
* Validates indices defining a range in this builder.
*
- * @param startIndex
- * the start index, inclusive.
- * @param endIndex
- * the end index, exclusive.
- * @throws StringIndexOutOfBoundsException
- * if the index is invalid
+ * @param startIndex the start index, inclusive.
+ * @param endIndex the end index, exclusive.
+ * @throws StringIndexOutOfBoundsException if the index is invalid
* @since 1.9
*/
protected void validateIndices(final int startIndex, final int endIndex) {
@@ -3314,13 +3090,10 @@
/**
* Validates parameters defining a range of the builder.
*
- * @param startIndex
- * the start index, inclusive, must be valid
- * @param endIndex
- * the end index, exclusive, must be valid except that if too large it is treated as end of string
+ * @param startIndex the start index, inclusive, must be valid
+ * @param endIndex the end index, exclusive, must be valid except that if too large it is treated as end of string
* @return A valid end index.
- * @throws StringIndexOutOfBoundsException
- * if the index is invalid
+ * @throws StringIndexOutOfBoundsException if the index is invalid
*/
protected int validateRange(final int startIndex, int endIndex) {
if (startIndex < 0) {
diff --git a/src/test/java/org/apache/commons/text/TextStringBuilderTest.java b/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
index 995f916..0ebf3f7 100644
--- a/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
+++ b/src/test/java/org/apache/commons/text/TextStringBuilderTest.java
@@ -39,6 +39,7 @@
import java.nio.charset.Charset;
import java.util.Arrays;
+import org.apache.commons.lang3.ArrayUtils;
import org.apache.commons.text.matcher.StringMatcher;
import org.apache.commons.text.matcher.StringMatcherFactory;
import org.junit.jupiter.api.Test;
@@ -2189,8 +2190,17 @@
}
@Test
- public void testWrap() {
- char[] test = "abc".toCharArray();
+ public void testWrap_CharArray() {
+ assertThrows(NullPointerException.class, () -> TextStringBuilder.wrap(null));
+ //
+ final TextStringBuilder initEmpty = TextStringBuilder.wrap(ArrayUtils.EMPTY_CHAR_ARRAY);
+ assertEquals(0, initEmpty.size());
+ assertEquals(0, initEmpty.length());
+ initEmpty.append('a');
+ assertEquals(1, initEmpty.size());
+ assertEquals(1, initEmpty.length());
+ //
+ final char[] test = "abc".toCharArray();
final TextStringBuilder sb = TextStringBuilder.wrap(test);
assertArrayEquals(test, sb.getBuffer());
assertEquals(test.length, sb.length());
@@ -2199,4 +2209,28 @@
assertFalse(Arrays.equals(test, sb.getBuffer()));
}
+ @Test
+ public void testWrap_CharArray_Int_at0() {
+ final char[] test = "abc".toCharArray();
+ //
+ assertThrows(NullPointerException.class, () -> TextStringBuilder.wrap(null, 0));
+ assertThrows(IllegalArgumentException.class, () -> TextStringBuilder.wrap(test, -1));
+ //
+ assertThrows(IllegalArgumentException.class, () -> TextStringBuilder.wrap(ArrayUtils.EMPTY_CHAR_ARRAY, 1));
+ //
+ final TextStringBuilder initEmpty = TextStringBuilder.wrap(ArrayUtils.EMPTY_CHAR_ARRAY, 0);
+ assertEquals(0, initEmpty.size());
+ assertEquals(0, initEmpty.length());
+ initEmpty.append('a');
+ assertEquals(1, initEmpty.size());
+ assertEquals(1, initEmpty.length());
+ //
+ final TextStringBuilder sb = TextStringBuilder.wrap(test, test.length);
+ assertArrayEquals(test, sb.getBuffer());
+ assertEquals(test.length, sb.length());
+ assertEquals(test.length, sb.size());
+ sb.ensureCapacity(sb.capacity() * 2);
+ assertFalse(Arrays.equals(test, sb.getBuffer()));
+ }
+
}
